mcp-server-architect

A Model Context Protocol server that acts as an AI Software Architect. It analyzes codebases to generate Product Requirements Documents (PRDs) and provides reasoning assistance for complex coding tasks using a powerful agent-based architecture.

Features

Multi-Model Architecture: Uses OpenAI's GPT-4o for primary agent tasks with access to specialized tools
Intelligent Codebase Analysis: Builds comprehensive code context from project files for architectural understanding
Agent-Based Design: Uses a smart agent that autonomously decides which tools to employ for each task
Tool-Based Processing: Equipped with specialized tools for code reading, web searches, and targeted LLM queries
Comprehensive PRD Generation: Creates detailed product requirement documents with architectural insights
Advanced Reasoning: Helps developers solve complex coding challenges with step-by-step reasoning
Logfire Instrumentation: Built-in monitoring and debugging of agent activity with detailed telemetry
MCP Integration: Seamlessly connects with Claude Code via the Model Context Protocol
Simple Deployment: Quick to install and run with uvx mcp-server-architect

How It Works

The Architect MCP Server implements a sophisticated agent-based architecture that mimics how a human software architect would approach complex design tasks:

Agent Loop: When a request is received (either for PRD generation or reasoning assistance), a primary GPT-4o based agent evaluates the task and orchestrates the solution process.
Tool-Based Architecture: The agent has access to specialized tools:
- Code Reader: Analyzes source code files and combines them into a coherent context representation
- Web Search: Uses Exa AI to find relevant technical information online
- LLM Tool: Makes targeted calls to specialized language models for specific sub-tasks
Autonomous Decision Making: The agent determines which tools to use, when to use them, and how to synthesize their outputs to produce the final result.
Contextual Awareness: For PRD generation, the system builds a deep understanding of your codebase structure, dependencies, and design patterns before making recommendations.
Flexible Response Generation: All outputs are formatted in clear, structured markdown for easy integration into your workflow.

Component Architecture

The system follows a modular design with the following key components:

┌─────────────────────────────────────────────────────────────────┐
│                       MCP Server Interface                      │
│                    (mcp_server_architect/__main__.py)           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Architect Core                            │
│                    (mcp_server_architect/core.py)               │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Agent Executor                            │
│                (mcp_server_architect/agents/executor.py)        │
└───┬─────────────────────┬────────────────────────┬──────────────┘
    │                     │                        │
    ▼                     ▼                        ▼
┌───────────────┐    ┌─────────────┐         ┌─────────────┐
│ LLM Models    │    │    Tools    │         │ Dependencies│
│ OpenAI GPT-4o │    │ code_reader │         │ArchitectDeps│
│ Gemini 2.5    │    │ web_search  │         └─────────────┘
└───────────────┘    │ llm         │
                     └─────────────┘

Component Flow:

MCP Server Interface: Entry point that exposes the services via Model Context Protocol
- Registers tools (generate_prd and think)
- Handles incoming requests and routes them to the core
Architect Core: Central component that coordinates operations
- Manages agent creation and execution
- Implements the public API (generate_prd, think)
- Handles errors and logging
Agent Executor: Creates and configures agents with appropriate models and tools
- Selects models based on task (OpenAI or Gemini)
- Uses direct model initialization for OpenAI models
- Registers tools with the agent
- Provides methods for running the agent for different tasks
LLM Models:
- OpenAI GPT-4o for main agent loop (default for general tasks)
- Gemini 2.5 for specific tasks (PRD generation and thinking)
Tools:
- code_reader: Analyzes source code files from a codebase
- web_search: Searches the web for relevant information
- llm: Makes targeted LLM calls for specific sub-tasks
Dependencies:
- ArchitectDependencies: Provides codebase path and API keys to tools

Data Flow:

User request → MCP Server Interface
Interface routes request → Architect Core
Core calls appropriate method on Agent Executor
Agent Executor creates and configures agent
Agent executes with tools, accessing models as needed
Results flow back through the same chain
Formatted response returned to user

See the CHANGELOG for details on the latest improvements.

Prerequisites

Python 3.10 or higher
OpenAI API key for GPT-4o (get one from OpenAI Platform)
Google API key for Gemini Pro (get one from Google AI Studio)
Exa API key for web search capabilities (get one from Exa AI)
Logfire API key for monitoring (optional, get one from Logfire)

The system will prioritize using OpenAI's models for the main agent tasks, while using Google Gemini for specific tool operations. Both AI model API keys are recommended for optimal performance. The Logfire API key is optional but provides valuable telemetry for monitoring and debugging agent activity.

Installation

Quick Installation with uv (Recommended)

The simplest way to install and use the server is with uv package manager:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# No installation needed - run directly with uvx (one-liner)
env GEMINI_API_KEY=your_api_key_here uvx mcp-server-architect

Installation with pip

You can also install the package from PyPI:

pip install mcp-server-architect

After installation, you can run it as a command:

env GEMINI_API_KEY=your_api_key_here mcp-server-architect

API Key Requirements

This server requires a Gemini API key for accessing the Google Gemini model. You can obtain one from Google AI Studio. The API key can be provided in multiple ways:

As an environment variable with the env prefix: env GEMINI_API_KEY=your_key mcp-server-architect
Through a .env file in the current directory with GEMINI_API_KEY=your_key

Note: Setting the environment variable with export before running may not work reliably. The env command prefix is the recommended approach.

Development Installation

If you're developing or modifying the code:

Clone the Repository:

git clone <your-repo-url>
cd <your-repo-directory>

Setup Development Environment:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Run in Development Mode:

env GEMINI_API_KEY=your_api_key_here python -m mcp_server_architect

Run with MCP Inspector for Development:

env GEMINI_API_KEY=your_api_key_here npx @modelcontextprotocol/inspector python -m mcp dev --with-editable . mcp_server_architect/__main__.py

Running and Using the Server

Direct Execution with uvx

The easiest way to run the server is with uvx, passing your Gemini API key:

# As a one-liner (recommended)
env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# Alternatively, use a .env file in the current directory
# with GEMINI_API_KEY and EXA_API_KEY environment variables

Using with MCP Inspector

To debug or test the server with the MCP Inspector:

env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here npx @modelcontextprotocol/inspector uvx mcp-server-architect

This will open an inspector interface (usually at http://localhost:8787) that allows you to test the server's tools interactively.

Adding to Claude Code

Claude Code supports MCP servers in various scopes. Here's how to add the Architect server with your Gemini API key:

# Local scope (only available to you in the current project)
claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# Project scope (shared with everyone via .mcp.json)
claude mcp add architect -s project -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# User scope (available to you across all projects)
claude mcp add architect -s user -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

Important: Replace your_api_key_here with your actual Google API key for Gemini and your_exa_key_here with your Exa API key for web search

Understanding MCP Server Scopes

Claude Code provides three different scopes for MCP servers:

Local (default): Available only to you in the current project
Project: Stored in a .mcp.json file that can be committed to version control and shared with your team
User: Available to you across all your projects

For team collaboration, the Project scope is recommended as it allows everyone on the team to access the same MCP servers without individual setup.

Storing API Keys Securely

For security, you may want to store your API key in a more secure way. You can:

Use a .env file (in project scope):

# Create a .env file (don't commit this!)
echo "GEMINI_API_KEY=your_api_key_here" > .env
echo "EXA_API_KEY=your_exa_key_here" >> .env

# Add to Claude Code with the env prefix
claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

Use your OS's secure credential storage:
- On macOS, you can store it in Keychain and retrieve it with a script
- Add the script reference in your command

Verifying Installation

After installation, you can verify the server is registered with Claude:

# List all configured servers
claude mcp list

# Get details for the architect server
claude mcp get architect

Running Tests

To run the test suite:

# Using uv
uv run pytest

# Using pip
python -m pytest

The tests use pytest-recording to record HTTP interactions with APIs. By default, tests will use previously recorded responses. To update the recordings:

# Force rewrite of API recordings
pytest tests/ --record-mode=all

For more details about testing, see tests/README.md.

MCP Resources and Tools

This MCP server exposes the following resources and tools:

Tools

Architect::generate_prd: Generates a Product Requirements Document based on codebase analysis
- Parameters:
  - task_description (required): Detailed description of the programming task or feature to implement
  - codebase_path (required): Local file path to the codebase directory to analyze
Architect::think: Provides reasoning assistance for a stuck LLM on a coding task
- Parameters:
  - request (required): Detailed description of the coding task/issue and relevant code snippets

Usage Examples

Generate PRD Example

After installation, you can use the PRD tool in Claude Code by prompting:

@Architect please generate a PRD for creating a new feature.
Task Description: "Create a user profile page that displays user information and activity history, with edit functionality."
Codebase Path: "/path/to/your/local/project"

Example with more specific technical details:

@Architect generate a PRD for a new feature.
Task Description: "Implement JWT authentication in a Flask application, with login, registration, and token refresh endpoints. Add middleware for protected routes and handle token expiration gracefully."
Codebase Path: "/Users/username/projects/my-flask-app"

Reasoning Assistance Example

When you're stuck on a coding task, use the thinking tool to get detailed reasoning:

@Architect I need help thinking through a coding problem.
I'm trying to implement a function that reverses a linked list but I'm stuck on handling the edge cases.
Here's my code:
```python
def reverse_linked_list(head):
    if not head or not head.next:
        return head
    prev = None
    current = head
    while current:
        next_node = current.next
        current.next = prev
        prev = current
        current = next_node
    return prev

What edge cases am I missing? Is my implementation correct?


You can also create custom slash commands for easier access:

1. Create a commands directory in your project:
   ```bash
   mkdir -p .claude/commands

Create command files for Architect tools:

# PRD generation command
echo "Generate a PRD for the following task:\n\nTask Description: \"$ARGUMENTS\"\nCodebase Path: \"`pwd`\"" > .claude/commands/prd.md

# Thinking assistance command
echo "I need help thinking through this coding problem:\n\n$ARGUMENTS" > .claude/commands/think.md

Use them in Claude Code:

# For PRD generation
/project:prd Implement a new user authentication system

# For reasoning assistance
/project:think I'm trying to optimize this recursive function but hitting a stack overflow...

Building and Publishing

To build and publish the package to PyPI using uv:

Build the package:
```
uv build --no-sources
```
This creates distribution packages in the dist/ directory.

Publish to TestPyPI (optional but recommended):

# Set your TestPyPI token
export UV_PUBLISH_TOKEN=your_testpypi_token

# Publish to TestPyPI
uv publish --publish-url https://test.pypi.org/legacy/

Publish to PyPI:

# Set your PyPI token
export UV_PUBLISH_TOKEN=your_pypi_token

# Publish to PyPI
uv publish

Release Steps Summary

Here's a summary of all steps to prepare and release a new version:

Update version following semantic versioning (major.minor.patch) in:
- pyproject.toml
- mcp_server_architect/version.py
- mcp_server_architect/__init__.py
Make sure tests pass:
```
uv run pytest
```
Build the package:
```
uv build --no-sources
```

Test the package locally:

# Create a temporary directory
mkdir -p /tmp/test-architect
cd /tmp/test-architect

# Test installing from the built package
uv run --with-pin /path/to/your/dist/mcp_server_architect-*.whl --no-project -- python -c "from mcp_server_architect import __version__; print(__version__)"

Publish to PyPI:
```
uv publish
```

Verify the installation:

# In a fresh environment
uvx mcp-server-architect --version

License

MIT