AI Software Architect MCP Server

Model Context Protocol (MCP) server providing the AI Software Architect framework as programmatic tools for Claude Code, Cursor, and other MCP-compatible AI assistants.

Overview

The MCP server exposes the framework's core capabilities as callable tools, enabling:

• Programmatic Access: Use tools in automated workflows and scripts
• Precise Control: Call specific tools with exact parameters
• Integration: Connect with other MCP tools and services
• Multi-Assistant Support: Works with Claude Code, Cursor, and MCP-compatible assistants

For comparison with other integration methods, see the main README.

When to Choose MCP Server

Choose MCP Server if you:

• Need programmatic access to framework tools (automation, scripts, CI/CD)
• Want precise control with explicit tool parameters
• Use Claude Code or Cursor (MCP-compatible)
• Want advanced project analysis and automatic initial assessment
• Need to integrate with other MCP tools and services
• Prefer structured tool calls over natural language

Choose Claude Skills if you:

• Use Claude Code exclusively
• Want the simplest setup (no dependencies)
• Prefer automatic skill invocation
• Need all advanced features (pragmatic mode, dynamic members)
• Value portability across projects

Choose Traditional Method if you:

• Use multiple AI assistants (Copilot, Codex, etc.)
• Want maximum flexibility and customization
• Need full feature support (recalibration, pragmatic mode)
• Prefer natural language commands
• Want easiest setup (just clone repository)

See Feature Comparison Table for detailed breakdown.

Installation

Option 1: Using Claude Code

First install the package:

npm install -g ai-software-architect

Then add it to Claude Code:

claude mcp add ai-software-architect mcp

Option 2: Install via npm

npm install -g ai-software-architect

Option 3: Install from source

git clone https://github.com/codenamev/ai-software-architect.git
cd ai-software-architect/mcp
npm install

Configuration

Claude Code Configuration

Add this to your Claude Code configuration file (~/.claude/config.json):

For npm global install:

{
  "mcpServers": {
    "ai-software-architect": {
      "command": "mcp",
      "args": [],
      "env": {}
    }
  }
}

For source install:

{
  "mcpServers": {
    "ai-software-architect": {
      "command": "node",
      "args": ["/path/to/ai-software-architect/mcp/index.js"],
      "env": {}
    }
  }
}

Cursor Configuration

Add this to your Cursor settings (settings.json):

For npm global install:

{
  "mcp.servers": {
    "ai-software-architect": {
      "command": "mcp",
      "args": []
    }
  }
}

For source install:

{
  "mcp.servers": {
    "ai-software-architect": {
      "command": "node",
      "args": ["/path/to/ai-software-architect/mcp/index.js"]
    }
  }
}

Quick Start

For Claude Code Users (Easiest)

1. Install with Claude Code:

   npm install -g ai-software-architect
   claude mcp add ai-software-architect mcp

2. Test the installation: Open Claude Code and try:

   Use the setup_architecture tool to set up the AI Software Architect framework in my current project.

3. Start using the framework:

   • Create ADRs: "Use create_adr to document our database choice"
   • Run reviews: "Use start_architecture_review for version 1.0.0"
   • Get specialist input: "Use specialist_review with Security Architect for our API"

For Other AI Assistants

1. Install the MCP server:

   npm install -g ai-software-architect

2. Configure your AI assistant (see configuration sections above)

3. Test and use (same as steps 2-3 above)

Available Tools (8 Core Tools)

The MCP server provides 8 core tools corresponding to the framework's main capabilities:

setup_architecture

Standard Command Equivalent: "Setup ai-software-architect"

Sets up the AI Software Architect framework in your project with full customization and analysis.

What it does:

1. Project Analysis - Detects languages, frameworks, and architectural patterns
2. Framework Installation - Creates complete .architecture/ structure
3. Customization - Tailors team members, principles, and templates to your stack
4. Integration Setup - Configures CLAUDE.md for AI assistant collaboration
5. Initial Analysis - Conducts multi-perspective architectural analysis
6. Documentation - Creates customized templates and principles

Parameters:

• projectPath (string, required): Path to your project root directory

Creates:

• .architecture/ with subdirectories (decisions, reviews, recalibration, comparisons, templates)
• .coding-assistants/ configuration directories
• CLAUDE.md integration (created or enhanced)
• .architecture/reviews/initial-system-analysis.md - Comprehensive initial assessment

MCP-Specific Features:

• Advanced project analysis (language/framework detection)
• Automatic member customization based on tech stack
• Initial architectural analysis from all team members

create_adr

Standard Command Equivalent: "Create ADR for [decision topic]"

Creates a new Architectural Decision Record with automatic numbering.

Parameters:

• title (string, required): Title of the ADR
• context (string, required): Context and background for the decision
• decision (string, required): The architectural decision being made
• consequences (string, required): Consequences of this decision
• projectPath (string, required): Path to your project root directory

Creates:

• .architecture/decisions/adrs/ADR-XXX-title.md with sequential numbering
• Formatted ADR with status, context, decision, and consequences

Example:

{
  title: "Use PostgreSQL for primary database",
  context: "Need reliable ACID-compliant relational database with JSONB support",
  decision: "Adopt PostgreSQL 15+ as primary database",
  consequences: "Better data integrity, requires PostgreSQL expertise on team",
  projectPath: "/path/to/project"
}

start_architecture_review

Standard Command Equivalent: "Start architecture review for [version/feature]"

Creates a comprehensive multi-perspective architecture review template.

Parameters:

• reviewTarget (string, required): Version ('1.0.0') or feature name ('authentication')
• projectPath (string, required): Path to your project root directory

Creates:

• .architecture/reviews/[target].md with sections for each team member
• Review template with individual perspectives and collaborative discussion sections

Note: This tool creates the review template. You'll need to fill in the analysis for each team member.

specialist_review

Standard Command Equivalent: "Ask [Specialist Name] to review [target]"

Creates a focused review template from a specific specialist's perspective.

Parameters:

• specialist (string, required): Specialist name or role (e.g., 'Security Specialist', 'Performance Expert')
• target (string, required): What to review (e.g., 'API authentication', 'database queries')
• projectPath (string, required): Path to your project root directory

Creates:

• .architecture/reviews/specialist-[role]-[target].md with specialist focus template

Behavior:

• If specialist exists in members.yml: Uses their defined perspective
• If specialist doesn't exist: Returns error with list of available specialists

Note: Unlike Claude Skills/Traditional methods, MCP does not auto-create missing specialists.

list_architecture_members

Standard Command Equivalent: "List architecture members"

Lists all architecture team members with their specialties and domains.

Parameters:

• projectPath (string, required): Path to your project root directory

Returns:

• Formatted list of team members from .architecture/members.yml
• Each member's name, title, specialties, domains, and perspective

get_architecture_status

Standard Command Equivalent: "What's our architecture status?"

Gets current state of architecture documentation with counts and metrics.

Parameters:

• projectPath (string, required): Path to your project root directory

Returns:

• ADR count (from .architecture/decisions/adrs/)
• Review count (from .architecture/reviews/)
• Team member count (from .architecture/members.yml)
• Framework setup status
• Available actions summary

configure_pragmatic_mode

Standard Command Equivalent: "Enable pragmatic mode"

Enables and configures Pragmatic Mode (YAGNI Enforcement) to prevent over-engineering.

What it does:

1. Configuration Management - Creates or updates .architecture/config.yml with pragmatic mode settings
2. Mode Activation - Enables/disables the Pragmatic Enforcer in reviews
3. Intensity Control - Sets how aggressively complexity is challenged
4. Deferrals Setup - Creates deferrals tracking file if enabled

Parameters:

• projectPath (string, required): Path to your project root directory
• enabled (boolean, optional): Enable or disable Pragmatic Mode
• intensity (string, optional): Intensity level - "strict", "balanced", or "lenient"

Creates/Updates:

• .architecture/config.yml - Pragmatic mode configuration
• .architecture/deferrals.md - Deferred decisions tracking (if enabled)

Behavior by Intensity:

• Strict: Challenges aggressively, requires strong justification for any complexity
• Balanced: Thoughtful challenges, accepts justified complexity (recommended)
• Lenient: Raises concerns without blocking, suggests alternatives as options

When Pragmatic Mode is Enabled: The Pragmatic Enforcer participates in:

• Architecture reviews (start_architecture_review)
• Specialist reviews (specialist_review)
• ADR creation (create_adr)

The Pragmatic Enforcer will:

• Challenge complexity and abstractions with structured questions
• Score necessity vs. complexity (target ratio <1.5)
• Propose simpler alternatives that meet current requirements
• Track deferred decisions with trigger conditions

Example:

{
  projectPath: "/path/to/project",
  enabled: true,
  intensity: "balanced"
}

Note: This tool provides the same pragmatic mode capabilities available in Claude Skills via the pragmatic-guard skill.

pragmatic_enforcer

Standard Command Equivalent: "Ask Pragmatic Enforcer to review..."

Invokes the Pragmatic Enforcer to analyze proposals, code changes, designs, or architectural decisions for over-engineering and propose simpler alternatives. This tool allows selective pragmatic analysis independent of whether Pragmatic Mode is globally enabled.

What it does:

1. Load Configuration - Reads current pragmatic mode settings (intensity, exemptions, thresholds)
2. Provide Framework - Presents structured analysis framework with key questions
3. Guide Analysis - Guides through necessity assessment, complexity assessment, and ratio calculation
4. Template Output - Provides structured template for consistent pragmatic reviews
5. Context-Aware - Adapts guidance based on review type and configured intensity

Parameters:

• projectPath (string, required): Path to your project root directory
• reviewType (string, required): Type of review - one of:
  • "proposal" - Architectural recommendation or suggestion
  • "code" - Code changes or implementation
  • "design" - Existing design or architecture
  • "decision" - Architectural decision or ADR
  • "implementation" - Feature implementation plan
• target (string, required): The content to review (proposal text, code snippet, design description, etc.)
• context (string, optional): Additional context about current requirements, constraints, or problem being solved
• source (string, optional): Source attribution (architect name, file path, PR number, etc.)

Output Provides:

• Key questions framework (necessity, simplicity, cost, alternatives, best practices)
• Structured analysis template with scoring guidelines
• Complexity-to-necessity ratio calculation guide (target < 1.5)
• Recommendation options (Implement Now / Simplified Version / Defer / Skip)
• Intensity-specific guidance based on configuration
• Exemption checks for security, compliance, accessibility

Review Types Explained:

• proposal: Use for architectural recommendations from other architects or team members
• code: Use for reviewing actual code changes or implementations for over-engineering
• design: Use for analyzing existing architectural designs or patterns
• decision: Use for reviewing architectural decisions before documenting in ADRs
• implementation: Use for analyzing feature implementation plans or technical approaches

Example:

{
  projectPath: "/path/to/project",
  reviewType: "proposal",
  target: "We should implement a microservices architecture with event sourcing, CQRS, and a service mesh for inter-service communication",
  context: "Current system is a monolith with 50k LOC serving 500 users. Performance is acceptable.",
  source: "Lead Architect"
}

Benefits:

• Selective Application: Use pragmatic analysis only when needed, without enabling globally
• Structured Reviews: Consistent framework ensures thorough analysis
• Educational: Helps teams learn YAGNI principles through guided analysis
• Flexible: Works with any review type - proposals, code, designs, decisions, implementations
• Context-Aware: Adapts to project's intensity settings and exemptions

Note: This tool can be used even when Pragmatic Mode is disabled in config.yml. It provides the analysis framework and guidance, allowing you or your AI assistant to perform pragmatic reviews on-demand.

Usage Examples

Once configured, you can use these tools through your AI assistant:

Setup

Use the setup_architecture tool to set up the framework in my current project at /Users/me/projects/myapp

Create an ADR

Use the create_adr tool with:
- title: "Use PostgreSQL for primary database"
- context: "Need ACID compliance and JSONB support for semi-structured data"
- decision: "Adopt PostgreSQL 15+ as our primary database"
- consequences: "Improves data integrity and flexibility, requires PostgreSQL expertise"
- projectPath: /Users/me/projects/myapp

Start a Review

Use the start_architecture_review tool to review version 2.0.0 of our system at /Users/me/projects/myapp

Get Specialist Input

Use the specialist_review tool with:
- specialist: "Security Specialist"
- target: "API authentication system"
- projectPath: /Users/me/projects/myapp

Check Status

Use the get_architecture_status tool to see the current state of architecture documentation at /Users/me/projects/myapp

Enable Pragmatic Mode

Use the configure_pragmatic_mode tool with:
- projectPath: /Users/me/projects/myapp
- enabled: true
- intensity: "balanced"

Use Pragmatic Enforcer

Use the pragmatic_enforcer tool with:
- projectPath: /Users/me/projects/myapp
- reviewType: "code"
- target: "[paste code changes or proposal here]"
- context: "This is for handling user uploads in our MVP"
- source: "PR #123"

Example Workflow

Complete Setup and First Review:

1. Use setup_architecture tool (sets up framework, analyzes project, creates initial review)
2. Review the initial analysis in .architecture/reviews/initial-system-analysis.md
3. Use create_adr to document key existing decisions
4. Use list_architecture_members to see your customized team
5. Use get_architecture_status to verify setup

Pre-Release Review Workflow:

1. Use get_architecture_status to check current state
2. Use start_architecture_review for version 2.0.0
3. Fill in team member perspectives in the created template
4. Use create_adr for any new decisions identified

Feature Parity

The MCP server provides all 8 core framework tools with full feature parity to Claude Skills:

✅ Fully Supported Features

• Setup Architecture: With advanced project analysis and initial system analysis
• Create ADR: With automatic numbering
• Architecture Review: Template creation with all team members
• Specialist Review: Focused review templates
• List Members: Complete team roster
• Get Status: Documentation metrics and health
• Pragmatic Mode: Full config.yml reading, mode configuration, and YAGNI enforcement

⚠️ Partially Supported Features

• Input Validation: Basic filename sanitization (no security-focused validation guidance)
• Review Generation: Creates templates (manual completion required vs. AI-generated)

❌ Not Yet Supported Features

• Dynamic Member Creation: Returns error for missing specialists (vs. auto-creating them)
• Recalibration Process: No tool for architecture recalibration
• Health Analysis: Basic status counts only (no health scoring or recommendations)

MCP-Specific Advantages

• Advanced Project Analysis: Best-in-class language/framework detection
• Initial System Analysis: Automatically created during setup
• Programmatic Access: Can be called from scripts and automation
• Precise Control: Exact parameters for each tool

Comparison with Other Methods

| Feature | MCP Server | Claude Skills | Traditional | |---------|-----------|---------------|-------------| | Core Tools (7) | ✅ All | ✅ All | ✅ All | | Pragmatic Mode | ✅ | ✅ | ✅ | | Dynamic Members | ❌ | ✅ | ✅ | | Recalibration | ❌ | ⚠️ Planned | ✅ | | Initial Analysis | ✅ Best | ❌ | ✅ | | Input Validation | ⚠️ Basic | ✅ Comprehensive | ❌ | | Setup Complexity | ⭐⭐ Medium | ⭐ Simple | ⭐ Simple | | Programmatic Use | ✅ Best | ❌ | ❌ |

For complete feature comparison, see main README and Feature Parity Analysis.

Roadmap

Planned Improvements (Priority: High):

1. Add dynamic member creation (auto-create missing specialists)
2. Add recalibration tool (parse reviews, generate action plans)
3. Enhance input validation (security-focused checks)
4. Add health analysis to status tool (documentation completeness scoring)

Recently Completed:

• ✅ Pragmatic mode support (configure_pragmatic_mode tool) - Full config.yml reading and YAGNI enforcement

Development

To modify or extend the server:

1. Edit index.js to add new tools or modify existing ones
2. Update the tool schemas in the ListToolsRequestSchema handler
3. Add corresponding implementation methods
4. Test with npm start

Contributing: Contributions welcome! Priority areas:

• Pragmatic mode integration
• Dynamic member creation
• Recalibration tool implementation
• Enhanced validation and error handling

Directory Structure

The MCP server creates and manages this structure in your project:

.architecture/
├── decisions/
│   ├── adrs/                # Architectural Decision Records
│   └── principles.md        # Architectural principles document
├── reviews/                 # Architecture review documents
├── recalibration/           # Recalibration plans and tracking
├── comparisons/             # Version-to-version comparisons
├── docs/                    # General architecture documentation
├── templates/               # Templates for various documents
└── members.yml              # Architecture review team members

Alternative Integration Methods

If the MCP server doesn't fit your needs, consider these alternatives:

Claude Skills (Recommended for Claude Code users)

• Installation: Copy skills to ~/.claude/skills/
• Advantages: Simpler setup, no dependencies, automatic invocation, all advanced features
• Documentation: USAGE-WITH-CLAUDE-SKILLS.md

Traditional CLAUDE.md Method (Recommended for multi-assistant)

• Installation: Clone repository and add to CLAUDE.md
• Advantages: Works with all AI assistants, maximum flexibility, complete feature set
• Documentation: USAGE-WITH-CLAUDE.md, USAGE-WITH-CURSOR.md, USAGE-WITH-CODEX.md

Feature Comparison

See main README for detailed feature comparison matrix.

Troubleshooting

MCP server not connecting:

• Verify installation: which mcp or npm list -g ai-software-architect
• Check configuration file syntax (valid JSON)
• Restart your AI assistant after configuration changes
• Check logs: MCP server outputs to stderr

Tools not appearing:

• Ensure MCP server is running: Check assistant's MCP status
• Verify configuration points to correct command/path
• Check Node.js version: Requires Node.js ≥18

Permission errors:

• Ensure project path is accessible
• Check file permissions in .architecture/ directory
• Verify write permissions for creating files

Missing specialists in specialist_review:

• MCP server doesn't auto-create specialists
• Manually add to .architecture/members.yml or
• Use Claude Skills/Traditional method for auto-creation

Support

• Issues: https://github.com/codenamev/ai-software-architect/issues
• Documentation: See repository root for full documentation
• Feature Requests: Open an issue with [Feature Request] prefix

License

MIT