Yellhorn Mcp

Yellhorn MCP acts like a highly organized project manager for software developers working with AI. It takes a developer's idea or task and turns it into a step-by-step instruction manual called a workplan. Because it can "see" the entire codebase at once, it ensures that every plan it creates is actually relevant to the existing project, rather than just guessing based on generic coding patterns. This server bridges the gap between powerful reasoning models—including Gemini 2.5 Pro, OpenAI’s o3, and xAI’s Grok—and a developer’s local environment. It doesn't just generate text; it automatically creates labeled GitHub issues for these workplans, which coding agents like Claude Code or Cursor can then reference as a source of truth. It handles the heavy lifting of managing large codebases by intelligently chunking data and using a feature called context curation, which creates a whitelist of relevant directories to save on tokens and improve the AI's focus. For developers who need to maintain high standards, the tool includes a specialized "judge" that evaluates git diffs against the original workplan. This ensures that the final implementation doesn't deviate from the original requirements and provides specific feedback on what needs to change. With built-in Google Search grounding for real-time research, automatic cost tracking, and support for "deep research" models, Yellhorn MCP provides a robust infrastructure for building a semi-autonomous development workflow that is both cost-aware and contextually grounded.

Category: Developer Tools & Code Intelligence

Tags: codebase, git, github, task-management, workflow-automation

Visit Yellhorn Mcp

How to install and configure Yellhorn Mcp

Based on the content provided, here are the installation and configuration instructions for Yellhorn MCP.

1. Installation You can install Yellhorn MCP either from the source using `uv` or via PyPI. Requirement: The GitHub CLI (`gh`) must be installed and authenticated on your system. Option A: Install from source (using uv) `bash # Clone the repository git clone https://github.com/msnidal/yellhorn-mcp.git cd yellhorn-mcp # Provision the environment and install dependencies uv sync --group dev # Optional: activate the environment source .venv/bin/activate # Verify installation uv run yellhorn-mcp --help` Option B: Install from PyPI `bash uv pip install yellhorn-mcp` ---

2. Configuration

Required Environment Variables The server requires at least one API key and the repository path: * `GEMINI_API_KEY`: Required for Gemini models. * `OPENAI_API_KEY`: Required for OpenAI models. * `XAI_API_KEY`: Required for Grok models. * `REPO_PATH`: Path to your repository (defaults to current directory). * `YELLHORN_MCP_MODEL`: Model to use (defaults to `gemini-2.5-pro`). * `YELLHORN_MCP_REASONING_EFFORT`: For GPT-5 models (`low`, `medium`, `high`). * `YELLHORN_MCP_SEARCH`: Enable/disable Google Search Grounding (`on` or `off`).

Claude Code Setup Add a `.mcp.json` file to your project root: `json { "mcpServers": { "yellhorn-mcp": { "type": "stdio", "command": "uv", "args": ["run", "yellhorn-mcp", "--model", "o3"], "env": { "YELLHORN_MCP_SEARCH": "on" } } } }`

VSCode / Cursor Setup Create or update `.vscode/mcp.json` in your workspace root: 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}" } } } }

Codex CLI Setup Add this to your `~/.config/codex/config.toml`: `toml [mcp_servers.yellhorn-mcp] command = "uv" args = ["run", "yellhorn-mcp"] env = { "GEMINI_API_KEY" = "your-api-key", "REPO_PATH" = "/path/to/your/repo" }` ---

3. Available Tools * `curate_context`: Analyzes the codebase and creates a `.yellhorncontext` whitelist to optimize token usage. * Parameters: `user_task`, `codebase_reasoning` (full, lsp, file_structure, none), `ignore_file_path`, `output_path`, `depth_limit`. * `create_workplan`: Generates a detailed implementation plan and posts it as a GitHub issue. * Parameters: `title`, `detailed_description`, `codebase_reasoning`, `debug`. * `get_workplan`: Retrieves the content of an existing workplan from a GitHub issue. * Parameters: `issue_number`. * `revise_workplan`: Updates an existing workplan GitHub issue based on new instructions. * Parameters: `issue_number`, `revision_instructions`, `codebase_reasoning`. * `judge_workplan`: Compares a git diff (between two refs) against a workplan issue to evaluate implementation accuracy. * Parameters: `issue_number`, `base_ref` (default 'main'), `head_ref` (default 'HEAD'), `codebase_reasoning`. ---

4. Example Prompts While specific prompts aren't listed as a standalone section, the tools suggest the following usage patterns: * Context Optimization: "Analyze my codebase and create a context file for a task involving updating the user authentication flow." * Planning: "Create a workplan for adding Stripe subscription support, considering my current API structure." * Reviewing: "Judge the current changes in my feature branch against workplan issue #42 and tell me if I missed any requirements." * Refining: "Revise workplan #45 to include documentation requirements for the new API endpoints."

What you can do with Yellhorn Mcp

Use Case 1: Architecting Complex Features in Large Codebases Problem: When developers or AI agents (like Claude Code) attempt to implement a new feature in a massive repository, they often lack the global context of existing design patterns, internal utility functions, or potential side effects, leading to technical debt or redundant code. Solution: The `create_workplan` tool allows a user to provide a high-level goal and uses powerful models (like Gemini 2.5 Pro or OpenAI o3) to scan the entire codebase. It generates a step-by-step implementation plan as a GitHub issue, ensuring the new feature aligns with existing architecture. Example: A developer needs to add a new multi-tenant billing logic. They call `create_workplan` with the description of the feature. Yellhorn analyzes the existing `auth

,db/, andbilling/` directories, then creates a GitHub issue detailing exactly which files to modify and which existing helper functions to reuse, serving as a blueprint for the coding agent.

Use Case 2: Automated Code Review and Requirement Verification Problem: Coding agents can sometimes "drift" from the original requirements or introduce regressions that aren't caught by unit tests alone. Manually reviewing large diffs to ensure every requirement in a workplan was met is time-consuming. Solution: The `judge_workplan` tool automates the "Manager AI" pattern. It compares a specific Git branch (head) against the main branch (base) and evaluates the changes against the original workplan stored in a GitHub issue. It provides detailed feedback on whether the implementation matches the original intent. Example: After an AI agent finishes a task, the developer runs `judge_workplan`. Yellhorn creates a "judgement" sub-issue on GitHub, pointing out that while the logic was implemented, the agent forgot to update the documentation files specified in the original workplan, and suggests the specific lines to add.

Use Case 3: Intelligent Context Optimization for Token Efficiency Problem: Sending an entire codebase to an LLM for every single request is expensive and can exceed context limits or "confuse" the model with irrelevant files (e.g., assets, logs, or unrelated modules). Solution: The `curate_context` tool analyzes the user's specific task and the repository structure to generate a `.yellhorncontext` file. This acts as a whitelist, narrowing the AI's focus to only the relevant directories and files needed for that specific task. Example: A developer wants to fix a bug in the React frontend. They use `curate_context` with the task "Fix checkout button alignment." Yellhorn identifies that only `src

components/checkout/`…

Key facts

Part of MCP Servers

Related MCP servers

MCP LaTeX Server — Create, edit, and manage LaTeX files. Requires an external LaTeX distribution like MiKTeX, TeX Live, or MacTeX.
MCP JSON — A collection of servers for file system operations, Google search, web automation, and executing terminal commands.
MCP Jupyter Complete — A server for Jupyter notebook manipulation with position-based operations and VS Code integration.
MCP LSP Go — An MCP server that connects AI assistants to Go's Language Server Protocol (LSP) for advanced code analysis.
MCP Kanban Memory — Manage complex AI agent workflows with a Kanban-based task management system.
MCP Manager — A full-stack application for managing Model Context Protocol (MCP) servers for Claude Desktop with a modern web interface.