cardosolucass96/mcp-cloudflare-workers-template

🚀 MCP Cloudflare Workers Template

Template profissional para desenvolvimento de servidores MCP (Model Context Protocol) otimizado para Cloudflare Workers com TypeScript.

⚡ Por que Cloudflare Workers?

• ✅ Deploy global em segundos - CDN em 300+ cidades
• ✅ Serverless - Zero configuração de infraestrutura
• ✅ Escalabilidade automática - Lida com milhões de requisições
• ✅ Custo baixo - 100.000 requisições/dia grátis
• ✅ Latência ultra-baixa - Edge computing
• ✅ Desenvolvimento rápido - Hot reload local com Inspector

🎯 Desenvolvimento Prático em 2 Modos

1. Desenvolvimento Local com Inspector (Debug Completo)

npm run dev

O que acontece:

1. ✅ Compila TypeScript automaticamente
2. ✅ Inicia servidor MCP via stdio
3. ✅ Abre Inspector no navegador
4. ✅ Conecta automaticamente

Ideal para:

• Testar ferramentas em tempo real
• Ver mensagens JSON cliente/servidor
• Debug de schemas e validações
• Desenvolvimento rápido de features

2. Deploy para Cloudflare Workers (Produção)

npm run cf:dev     # Testa localmente como Workers
npm run cf:deploy  # Deploy global em segundos

Ideal para:

• Testar em ambiente real
• APIs HTTP públicas
• Integrações web
• Produção escalável

🚀 Início Rápido

Instalação

npm install

Desenvolvimento

npm run dev

Este comando abre o Inspector automaticamente para desenvolvimento com debug completo.

📁 Estrutura do Projeto

mcp-cloudflare-workers-template/
├── src/
│   ├── index.ts          # Servidor MCP via stdio (Inspector)
│   └── worker.ts         # Versão Cloudflare Workers (HTTP)
├── dist/                 # Código compilado
├── llms-full.txt         # Documentação MCP oficial
├── wrangler.toml         # Config Cloudflare Workers
├── tsconfig.json         # Config TypeScript
└── package.json

🔧 Comandos

🛠️ Criar Suas Ferramentas MCP

1. Definir Ferramentas

Edite src/index.ts e src/worker.ts:

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "buscar_usuario",
        description: "Busca informações de um usuário",
        inputSchema: {
          type: "object",
          properties: {
            id: {
              type: "string",
              description: "ID do usuário",
            },
          },
          required: ["id"],
        },
      },
    ],
  };
});

2. Implementar Lógica

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case "buscar_usuario":
      // Sua lógica aqui
      const usuario = await buscarUsuario((args as any).id);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(usuario),
          },
        ],
      };
  }
});

3. Testar

npm run dev

O Inspector abre automaticamente. Teste suas ferramentas em tempo real!

☁️ Deploy para Cloudflare Workers

1. Login na Cloudflare

npx wrangler login

2. Testar Localmente

npm run cf:dev

Servidor disponível em: http://localhost:8787

Endpoints disponíveis:

• GET /health - Health check
• GET /sse - Server-Sent Events (streaming)
• POST /tools/{nome} - Chamar ferramentas

3. Deploy Global

npm run cf:deploy

Pronto! Sua aplicação está rodando globalmente em:

https://mcp-cloudflare-workers-template.seu-usuario.workers.dev

🌐 Usando em Produção

Via HTTP (Cloudflare Workers)

# Health check
curl https://your-worker.workers.dev/health

# Chamar ferramenta
curl -X POST https://your-worker.workers.dev/tools/echo \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello MCP!"}'

# SSE Streaming
curl https://your-worker.workers.dev/sse

Via Stdio (Aplicações Locais)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"],
});

const client = new Client(
  { name: "my-client", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

📋 Diferenças: Local vs Cloudflare

📚 Documentação MCP

Este template inclui llms-full.txt com a documentação oficial completa do MCP.

Recursos:

• MCP Documentation
• MCP TypeScript SDK
• Cloudflare Workers
• Wrangler CLI

🎓 Exemplos de Uso

Ferramentas Incluídas

1. echo - Retorna mensagem enviada
2. get_time - Retorna timestamp atual

Adicionar Mais Ferramentas

O template é extensível. Adicione:

• Integração com APIs externas
• Acesso a banco de dados (D1, KV)
• Processamento de dados
• Webhooks
• E muito mais!

🤝 Contribuindo

1. Fork este template
2. Crie sua feature branch
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

📄 Licença

MIT

🚀 Vantagens do Template

✅ Produtividade - npm run dev e comece a desenvolver
✅ Escalável - Deploy global automático
✅ Econômico - Serverless, pague apenas pelo uso
✅ Rápido - Hot reload + Inspector integrado
✅ Moderno - TypeScript + Cloudflare Workers

Pronto para começar? Execute npm run dev e desenvolva seu servidor MCP! 🚀