@agiflowai/architect-mcp

MCP server for design pattern guidance and code review

Help AI coding agents write code that follows your team's architectural patterns and coding standards. architect-mcp provides context-aware guidance before editing files and validates code against rules after changes.

Why Use This?

When AI agents edit code, they don't know your team's conventions:

• Which patterns apply to service files vs. tool files?
• What are the must-do and must-not-do rules?
• How should errors be handled in this codebase?

architect-mcp solves this by:

1. Providing patterns before editing - Agent sees relevant design patterns for the file
2. Validating code after editing - Agent gets feedback on rule violations
3. Enforcing standards automatically - Rules from RULES.yaml are checked programmatically

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 AI agent now has access to architecture 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 |

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.

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
• AI agent does its own analysis
• Fast, no external API 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 based on file content
• Reviews code and returns specific violations
• Precise, context-aware feedback

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

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

# 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"

Hooks Integration (Experimental)

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

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx @agiflowai/architect-mcp hook --type claude-code.preToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|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

| 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 | | --review-tool | LLM for code review (claude-code, gemini-cli, codex) | disabled |

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