黄色号角-mcp

Name: 黄色号角-mcp
Author: msnidal

作者：msnidal14 星标更新：2025-09-28

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

项目介绍

Yellhorn MCP

Yellhorn Logo

Yellhorn MCP 是一个模型上下文协议（MCP）服务器，提供创建详细工作计划的功能，以实现任务或特性。这些工作计划由大型强大的模型生成（如 gemini 2.5 pro 或 o3 深度研究 API），默认情况下会将整个代码库插入到上下文窗口中，并且根据使用的模型可以访问 URL 上下文并进行网络搜索。这种使用强大推理模型创建工作计划的模式对于定义由代码助手（如 Claude Code 或其他兼容 MCP 的编码代理）执行的工作非常有用，同时还可以作为审查此类编码模型输出的参考，确保它们满足原始需求。

功能

创建工作计划：基于提示创建详细的实施计划，考虑整个代码库，并将其发布为 GitHub 问题，作为 MCP 资源暴露给编码代理。
评估代码差异：提供工具来评估 git 差异与原始工作计划的对比，提供详细的反馈，确保实现不偏离原始需求，并提供指导以进行必要的更改。
无缝 GitHub 集成：自动创建带有标签的问题，并发布带有原始工作计划问题引用的子问题。
上下文控制：使用 .yellhornignore 文件排除特定文件和目录，类似于 .gitignore。
MCP 资源：将工作计划作为标准 MCP 资源暴露，便于列出和检索。
Google 搜索定位：默认启用 Gemini 模型的搜索能力，提供自动格式化的引用。
自动分段：处理超过模型上下文限制的大代码库，通过智能拆分提示来处理。
速率限制处理：针对速率限制和瞬时故障的健壮重试逻辑，采用指数退避策略。
成本跟踪：实时估算和跟踪所有 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)

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

# 配置环境并安装所有依赖组
uv sync --group dev

# 可选：激活环境以便直接在 shell 中使用
source .venv/bin/activate

# 验证 CLI 入口点
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 搜索定位（默认为 Gemini 模型启用）。选项：
- "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 设置

要直接配置 Yellhorn MCP 与 Claude Code，可以在项目根目录下添加一个 .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 上下文，显著减少令牌使用并提高 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 搜索定位

输出：

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

.yellhorncontext 文件充当白名单——只有匹配模式的文件才会被包含在后续的工作计划/评估调用中。这显著减少了令牌使用并提高了 AI 对相关代码的关注。

示例 .yellhorncontext 输出：

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

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 搜索定位

输出：

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

revise_workplan

根据修订指令更新现有工作计划。该工具从指定的 GitHub 问题中获取当前工作计划，并使用 AI 根据您的指令进行修订。

输入：

issue_number：包含要修订的工作计划的 GitHub 问题编号
revision_instructions：描述如何修订工作计划的指令
codebase_reasoning：（可选）控制是否执行 AI 增强：
- "full"：（默认）使用完整的代码库上下文修订
- "lsp"：使用轻量级代码库上下文的 AI（仅函数/方法签名）
- "file_structure"：使用仅目录结构的 AI（最快）
- "none"：最小的代码库上下文
debug：（可选）如果设置为 true，则在问题中添加一条评论，其中包含生成的完整提示
disable_search_grounding：（可选）如果设置为 true，则禁用此请求的 Google 搜索定位

输出：

包含以下内容的 JSON 字符串：
- issue_url：更新的 GitHub 问题的 URL
- issue_number：GitHub 问题编号

judge_workplan

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

输入：

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

工作计划中提到的任何 URL 将被提取并在评估结果中保留。

输出：

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

文件过滤系统

Yellhorn MCP 提供了一个复杂的多层次文件过滤系统，以控制哪些文件包含在 AI 上下文中。该系统按照优先顺序确定文件包含：

过滤层（按优先顺序）

.yellhorncontext 白名单：如果此文件存在且包含模式，则只有匹配这些模式的文件会被包含。
.yellhorncontext 黑名单：匹配黑名单模式（以 ! 开头）的文件将被排除。
.yellhornignore 白名单：匹配白名单模式（以 ! 开头）的文件将被明确包含。
.yellhornignore 黑名单：匹配这些模式的文件将被排除。
.gitignore 黑名单：被 Git 忽略的文件将自动被排除。

始终忽略的模式

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

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

文件格式

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

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

示例 .yellhornignore

# 排除测试文件
tests/
*.test.js

# 排除构建产物
dist/
build/

# 但包含重要的测试工具
!tests/utils/

示例 .yellhorncontext

# 仅包含源代码和文档
src/
docs/
README.md

# 即使在 src 中也要排除生成的文件
!src/generated/

资源访问

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

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

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

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

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

开发

# 确保环境是最新的
uv sync --group dev

# 运行测试
uv run --group dev pytest

# 运行带有覆盖率报告的测试
uv run --group dev pytest -- --cov=yellhorn_mcp --cov-report term-missing

# 添加或移除依赖项
uv add some-package
uv remove some-package

# 重新生成锁文件（提交结果）
uv lock

CI/CD

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

测试：在拉取请求和主分支推送时自动运行
- 使用 flake8 进行代码检查
- 使用 black 进行格式检查
- 使用 pytest 进行测试
发布：当推送版本标签时自动发布到 PyPI
- 标签必须与 pyproject.toml 中的版本匹配（例如，v0.2.2）
- 需要将 PyPI API 令牌存储为 GitHub 存储库密钥（PYPI_API_TOKEN）

要发布新版本：

更新 pyproject.toml 和 yellhorn_mcp/__init__.py 中的版本
在 CHANGELOG.md 中更新新变化
提交更改：git commit -am "Bump version to X.Y.Z"
标记提交：git tag vX.Y.Z
推送更改和标签：git push && git push --tags

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

有关更多详细说明，请参阅 Usage Guide。

许可

MIT