Yellhorn MCP

Un servidor MCP que integra los modelos Gemini 2.5 Pro y OpenAI para tareas de desarrollo de software, permitiendo usar todo tu código base como contexto.

GitHub

Prueba este MCPPatrocinado

Documentación

Yellhorn MCP

Yellhorn Logo

Un servidor de Model Context Protocol (MCP) que proporciona funcionalidad para crear planes de trabajo detallados para implementar una tarea o funcionalidad. Estos planes de trabajo se generan con un modelo grande y potente (como gemini 2.5 pro o incluso la API o3 deep research), insertan todo tu código fuente en la ventana de contexto por defecto, y también pueden acceder al contexto de URL y realizar búsquedas web dependiendo del modelo utilizado. Este patrón de crear planes de trabajo usando un modelo de razonamiento potente es muy útil para definir el trabajo a realizar por asistentes de código como Claude Code u otros agentes de codificación compatibles con MCP, así como para proporcionar una referencia para revisar la salida de dichos modelos de codificación y asegurar que cumplen exactamente con los requisitos originales especificados.

Características

Crear planes de trabajo: Crea planes de implementación detallados basados en un prompt y teniendo en cuenta todo tu código fuente, publicándolos como issues de GitHub y exponiéndolos como recursos MCP para tu agente de codificación
Evaluar diffs de código: Proporciona una herramienta para evaluar diffs de git contra el plan de trabajo original con contexto completo del código fuente y proporciona retroalimentación detallada, asegurando que la implementación no se desvíe de los requisitos originales y proporcionando orientación sobre qué cambiar para lograrlo
Integración perfecta con GitHub: Crea automáticamente issues etiquetados, publica sub-issues de evaluación con referencias a los issues del plan de trabajo original
Control de contexto: Usa archivos .yellhornignore para excluir archivos y directorios específicos del contexto de IA, similar a .gitignore
Recursos MCP: Expone los planes de trabajo como recursos MCP estándar para facilitar su listado y recuperación
Fundamentación de búsqueda de Google: Habilitada por defecto para modelos Gemini, proporcionando capacidades de búsqueda con citas formateadas automáticamente en Markdown
Fragmentación automática: Maneja códigos fuente grandes que exceden los límites de contexto del modelo dividiendo inteligentemente los prompts
Manejo de límites de tasa: Lógica de reintento robusta con retroceso exponencial para límites de tasa y fallos transitorios
Seguimiento de costos: Estimación de costos en tiempo real y seguimiento de uso para todas las llamadas a la API
Soporte multi-modelo: Interfaz unificada que soporta modelos OpenAI (GPT-4o, GPT-5, o3, o4-mini), xAI Grok (Grok-4, Grok-4 Fast) y Gemini (2.5-pro, 2.5-flash) con soporte de modo de razonamiento para GPT-5

Instalación

Inicialización del proyecto (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 aprovisiona .venv, instala el paquete en modo editable y aplica el grupo de dependencias dev definido en pyproject.toml.

Instalar desde PyPI

uv pip install yellhorn-mcp

Configuración

El servidor requiere las siguientes variables de entorno:

GEMINI_API_KEY: Tu clave API de Gemini (requerida para modelos Gemini)
OPENAI_API_KEY: Tu clave API de OpenAI (requerida para modelos OpenAI)
XAI_API_KEY: Tu clave API de xAI (requerida para modelos Grok)
REPO_PATH: Ruta a tu repositorio (por defecto el directorio actual)
YELLHORN_MCP_MODEL: Modelo a utilizar (por defecto "gemini-2.5-pro"). Opciones disponibles:
- Modelos Gemini: "gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite"
- Modelos OpenAI: "gpt-4o", "gpt-4o-mini", "o4-mini", "o3", "gpt-4.1"
- Modelos GPT-5: "gpt-5", "gpt-5-mini", "gpt-5-nano" (soporte de modo de razonamiento para gpt-5 y gpt-5-mini)
- Modelos xAI Grok: "grok-4" (contexto de 256K) y "grok-4-fast" (contexto de 2M)
- Modelos Deep Research: "o3-deep-research", "o4-mini-deep-research"
- Nota: Los modelos Deep Research (incluyendo GPT-5) habilitan automáticamente las herramientas web_search_preview y code_interpreter para capacidades de investigación mejoradas
YELLHORN_MCP_REASONING_EFFORT: Establece el nivel de esfuerzo de razonamiento para modelos GPT-5. Opciones: "low", "medium", "high". Esto proporciona capacidades de razonamiento mejoradas a mayor costo para modelos compatibles (gpt-5, gpt-5-mini). El nivel de esfuerzo determina la cantidad de cómputo utilizado para el razonamiento, con niveles más altos proporcionando un razonamiento más exhaustivo a un costo mayor. El servidor ahora reenvía este valor a cada solicitud GPT-5 y las métricas de costo incluyen automáticamente la prima de razonamiento apropiada.
YELLHORN_MCP_SEARCH: Habilitar/deshabilitar la fundamentación de búsqueda de Google (por defecto "on" para modelos Gemini). Opciones:
- "on" - Fundamentación de búsqueda habilitada para modelos Gemini
- "off" - Fundamentación de búsqueda deshabilitada para todos los modelos

ℹ️ Los modelos Grok ahora usan el xai-sdk oficial; asegúrate de que esté instalado en el entorno (está incluido en las dependencias del proyecto, pero los despliegues personalizados deberían añadirlo explícitamente).

El servidor también requiere que la CLI de GitHub (gh) esté instalada y autenticada.

Uso

Primeros pasos

Configuración de Codex CLI

Añade la configuración del servidor a continuación a tu config.toml de Codex CLI (~/.config/codex/config.toml por defecto). Actualiza los valores de GEMINI_API_KEY (o intercambia por OPENAI_API_KEY/XAI_API_KEY y ajusta el modelo) y REPO_PATH para que coincidan con tu entorno.

[mcp_servers.yellhorn-mcp]
command = "uv"
args = ["run", "yellhorn-mcp"]
env = { "GEMINI_API_KEY" = "your-api-key", "REPO_PATH" = "/path/to/your/repo" }

Reinicia Codex después de actualizar la configuración para que detecte el nuevo servidor MCP.

Configuración de VSCode/Cursor

Para configurar Yellhorn MCP en VSCode o Cursor, crea un archivo .vscode/mcp.json en la raíz de tu espacio de trabajo con el siguiente contenido:

{
  "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}"
      }
    }
  }
}

Configuración de Claude Code

Para configurar Yellhorn MCP con Claude Code directamente, añade un archivo .mcp.json a nivel de raíz en tu proyecto con el siguiente contenido:

{
  "mcpServers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "yellhorn-mcp", "--model", "o3"],
      "env": {
        "YELLHORN_MCP_SEARCH": "on"
      }
    }
  }
}

Herramientas

curate_context

Analiza el código fuente y crea un archivo .yellhorncontext que lista los directorios a incluir en el contexto de IA. Esta herramienta ayuda a optimizar el contexto de IA al comprender la tarea que deseas realizar y crear una lista blanca de directorios relevantes, reduciendo significativamente el uso de tokens y mejorando el enfoque de la IA en el código relevante.

Entrada:

user_task: Descripción de la tarea que deseas realizar
codebase_reasoning: (opcional) Controla el nivel de análisis del código fuente:
- "file_structure": (por defecto) Análisis básico de la estructura de archivos (más rápido)
- "lsp": Solo firmas de funciones y docstrings (más ligero)
- "full": Contenido completo de archivos (más exhaustivo)
- "none": Sin contexto del código fuente
ignore_file_path: (opcional) Ruta al archivo de ignorados (por defecto .yellhornignore)
output_path: (opcional) Ruta de salida para el archivo de contexto (por defecto .yellhorncontext)
depth_limit: (opcional) Profundidad máxima de directorio a analizar (0 = sin límite)
disable_search_grounding: (opcional) Si se establece en true, deshabilita la fundamentación de búsqueda de Google para esta solicitud

Salida:

Cadena JSON que contiene:
- context_file_path: Ruta al archivo .yellhorncontext creado
- directories_included: Número de directorios incluidos en el contexto
- files_analyzed: Número de archivos analizados durante la curación

El archivo .yellhorncontext actúa como una lista blanca: solo los archivos que coincidan con los patrones se incluirán en llamadas posteriores de plan de trabajo/evaluación. Esto reduce significativamente el uso de tokens y mejora el enfoque de la IA en el código relevante.

Ejemplo de salida de .yellhorncontext:

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

create_workplan

Crea un issue de GitHub con un plan de trabajo detallado basado en el título y la descripción detallada.

Entrada:

title: Título para el issue de GitHub (se usará como título y encabezado del issue)
detailed_description: Descripción detallada para el plan de trabajo. Cualquier URL proporcionada aquí se extraerá e incluirá en una sección de Referencias.
codebase_reasoning: (opcional) Controla si se realiza el mejoramiento con IA:
- "full": (por defecto) Usar IA para mejorar el plan de trabajo con contexto completo del código fuente
- "lsp": Usar IA con contexto ligero del código fuente (firmas de funciones/métodos, atributos de clase y campos de struct para Python y Go)
- "none": Omitir el mejoramiento con IA, usar la descripción proporcionada tal cual
debug: (opcional) Si se establece en true, añade un comentario al issue con el prompt completo utilizado para la generación
disable_search_grounding: (opcional) Si se establece en true, deshabilita la fundamentación de búsqueda de Google para esta solicitud

Salida:

Cadena JSON que contiene:
- issue_url: URL al issue de GitHub creado
- issue_number: El número del issue de GitHub

get_workplan

Recupera el contenido del plan de trabajo (cuerpo del issue de GitHub) asociado con un plan de trabajo.

Entrada:

issue_number: El número del issue de GitHub para el plan de trabajo.
disable_search_grounding: (opcional) Si se establece en true, deshabilita la fundamentación de búsqueda de Google para esta solicitud

Salida:

El contenido del issue del plan de trabajo como una cadena

revise_workplan

Actualiza un plan de trabajo existente basado en instrucciones de revisión. La herramienta obtiene el plan de trabajo actual del issue de GitHub especificado y usa IA para revisarlo según tus instrucciones.

Entrada:

issue_number: El número del issue de GitHub que contiene el plan de trabajo a revisar
revision_instructions: Instrucciones que describen cómo revisar el plan de trabajo
codebase_reasoning: (opcional) Controla si se realiza el mejoramiento con IA:
- "full": (por defecto) Usar IA para revisar con contexto completo del código fuente
- "lsp": Usar IA con contexto ligero del código fuente (solo firmas de funciones/métodos)
- "file_structure": Usar IA solo con la estructura de directorios (más rápido)
- "none": Contexto mínimo del código fuente
debug: (opcional) Si se establece en true, añade un comentario al issue con el prompt completo utilizado para la generación
disable_search_grounding: (opcional) Si se establece en true, deshabilita la fundamentación de búsqueda de Google para esta solicitud

Salida:

Cadena JSON que contiene:
- issue_url: URL al issue de GitHub actualizado
- issue_number: El número del issue de GitHub

judge_workplan

Activa una evaluación de código asíncrona que compara dos refs de git (ramas o commits) contra un plan de trabajo descrito en un issue de GitHub. Crea un sub-issue de GitHub de marcador de posición inmediatamente y luego procesa la evaluación de IA de forma asíncrona, actualizando el sub-issue con los resultados.

Entrada:

issue_number: El número del issue de GitHub para el plan de trabajo.
base_ref: Ref de git base (SHA de commit, nombre de rama, etiqueta) para la comparación. Por defecto 'main'.
head_ref: Ref de git head (SHA de commit, nombre de rama, etiqueta) para la comparación. Por defecto 'HEAD'.
codebase_reasoning: (opcional) Controla qué contexto del código fuente se proporciona:
- "full": (por defecto) Usar contexto completo del código fuente
- "lsp": Usar contexto más ligero del código fuente (solo firmas de funciones para Python y Go, más archivos diff completos)
- "file_structure": Usar solo la estructura de directorios sin contenidos de archivos para un procesamiento más rápido
- "none": Omitir completamente el contexto del código fuente para el procesamiento más rápido
debug: (opcional) Si se establece en true, añade un comentario al sub-issue con el prompt completo utilizado para la generación
disable_search_grounding: (opcional) Si se establece en true, deshabilita la fundamentación de búsqueda de Google para esta solicitud

Cualquier URL mencionada en el plan de trabajo se extraerá y conservará en una sección de Referencias en la evaluación.

Salida:

Cadena JSON que contiene:
- message: Confirmación de que la tarea de evaluación se ha iniciado
- subissue_url: URL al sub-issue de marcador de posición creado donde se publicarán los resultados
- subissue_number: El número del issue de GitHub del sub-issue de marcador de posición

Sistema de filtrado de archivos

Yellhorn MCP proporciona un sistema sofisticado de filtrado de archivos de múltiples capas para controlar qué archivos se incluyen en el contexto de IA. El sistema sigue un orden de prioridad para determinar la inclusión de archivos:

Capas de filtrado (en orden de prioridad)

Lista blanca .yellhorncontext: Si este archivo existe y contiene patrones, SOLO se incluyen los archivos que coinciden con estos patrones
Lista negra .yellhorncontext: Los archivos que coinciden con patrones de lista negra (que comienzan con !) se excluyen
Lista blanca .yellhornignore: Los archivos que coinciden con patrones de lista blanca (que comienzan con !) se incluyen explícitamente
Lista negra .yellhornignore: Los archivos que coinciden con estos patrones se excluyen
Lista negra .gitignore: Los archivos ignorados por git se excluyen automáticamente

Patrones siempre ignorados

Los siguientes patrones siempre se ignoran independientemente de otras configuraciones:

.git/ - metadatos de Git
__pycache__/ - archivos de caché de Python
node_modules/ - dependencias de Node.js
*.pyc - archivos compilados de Python
.venv/, venv/ - entornos virtuales de Python

Formato de archivo

Tanto los archivos .yellhornignore como .yellhorncontext siguen una sintaxis similar a gitignore:

Un patrón por línea
Las líneas que comienzan con # son comentarios
Las líneas vacías se ignoran
Usa el prefijo ! para patrones de lista blanca (incluir explícitamente)
Los patrones de directorio deben terminar con /

Ejemplo `.yellhornignore`

# Exclude test files
tests/
*.test.js

# Exclude build artifacts
dist/
build/

# But include important test utilities
!tests/utils/

Ejemplo `.yellhorncontext`

# Only include source code and documentation
src/
docs/
README.md

# Exclude generated files even in src
!src/generated/

Acceso a recursos

Yellhorn MCP también implementa la API de recursos estándar de MCP para proporcionar acceso a los planes de trabajo:

list-resources: Lista todos los planes de trabajo (issues de GitHub con la etiqueta yellhorn-mcp)
get-resource: Recupera el contenido de un plan de trabajo específico por número de issue

Se puede acceder a ellos mediante los comandos estándar de la CLI de MCP:

# List all workplans
mcp list-resources yellhorn-mcp

# Get a specific workplan by issue number
mcp get-resource yellhorn-mcp 123

Desarrollo

# 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

El proyecto utiliza GitHub Actions para la integración y el despliegue continuos:

Pruebas: Se ejecutan automáticamente en pull requests y pushes a la rama principal
- Linting con flake8
- Verificación de formato con black
- Pruebas con pytest
Publicación: Publica automáticamente en PyPI cuando se empuja una etiqueta de versión
- La etiqueta debe coincidir con la versión en pyproject.toml (p. ej., v0.2.2)
- Requiere un token de API de PyPI almacenado como secreto del repositorio de GitHub (PYPI_API_TOKEN)

Para publicar una nueva versión:

Actualiza la versión en pyproject.toml y yellhorn_mcp/init.py
Actualiza CHANGELOG.md con los nuevos cambios
Haz commit de los cambios: git commit -am "Bump version to X.Y.Z"
Etiqueta el commit: git tag vX.Y.Z
Empuja los cambios y la etiqueta: git push && git push --tags

Para un historial de cambios, consulta el Changelog.

Para instrucciones más detalladas, consulta la Guía de uso.

Licencia

MIT

Yellhorn MCP

Documentación

Yellhorn MCP

Características

Instalación

Inicialización del proyecto (uv)

Instalar desde PyPI

Configuración

Uso

Primeros pasos

Configuración de Codex CLI

Configuración de VSCode/Cursor

Configuración de Claude Code

Herramientas

curate_context

create_workplan

get_workplan

revise_workplan

judge_workplan

Sistema de filtrado de archivos

Capas de filtrado (en orden de prioridad)

Patrones siempre ignorados

Formato de archivo

Ejemplo .yellhornignore

Ejemplo .yellhorncontext

Acceso a recursos

Desarrollo

CI/CD

Licencia

Ejemplo `.yellhornignore`

Ejemplo `.yellhorncontext`