Yellhorn

You run Yellhorn MCP to generate detailed workplans for implementing tasks or features, incorporating your entire codebase and web search context when available. This enables your coding agents to turn high‑level prompts into concrete implementation steps while keeping alignment with original requirements.

How to use

You access Yellhorn MCP through an MCP client. Start by configuring a local or remote MCP server entry, then request workplans, have the server generate or judge plans, and review results in an organized, GitHub‑backed workflow.

Typical usage patterns include creating detailed workplans from prompts, judging code diffs against the original workplan, and curating the codebase context to optimize the AI’s focus. You can also retrieve existing workplans and revise them as your project evolves.

How to install

Install from source or from PyPI, then run the MCP server locally.

# 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
````?

Configuration and usage notes

Set API keys and paths as environment variables when you start the MCP server. The following environment variables are used by the server:

• GEMINI_API_KEY: Your Gemini API key
• OPENAI_API_KEY: Your OpenAI API key
• XAI_API_KEY: Your xAI API key
• REPO_PATH: Path to your repository
• YELLHORN_MCP_MODEL: Model to use (defaults to gemini-2.5-pro)
• YELLHORN_MCP_REASONING_EFFORT: Reasoning effort level for GPT-5 models (low, medium, high)
• YELLHORN_MCP_SEARCH: Enable/disable Google Search Grounding (on or off)

Example server startup with environment variables in place:

OPENAI_API_KEY=your OpenAI key
XAI_API_KEY=your xAI key
REPO_PATH=/path/to/your/repo
YELLHORN_MCP_MODEL=gemini-2.5-pro
YELLHORN_MCP_SEARCH=on
uv run yellhorn-mcp```

## Troubleshooting and tips

If you need to tune how much codebase context is analyzed, use the curate\_context tool to generate a `.yellhorncontext` whitelist. This helps reduce token usage and keeps the AI focused on relevant parts of your codebase.

For large projects, Yellhorn MCP automatically chunks prompts and handles rate limits with retry logic. Monitor cost estimates and usage in real time to manage compute resources.

## Security and access

Keep your API keys secret. Use per‑project environment configurations and restrict access to the MCP server to trusted agents. Use the built‑in references and workplan management to maintain an auditable trail of decisions and changes.

## Available tools

### create\_workplan

Creates a detailed implementation plan from a prompt and the full codebase, posting it as a GitHub issue and exposing it as an MCP resource.

### judge\_workplan

Evaluates a code diff against the original workplan with full context and provides feedback and guidance on changes needed.

### curate\_context

Analyzes the codebase and creates a whitelist of files/folders to include in AI context via a `.yellhorncontext` file.

### get\_workplan

Retrieves the content of a workplan by its GitHub issue number.

### revise\_workplan

Updates an existing workplan based on revision instructions, using AI with appropriate codebase context.

### list\_resources

Lists all workplans (GitHub issues with the yellhorn-mcp label) via the MCP resource API.