mcp-rubber-duck

MCP Rubber Duck

Um servidor MCP (Model Context Protocol) que atua como uma ponte para consultar múltiplos LLMs — tanto APIs HTTP compatíveis com OpenAI quanto agentes de codificação CLI. Assim como na depuração com rubber duck, explique seus problemas para vários "patos" de IA e obtenha diferentes perspectivas!

Por que integração direta com provedores? A primitiva sampling do MCP — um servidor que empresta o modelo do host — foi descontinuada na especificação RC de 2026-07-28 em favor de servidores que se integram diretamente com as APIs dos provedores de LLM. O Rubber Duck sempre funcionou dessa forma (ele traz seus próprios patos), então está alinhado com o rumo do protocolo — sem necessidade de migração.

Recursos

• Compatibilidade Universal com OpenAI — Funciona com qualquer endpoint de API compatível com OpenAI
• Suporte a Agentes CLI — Use agentes de codificação CLI (Claude Code, Codex, Gemini CLI, Grok, Aider) como patos
• Múltiplos Patos — Configure e consulte vários provedores de LLM simultaneamente
• Gerenciamento de Conversas — Mantenha contexto entre múltiplas mensagens
• Conselho de Patos — Obtenha respostas de todos os seus LLMs configurados de uma só vez
• Votação por Consenso — Votação multi-pato com raciocínio e pontuações de confiança
• LLM como Juiz — Faça os patos avaliarem e classificarem as respostas uns dos outros
• Refinamento Iterativo — Dois patos melhoram respostas colaborativamente
• Debates Estruturados — Formatos de debate Oxford, Socrático e adversarial
• Prompts MCP — 8 modelos de prompt reutilizáveis para fluxos de trabalho multi-LLM
• Entrada de Visão — Envie imagens junto com prompts para modelos com capacidade de visão (docs)
• Failover Automático — Alterna para outros provedores se o principal falhar
• Monitoramento de Saúde — Verificações de saúde em tempo real para todos os provedores
• Rastreamento de Uso — Rastreie requisições, tokens e custos estimados por provedor
• Ponte MCP — Conecte patos a outros servidores MCP para funcionalidade estendida (docs)
• Proteções — Camada de segurança plugável com limite de taxa, limites de tokens, bloqueio de padrões e redação de PII (docs)
• Segurança Granular — Controles de aprovação por servidor com aprovações baseadas em sessão
• UIs Interativas — Painéis HTML ricos para ferramentas de comparação, votação, debate e uso (via MCP Apps)
• Anotações de Ferramentas — Dicas compatíveis com MCP para comportamento de ferramentas (somente leitura, destrutivas, etc.)
• Saída Estruturada — outputSchema em ferramentas que retornam JSON estruturado para validação no lado do cliente (Cursor, VS Code/Copilot)
• Alinhado à Especificação por Design — conecta-se diretamente às APIs dos provedores, o caminho que a especificação 2026-07-28 do MCP recomenda agora que o sampling no lado do servidor foi descontinuado (SEP-2577)

Provedores Suportados

Provedores HTTP (API compatível com OpenAI)

Qualquer provedor com endpoint de API compatível com OpenAI, incluindo:

• OpenAI
• Google Gemini
• Anthropic (via endpoints compatíveis com OpenAI)
• Groq (inferência rápida para modelos de pesos abertos)
• Together AI (amplo catálogo de modelos de pesos abertos)
• Perplexity (modelos online com busca na web)
• Anyscale, Azure OpenAI, Ollama, LM Studio, Customizado

Provedores CLI (Agentes de Codificação)

Agentes de codificação de linha de comando que rodam como processos locais:

• Claude Code (claude) — Codex (codex) — Gemini CLI (gemini) — Grok CLI (grok) — Aider (aider) — Customizado

Consulte Provedores CLI para configuração completa.

Início Rápido

# Install globally
npm install -g mcp-rubber-duck

# Or use npx directly in Claude Desktop config
npx mcp-rubber-duck

Usando Claude Desktop? Vá para Configuração do Claude Desktop. Usando Cursor, VS Code, Windsurf ou outra ferramenta? Consulte o Guia de Configuração.

Instalação

Pré-requisitos

• Node.js 20 ou superior
• npm ou yarn
• Pelo menos uma chave de API para um provedor HTTP, ou um agente de codificação CLI instalado localmente

Instalar a partir do NPM

npm install -g mcp-rubber-duck

Instalar a partir do Código Fonte

git clone https://github.com/nesquikm/mcp-rubber-duck.git
cd mcp-rubber-duck
npm install
npm run build
npm start

Configuração

Crie um arquivo .env ou config/config.json. Principais variáveis de ambiente:

Variável	Descrição
OPENAI_API_KEY	Chave da API OpenAI
GEMINI_API_KEY	Chave da API Google Gemini
GROQ_API_KEY	Chave da API Groq
DEFAULT_PROVIDER	Provedor padrão (ex.: openai)
DEFAULT_TEMPERATURE	Temperatura padrão (ex.: 0.7)
LOG_LEVEL	debug, info, warn, error
MCP_SERVER	Defina como true para modo servidor MCP
MCP_BRIDGE_ENABLED	Habilita a Ponte MCP (patos acessam servidores MCP externos)
CUSTOM_{NAME}_*	Provedores HTTP customizados
CLI_{AGENT}_ENABLED	Habilita agentes CLI (CLAUDE, CODEX, GEMINI, GROK, AIDER)

Referência completa: Documentação de Configuração

UIs Interativas (MCP Apps)

Quatro ferramentas — compare_ducks, duck_vote, duck_debate e get_usage_stats — podem renderizar painéis HTML interativos ricos dentro de clientes MCP suportados via MCP Apps. Uma vez que este servidor MCP esteja configurado em um cliente compatível, as UIs aparecem automaticamente — sem configuração adicional necessária. Clientes sem suporte a MCP Apps ainda recebem a mesma saída de texto simples (nenhuma funcionalidade é perdida). Consulte o repositório MCP Apps para uma lista atualizada de clientes suportados.

Comparar Patos

Compare múltiplas respostas de modelos lado a lado, com indicadores de latência, contagens de tokens, selos de modelo e estados de erro.

Votação de Patos

Faça múltiplos patos votarem em opções, exibido como uma contagem visual de votos com gráficos de barras, selo de consenso, cartão do vencedor, barras de confiança e raciocínio recolhível.

Debate de Patos

Debate estruturado multi-round entre patos, mostrado como uma visão round a round com selo de formato, lista de participantes, rounds recolhíveis e seção de síntese.

Estatísticas de Uso

Análises de uso com cartões de resumo, detalhamento por provedor com linhas expansíveis, barras de distribuição de tokens e custos estimados.

Ferramentas Disponíveis

Ferramenta	Descrição
ask_duck	Faça uma única pergunta a um provedor de LLM específico
chat_with_duck	Conversa com contexto mantido entre mensagens
clear_conversations	Limpe todo o histórico de conversas
list_ducks	Liste provedores configurados e status de saúde
list_models	Liste modelos disponíveis para provedores
compare_ducks	Faça a mesma pergunta a múltiplos provedores simultaneamente
duck_council	Obtenha respostas de todos os patos configurados
get_usage_stats	Estatísticas de uso e custos estimados
duck_vote	Votação multi-pato com raciocínio e confiança
duck_judge	Faça um pato avaliar e classificar as respostas dos outros
duck_iterate	Refine iterativamente uma resposta entre dois patos
duck_debate	Debate estruturado multi-round entre patos
mcp_status	Status da Ponte MCP e servidores conectados
get_pending_approvals	Solicitações pendentes de aprovação de ferramentas MCP
approve_mcp_request	Aprove ou negue uma solicitação de ferramenta MCP de um pato

Referência completa com esquemas de entrada: Documentação de Ferramentas

Prompts Disponíveis

Prompt	Finalidade	Argumentos Obrigatórios
perspectives	Análise multi-ângulo com lentes atribuídas	problem, perspectives
assumptions	Superficie suposições ocultas em planos	plan
blindspots	Procure por riscos e lacunas negligenciados	proposal
tradeoffs	Comparação estruturada de opções	options, criteria
red_team	Análise de segurança/risco de múltiplos ângulos	target
reframe	Reformulação de problemas em diferentes níveis	problem
architecture	Revisão de design em diferentes preocupações	design, workloads, priorities
diverge_converge	Exploração divergente e depois convergência	challenge

Referência completa com exemplos: Documentação de Prompts

Desenvolvimento

npm run dev        # Development with watch mode
npm test           # Run all tests
npm run lint       # ESLint
npm run typecheck  # Type check without emit

Documentação

Tópico	Link
Guia de configuração (todas as ferramentas)	docs/setup.md
Referência completa de configuração	docs/configuration.md
Configuração do Claude Desktop	docs/claude-desktop.md
Todas as ferramentas com esquemas	docs/tools.md
Modelos de prompt	docs/prompts.md
Agentes de codificação CLI	docs/cli-providers.md
Ponte MCP	docs/mcp-bridge.md
Proteções	docs/guardrails.md
Implantação Docker	docs/docker.md
Configuração específica por provedor	docs/provider-setup.md
Exemplos de uso	docs/usage-examples.md
Arquitetura	docs/architecture.md
Roadmap	docs/roadmap.md

Solução de Problemas

Provedor Não Funcionando

1. Verifique se a chave da API está configurada corretamente
2. Verifique se a URL do endpoint está correta
3. Execute a verificação de saúde: list_ducks({ check_health: true })
4. Verifique os logs para mensagens de erro detalhadas

Problemas de Conexão

• Para provedores locais (Ollama, LM Studio), certifique-se de que estão em execução
• Verifique as configurações de firewall para endpoints locais
• Verifique a conectividade de rede com provedores em nuvem

Limite de Taxa

• Configure failover para provedores alternativos
• Ajuste as configurações de max_retries e timeout
• Consulte Proteções para configuração de limite de taxa

Contribuindo

     __
   <(o )___
    ( ._> /
     `---'  Quack! Ready to debug!

Adoramos contribuições! Seja corrigindo bugs, adicionando recursos ou ensinando novos truques aos nossos patos, adoraríamos ter você no bando.

Consulte nosso Guia de Contribuição para começar.

Início rápido para contribuidores:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Siga nossas diretrizes de commit convencional
4. Adicione testes para novas funcionalidades
5. Envie um pull request

Licença

Licença MIT — consulte o arquivo LICENSE para detalhes

Agradecimentos

• Inspirado pelo método de depuração com rubber duck
• Construído sobre o Model Context Protocol (MCP)
• Usa o SDK da OpenAI para compatibilidade com provedores HTTP
• Suporta agentes de codificação CLI (Claude Code, Codex, Gemini CLI, Grok, Aider)

Changelog

Consulte CHANGELOG.md para um histórico detalhado de mudanças e versões.

Registro e Diretórios

• Pacote NPM: npmjs.com/package/mcp-rubber-duck
• Imagens Docker: ghcr.io/nesquikm/mcp-rubber-duck
• Registro MCP: Servidor MCP oficial io.github.nesquikm/rubber-duck
• Diretório Glama: glama.ai/mcp/servers/@nesquikm/mcp-rubber-duck
• Awesome MCP Servers: Listado no diretório da comunidade

Suporte

• Reporte problemas: https://github.com/nesquikm/mcp-rubber-duck/issues
• Documentação: https://github.com/nesquikm/mcp-rubber-duck/wiki
• Discussões: https://github.com/nesquikm/mcp-rubber-duck/discussions

---

Feliz Depuração com seu Painel de Patos de IA!