Yellhorn MCP

A Model Context Protocol (MCP) server that provides functionality to create detailed workplans to implement a task or feature. These workplans are generated with a large, powerful model (such as gemini 2.5 pro or even the o3 deep research API), insert your entire codebase into the context window by default, and can also access URL context and do web search depending on the model used. This pattern of creating workplans using a powerful reasoning model is highly useful for defining work to be done by code assistants like Claude Code or other MCP compatible coding agents, as well as providing a reference to reviewing the output of such coding models and ensure they meet the exactly specified original requirements.

Features

• Create Workplans: Creates detailed implementation plans based on a prompt and taking into consideration your entire codebase, posting them as GitHub issues and exposing them as MCP resources for your coding agent
• Judge Code Diffs: Provides a tool to evaluate git diffs against the original workplan with full codebase context and provides detailed feedback, ensuring the implementation does not deviate from the original requirements and providing guidance on what to change to do so
• Seamless GitHub Integration: Automatically creates labeled issues, posts judgement sub-issues with references to original workplan issues
• Context Control: Use .yellhornignore files to exclude specific files and directories from the AI context, similar to .gitignore
• MCP Resources: Exposes workplans as standard MCP resources for easy listing and retrieval
• Google Search Grounding: Enabled by default for Gemini models, providing search capabilities with automatically formatted citations in Markdown
• Automatic Chunking: Handles large codebases that exceed model context limits by intelligently splitting prompts
• Rate Limit Handling: Robust retry logic with exponential backoff for rate limits and transient failures
• Cost Tracking: Real-time cost estimation and usage tracking for all API calls
• Multi-Model Support: Unified interface supporting OpenAI (GPT-4o, GPT-5, o3, o4-mini), xAI Grok (Grok-4, Grok-4 Fast), and Gemini (2.5-pro, 2.5-flash) models with reasoning mode support for GPT-5

Installation

Project bootstrap (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 provisions .venv, installs the package in editable mode, and applies the dev dependency group defined in pyproject.toml.

Install from PyPI

uv pip install yellhorn-mcp

Configuration

The server requires the following environment variables: