MCP服务器架构师

Name: MCP服务器架构师
Author: funtusov

作者：funtusov2 星标更新：2025-04-01

安装使用来源：spider==github.com

项目介绍

mcp-server-architect

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

特性

多模型架构：使用OpenAI的GPT-4o作为主要代理任务，并访问专用工具
智能代码库分析：从项目文件中构建全面的代码上下文，以便于架构理解
基于代理的设计：使用智能代理自主决定在每个任务中使用哪些工具
基于工具的处理：配备有专门用于代码阅读、网络搜索和特定语言模型查询的工具
详尽的PRD生成：创建包含架构见解的详细产品需求文档
高级推理：帮助开发者解决复杂的编码挑战，提供逐步推理
Logfire监控：内置代理活动的监控和调试，带有详细的遥测数据
MCP集成：通过模型上下文协议无缝连接到Claude Code
简单部署：快速安装和运行，只需执行uvx mcp-server-architect

工作原理

架构师MCP服务器实现了一种模仿人类软件架构师处理复杂设计任务的复杂基于代理的架构：

代理循环：当收到请求（无论是生成PRD还是推理辅助）时，主要基于GPT-4o的代理评估任务并协调解决方案过程。
基于工具的架构：代理可以访问专用工具：
- 代码阅读器：分析源代码文件并将其组合成连贯的上下文表示
- 网络搜索：使用Exa AI在线查找相关技术信息
- LLM工具：针对特定子任务向专业语言模型发出有针对性的调用
自主决策：代理确定何时使用哪些工具以及如何合成它们的输出以产生最终结果。
上下文感知：对于PRD生成，系统会先对您的代码库结构、依赖关系和设计模式进行深入理解，然后再提供建议。
灵活响应生成：所有输出都以清晰、结构化的Markdown格式呈现，便于集成到您的工作流程中。

组件架构

该系统遵循模块化设计，具有以下关键组件：

┌─────────────────────────────────────────────────────────────────┐
│                       MCP服务器接口                             │
│                    (mcp_server_architect/__main__.py)           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       架构核心                                 │
│                    (mcp_server_architect/core.py)               │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       代理执行器                               │
│                (mcp_server_architect/agents/executor.py)        │
└───┬─────────────────────┬────────────────────────┬──────────────┘
    │                     │                        │
    ▼                     ▼                        ▼
┌───────────────┐    ┌─────────────┐         ┌─────────────┐
│ LLM模型       │    │ 工具        │         │ 依赖项      │
│ OpenAI GPT-4o │    │ code_reader │         │ ArchitectDeps│
│ Gemini 2.5    │    │ web_search  │         └─────────────┘
└───────────────┘    │ llm         │
                     └─────────────┘

组件流程：

MCP服务器接口：暴露服务的入口点，通过模型上下文协议
- 注册工具（generate_prd 和 think）
- 处理传入请求并将它们路由到核心
架构核心：协调操作的中心组件
- 管理代理的创建和执行
- 实现公共API（generate_prd, think）
- 处理错误和日志记录
代理执行器：创建和配置具有适当模型和工具的代理
- 根据任务选择模型（OpenAI或Gemini）
- 使用直接模型初始化OpenAI模型
- 将工具注册到代理
- 提供方法以运行不同任务的代理
LLM模型：
- OpenAI GPT-4o用于主代理循环（默认用于一般任务）
- Gemini 2.5用于特定任务（PRD生成和思考）
工具：
- code_reader：分析代码库中的源代码文件
- web_search：在网络上搜索相关信息
- llm：针对特定子任务发出有针对性的LLM调用
依赖项：
- ArchitectDependencies：提供代码库路径和API密钥给工具

数据流：

用户请求 → MCP服务器接口
接口路由请求 → 架构核心
核心调用代理执行器上的适当方法
代理执行器创建和配置代理
代理使用工具执行，根据需要访问模型
结果通过相同的链返回
格式化响应返回给用户

查看CHANGELOG了解最新改进的详细信息。

预备条件

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

该系统将优先使用OpenAI的模型进行主要代理任务，而使用Google Gemini进行特定工具操作。建议同时拥有两个AI模型的API密钥以获得最佳性能。Logfire API密钥是可选的，但提供了宝贵的遥测数据，用于监控和调试代理活动。

安装

快速安装与uv（推荐）

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

# 如果尚未安装，请安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 不需要安装 - 直接使用uvx运行（一行命令）
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密钥可以通过多种方式提供：

作为带有env前缀的环境变量：env GEMINI_API_KEY=your_key mcp-server-architect
当前目录中的.env文件，包含GEMINI_API_KEY=your_key

注意：在运行之前设置环境变量可能不可靠。推荐使用env命令前缀。

开发安装

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

克隆仓库：

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

设置开发环境：

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

开发模式运行：

env GEMINI_API_KEY=your_api_key_here python -m mcp_server_architect

使用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密钥：

# 作为一行命令（推荐）
env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# 或者，在当前目录中使用带有GEMINI_API_KEY和EXA_API_KEY环境变量的.env文件

使用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

这将打开一个检查器界面（通常位于http://localhost:8787），允许您交互地测试服务器的工具。

添加到Claude Code

Claude Code支持各种范围内的MCP服务器。这是如何添加架构师服务器及其Gemini API密钥：

# 本地范围（仅在当前项目中可用给您）
claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

# 项目范围（通过.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

# 用户范围（跨所有项目可用给您）
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替换为您实际的Google API密钥用于Gemini，将your_exa_key_here替换为您实际的Exa API密钥用于网络搜索

理解MCP服务器范围

Claude Code提供了三种不同的MCP服务器范围：

本地（默认）：仅在当前项目中可用给您
项目：存储在.mcp.json文件中，可以提交到版本控制并与团队共享
用户：跨所有项目可用给您

为了团队协作，推荐使用项目范围，因为它允许团队中的每个人访问相同的MCP服务器，无需单独设置。

安全存储API密钥

为了安全起见，您可能希望更安全地存储API密钥。您可以：

使用.env文件（在项目范围内）：

# 创建一个.env文件（不要提交这个！）
echo "GEMINI_API_KEY=your_api_key_here" > .env
echo "EXA_API_KEY=your_exa_key_here" >> .env

# 使用env前缀添加到Claude Code
claude mcp add architect -- env GEMINI_API_KEY=your_api_key_here EXA_API_KEY=your_exa_key_here uvx mcp-server-architect

使用您的操作系统安全凭证存储：
- 在macOS上，您可以将其存储在Keychain中，并通过脚本检索
- 在命令中添加脚本引用

验证安装

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

# 列出所有配置的服务器
claude mcp list

# 获取架构师服务器的详细信息
claude mcp get architect

运行测试

要运行测试套件：

# 使用uv
uv run pytest

# 使用pip
python -m pytest

测试使用pytest-recording来录制与API的HTTP交互。默认情况下，测试将使用先前录制的响应。要更新录制：

# 强制重写API录制
pytest tests/ --record-mode=all

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

MCP资源和工具

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

工具

Architect::generate_prd：基于代码库分析生成产品需求文档
- 参数：
  - task_description（必需）：编程任务或功能的详细描述
  - codebase_path（必需）：要分析的代码库目录的本地文件路径
Architect::think：为陷入困境的LLM提供编码任务的推理辅助
- 参数：
  - request（必需）：编码任务/问题的详细描述及相关代码片段

使用示例

生成PRD示例

安装后，您可以在Claude Code中使用PRD工具，提示如下：

@Architect 请为创建新功能生成一个PRD。
任务描述："创建一个显示用户信息和活动历史的用户个人资料页面，并具有编辑功能。"
代码库路径："/path/to/your/local/project"

带有更多具体技术细节的示例：

@Architect 为新功能生成一个PRD。
任务描述："在Flask应用中实现JWT认证，包括登录、注册和刷新令牌端点。为受保护的路由添加中间件，并优雅地处理令牌过期。"
代码库路径："/Users/username/projects/my-flask-app"

推理辅助示例

当您在编码任务上卡住时，使用思考工具获取详细推理：

@Architect 我需要帮助思考一个编码问题。
我试图实现一个反转链表的函数，但在处理边界情况时遇到了困难。
这是我的代码：
```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

我遗漏了哪些边界情况？我的实现正确吗？


您还可以创建自定义斜杠命令以方便访问：

1. 在您的项目中创建一个命令目录：
   ```bash
   mkdir -p .claude/commands

为Architect工具创建命令文件：

# PRD生成命令
echo "为以下任务生成一个PRD：\n\n任务描述：\"$ARGUMENTS\"\n代码库路径：\"`pwd`\"" > .claude/commands/prd.md

# 思考辅助命令
echo "我需要帮助思考这个问题：\n\n$ARGUMENTS" > .claude/commands/think.md

在Claude Code中使用它们：

# 为PRD生成
/project:prd 实现一个新的用户认证系统

# 为推理辅助
/project:think 我试图优化这个递归函数，但遇到了堆栈溢出...

构建和发布

使用uv构建并发布到PyPI：

构建包：
```
uv build --no-sources
```
这将在dist/目录中创建分发包。

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

# 设置您的TestPyPI令牌
export UV_PUBLISH_TOKEN=your_testpypi_token

# 发布到TestPyPI
uv publish --publish-url https://test.pypi.org/legacy/

发布到PyPI：

# 设置您的PyPI令牌
export UV_PUBLISH_TOKEN=your_pypi_token

# 发布到PyPI
uv publish

发布步骤总结

以下是准备和发布新版本的所有步骤总结：

更新版本，遵循语义版本化（主.次.补丁）：
- pyproject.toml
- mcp_server_architect/version.py
- mcp_server_architect/__init__.py
确保测试通过：
```
uv run pytest
```
构建包：
```
uv build --no-sources
```

在本地测试包：

# 创建一个临时目录
mkdir -p /tmp/test-architect
cd /tmp/test-architect

# 测试从构建的包安装
uv run --with-pin /path/to/your/dist/mcp_server_architect-*.whl --no-project -- python -c "from mcp_server_architect import __version__; print(__version__)"

发布到PyPI：
```
uv publish
```

验证安装：

# 在新的环境中
uvx mcp-server-architect --version

许可证

MIT