io.github.weareconnectry/connectry-architect-mcp

What is Architect Cert?

Architect Cert is a free, open-source MCP server that turns Claude into your personal certification tutor for the Claude Certified Architect — Foundations exam. No courses, no slides, no video lectures — just ask Claude and study.

It ships with:

• 390 scenario-based questions across all 5 exam domains and 30 task statements
• Interactive clickable UI — answer questions with A/B/C/D buttons, select follow-ups, pick domains with checkboxes — all inside Claude
• Lessons-first assessment — learn each domain's concepts before being tested on them
• Guided capstone build — shape your own project, then build it step-by-step while learning every task statement hands-on
• 30 concept handouts — one per task statement, with code examples and common mistakes
• 6 reference projects — runnable TypeScript codebases demonstrating each domain in practice
• Practice exams — 60-question weighted exams with history tracking and improvement trends
• Progress dashboard — glassmorphism visual dashboard with mastery levels, exam history chart, activity timeline
• Visual progress tracking — todo checklists track your progress through assessments, exams, and capstone builds in real time
• Interactive follow-ups — wrong answer? Click to see code examples, concept lessons, handouts, or reference projects
• PDF generation — branded handout PDFs with the Architect Cert logo for offline study
• Spaced repetition — SM-2 algorithm schedules reviews at optimal intervals
• Deterministic grading — pure function grading, no LLM judgment, zero sycophancy

Everything runs locally. No cloud, no accounts, no telemetry.

Quick Start

1. Install

npm install -g connectry-architect-mcp

2. Configure Your MCP Client

claude mcp add connectry-architect -- connectry-architect-mcp

That's it. Restart Claude Code and the server starts automatically.

Add to .mcp.json in your project or ~/.claude.json globally:

{
  "mcpServers": {
    "connectry-architect": {
      "command": "connectry-architect-mcp"
    }
  }
}

Restart Claude Code. The server starts automatically when Claude loads.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "connectry-architect": {
      "command": "connectry-architect-mcp"
    }
  }
}

Tip: If you use nvm, you may need to specify the full path to the binary:

json

"command": "/Users/yourname/.nvm/versions/node/v22.20.0/bin/connectry-architect-mcp"

Restart Claude Desktop. You'll see the MCP tools icon appear in the chat input.

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "connectry-architect": {
      "command": "connectry-architect-mcp"
    }
  }
}

Restart Claude Desktop. You'll see the MCP tools icon appear in the chat input.

Architect Cert works with any client that supports the Model Context Protocol. Configure it as a stdio server:

• Command: connectry-architect-mcp
• Arguments: none
• Transport: stdio

The server exposes 18 tools, 8 prompts, and 3 resource types.

3. Start Studying

Restart your MCP client and start chatting:

Learning Path

Architect Cert is designed to follow a natural progression. Here's the recommended order:

1. Assessment        → Baseline your knowledge across all 5 domains
       ↓
2. Learn concepts    → Read handouts for weak domains before practicing
       ↓
3. Adaptive practice → Questions prioritized by weakness, reviews, new material
       ↓
4. Follow-ups        → Dive into code examples, concept lessons, reference projects
       ↓
5. Capstone build    → Build your own project covering all 30 task statements
       ↓
6. Practice exams    → Simulate the real exam (60 questions, scored out of 1000)
       ↓
7. Review & repeat   → Dashboard tracks mastery, spaced repetition handles scheduling

You can jump to any stage at any time — the system adapts. But the path above gives you the most structured experience.

Interactive Experience

Architect Cert uses Claude's built-in interactive UI to make studying feel natural. No typing answer letters — just click.

Clickable Answer Selection

Every question presents clickable A/B/C/D buttons directly in Claude. You tap your answer instead of typing it. If the question includes code in the scenario, a code preview appears alongside each option so you can reference it while deciding.

Follow-Up Actions

After every answer, clickable follow-up buttons appear:

After a wrong answer:

• Got it, next question
• Explain with a code example
• Show me the concept lesson
• Show me the handout
• Show me in the reference project

After a correct answer:

• Next question
• Explain why the others are wrong

Multi-Select Domain Picker

When requesting a study plan, you can select multiple domains to focus on using checkboxes — no need to list them out by name.

Visual Progress Checklists

Long flows like the assessment (15 questions), practice exams (60 questions), and capstone build (18 steps) create a visual todo checklist that updates in real time as you progress. You always know where you are and what's left.

Skip & Other

Every question selection includes a Skip button to move on and an Other option to ask a free-form question. If you use "Other" to ask something, Claude answers your question and then re-presents the same quiz question — you never lose your place. "Skip" moves to the next question; skipped questions remain unanswered and will reappear later.

Initial Assessment

Start with a 15-question diagnostic (3 per domain) that determines your learning path. The assessment works differently from raw practice:

Lessons-First Flow

When the assessment reaches a new domain for the first time, it pauses to show you the concept handout before asking questions. This means you learn the key ideas, see code examples, and understand common mistakes before being tested — no guessing blindly.

The flow for each domain:

1. Concept handout is shown (one-time per domain)
2. 3 questions presented one at a time (easy, medium, hard)
3. Each answer graded immediately with explanation
4. Move to the next domain

Path Assignment

Based on your overall accuracy:

Progress Tracking

The assessment creates a 15-item visual checklist (Q1 through Q15, grouped by domain) that updates after each answer. You always see exactly how far you've progressed.

Concept Handouts

Every task statement has a concept handout — a structured study document (~500-800 words) that covers:

• Concept — The core idea, mental model, and when/why to use it
• Code Example — Realistic TypeScript demonstrating the pattern
• Common Mistakes — The 3-5 most frequent errors (which map to exam wrong answers)
• References — Links to Anthropic's official documentation

Reading Handouts in Claude

You: "Show me the handout for task 2.3"

Claude: [loads the full handout with concept, code, mistakes, references]

When Handouts Appear Automatically

• During assessment — shown before the first question of each new domain
• After a wrong answer — "Show me the handout" is one of the follow-up options
• During capstone build — relevant handouts are available at each build step

Generating PDF Handouts

Generate branded PDFs for all 30 handouts for offline study:

cd connectrylab-architect-cert-mcp
npm run generate:pdfs

This creates 30 PDFs in generated/handouts/ with:

• Architect Cert logo and domain label in the header
• Clean formatting with syntax-highlighted code blocks
• "Connectry LABS — Claude Certified Architect Exam Prep — Free & Open Source" footer

Adaptive Practice

Every practice question is selected by a three-priority algorithm:

1. Overdue reviews — Spaced repetition items due for review today
2. Weak areas — Topics where your mastery is below 50%
3. New material — Fresh questions from your recommended domain

Filtering

You can filter practice questions by domain and/or difficulty:

You: "Give me a hard question about prompt engineering"

Claude: [presents a hard Domain 4 question with clickable A/B/C/D buttons]

Interactive Follow-Ups

After every answer, you get clickable follow-up options. Each option dives deeper into the concept — then brings you right back to your quiz. You never leave your study flow to look something up.

Mastery Levels

Each of the 30 task statements has an independent mastery level:

Spaced Repetition (SM-2)

The SM-2 algorithm schedules review intervals:

• First review: 1 day after answering
• Second review: 3 days after first review
• Subsequent reviews: Previous interval x ease factor (starts at 2.5)
• Wrong answer: Interval resets, ease factor decreases by 0.2 (floor: 1.3)
• Correct answer: Ease factor increases by 0.1

Difficult questions come back often. Easy ones space out to weeks or months.

Guided Capstone Build

The most hands-on way to learn — build your own project from scratch while covering all 30 task statements. Instead of just answering questions, you architect a real system themed to your own idea.

How It Works

The capstone build has three phases:

Phase 1 — Project Shaping

You describe a project idea (e.g., "a multi-agent code review system"). Claude analyzes your idea against all 30 architectural criteria and identifies gaps. You refine together until every task statement is covered.

You: "I want to start a guided capstone build"

Claude: [presents the 30 criteria across all 5 domains]
        Describe your project idea and I'll analyze coverage.

You: "A multi-agent code review system that analyzes PRs"

Claude: Your idea naturally covers 24/30 criteria. To cover the
        remaining 6, I'd suggest adding: [specific suggestions
        mapped to task statements]

Phase 2 — Interleaved Build (18 steps)

Each step follows the same pattern:

1. Quiz — 2-3 questions on the task statements you're about to build (clickable A/B/C/D)
2. Build — Claude generates the file's code, themed to your project
3. Walkthrough — Line-by-line explanation mapping code to task statements

A visual 18-step checklist tracks your progress in real time.

The 18 steps build incrementally:

Every quiz answer feeds into the same spaced repetition and mastery tracking as regular practice.

Phase 3 — Final Review

After step 18, you get a complete coverage map: all 30 task statements, where each is demonstrated in your project, and your quiz performance per domain. Weak areas are flagged for further study.

Capstone Build Tools

How It Connects to Everything Else

• Quiz answers during the build use the same submit_answer grading and SM-2 scheduling
• After any quiz question, you can use the same follow-up options (code example, concept lesson, handout, reference project)
• The reference projects show how the capstone structure looks when complete
• Progress persists across sessions — pick up where you left off

Practice Exams

Full 60-question exams that simulate the real certification:

All attempts are saved with per-domain score breakdowns and improvement trends.

Progress Dashboard

Architect Cert includes a glassmorphism visual dashboard that renders directly inside Claude via Claude Preview.

What It Shows

• Readiness Ring — Overall exam readiness percentage in a circular progress indicator
• Domain Mastery Grid — 5 cards with progress bars for each exam domain
• Exam History Chart — Line chart plotting your practice exam scores over time, with the 720 passing score marked
• Recent Activity Timeline — Your last 10 answers with correct/incorrect indicators
• Capstone Progress — Current build step and completion percentage
• Quick Action Buttons — Jump to practice, exam, study plan, or capstone

How to Open

You: "Show my dashboard"

Claude: [opens the branded dashboard in Claude Preview]

The dashboard can be reopened at any time by asking Claude again. It always reflects your latest data.

Text Fallback

For MCP clients that don't support Claude Preview, the dashboard tool also returns a text summary with mastery percentages and exam stats.

Reference Projects

Architect Cert includes 6 complete reference projects — runnable TypeScript codebases that demonstrate certification concepts in real code. Every file has a header comment mapping it to specific task statements.

How to Access

You: "Show me a reference project for domain 1"

Claude: [returns the project README, file listing, and architecture walkthrough]

How They Connect to the Study Flow

When you get a question wrong, one of the follow-up options is "Show me in the reference project" — this takes you straight to the relevant domain project so you can see the concept implemented in real code. Then you jump back to your quiz.

Study Plan

Get personalized study recommendations based on your performance, exam weights, and spaced repetition schedule.

Multi-Select Domain Focus

When requesting a study plan, you can pick specific domains to focus on using checkboxes:

You: "What should I study next?"

Claude: [shows domain checkboxes — select the ones you want to focus on]
        [generates a personalized study plan with a visual checklist]

The study plan creates a visual checklist so you can track your progress through each recommendation.

Exam Domains

The Claude Certified Architect — Foundations exam covers 5 domains:

30 Task Statements

Tools

Architect Cert provides 18 MCP tools that Claude uses to deliver the study experience:

Study Flow

Progress & Planning

Practice Exams

Capstone Build

Reference & Admin

The server also registers 8 interactive prompts and 3 resource types (concept handouts, reference projects, exam overview).

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                           YOUR MACHINE                               │
│                                                                      │
│   ┌──────────────┐       ┌────────────────────────────────┐          │
│   │ Claude Desktop│       │     Architect Cert MCP          │          │
│   │ Claude Code   │◄─────►│                                │          │
│   │ Any MCP client│ stdio │  18 tools                      │          │
│   └──────┬───────┘       │   8 prompts                     │          │
│          │                │   3 resource types              │          │
│          │                └──────────┬─────────────────────┘          │
│          │                           │                                │
│          │         ┌────────────────┼────────────────────┐           │
│          │         │                │                     │           │
│          │   ~/.connectry-      390 questions         6 reference     │
│          │    architect/       30 handouts            projects        │
│          │    progress.db     (bundled JSON/MD)      (bundled TS)     │
│          │                                                            │
│          │  ┌──────────────────────────┐                              │
│          └──► Claude Preview (Dashboard) │                              │
│             │ localhost HTTP server      │                              │
│             └──────────────────────────┘                              │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Core Components

Interactive UI Architecture

Architect Cert doesn't build its own chat UI. Instead, it instructs Claude to use built-in interactive tools:

• AskUserQuestion — Presents clickable buttons for A/B/C/D answers, follow-up actions, and domain selection. Supports single-select (radio buttons), multi-select (checkboxes), and free-text input via "Other".
• TodoWrite — Creates visual progress checklists that update in real time during assessments, exams, and capstone builds.
• Claude Preview — Renders the glassmorphism dashboard HTML on a local HTTP server.

This approach works across Claude Code and Claude Desktop without requiring any custom UI code on the client side.

Anti-Sycophancy Design

This server enforces honest grading at the protocol level — not just in prompts:

1. Deterministic grading — gradeAnswer() is a pure function. No LLM is involved in judging correctness.
2. Tool-level enforcement — The submit_answer tool description instructs Claude to relay results verbatim.
3. No partial credit — Multiple choice, one correct answer. No "you were on the right track."
4. Wrong answer explanations — Every incorrect option has a specific whyWrongMap entry explaining the misconception.
5. System prompt rules — Five anti-sycophancy directives prevent Claude from softening incorrect results.

Question Bank Details

Data Storage

• Progress is stored locally at ~/.connectry-architect/progress.db (SQLite, WAL mode)
• Your user config lives at ~/.connectry-architect/config.json (auto-created on first run)
• No cloud, no accounts, no telemetry — everything stays on your machine

Contributing

We welcome contributions! Here's how to get started:

# Clone the repo
git clone https://github.com/Connectry-io/connectrylab-architect-cert-mcp.git
cd connectrylab-architect-cert-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Generate PDF handouts
npm run generate:pdfs

# Run locally
node dist/index.js

Project Structure

src/
├── index.ts              # MCP server entry point
├── config.ts             # User config management
├── types.ts              # All TypeScript interfaces
├── data/
│   ├── loader.ts         # Lazy-cached data loading
│   ├── curriculum.json   # 30 task statements
│   ├── questions/        # 390 questions (5 domain files)
│   ├── handouts/         # 30 concept handouts (markdown)
│   ├── criteria.ts       # 30 task statement criteria for capstone validation
│   ├── build-steps.ts    # 18 capstone build step definitions
│   └── system-prompt.ts  # Anti-sycophancy rules
├── db/
│   ├── schema.ts         # SQLite schema (9 tables)
│   ├── store.ts          # Database initialization
│   ├── mastery.ts        # Mastery level calculations
│   ├── answers.ts        # Answer recording
│   ├── review-schedule.ts # SM-2 review scheduling
│   ├── capstone.ts       # Capstone build CRUD operations
│   ├── users.ts          # User management
│   └── exam-attempts.ts  # Practice exam tracking
├── engine/
│   ├── grading.ts        # Deterministic grading
│   ├── spaced-repetition.ts  # SM-2 algorithm
│   ├── question-selector.ts  # Priority-based selection
│   ├── exam-builder.ts       # Practice exam generation
│   └── adaptive-path.ts      # Learning path recommendations
├── tools/                # 18 MCP tool handlers
│   ├── index.ts          # Tool registration
│   ├── elicit.ts         # MCP elicitation helper (graceful fallback)
│   ├── start-assessment.ts
│   ├── submit-answer.ts
│   ├── get-practice-question.ts
│   ├── follow-up.ts
│   ├── get-progress.ts
│   ├── get-curriculum.ts
│   ├── get-section-details.ts
│   ├── get-weak-areas.ts
│   ├── get-study-plan.ts
│   ├── start-practice-exam.ts
│   ├── submit-exam-answer.ts
│   ├── get-exam-history.ts
│   ├── scaffold-project.ts
│   ├── start-capstone-build.ts
│   ├── capstone-build-step.ts
│   ├── capstone-build-status.ts
│   ├── reset-progress.ts
│   └── dashboard.ts
├── ui/
│   ├── server.ts         # Dashboard HTTP server
│   ├── dashboard.html    # Glassmorphism dashboard UI
│   ├── meta.ts           # Quiz widget metadata
│   └── loader.ts         # HTML asset loader
├── prompts/              # 8 MCP prompt definitions
└── resources/            # 3 MCP resource types

projects/
├── capstone/             # All 5 domains — multi-agent support system
├── d1-agentic/           # Domain 1 — agentic loop research coordinator
├── d2-tools/             # Domain 2 — MCP server with tool patterns
├── d3-config/            # Domain 3 — Claude Code configuration layout
├── d4-prompts/           # Domain 4 — extraction & prompt engineering
└── d5-context/           # Domain 5 — context management & reliability

scripts/
└── generate-pdfs.ts      # PDF handout generator

License

MIT © Connectry Labs

Credits

• Anthropic — Claude & the Claude Certified Architect certification program
• Model Context Protocol — The protocol that makes this possible
• better-sqlite3 — Fast, synchronous SQLite for Node.js