Yellhorn MCP

Yellhorn MCP

一个模型上下文协议（MCP）服务，提供创建详细工作计划的功能，用于实施任务或功能。这些工作计划由强大的大模型生成（例如 gemini 2.5 pro，甚至 o3 deep research API）。默认情况下，会将整个代码库加入上下文窗口；具体使用的模型还可能支持访问 URL 上下文和网页搜索。使用强大的推理模型来创建工作计划非常有用，可用于定义 Claude Code 等编码助手或其他兼容 MCP 的编码 Agent 要完成的工作，也可作为审查这些编码模型输出的参考，以确保其严格符合原始需求。

功能

• 创建工作计划：根据提示词创建详细的实施计划，并考虑整个代码库；将计划发布为 GitHub issue，并作为 MCP 资源提供给编码 Agent
• 评估代码差异：提供工具，在完整代码库上下文中根据原始工作计划评估 git 差异，并给出详细反馈，确保实施不偏离原始需求，同时指导如何修改以符合要求
• 无缝集成 GitHub：自动创建带标签的 issue，并发布引用原始工作计划 issue 的评审子 issue
• 上下文控制：使用 .yellhornignore 文件从 AI 上下文中排除特定文件和目录，类似于 .gitignore
• MCP 资源：将工作计划作为标准 MCP 资源提供，便于列出和检索
• Google 搜索 Grounding：默认对 Gemini 模型启用，提供搜索能力，并自动生成格式化的 Markdown 引用
• 自动分块：通过智能拆分提示词，处理超出模型上下文限制的大型代码库
• 速率限制处理：针对速率限制和暂时性故障，提供带指数退避的可靠重试逻辑
• 成本跟踪：实时估算成本并跟踪所有 API 调用的用量
• 多模型支持：提供统一接口，支持 OpenAI（GPT-4o、GPT-5、o3、o4-mini）、xAI Grok（Grok-4、Grok-4 Fast）和 Gemini（2.5-pro、2.5-flash）模型，并支持 GPT-5 的推理模式

安装

项目初始化（uv）

# Install from source
git clone https://github.com/msnidal/yellhorn-mcp.git
cd yellhorn-mcp

# Provision the environment and install all dependency groups
uv sync --group dev

# Optional: activate the environment for direct shell usage
source .venv/bin/activate

# Verify the CLI entrypoint
uv run yellhorn-mcp --help

uv sync 会创建 .venv、以可编辑模式安装软件包，并应用 pyproject.toml 中定义的 dev 依赖组。

从 PyPI 安装

uv pip install yellhorn-mcp

配置

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

• GEMINI_API_KEY：你的 Gemini API 密钥（Gemini 模型必需）
• OPENAI_API_KEY：你的 OpenAI API 密钥（OpenAI 模型必需）
• XAI_API_KEY：你的 xAI API 密钥（Grok 模型必需）
• REPO_PATH：代码库路径（默认为当前目录）
• YELLHORN_MCP_MODEL：要使用的模型（默认为 "gemini-2.5-pro"）。可用选项：
  • Gemini 模型："gemini-2.5-pro"、"gemini-2.5-flash"、"gemini-2.5-flash-lite"
  • OpenAI 模型："gpt-4o"、"gpt-4o-mini"、"o4-mini"、"o3"、"gpt-4.1"
  • GPT-5 模型："gpt-5"、"gpt-5-mini"、"gpt-5-nano"（gpt-5 和 gpt-5-mini 支持推理模式）
  • xAI Grok 模型："grok-4"（256K 上下文）和 "grok-4-fast"（2M 上下文）
  • 深度研究模型："o3-deep-research"、"o4-mini-deep-research"
  • 注意：深度研究模型（包括 GPT-5）会自动启用 web_search_preview 和 code_interpreter 工具，以增强研究能力
• YELLHORN_MCP_REASONING_EFFORT：设置 GPT-5 模型的推理力度级别。选项："low"、"medium"、"high"。对于受支持的模型（gpt-5、gpt-5-mini），更高的推理力度可提供更强的推理能力，但成本也更高。该级别决定推理所用的计算量；级别越高，推理越全面，成本也越高。现在，服务会将此值转发给每个 GPT-5 请求，并在成本指标中自动计入相应的推理溢价。
• YELLHORN_MCP_SEARCH：启用/禁用 Google Search Grounding（Gemini 模型默认值为 "on"）。选项：
  • "on" — 为 Gemini 模型启用搜索接地
  • "off" — 为所有模型禁用搜索接地

ℹ️ Grok 模型现在使用官方 xai-sdk；请确保已在环境中安装（它已包含在项目依赖项中，但自定义部署应显式添加）。

该服务还要求安装并完成身份验证的 GitHub CLI（gh）。

使用方法

入门

Codex CLI 设置

将下方的服务配置添加到 Codex CLI 的 config.toml（默认路径为 ~/.config/codex/config.toml）。请根据你的环境更新 GEMINI_API_KEY（或替换为 OPENAI_API_KEY/XAI_API_KEY 并调整模型）和 REPO_PATH 的值。

[mcp_servers.yellhorn-mcp]
command = "uv"
args = ["run", "yellhorn-mcp"]
env = { "GEMINI_API_KEY" = "your-api-key", "REPO_PATH" = "/path/to/your/repo" }

更新配置后，重启 Codex，使其加载新的 MCP 服务。

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": "uv",
      "args": ["run", "yellhorn-mcp"],
      "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": "uv",
      "args": ["run", "yellhorn-mcp", "--model", "o3"],
      "env": {
        "YELLHORN_MCP_SEARCH": "on"
      }
    }
  }
}

工具

curate_context

分析代码库并创建 .yellhorncontext 文件，列出要纳入 AI 上下文的目录。此工具会根据你想完成的任务进行分析，并创建相关目录的白名单，从而优化 AI 上下文，显著减少 token 用量，并让 AI 更专注于相关代码。

输入：

• user_task：你想完成的任务描述
• codebase_reasoning：（可选）控制代码库分析的程度：
  • "file_structure"：（默认）基本文件结构分析（速度最快）
  • "lsp"：仅分析函数签名和文档字符串（更轻量）
  • "full"：完整文件内容（最全面）
  • "none"：不提供代码库上下文
• ignore_file_path：（可选）忽略文件的路径（默认为 .yellhornignore）
• output_path：（可选）上下文文件的输出路径（默认为 .yellhorncontext）
• depth_limit：（可选）要分析的最大目录深度（0 = 无限制）
• disable_search_grounding：（可选）如果设为 true，则对此请求禁用 Google Search Grounding

输出：

• 包含以下内容的 JSON 字符串：
  • context_file_path：所创建 .yellhorncontext 文件的路径
  • directories_included：上下文中包含的目录数
  • files_analyzed：整理过程中分析的文件数

.yellhorncontext 文件充当白名单——后续工作计划/判断调用只会纳入与这些模式匹配的文件。这能显著减少 token 用量，并让 AI 更专注于相关代码。

.yellhorncontext 输出示例：

src/api/
src/models/
tests/api/
*.config.js

create_workplan

根据标题和详细描述创建包含详细工作计划的 GitHub issue。

输入：

• title：GitHub issue 的标题（将用作 issue 标题和标题栏）
• detailed_description：工作计划的详细描述。此处提供的任何 URL 都会被提取并加入“参考资料”部分。
• codebase_reasoning：（可选）控制是否进行 AI 增强：
  • "full"：（默认）使用 AI 并结合完整代码库上下文增强工作计划
  • "lsp"：使用 AI 并结合轻量级代码库上下文（函数/方法签名、Python 和 Go 中的类属性及结构体字段）
  • "none"：跳过 AI 增强，按原样使用提供的描述
• debug：（可选）如果设为 true，则向 issue 添加一条评论，其中包含用于生成内容的完整提示词
• disable_search_grounding：（可选）如果设为 true，则对此请求禁用 Google Search Grounding

输出：

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

get_workplan

获取与工作计划关联的内容（GitHub issue 正文）。

输入：

• issue_number：工作计划对应的 GitHub issue 编号。
• disable_search_grounding：（可选）如果设为 true，则对此请求禁用 Google Search Grounding

输出：

• 工作计划 issue 的内容，以字符串形式返回

revise_workplan

根据修订说明更新现有工作计划。该工具会从指定的 GitHub issue 获取当前工作计划，并使用 AI 按照你的说明进行修订。

输入：

• issue_number：包含待修订工作计划的 GitHub issue 编号
• revision_instructions：描述如何修订工作计划的说明
• codebase_reasoning：（可选）控制是否执行 AI 增强：
  • "full"：（默认）使用完整代码库上下文通过 AI 进行修订
  • "lsp"：使用轻量级代码库上下文（仅函数/方法签名）通过 AI 进行修订
  • "file_structure"：仅使用目录结构通过 AI 进行修订（速度最快）
  • "none"：使用最少的代码库上下文
• debug：（可选）如果设为 true，会在 issue 中添加一条评论，其中包含生成时使用的完整提示词
• disable_search_grounding：（可选）如果设为 true，会为此请求停用 Google Search Grounding

输出：

• 包含以下内容的 JSON 字符串：
  • issue_url：更新后的 GitHub issue 的 URL
  • issue_number：GitHub issue 编号

judge_workplan

异步触发代码判定，根据 GitHub issue 中描述的工作计划，对比两个 git 引用（分支或提交）。该工具会立即创建一个占位 GitHub 子 issue，然后异步处理 AI 判定，并使用结果更新该子 issue。

输入：

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

工作计划中提到的任何 URL 都会被提取，并保留在判定结果的 References 部分。

输出：

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

文件筛选系统

Yellhorn MCP 提供了多层文件筛选系统，用于控制哪些文件会纳入 AI 上下文。该系统按优先级顺序决定文件是否纳入：

筛选层（按优先级排序）

1. .yellhorncontext 白名单：如果此文件存在且包含匹配模式，则仅纳入匹配这些模式的文件
2. .yellhorncontext 黑名单：排除匹配黑名单模式（以 ! 开头）的文件
3. .yellhornignore 白名单：明确纳入匹配白名单模式（以 ! 开头）的文件
4. .yellhornignore 黑名单：排除匹配这些模式的文件
5. .gitignore 黑名单：自动排除被 git 忽略的文件

始终忽略的模式

无论其他设置如何，以下模式始终会被忽略：

• .git/ - Git 元数据
• __pycache__/ - Python 缓存文件
• node_modules/ - Node.js 依赖项
• *.pyc - Python 编译文件
• .venv/、venv/ - Python 虚拟环境

文件格式

.yellhornignore 和 .yellhorncontext 文件都遵循类似 gitignore 的语法：

• 每行一个模式
• 以 # 开头的行是注释
• 空行会被忽略
• 使用 ! 前缀表示白名单模式（明确纳入）
• 目录模式应以 / 结尾

.yellhornignore 示例

# Exclude test files
tests/
*.test.js

# Exclude build artifacts
dist/
build/

# But include important test utilities
!tests/utils/

.yellhorncontext 示例

# Only include source code and documentation
src/
docs/
README.md

# Exclude generated files even in src
!src/generated/

资源访问

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

• list-resources：列出所有工作计划（带有 yellhorn-mcp 标签的 GitHub issue）
• get-resource：根据 issue 编号获取特定工作计划的内容

可以通过标准 MCP CLI 命令访问这些资源：

# List all workplans
mcp list-resources yellhorn-mcp

# Get a specific workplan by issue number
mcp get-resource yellhorn-mcp 123

开发

# Ensure the environment is up to date
uv sync --group dev

# Run tests
uv run --group dev pytest

# Run tests with coverage report
uv run --group dev pytest -- --cov=yellhorn_mcp --cov-report term-missing

# Add or remove dependencies
uv add some-package
uv remove some-package

# Regenerate the lockfile (commit the result)
uv lock

CI/CD

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

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

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

如需查看变更历史，请参阅 变更日志。

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

许可证

MIT