mcp-server-architect

mcp-server-architect

一个充当 AI 软件架构师的 Model Context Protocol 服务。它会分析代码库以生成产品需求文档（PRD），并通过强大的 Agent 架构为复杂编码任务提供推理辅助。

特性

• 多模型架构：使用 OpenAI 的 GPT-4o 执行主要 Agent 任务，并可调用专用工具
• 智能代码库分析：从项目文件中构建全面的代码上下文，以便理解架构
• 基于 Agent 的设计：使用智能 Agent，自主决定每项任务应调用哪些工具
• 基于工具的处理：配备专用于代码读取、网页搜索和定向大模型查询的工具
• 全面的 PRD 生成：创建包含架构洞察的详细产品需求文档
• 高级推理：通过逐步推理帮助开发者解决复杂的编码难题
• Logfire 埋点：内置 Agent 活动监控和调试功能，并提供详细的遥测数据
• MCP 集成：通过 Model Context Protocol 与 Claude Code 无缝连接
• 简单部署：使用 uvx mcp-server-architect 即可快速安装和运行

工作原理

Architect MCP 服务采用复杂的 Agent 架构，模拟人类软件架构师处理复杂设计任务的方式：

1. Agent 循环：收到请求（生成 PRD 或提供推理辅助）后，基于 GPT-4o 的主 Agent 会评估任务并统筹解决过程。

2. 基于工具的架构：Agent 可以调用专用工具：

   • 代码读取器：分析源代码文件，并将其整合为连贯的上下文表示
   • 网页搜索：使用 Exa AI 在线查找相关技术信息
   • 大模型工具：针对特定子任务调用专用语言模型

3. 自主决策：Agent 会确定使用哪些工具、何时使用，以及如何综合工具的输出以生成最终结果。

4. 上下文感知：生成 PRD 时，系统会先深入了解代码库的结构、依赖项和设计模式，再提出建议。

5. 灵活生成响应：所有输出均采用清晰、结构化的 Markdown 格式，便于集成到工作流中。

组件架构

系统采用模块化设计，包含以下关键组件：

┌─────────────────────────────────────────────────────────────────┐
│                       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         │
                     └─────────────┘

组件流程：

1. MCP 服务接口：通过 Model Context Protocol 提供服务的入口

   • 注册工具（generate_prd 和 think）
   • 处理传入请求并将其路由到核心组件

2. Architect 核心：协调各项操作的中央组件

   • 管理 Agent 的创建与执行
   • 实现公开 API（generate_prd、think）
   • 处理错误和日志记录

3. Agent 执行器：使用合适的模型和工具创建并配置 Agent

   • 根据任务选择模型（OpenAI 或 Gemini）
   • 直接初始化 OpenAI 模型
   • 为 Agent 注册工具
   • 提供针对不同任务运行 Agent 的方法

4. 大模型：

   • OpenAI GPT-4o：用于主 Agent 循环（通用任务的默认模型）
   • Gemini 2.5：用于特定任务（PRD 生成和推理）

5. 工具：

   • code_reader：分析代码库中的源代码文件
   • web_search：在网络上搜索相关信息
   • llm：针对特定子任务进行定向大模型调用

6. 依赖项：

   • ArchitectDependencies：向工具提供代码库路径和 API 密钥

数据流：

1. 用户请求 → MCP 服务接口
2. 接口将请求路由至 → Architect Core
3. Core 调用 Agent Executor 上的相应方法
4. Agent Executor 创建并配置 Agent
5. Agent 使用工具执行任务，并按需访问模型
6. 结果沿相同链路返回
7. 格式化后的响应返回给用户

有关最新改进的详细信息，请参阅 CHANGELOG。

前提条件

• Python 3.10 或更高版本
• 用于 GPT-4o 的 OpenAI API 密钥（从 OpenAI Platform 获取）
• 用于 Gemini Pro 的 Google API 密钥（从 Google AI Studio 获取）
• 用于网页搜索功能的 Exa API 密钥（从 Exa AI 获取）
• 用于监控的 Logfire API 密钥（可选，从 Logfire 获取）

系统会优先使用 OpenAI 的模型执行主要 Agent 任务，同时使用 Google Gemini 执行特定工具操作。建议提供这两个 AI 模型的 API 密钥，以获得最佳性能。Logfire API 密钥为可选项，但能为监控和调试 Agent 活动提供有价值的遥测数据。

安装

使用 uv 快速安装（推荐）

安装和使用此服务最简单的方式是使用 uv 包管理器：

# 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

使用 pip 安装

你也可以从 PyPI 安装此软件包：

pip install mcp-server-architect

安装后，可以通过命令运行：

env GEMINI_API_KEY=your_api_key_here mcp-server-architect

API 密钥要求

此服务需要 Gemini API 密钥才能访问 Google Gemini 模型。你可以从 Google AI Studio 获取密钥。可以通过多种方式提供 API 密钥：

1. 使用 env 前缀设置环境变量：env GEMINI_API_KEY=your_key mcp-server-architect
2. 在当前目录的 .env 文件中设置：GEMINI_API_KEY=your_key

注意： 运行前使用 export 设置环境变量可能不可靠。建议使用 env 命令前缀。

开发环境安装

如果你正在开发或修改代码：

1. 克隆仓库：

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

2. 设置开发环境：

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

3. 在开发模式下运行：

   env GEMINI_API_KEY=your_api_key_here python -m mcp_server_architect
   

4. 使用 MCP Inspector 进行开发：

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

运行和使用服务

使用 uvx 直接运行

运行此服务最简单的方式是使用 uvx，并传入 Gemini API 密钥：

# 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

使用 MCP Inspector

如需使用 MCP Inspector 调试或测试此服务：

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

这会打开一个 Inspector 界面（通常位于 http://localhost:8787），你可以在其中交互式测试服务的工具。

添加到 Claude Code

Claude Code 支持在不同作用域中使用 MCP 服务。以下介绍如何使用 Gemini API 密钥添加 Architect 服务：

# 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

重要： 将 your_api_key_here 替换为你实际的 Gemini Google API 密钥，并将 your_exa_key_here 替换为用于网页搜索的 Exa API 密钥

了解 MCP 服务作用域

Claude Code 为 MCP 服务提供三种不同的作用域：

• 本地（默认）：仅在当前项目中对你可用
• 项目：存储在 .mcp.json 文件中，可提交到版本控制并与团队共享
• 用户：在你的所有项目中均可使用

对于团队协作，建议使用项目作用域，这样团队中的每个人都可以访问相同的 MCP 服务，无需单独设置。

安全存储 API 密钥

为确保安全，你可能希望以更安全的方式存储 API 密钥。你可以：

1. 使用 .env 文件（项目作用域）：

   # 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
   

2. 使用操作系统的安全凭据存储：

   • 在 macOS 上，你可以将密钥存储在 Keychain 中，并通过脚本读取
   • 在命令中添加脚本引用

验证安装

安装后，你可以验证服务是否已注册到 Claude：

# List all configured servers
claude mcp list

# Get details for the architect server
claude mcp get architect

运行测试

运行测试套件：

# Using uv
uv run pytest

# Using pip
python -m pytest

测试使用 pytest-recording 记录与 API 的 HTTP 交互。默认情况下，测试会使用之前录制的响应。要更新录制内容：

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

有关测试的更多详情，请参阅 tests/README.md。

MCP 资源和工具

此 MCP 服务提供以下资源和工具：

工具

• Architect::generate_prd：根据代码库分析生成产品需求文档

  • 参数：
    • task_description（必填）：要实现的编程任务或功能的详细说明
    • codebase_path（必填）：要分析的代码库目录的本地文件路径

• Architect::think：为在编码任务中遇到难题的大模型提供推理辅助

  • 参数：
    • request（必填）：编码任务／问题的详细说明及相关代码片段

使用示例

生成 PRD 示例

安装后，你可以在 Claude Code 中通过提示词使用 PRD 工具：

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

技术细节更具体的示例：

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

推理辅助示例

在编码任务中遇到难题时，使用思考工具获取详细推理：

@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

我遗漏了哪些边缘情况？我的实现是否正确？

You can also create custom slash commands for easier access:

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

2. 为 Architect 工具创建命令文件：

   # 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
   

3. 在 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...
   

构建和发布

使用 uv 构建软件包并发布到 PyPI：

1. 构建软件包：

   uv build --no-sources
   

   这会在 dist/ 目录中创建分发包。

2. 发布到 TestPyPI（可选，但建议）：

   # Set your TestPyPI token
   export UV_PUBLISH_TOKEN=your_testpypi_token
   
   # Publish to TestPyPI
   uv publish --publish-url https://test.pypi.org/legacy/
   

3. 发布到 PyPI：

   # Set your PyPI token
   export UV_PUBLISH_TOKEN=your_pypi_token
   
   # Publish to PyPI
   uv publish
   

发布步骤概要

以下是准备并发布新版本的全部步骤概要：

1. 按语义化版本规范（major.minor.patch）更新以下文件中的版本：

   • pyproject.toml
   • mcp_server_architect/version.py
   • mcp_server_architect/__init__.py

2. 确保测试通过：

   uv run pytest
   

3. 构建软件包：

   uv build --no-sources
   

4. 在本地测试软件包：

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

5. 发布到 PyPI：

   uv publish
   

6. 验证安装：

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

许可证

MIT