Yellhorn MCP（根据上下文，这可能是一个特定名称或缩写，直接翻译为中文可能无法准确传达其含义，但按字面可译为“耶尔霍恩 MCP”，具体含义需结合上下文确定）
一个模型上下文协议（MCP）服务器，提供创建详细工作计划的功能以实现任务或功能。这些工作计划由一个大型、强大的模型（如Gemini 2.5 Pro甚至O3深度研究API）生成，默认情况下会将整个代码库插入到上下文窗口中，并且根据所使用的模型还可以访问URL上下文和执行网络搜索。这种使用强大推理模型创建工作计划的模式对于定义代码助手（如Claude Code或其他兼容MCP的编码代理）要执行的工作非常有用，同时也为审查此类编码模型的输出并确保它们完全符合最初指定的要求提供了参考。
特点/特性
- 制定工作计划根据提示并考虑您的整个代码库，创建详细的实施计划，将它们作为GitHub问题发布，并作为MCP资源提供给您的编码代理
- 判决代码差异提供一个工具，用于将Git差异与原始工作计划进行对比评估，该工具具备完整的代码库上下文，并提供详细的反馈，确保实现过程不偏离原始要求，并指导应进行哪些更改以达到这一目的
- 与GitHub无缝集成自动创建带有标签的问题，并发布引用原始工作计划问题的判断子问题
- 上下文控制使用
.yellhornignore文件用于从AI上下文中排除特定的文件和目录，类似于.gitignore - MCP Resources（公司名，可译为“MCP资源公司”或根据具体语境保留原名）将工作计划作为标准MCP资源公开，以便轻松列出和检索
- 谷歌搜索定位默认情况下在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 --helpuv sync 条款；规定 .venv安装包时以可编辑模式进行，并应用 dev 在……中定义的依赖组 pyproject.toml。
从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-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”（深度研究-O3），“o4-mini-deep-research”（小型深度研究-O4） - 注：深度研究模型（包括GPT-5）自动启用 web_search_preview 并且 code_interpreter 增强研究能力的工具
YELLHORN_MCP_REASONING_EFFORT为GPT-5模型设置推理努力级别。选项：“低”、“中”、“高”。此设置为支持的模型（gpt-5、gpt-5-mini）提供了更高的推理能力，但成本也会相应增加。努力级别决定了推理过程中使用的计算量，级别越高，推理越彻底，但成本也越高。服务器现在会将此值传递给每个GPT-5请求，并且成本指标会自动包含相应的推理溢价。YELLHORN_MCP_SEARCH启用/禁用谷歌搜索验证（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}"
}
}
}
}克劳德编码设置
要直接在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创建工作计划
根据标题和详细描述，创建一个包含详细工作计划的GitHub问题（issue）。
输入：
titleGitHub 问题标题（将用作问题标题和页眉）detailed_description工作计划的详细描述。此处提供的任何网址都将被提取并包含在“参考文献”部分中。codebase_reasoning（可选）控制是否执行AI增强：
- "full"（默认）使用AI结合完整的代码库上下文来增强工作计划 - "lsp"使用包含轻量级代码库上下文（对于Python和Go，包括函数/方法签名、类属性和结构体字段）的人工智能 - "none"跳过AI增强，直接使用提供的描述
debug（可选）如果设置为true在问题中添加了一条评论，其中包含了用于生成的完整提示disable_search_grounding（可选）如果设置为true禁用此请求的Google搜索验证功能
输出：
- 包含以下内容的JSON字符串：
- issue_url创建的GitHub问题的URL - issue_numberGitHub 问题编号
获取工作计划
检索与工作计划相关联的工作计划内容（GitHub 问题正文）。
输入:
issue_number该工作计划在GitHub上的问题编号。disable_search_grounding（可选）如果设置为true，禁用此请求的Google搜索结果引用功能
输出:
- 工作计划问题的内容（以字符串形式）
修订工作计划
根据修订说明更新现有工作计划。该工具会从指定的GitHub问题中获取当前的工作计划，并使用人工智能根据您的说明对其进行修订。
输入：
issue_number包含修订工作计划的GitHub问题编号revision_instructions说明如何修订工作计划的指示codebase_reasoning（可选）控制是否执行AI增强：
- "full"(默认) 使用AI在完整代码库上下文中进行修订 - "lsp"使用仅包含轻量级代码库上下文（仅函数/方法签名）的人工智能 - "file_structure"仅使用带有目录结构的AI（最快） - "none"最小的代码库上下文
debug（可选）如果设置为true在问题中添加了使用完整提示生成时的评论disable_search_grounding（可选）如果设置为true，禁用此请求的Google搜索验证功能
输出:
- 包含以下内容的JSON字符串：
- issue_url更新后的GitHub问题页面的URL - issue_numberGitHub问题编号
法官工作计划
触发异步代码判断，将两个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搜索支持功能
工作计划中提到的所有网址将被提取并保存在判决书的“参考文献”部分。
输出：
- 包含以下内容的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
# 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 问题）get-resource通过问题编号检索特定工作计划的内容
这些可以通过标准的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进行持续集成和部署：
- 测试在拉取请求时自动运行，并推送到主分支
- 使用flake8进行代码检查 - 用黑色进行格式检查 - 使用 pytest 进行测试
- 出版当推送版本标签时，自动发布到PyPI
- 标签必须与 pyproject.toml 中的版本相匹配（例如，v0.2.2） - 需要一个作为GitHub仓库密钥存储的PyPI API令牌（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
如需了解变更历史，请参阅 更新日志.
如需更详细的说明，请参阅 使用指南。
许可证
麻省理工学院（MIT）