Yellhorn MCP

Um servidor MCP que

Documentação

Yellhorn MCP

Yellhorn Logo

Um servidor Model Context Protocol (MCP) que fornece funcionalidade para criar planos de trabalho detalhados para implementar uma tarefa ou funcionalidade. Esses planos de trabalho são gerados com um modelo grande e poderoso (como gemini 2.5 pro ou até mesmo a API o3 deep research), inserem todo o seu código-fonte na janela de contexto por padrão, e também podem acessar contexto de URL e fazer pesquisa na web dependendo do modelo utilizado. Esse padrão de criar planos de trabalho usando um modelo de raciocínio poderoso é extremamente útil para definir o trabalho a ser feito por assistentes de código como Claude Code ou outros agentes de codificação compatíveis com MCP, além de fornecer uma referência para revisar a saída de tais modelos de codificação e garantir que atendam exatamente aos requisitos originais especificados.

Funcionalidades

Criar Planos de Trabalho: Cria planos de implementação detalhados com base em um prompt e levando em consideração todo o seu código-fonte, publicando-os como issues do GitHub e expondo-os como recursos MCP para o seu agente de codificação
Avaliar Diffs de Código: Fornece uma ferramenta para avaliar git diffs contra o plano de trabalho original com contexto completo do código-fonte e fornece feedback detalhado, garantindo que a implementação não se desvie dos requisitos originais e fornecendo orientação sobre o que alterar para isso
Integração Perfeita com GitHub: Cria automaticamente issues rotuladas, publica sub-issues de avaliação com referências às issues do plano de trabalho original
Controle de Contexto: Use arquivos .yellhornignore para excluir arquivos e diretórios específicos do contexto de IA, semelhante ao .gitignore
Recursos MCP: Expõe planos de trabalho como recursos MCP padrão para fácil listagem e recuperação
Fundamentação com Pesquisa Google: Habilitada por padrão para modelos Gemini, fornecendo capacidades de pesquisa com citações formatadas automaticamente em Markdown
Fragmentação Automática: Lida com grandes bases de código que excedem os limites de contexto do modelo, dividindo prompts de forma inteligente
Tratamento de Limites de Taxa: Lógica de nova tentativa robusta com backoff exponencial para limites de taxa e falhas transitórias
Rastreamento de Custos: Estimativa de custo em tempo real e rastreamento de uso para todas as chamadas de API
Suporte a Múltiplos Modelos: Interface unificada que suporta modelos OpenAI (GPT-4o, GPT-5, o3, o4-mini), xAI Grok (Grok-4, Grok-4 Fast) e Gemini (2.5-pro, 2.5-flash) com suporte a modo de raciocínio para GPT-5

Instalação

Bootstrap do projeto (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 provisiona .venv, instala o pacote em modo editável e aplica o grupo de dependências dev definido em pyproject.toml.

Instalar a partir do PyPI

uv pip install yellhorn-mcp

Configuração

O servidor requer as seguintes variáveis de ambiente:

GEMINI_API_KEY: Sua chave de API Gemini (necessária para modelos Gemini)
OPENAI_API_KEY: Sua chave de API OpenAI (necessária para modelos OpenAI)
XAI_API_KEY: Sua chave de API xAI (necessária para modelos Grok)
REPO_PATH: Caminho para o seu repositório (padrão: diretório atual)
YELLHORN_MCP_MODEL: Modelo a ser usado (padrão: "gemini-2.5-pro"). Opções disponíveis:
- 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" (suportam modo de raciocínio para gpt-5 e gpt-5-mini)
- Modelos xAI Grok: "grok-4" (contexto de 256K) e "grok-4-fast" (contexto de 2M)
- Modelos Deep Research: "o3-deep-research", "o4-mini-deep-research"
- Nota: Modelos Deep Research (incluindo GPT-5) habilitam automaticamente as ferramentas web_search_preview e code_interpreter para capacidades aprimoradas de pesquisa
YELLHORN_MCP_REASONING_EFFORT: Define o nível de esforço de raciocínio para modelos GPT-5. Opções: "low", "medium", "high". Isso fornece capacidades de raciocínio aprimoradas a um custo maior para modelos suportados (gpt-5, gpt-5-mini). O nível de esforço determina a quantidade de computação usada para raciocínio, com níveis mais altos fornecendo raciocínio mais completo a um custo aumentado. O servidor agora encaminha esse valor para cada solicitação GPT-5 e as métricas de custo incluem automaticamente o prêmio de raciocínio apropriado.
YELLHORN_MCP_SEARCH: Ativa/desativa a Fundamentação com Pesquisa Google (padrão: "on" para modelos Gemini). Opções:
- "on" - Fundamentação de pesquisa habilitada para modelos Gemini
- "off" - Fundamentação de pesquisa desabilitada para todos os modelos

ℹ️ Os modelos Grok agora usam o xai-sdk oficial; certifique-se de que ele esteja instalado no ambiente (está incluído nas dependências do projeto, mas implantações personalizadas devem adicioná-lo explicitamente).

O servidor também requer que o GitHub CLI (gh) esteja instalado e autenticado.

Uso

Primeiros Passos

Configuração do Codex CLI

Adicione a configuração do servidor abaixo ao seu config.toml do Codex CLI (~/.config/codex/config.toml por padrão). Atualize o GEMINI_API_KEY (ou troque por OPENAI_API_KEY/XAI_API_KEY e ajuste o modelo) e os valores de REPO_PATH para corresponder ao seu ambiente.

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

Reinicie o Codex após atualizar a configuração para que ele reconheça o novo servidor MCP.

Configuração no VSCode/Cursor

Para configurar o Yellhorn MCP no VSCode ou Cursor, crie um arquivo .vscode/mcp.json na raiz do seu workspace com o seguinte conteúdo:

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

Configuração do Claude Code

Para configurar o Yellhorn MCP com Claude Code diretamente, adicione um arquivo .mcp.json de nível raiz no seu projeto com o seguinte conteúdo:

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

Ferramentas

curate_context

Analisa o código-fonte e cria um arquivo .yellhorncontext listando diretórios a serem incluídos no contexto de IA. Esta ferramenta ajuda a otimizar o contexto de IA entendendo a tarefa que você deseja realizar e criando uma lista de permissões de diretórios relevantes, reduzindo significativamente o uso de tokens e melhorando o foco da IA no código relevante.

Entrada:

user_task: Descrição da tarefa que você deseja realizar
codebase_reasoning: (opcional) Controla o nível de análise do código-fonte:
- "file_structure": (padrão) Análise básica da estrutura de arquivos (mais rápida)
- "lsp": Apenas assinaturas de funções e docstrings (mais leve)
- "full": Conteúdo completo dos arquivos (mais abrangente)
- "none": Sem contexto do código-fonte
ignore_file_path: (opcional) Caminho para o arquivo de ignorados (padrão: .yellhornignore)
output_path: (opcional) Caminho de saída para o arquivo de contexto (padrão: .yellhorncontext)
depth_limit: (opcional) Profundidade máxima de diretório a analisar (0 = sem limite)
disable_search_grounding: (opcional) Se definido como true, desabilita a Fundamentação com Pesquisa Google para esta solicitação

Saída:

String JSON contendo:
- context_file_path: Caminho para o arquivo .yellhorncontext criado
- directories_included: Número de diretórios incluídos no contexto
- files_analyzed: Número de arquivos analisados durante a curadoria

O arquivo .yellhorncontext atua como uma lista de permissões - apenas arquivos que correspondem aos padrões serão incluídos em chamadas subsequentes de plano de trabalho/avaliação. Isso reduz significativamente o uso de tokens e melhora o foco da IA no código relevante.

Exemplo de saída .yellhorncontext:

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

create_workplan

Cria uma issue do GitHub com um plano de trabalho detalhado com base no título e na descrição detalhada.

Entrada:

title: Título para a issue do GitHub (será usado como título da issue e cabeçalho)
detailed_description: Descrição detalhada para o plano de trabalho. Quaisquer URLs fornecidas aqui serão extraídas e incluídas em uma seção de Referências.
codebase_reasoning: (opcional) Controla se o aprimoramento por IA é realizado:
- "full": (padrão) Usa IA para aprimorar o plano de trabalho com contexto completo do código-fonte
- "lsp": Usa IA com contexto leve do código-fonte (assinaturas de funções/métodos, atributos de classe e campos de struct para Python e Go)
- "none": Pula o aprimoramento por IA, usa a descrição fornecida como está
debug: (opcional) Se definido como true, adiciona um comentário à issue com o prompt completo usado para geração
disable_search_grounding: (opcional) Se definido como true, desabilita a Fundamentação com Pesquisa Google para esta solicitação

Saída:

String JSON contendo:
- issue_url: URL para a issue do GitHub criada
- issue_number: O número da issue do GitHub

get_workplan

Recupera o conteúdo do plano de trabalho (corpo da issue do GitHub) associado a um plano de trabalho.

Entrada:

issue_number: O número da issue do GitHub para o plano de trabalho.
disable_search_grounding: (opcional) Se definido como true, desabilita a Fundamentação com Pesquisa Google para esta solicitação

Saída:

O conteúdo da issue do plano de trabalho como uma string

revise_workplan

Atualiza um plano de trabalho existente com base em instruções de revisão. A ferramenta busca o plano de trabalho atual da issue do GitHub especificada e usa IA para revisá-lo de acordo com suas instruções.

Entrada:

issue_number: O número da issue do GitHub contendo o plano de trabalho a ser revisado
revision_instructions: Instruções descrevendo como revisar o plano de trabalho
codebase_reasoning: (opcional) Controla se o aprimoramento por IA é realizado:
- "full": (padrão) Usa IA para revisar com contexto completo do código-fonte
- "lsp": Usa IA com contexto leve do código-fonte (apenas assinaturas de funções/métodos)
- "file_structure": Usa IA com apenas estrutura de diretórios (mais rápida)
- "none": Contexto mínimo do código-fonte
debug: (opcional) Se definido como true, adiciona um comentário à issue com o prompt completo usado para geração
disable_search_grounding: (opcional) Se definido como true, desabilita a Fundamentação com Pesquisa Google para esta solicitação

Saída:

String JSON contendo:
- issue_url: URL para a issue do GitHub atualizada
- issue_number: O número da issue do GitHub

judge_workplan

Aciona uma avaliação de código assíncrona comparando duas refs git (branches ou commits) contra um plano de trabalho descrito em uma issue do GitHub. Cria uma sub-issue placeholder do GitHub imediatamente e depois processa a avaliação por IA assincronamente, atualizando a sub-issue com os resultados.

Entrada:

issue_number: O número da issue do GitHub para o plano de trabalho.
base_ref: Ref git base (SHA de commit, nome de branch, tag) para comparação. Padrão: 'main'.
head_ref: Ref git head (SHA de commit, nome de branch, tag) para comparação. Padrão: 'HEAD'.
codebase_reasoning: (opcional) Controla qual contexto do código-fonte é fornecido:
- "full": (padrão) Usa contexto completo do código-fonte
- "lsp": Usa contexto mais leve do código-fonte (apenas assinaturas de funções para Python e Go, além dos arquivos diff completos)
- "file_structure": Usa apenas estrutura de diretórios sem conteúdo de arquivos para processamento mais rápido
- "none": Pula o contexto do código-fonte completamente para processamento mais rápido
debug: (opcional) Se definido como true, adiciona um comentário à sub-issue com o prompt completo usado para geração
disable_search_grounding: (opcional) Se definido como true, desabilita a Fundamentação com Pesquisa Google para esta solicitação

Quaisquer URLs mencionadas no plano de trabalho serão extraídas e preservadas em uma seção de Referências na avaliação.

Saída:

String JSON contendo:
- message: Confirmação de que a tarefa de avaliação foi iniciada
- subissue_url: URL para a sub-issue placeholder criada onde os resultados serão publicados
- subissue_number: O número da issue do GitHub da sub-issue placeholder

Sistema de Filtragem de Arquivos

O Yellhorn MCP fornece um sistema sofisticado de filtragem de arquivos em múltiplas camadas para controlar quais arquivos são incluídos no contexto de IA. O sistema segue uma ordem de prioridade para determinar a inclusão de arquivos:

Camadas de Filtro (em ordem de prioridade)

Lista de permissões .yellhorncontext: Se este arquivo existir e contiver padrões, SOMENTE arquivos que correspondem a esses padrões são incluídos
Lista de bloqueio .yellhorncontext: Arquivos que correspondem aos padrões de bloqueio (começando com !) são excluídos
Lista de permissões .yellhornignore: Arquivos que correspondem aos padrões de permissão (começando com !) são explicitamente incluídos
Lista de bloqueio .yellhornignore: Arquivos que correspondem a esses padrões são excluídos
Lista de bloqueio .gitignore: Arquivos ignorados pelo git são automaticamente excluídos

Padrões Sempre Ignorados

Os seguintes padrões são sempre ignorados, independentemente de outras configurações:

.git/ - Metadados do Git
__pycache__/ - Arquivos de cache do Python
node_modules/ - Dependências do Node.js
*.pyc - Arquivos compilados do Python
.venv/, venv/ - Ambientes virtuais do Python

Formato do Arquivo

Tanto os arquivos .yellhornignore quanto os .yellhorncontext seguem uma sintaxe semelhante à do gitignore:

Um padrão por linha
Linhas que começam com # são comentários
Linhas vazias são ignoradas
Use o prefixo ! para padrões de lista de permissões (incluir explicitamente)
Padrões de diretórios devem terminar com /

Exemplo de `.yellhornignore`

# Exclude test files
tests/
*.test.js

# Exclude build artifacts
dist/
build/

# But include important test utilities
!tests/utils/

Exemplo de `.yellhorncontext`

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

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

Acesso a Recursos

O Yellhorn MCP também implementa a API de recursos padrão do MCP para fornecer acesso aos planos de trabalho:

list-resources: Lista todos os planos de trabalho (issues do GitHub com o rótulo yellhorn-mcp)
get-resource: Recupera o conteúdo de um plano de trabalho específico pelo número da issue

Eles podem ser acessados por meio dos comandos padrão da CLI do MCP:

# List all workplans
mcp list-resources yellhorn-mcp

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

Desenvolvimento

# 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

O projeto usa GitHub Actions para integração contínua e implantação:

Testes: Executados automaticamente em pull requests e pushes para o branch principal
- Lint com flake8
- Verificação de formatação com black
- Testes com pytest
Publicação: Publica automaticamente no PyPI quando uma tag de versão é enviada
- A tag deve corresponder à versão em pyproject.toml (ex.: v0.2.2)
- Requer um token de API do PyPI armazenado como um segredo do repositório GitHub (PYPI_API_TOKEN)

Para lançar uma nova versão:

Atualize a versão em pyproject.toml e yellhorn_mcp/init.py
Atualize o CHANGELOG.md com as novas alterações
Faça commit das alterações: git commit -am "Bump version to X.Y.Z"
Crie a tag do commit: git tag vX.Y.Z
Envie as alterações e a tag: git push && git push --tags

Para um histórico de alterações, consulte o Changelog.

Para instruções mais detalhadas, consulte o Guia de Uso.

Licença

MIT

Yellhorn MCP

Documentação

Yellhorn MCP

Funcionalidades

Instalação

Bootstrap do projeto (uv)

Instalar a partir do PyPI

Configuração

Uso

Primeiros Passos

Configuração do Codex CLI

Configuração no VSCode/Cursor

Configuração do Claude Code

Ferramentas

curate_context

create_workplan

get_workplan

revise_workplan

judge_workplan

Sistema de Filtragem de Arquivos

Camadas de Filtro (em ordem de prioridade)

Padrões Sempre Ignorados

Formato do Arquivo

Exemplo de .yellhornignore

Exemplo de .yellhorncontext

Acesso a Recursos

Desenvolvimento

CI/CD

Licença

Exemplo de `.yellhornignore`

Exemplo de `.yellhorncontext`