Yellhorn MCP

Yellhorn MCP 是一个模型上下文协议（MCP）服务器，它将 Gemini 2.5 Pro 和 OpenAI 的能力暴露给 Claude Code，以便在软件开发任务中使用整个代码库作为提示。这种模式在定义由 Claude Code 或其他兼容 MCP 的编码助手完成的工作，并审查结果以确保它们完全符合原始需求时非常有用。

功能

• 创建工作计划：根据提示创建详细的实施计划，并考虑整个代码库，将其发布为 GitHub 问题，并作为 MCP 资源暴露给编码助手。
• 代码差异评审：提供一个工具，根据原始工作计划评估 git 差异，并提供详细的反馈，确保实现不偏离原始需求，并提供修改指导。
• 无缝 GitHub 集成：自动创建带有标签的问题，发布带有原始工作计划问题引用的评审子问题。
• 上下文控制：使用 .yellhornignore 文件从 AI 上下文中排除特定文件和目录，类似于 .gitignore。
• MCP 资源：将工作计划作为标准 MCP 资源暴露，便于列出和检索。
• Google 搜索基础：默认启用 Gemini 模型的搜索功能，提供自动格式化引用的 Markdown 搜索能力。

安装

# 从 PyPI 安装
pip install yellhorn-mcp

# 从源代码安装
git clone https://github.com/msnidal/yellhorn-mcp.git
cd yellhorn-mcp
pip install -e .

配置

服务器需要以下环境变量：

• GEMINI_API_KEY：您的 Gemini API 密钥（Gemini 模型必需）
• OPENAI_API_KEY：您的 OpenAI API 密钥（OpenAI 模型必需）
• REPO_PATH：您的代码库路径（默认为当前目录）
• YELLHORN_MCP_MODEL：使用的模型（默认为 "gemini-2.5-pro-preview-05-06"）。可用选项：
  • Gemini 模型："gemini-2.5-pro-preview-05-06", "gemini-2.5-flash-preview-05-20"
  • OpenAI 模型："gpt-4o", "gpt-4o-mini", "o4-mini", "o3"
• YELLHORN_MCP_SEARCH：启用/禁用 Google 搜索基础（默认对 Gemini 模型启用）。选项：
  • "on" - 对 Gemini 模型启用搜索基础
  • "off" - 对所有模型禁用搜索基础

服务器还需要安装并认证 GitHub CLI（gh）。

使用

入门

VSCode/Cursor 设置

要在 VSCode 或 Cursor 中配置 Yellhorn MCP，请在您的工作区根目录下创建一个 .vscode/mcp.json 文件，内容如下：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gemini-api-key",
      "description": "Gemini API Key"
    }
  ],
  "servers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "/Users/msnidal/.pyenv/shims/yellhorn-mcp",
      "args": [],
      "env": {
        "GEMINI_API_KEY": "${input:gemini-api-key}",
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

Claude Code 设置

要直接在 Claude Code 中配置 Yellhorn MCP，请在您的项目中添加一个根级别的 .mcp.json 文件，内容如下：

{
  "mcpServers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "yellhorn-mcp",
      "args": ["--model", "o3"],
      "env": {
        "YELLHORN_MCP_SEARCH": "on"
      }
    }
  }
}

工具

create_workplan

根据标题和详细描述创建一个带有详细工作计划的 GitHub 问题。

输入：

• title：GitHub 问题的标题（将用作问题标题和标题）
• detailed_description：工作计划的详细描述。此处提供的任何 URL 将被提取并包含在参考资料部分。
• codebase_reasoning：（可选）控制是否执行 AI 增强：
  • "full"：（默认）使用 AI 增强工作计划，提供完整的代码库上下文
  • "lsp"：使用 AI 增强，提供轻量级代码库上下文（Python 和 Go 的函数/方法签名、类属性和结构字段）
  • "none"：跳过 AI 增强，直接使用提供的描述
• debug：（可选）如果设置为 true，将在问题中添加一个包含生成完整提示的评论
• disable_search_grounding：（可选）如果设置为 true，禁用此请求的 Google 搜索基础

输出：

• 包含以下内容的 JSON 字符串：
  • issue_url：创建的 GitHub 问题的 URL
  • issue_number：GitHub 问题编号

get_workplan

检索与工作计划相关的工作计划内容（GitHub 问题正文）。

输入：

• issue_number：工作计划的 GitHub 问题编号。
• disable_search_grounding：（可选）如果设置为 true，禁用此请求的 Google 搜索基础

输出：

• 工作计划问题的内容作为字符串

judge_workplan

触发异步代码评审，比较两个 git 引用（分支或提交）与 GitHub 问题中描述的工作计划。立即创建一个占位符 GitHub 子问题，然后异步处理 AI 评审，更新子问题结果。

输入：

• issue_number：工作计划的 GitHub 问题编号。
• base_ref：用于比较的基础 Git 引用（提交 SHA、分支名称、标签）。默认为 'main'。
• head_ref：用于比较的目标 Git 引用（提交 SHA、分支名称、标签）。默认为 'HEAD'。
• codebase_reasoning：（可选）控制提供的代码库上下文：
  • "full"：（默认）使用完整的代码库上下文
  • "lsp"：使用轻量级代码库上下文（仅 Python 和 Go 的函数签名，加上完整的差异文件）
  • "file_structure"：仅使用目录结构，不包含文件内容，以加快处理速度
  • "none"：完全跳过代码库上下文，以最快速度处理
• debug：（可选）如果设置为 true，将在子问题中添加一个包含生成完整提示的评论
• disable_search_grounding：（可选）如果设置为 true，禁用此请求的 Google 搜索基础

工作计划中提到的任何 URL 将被提取并保留在评审的参考资料部分。

输出：

• 包含以下内容的 JSON 字符串：
  • message：确认评审任务已启动
  • subissue_url：创建的占位符子问题的 URL，结果将发布在此处
  • subissue_number：占位符子问题的 GitHub 问题编号

资源访问

Yellhorn MCP 还实现了标准的 MCP 资源 API，以提供对工作计划的访问：

• list-resources：列出所有工作计划（带有 yellhorn-mcp 标签的 GitHub 问题）
• get-resource：通过问题编号检索特定工作计划的内容

可以通过标准的 MCP CLI 命令访问这些功能：

# 列出所有工作计划
mcp list-resources yellhorn-mcp

# 通过问题编号获取特定工作计划
mcp get-resource yellhorn-mcp 123

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=yellhorn_mcp --cov-report term-missing

CI/CD

该项目使用 GitHub Actions 进行持续集成和部署：

• 测试：在拉取请求和推送到主分支时自动运行

  • 使用 flake8 进行代码检查
  • 使用 black 进行格式检查
  • 使用 pytest 进行测试

• 发布：在推送版本标签时自动发布到 PyPI

  • 标签必须与 pyproject.toml 中的版本匹配（例如，v0.2.2）
  • 需要将 PyPI API 令牌存储为 GitHub 仓库机密（PYPI_API_TOKEN）

要发布新版本：

1. 更新 pyproject.toml 和 yellhorn_mcp/__init__.py 中的版本
2. 更新 CHANGELOG.md 以包含新更改
3. 提交更改：git commit -am "Bump version to X.Y.Z"
4. 标记提交：git tag vX.Y.Z
5. 推送更改和标签：git push && git push --tags

有关更改的历史记录，请参阅 Changelog。

更详细的说明，请参阅 使用指南。

许可证

MIT