MCP 服务器

mcp-server-architect

funtusov

开发者工具

访问服务器

README

mcp-server-architect

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

特性

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

工作原理

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 或更高版本
用于 GPT-4o 的 OpenAI API 密钥（从 OpenAI Platform 获取）
用于 Gemini Pro 的 Google API 密钥（从 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

注意： 在运行之前使用 export 设置环境变量可能无法可靠地工作。建议使用 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

# 或者，在当前目录中使用一个 .env 文件
# 其中包含 GEMINI_API_KEY 和 EXA_API_KEY 环境变量

与 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 密钥添加 Architect 服务器：

# 本地范围（仅在当前项目中对您可用）
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

# 获取 architect 服务器的详细信息
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. 在您的项目中创建一个 commands 目录：
   ```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

发布步骤摘要

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

按照语义版本控制（major.minor.patch）更新以下位置的版本：
- 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

mcp-server-architect

README

mcp-server-architect

特性

工作原理

组件架构

组件流程：

数据流：

先决条件

安装

使用 uv 快速安装（推荐）

使用 pip 安装

API 密钥要求

开发安装

运行和使用服务器

使用 uvx 直接执行

与 MCP Inspector 一起使用

添加到 Claude Code

了解 MCP 服务器范围

安全地存储 API 密钥

验证安装

运行测试

MCP 资源和工具

工具

用法示例

生成 PRD 示例

推理辅助示例

构建和发布

发布步骤摘要

许可证

推荐服务器