MCP Server Architect

mcp服务器架构师

充当AI软件架构师的模型上下文协议服务器。它分析代码库以生成产品需求文档（PRD），并使用强大的基于代理的架构为复杂的编码任务提供推理帮助。

特性

• 多模型架构：使用OpenAI的GPT-4o执行主代理任务，并可访问专用工具
• 智能代码库分析：从项目文件构建全面的代码上下文，以了解架构
• 基于Agent的设计：使用智能代理，自主决定为每项任务使用哪些工具
• 基于工具的处理：配备用于代码阅读、网络搜索和有针对性的LLM查询的专用工具
• 全面PRD发电：创建具有架构见解的详细产品需求文档
• 高级推理：通过逐步推理帮助开发人员解决复杂的编码挑战
• Logfire仪表：通过详细的遥测技术对代理活动进行内置监控和调试
• MCP集成：通过模型上下文协议与Claude代码无缝连接
• 简单部署：快速安装和运行 uvx mcp-server-architect

运作原理

Architect MCP Server实现了一个复杂的基于代理的架构，该架构模仿了人类软件架构师处理复杂设计任务的方式：

1. 代理循环：当收到请求（PRD生成或推理辅助）时，基于GPT-4o的主代理会评估任务并协调解决方案过程。

1. 基于工具的体系结构：代理人可以使用专门的工具：

- 代码阅读器：分析源代码文件并将其组合成连贯的上下文表示 - 网页搜索：使用Exa AI在线查找相关技术信息 - LLM工具：针对特定子任务对专门的语言模型进行有针对性的调用

1. 自主决策：代理决定使用哪些工具，何时使用它们，以及如何综合它们的输出以产生最终结果。

1. 情境意识：对于PRD生成，系统在提出建议之前，会深入了解您的代码库结构、依赖关系和设计模式。

1. 灵活的响应生成：所有输出都采用清晰、结构化的标记格式，便于集成到您的工作流程中。

组件体系结构

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

┌─────────────────────────────────────────────────────────────────┐
│                       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服务器接口：通过模型上下文协议公开服务的入口点

- 注册工具(generate_prd 和 think) - 处理传入请求并将其路由到核心

1. 建筑师核心：协调行动的核心组成部分

- 管理代理创建和执行 - 实现公共API（generate_prd，think） - 处理错误和日志记录

1. 代理执行人：使用适当的模型和工具创建和配置代理

- 根据任务选择模型（OpenAI或Gemini） - 对OpenAI模型使用直接模型初始化 - 向代理注册工具 - 提供为不同任务运行代理的方法

1. LLM模型:

- OpenAI GPT-4o用于主代理循环（默认用于一般任务） - Gemini 2.5用于特定任务（PRD生成和思考）

1. 工具:

- code_reader：分析代码库中的源代码文件 - web_search：在网上搜索相关信息 - llm：针对特定子任务进行有针对性的LLM调用

1. 依赖项:

- ArchitectDependencies：为工具提供代码库路径和API键

数据流：

1. 用户请求→ MCP服务器接口
2. 接口路由请求→ 建筑师核心
3. 核心在代理执行器上调用适当的方法
4. 代理执行器创建并配置代理
5. 代理使用工具执行，根据需要访问模型
6. 结果通过同一链返回
7. 已格式化的响应返回给用户

请参阅 更新日志 了解最新改进的详细信息。

先决条件

• Python 3.10或更高版本
• GPT-4o的OpenAI API密钥（从 OpenAI平台)
• Gemini Pro的Google API密钥（从 谷歌人工智能工作室)
• 用于web搜索功能的Exa API密钥（从 Exa AI)
• 用于监控的Logfire API密钥（可选，从 日志)

该系统将优先使用OpenAI的模型进行主要代理任务，同时使用Google Gemini进行特定的工具操作。推荐使用两个AI模型API键以获得最佳性能。Logfire API密钥是可选的，但为监视和调试代理活动提供了有价值的遥测。

安装

紫外线快速安装（推荐）

安装和使用服务器的最简单方法是 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

管道安装

您还可以从PyPI安装该软件包：

pip install mcp-server-architect

安装后，您可以将其作为命令运行：

env GEMINI_API_KEY=your_api_key_here mcp-server-architect

API关键要求

此服务器需要Gemini API密钥才能访问Google Gemini模型。您可以从以下网址获得一个 谷歌人工智能工作室API密钥可以通过多种方式提供：

1. 作为带有env前缀的环境变量： env GEMINI_API_KEY=your_key mcp-server-architect
2. 通过当前目录中的.env文件 GEMINI_API_KEY=your_key

注： 使用以下参数设置环境变量 export 运行前可能无法可靠工作。这 env 建议使用命令前缀。

开发安装

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

1. 克隆存储库：

   git clone 
   cd 

1. 设置开发环境：

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

1. 在开发模式下运行：

   env GEMINI_API_KEY=your_api_key_here python -m mcp_server_architect

1. 使用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检查器一起使用

要使用MCP检查器调试或测试服务器，请执行以下操作：

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

这将打开一个检查器界面（通常在http://localhost:8787)这允许您以交互方式测试服务器的工具。

添加到克劳德代码

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服务器提供了三种不同的作用域：

• 本地 （默认）：仅在当前项目中对您可用
• 项目：存储在a中 .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

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

- 在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记录来记录与API的HTTP交互。默认情况下，测试将使用以前记录的响应。要更新录制内容，请执行以下操作：

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

有关测试的更多详细信息，请参阅 测试/README.md.

MCP资源和工具

此MCP服务器公开以下资源和工具：

工具

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

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

• Architect::think：为编码任务上卡住的LLM提供推理帮助

- 参数： - 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:

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:

   mkdir -p .claude/commands

1. 为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

1. 在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/ 目录。

1. 发布到TestPyPI （可选但推荐）：

   # Set your TestPyPI token
   export UV_PUBLISH_TOKEN=your_testpypi_token

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

1. 发布到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

1. 确保测试通过：

   uv run pytest

1. 构建包：

   uv build --no-sources

1. 在本地测试包：

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

1. 发布到PyPI：

   uv publish

1. 验证安装：

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

许可证

麻省理工学院