BeefChicken MCP

BeefChicken MCP 🚀

---

💡 O que é isso?

BeefChicken MCP é um servidor MCP genérico (proxy) que permite que qualquer Web API seja chamada diretamente por clientes MCP, como Claude ou Cursor, bastando apenas colocar um openapi.yaml.

Nenhum código de implementação dependente de API específica é necessário. Como um servidor OAuth 2.1 simplificado está incluído para clientes que não podem especificar chaves de API diretamente, você pode conectar diretamente ao Claude.ai (versão Web).

graph LR
    subgraph Client [AIクライアント]
        Claude[🤖 Claude.ai / Cursor 等]
    end

    subgraph Proxy [BeefChicken MCP]
        MCP[⚡ MCPサーバー<br/>Workers / Node.js / Docker]
        OAuth[🔐 内蔵 OAuth 2.1]
    end

    subgraph Target [接続先API]
        Spec[📄 docs/openapi.yaml]
        API[🌐 対象Web API<br/>Stripe / GitHub / 社内API]
    end

    Spec -->|ビルド時/起動時に静的JSON化| MCP
    Claude -->|MCPプロトコル / OAuth| MCP
    MCP -->|ネイティブfetch| API

---

⚡ Por que BeefChicken MCP?

❌ Problemas tradicionais

• Para criar um servidor MCP, é necessário escrever definições de ferramentas e manipuladores de requisição em TypeScript ou Python.
• Corrigir, testar e reimplantar o código a cada mudança na especificação da API é trabalhoso.
• Você quer usar suas próprias ferramentas no Claude.ai (versão Web), mas o obstáculo de construir um servidor de autenticação OAuth 2.1 é alto.

✅ Com BeefChicken MCP

• 🧩 0 linhas de código: Basta substituir o docs/openapi.yaml pelo documento de especificação da API que você deseja conectar!
• 🔐 Compatível imediatamente com Claude.ai (versão Web): Com o servidor OAuth 2.1 simplificado integrado, conectores personalizados do Claude Web também conectam em um clique.
• ⚡️ Custo de manutenção do servidor: R$ 0: Implante em segundos no Cloudflare Workers (também compatível com Docker / Node.js). Dentro do plano gratuito, o servidor MCP é seu de graça.
• 📥 Caminho mais curto, sem necessidade de implantação: Para clientes locais como Claude Desktop, não é necessário clonar nem compilar. Inicie imediatamente com npx beefchicken-mcp a partir do npm.
• 📦 Ultraleve e zero overhead de parsing: O documento OpenAPI é convertido em JSON estático no momento do build (Workers), na inicialização (Docker) ou antes da implantação via npm run generate (Node.js). Nenhum parsing YAML é necessário durante o processamento de requisições.

---

📊 Comparação com outras abordagens

Recurso / Característica	Implementação manual (SDK TS/Python)	Frameworks MCP comuns (FastMCP etc.)	BeefChicken MCP
Escrita de código	Necessária (muita)	Necessária (pouca)	Desnecessária (0 linhas, basta colocar YAML)
Suporte a OpenAPI	❌ Requer conversão manual	⚠️ Requer implementação de handlers	✅ Apenas substituir o arquivo
Servidor OAuth 2.1 integrado	❌ Precisa criar do zero	❌ Precisa criar do zero	✅ Integrado (compatível com Claude Web imediatamente)
Cloudflare Workers	⚠️ Requer ajustes	⚠️ Requer ajustes	✅ Totalmente compatível (implantação com botão)
Pegada em tempo de execução	-	Média a grande	Mínima (JSON estático)

---

✨ Principais características

• 🧩 Concluído apenas substituindo o arquivo de configuração: Transforme qualquer Web API em ferramenta MCP sem escrever uma única linha de código.
• 🎯 Design focado em proxy dedicado: Elimina a escrita de handlers complexos e opera como um proxy puro conforme a especificação.
• 📦 Conversão para JSON estático: Sem parser YAML em tempo de execução ou lógica de resolução de $ref, minimizando o tamanho do bundle do Worker.
• 🔌 Retransmissão nativa de fetch: Retransmite respostas diretamente, sem bibliotecas HTTP clientes desnecessárias.
• 🛡️ Stateless e robusto: Configuração responseMode: 'json' que não depende de conexões SSE de longa duração. Design robusto e resistente a limites de timeout.
• 📦 4 formas de distribuição: Cloudflare Workers / Node.js / imagem Docker (GHCR) / CLI npm (npx beefchicken-mcp). Escolha conforme a necessidade.

⚠️ Atenção antes da publicação em produção: Este servidor não possui limite de taxa. Ao publicar, controle com Rate Limiting Rules do Cloudflare ou um proxy reverso. Além disso, o servidor OAuth 2.1 incluído é uma implementação simplificada. Consulte a documentação de autenticação para detalhes.

---

🚀 Início rápido

1. Colocação do documento de especificação

Substitua o docs/openapi.yaml pelo documento de especificação OpenAPI 3.0 da API que você deseja conectar.

💡 Dica: OpenAPI padrão de Stripe, GitHub etc. podem ser obtidos oficialmente ou em APIs.guru.

npm install
npm run generate   # docs/openapi.yaml を解析し、src/generated/tools.json を自動生成

2. Implantação / Execução

Para clientes MCP locais (Claude Desktop etc.) — caminho mais curto:

npx beefchicken-mcp --openapi /絶対パス/to/openapi.yaml

Como é distribuído como pacote npm, não é necessário clonar nem implantar (neste caminho, o npm install / npm run generate do passo 1 também não é necessário; a especificação indicada é analisada em memória a cada inicialização). Consulte o passo 4 para saber como registrar especificamente na configuração do cliente.

Para Cloudflare Workers:

npx wrangler deploy

Se for bem-sucedido, um https://beefchicken-mcp.<あなたのサブドメイン>.workers.dev/mcp será emitido (detalhes como configuração D1 estão em procedimento de implantação).

Para Node.js:

API_BASE_URL=https://api.example.com npm run node:dev

Para Docker:

docker run -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e ALLOWED_HOSTS=127.0.0.1,localhost \
  -e API_BASE_URL=https://api.example.com \
  -v $(pwd)/docs/openapi.yaml:/app/docs/openapi.yaml:ro \
  ghcr.io/watanabebashi/beefchicken-mcp

A imagem é distribuída via GHCR, sem necessidade de build. Ao montar seu próprio openapi.yaml, ele é analisado na inicialização do contêiner para gerar o tools.json (se não montar, o documento de especificação de exemplo incluído é usado). As tags disponíveis são latest (última versão), vX.Y.Z (versão específica fixa) e edge (build mais recente do branch main). Para testar alterações locais, você pode compilar com docker build -t beefchicken-mcp . como de costume.

3. Conexão a partir do cliente

Configure no cliente MCP a URL emitida com o cabeçalho Authorization: Bearer <対象APIのAPIキー>.

4. Uso direto de clientes MCP locais (Claude Desktop etc.)

Para clientes que iniciam o servidor MCP como subprocesso, como Claude Desktop / Claude Code, você pode conectar diretamente via npx sem implantação. Adicione o seguinte ao arquivo de configuração (ex.: claude_desktop_config.json).

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["beefchicken-mcp", "--openapi", "/絶対パス/to/your-api-openapi.yaml"],
      "env": {
        "API_KEY": "<対象APIのAPIキー>",
        "API_BASE_URL": "https://api.example.com"
      }
    }
  }
}

• Se você especificar um caminho absoluto para o documento de especificação OpenAPI da API de destino em --openapi, as definições de ferramentas serão geradas em memória a cada inicialização (o npm run generate prévio não é necessário). O mesmo comportamento ocorre com o argumento posicional sem a flag (["beefchicken-mcp", "/絶対パス/to/your-api-openapi.yaml"]). Se nenhum caminho for especificado, ele usa o src/generated/tools.json pré-gerado no repositório clonado (se não existir, para com erro na inicialização). Não há documento de especificação padrão relativo ao cwd intencionalmente. Como o cwd ao iniciar o subprocesso pelo cliente MCP é imprevisível, especifique sempre um caminho absoluto.
• API_KEY é obrigatório. O modo stdio não passa pelo servidor OAuth simplificado para a versão Web; o valor de API_KEY é usado diretamente como Authorization: Bearer para a API de destino.
• Se quiser registrar o repositório clonado no cliente, defina command como npx, args como ["tsx", "src/stdio.ts", "--openapi", "./docs/openapi.yaml"] e cwd (se o cliente suportar) como a raiz do repositório; o mesmo ponto de entrada (src/stdio.ts) será iniciado (não use npm run stdio na configuração do cliente, pois a saída do banner de npm se mistura à saída padrão e corrompe a comunicação JSON-RPC do stdio. Use apenas para verificar a operação isolada no seu terminal).

---

📚 Documentação

Tópico	Conteúdo
🔑 Autenticação	Método de envio da chave de API, política de design e conexão de conectores personalizados para claude.ai Web
☁️ Implantação	Procedimentos de implantação em Cloudflare Workers / Node.js / Docker
⚙️ Variáveis de ambiente	Referência de todos os itens de configuração
🛠 Desenvolvimento	Execução local, procedimentos de teste, atualização do OpenAPI e verificação de segurança

---

📜 Licença

Licença MIT. Consulte LICENSE para detalhes.