@agiflowai/architect-mcp

MCP server for design pattern guidance and code review

Use this server to provide file-specific patterns before edits and rule-based review after edits.

Quick Start

1. Install Templates

# Downloads templates with architect.yaml and RULES.yaml
npx @agiflowai/aicode-toolkit init

2. Configure Your AI Agent

Add to your MCP config (.mcp.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "architect-mcp": {
      "command": "npx",
      "args": [
        "-y", "@agiflowai/architect-mcp", "mcp-serve",
        "--admin-enable",
        "--design-pattern-tool", "claude-code",
        "--review-tool", "gemini-cli"
      ]
    }
  }
}

Flags:

• --admin-enable: Enables tools for adding new patterns/rules
• --design-pattern-tool claude-code: Uses Claude to filter relevant patterns
• --review-tool claude-code: Uses Claude for intelligent code review

3. Start Using

Your agent can now call architect tools:

You: "Add error handling to the user service"

Agent:
1. Calls get-file-design-pattern for src/services/UserService.ts
2. Sees: Service Layer Pattern, must use dependency injection, must handle errors
3. Writes code following the patterns
4. Calls review-code-change to validate
5. Fixes any violations

Available Tools

Standard Tools

| Tool | Purpose | When to Use | |------|---------|-------------| | get-file-design-pattern | Get patterns and rules for a file | Before editing any file | | review-code-change | Validate code against rules | After editing a file |

Admin Tools (with --admin-enable)

| Tool | Purpose | When to Use | |------|---------|-------------| | add-design-pattern | Add pattern to architect.yaml | Documenting new patterns | | add-rule | Add rule to RULES.yaml | Adding coding standards | | validate-architect | Validate architect.yaml syntax and schema | Debugging configuration issues |

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     Your AI Agent                           │
└─────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┴────────────────────┐
         ▼                                         ▼
  ┌──────────────────┐                    ┌──────────────────┐
  │ Before Editing   │                    │ After Editing    │
  │                  │                    │                  │
  │ get-file-design- │                    │ review-code-     │
  │ pattern          │                    │ change           │
  └──────────────────┘                    └──────────────────┘
         │                                         │
         ▼                                         ▼
  ┌──────────────────┐                    ┌──────────────────┐
  │ architect.yaml   │                    │ RULES.yaml       │
  │                  │                    │                  │
  │ • Design patterns│                    │ • must_do        │
  │ • File roles     │                    │ • should_do      │
  │ • Examples       │                    │ • must_not_do    │
  └──────────────────┘                    └──────────────────┘

architect.yaml - Design Patterns

Defines what each file type should do:

features:
  - name: Service Layer
    design_pattern: Service classes with dependency injection
    includes:
      - src/services/**/*.ts
    description: |
      Services contain business logic and are injected into tools.
      They should be stateless and delegate to repositories.

Pattern Inheritance & Override

architect-mcp supports a three-level configuration hierarchy:

┌─────────────────────────────────────────────────────────────┐
│  1. Project architect.yaml (highest priority)               │
│     packages/my-app/.architect.yaml                         │
│     → Project-specific patterns that override template      │
├─────────────────────────────────────────────────────────────┤
│  2. Template architect.yaml                                 │
│     templates/nextjs-15/architect.yaml                      │
│     → Framework-specific patterns                           │
├─────────────────────────────────────────────────────────────┤
│  3. Global architect.yaml (lowest priority)                 │
│     templates/architect.yaml                                │
│     → Shared patterns across all templates                  │
└─────────────────────────────────────────────────────────────┘

Example: override a template pattern for one project

Template pattern (templates/typescript-mcp-package/architect.yaml):

features:
  - name: tool-pattern
    design_pattern: Standard MCP Tool
    includes:
      - src/tools/**/*.ts

Project override (packages/my-custom-mcp/.architect.yaml):

features:
  - name: tool-pattern
    design_pattern: Custom Tool with Extended Validation
    includes:
      - src/tools/**/*.ts
    description: |
      This project requires additional input validation...

For files in packages/my-custom-mcp/src/tools/, the project-level pattern takes precedence.

RULES.yaml - Coding Standards

Defines how code should be written:

rules:
  - pattern: src/services/**/*.ts
    description: Service implementation standards
    must_do:
      - rule: Use dependency injection
        codeExample: |
          // ✓ GOOD
          constructor(private repo: UserRepository) {}
    must_not_do:
      - rule: Never use static-only utility classes
        codeExample: |
          // ✗ BAD
          class Utils { static doStuff() {} }

LLM Modes

architect-mcp works in two modes:

Mode 1: Agent-Driven (LLM flags disabled)

npx @agiflowai/architect-mcp mcp-serve

• Returns all applicable patterns and rules
• No external LLM calls

Mode 2: LLM-Enhanced (LLM flags enabled)

npx @agiflowai/architect-mcp mcp-serve \
  --design-pattern-tool claude-code \
  --review-tool claude-code

• Filters patterns by file content
• Reviews code and returns specific violations

Mode 3: Fallback Tool (single flag for both)

Use --fallback-tool when you want both tools to use the same LLM without specifying each separately. A specific --design-pattern-tool or --review-tool always takes precedence over the fallback.

# Both design-pattern and review use claude-code
npx @agiflowai/architect-mcp mcp-serve \
  --fallback-tool claude-code

# Override review specifically — design-pattern still uses the fallback
npx @agiflowai/architect-mcp mcp-serve \
  --fallback-tool claude-code \
  --review-tool gemini-cli

# With a custom model config applied to both tools
npx @agiflowai/architect-mcp mcp-serve \
  --fallback-tool claude-code \
  --fallback-tool-config '{"model":"claude-sonnet-4-6"}'

Precedence: --design-pattern-tool > --fallback-tool (same for --review-tool).

For .toolkit/settings.yaml or .toolkit/settings.local.yaml, you can also define an ordered fallback chain:

architect-mcp:
  mcp-serve:
    fallbacks:
      - tool: gemini-cli
        config:
          model: gemini-2.0-flash
      - tool: codex
        config:
          model: gpt-5.2-mini

The first valid entry is used when fallbackTool is not set.

CLI Commands

architect-mcp also works as a standalone CLI:

# Get design patterns for a file
npx @agiflowai/architect-mcp get-file-design-pattern src/services/UserService.ts

# Get design patterns with LLM filtering
npx @agiflowai/architect-mcp get-file-design-pattern src/services/UserService.ts \
  --llm-tool codex \
  --tool-config '{"model":"gpt-5.2"}'

# Review code against rules
npx @agiflowai/architect-mcp review-code-change src/services/UserService.ts

# Review code with LLM-powered analysis
npx @agiflowai/architect-mcp review-code-change src/services/UserService.ts \
  --llm-tool codex \
  --tool-config '{"model":"gpt-5.2"}'

# Add a design pattern
npx @agiflowai/architect-mcp add-pattern "Service Layer" "DI pattern" \
  "Services use dependency injection" \
  --template-name typescript-mcp-package \
  --includes "src/services/**/*.ts"

# Add a coding rule
npx @agiflowai/architect-mcp add-rule error-handling "Error handling standards" \
  --template-name typescript-mcp-package \
  --must-do "Use try-catch blocks" \
  --must-not-do "Never use empty catch blocks"

# Validate architect.yaml file
npx @agiflowai/architect-mcp validate-architect templates/nextjs-15/architect.yaml

# Validate by template name
npx @agiflowai/architect-mcp validate-architect -t typescript-mcp-package

# Verbose output showing all features
npx @agiflowai/architect-mcp validate-architect -t nextjs-15 -v

Hooks Integration (Experimental)

Hooks let architect-mcp provide guidance automatically when files are edited.

Claude Code setup (.claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx @agiflowai/architect-mcp hook --type claude-code.preToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx @agiflowai/architect-mcp hook --type claude-code.postToolUse"
          }
        ]
      }
    ]
  }
}

What happens:

• PreToolUse: Before editing, shows relevant patterns from architect.yaml
• PostToolUse: After editing, reviews code against RULES.yaml

See Hooks Documentation for details.

Server Options

# stdio transport (default)
npx @agiflowai/architect-mcp mcp-serve

# HTTP transport
npx @agiflowai/architect-mcp mcp-serve --type http --port 3000

# SSE transport
npx @agiflowai/architect-mcp mcp-serve --type sse --port 3000

# All features enabled
npx @agiflowai/architect-mcp mcp-serve \
  --admin-enable \
  --design-pattern-tool claude-code \
  --review-tool claude-code

# With custom tool configuration (e.g., specific model)
npx @agiflowai/architect-mcp mcp-serve \
  --design-pattern-tool codex \
  --design-pattern-tool-config '{"model":"gpt-5.2"}' \
  --review-tool codex \
  --review-tool-config '{"model":"gpt-5.2"}'

# Fallback tool — both tools use claude-code
npx @agiflowai/architect-mcp mcp-serve \
  --fallback-tool claude-code

# Fallback with config, override one tool specifically
npx @agiflowai/architect-mcp mcp-serve \
  --fallback-tool claude-code \
  --fallback-tool-config '{"model":"claude-sonnet-4-6"}' \
  --review-tool gemini-cli

For settings-file based configuration, fallbackTool / fallbackToolConfig still work, and fallbacks adds ordered multi-fallback support:

architect-mcp:
  mcp-serve:
    fallbacks:
      - tool: gemini-cli
        config:
          model: gemini-2.0-flash
      - tool: codex
        config:
          model: gpt-5.2-mini

| Option | Description | Default | |--------|-------------|---------| | -t, --type | Transport: stdio, http, sse | stdio | | -p, --port | Port for HTTP/SSE | 3000 | | --admin-enable | Enable pattern/rule creation tools | false | | --design-pattern-tool | LLM for pattern filtering (claude-code, gemini-cli, codex) | disabled | | --design-pattern-tool-config | JSON config for design pattern LLM tool (e.g., {"model":"gpt-5.2"}) | {} | | --review-tool | LLM for code review (claude-code, gemini-cli, codex) | disabled | | --review-tool-config | JSON config for review LLM tool (e.g., {"model":"gpt-5.2"}) | {} | | --fallback-tool | LLM used for both tools when the specific flag is not set | disabled | | --fallback-tool-config | JSON config applied to the CLI fallback tool; settings files may also use ordered fallbacks entries | {} |

Documentation

| Document | Description | |----------|-------------| | Design Pattern Overview | Philosophy and architecture of the pattern system | | Rules Overview | How RULES.yaml works, inheritance, review modes | | Hooks Integration | Setting up automatic hooks with AI agents |

License

AGPL-3.0