MCP Startup Framework

Um framework para construir servidores MCP no Cloudflare Workers com OAuth, PostgreSQL e Stripe.

GitHub
128
Experimente este MCPPatrocinado

Documentação

MCP Startup Framework

Um framework completo para construir servidores remotos Model Context Protocol (MCP) no Cloudflare Workers com autenticação OAuth, banco de dados PostgreSQL e ferramentas pagas com tecnologia Stripe.

🚀 Recursos

  • 🔐 Provedor OAuth 2.1 - Autenticação completa com registro/login de usuário
  • 🗄️ Integração PostgreSQL - Banco de dados escalável pronto para produção com connection pooling
  • 💳 Framework de Ferramentas Pagas - Ferramentas premium com tecnologia Stripe e suporte a assinaturas
  • 🌐 Agnóstico de Plataforma - Otimizado para Cloudflare Workers, mas implantável em qualquer lugar (Vercel, Railway, AWS, self-hosted)
  • 🛠️ Framework de Ferramentas MCP - Sistema modular de ferramentas com contexto de usuário
  • 🔌 Rotas de API REST - Sistema fácil de usar para adicionar endpoints personalizados
  • 🎨 Visualizações Personalizadas - Sistema de UI extensível para políticas de privacidade, Termos de Serviço, páginas de documentação
  • 📡 Transporte HTTP Streamable - Funciona com mcp-remote para integração local com Claude Desktop
  • 📱 Multiplataforma - Funciona em clientes MCP de desktop, web e mobile

⚡ Início Rápido

Pré-requisitos

Instalação

# Clone the repository
git clone https://github.com/f/mcp-startup-framework
cd mcp-startup-framework

# Install dependencies
npm install

# Copy environment template
cp .dev.vars.example .dev.vars

Configuração

Edite .dev.vars com suas configurações:

DATABASE_URL="postgresql://username:password@host:port/database"
JWT_SECRET="your-super-secret-jwt-key"
COOKIE_ENCRYPTION_KEY="32-character-encryption-key"
STRIPE_SECRET_KEY="sk_test_your_stripe_key"
STRIPE_PRICE_ID_FOR_PREMIUM_MATH="price_your_stripe_price_id"
BASE_URL="https://your-domain.workers.dev"

Desenvolvimento

# Start development server
npm run dev

# Initialize database (in another terminal)
curl -X POST http://localhost:8787/init-db

# Visit http://localhost:8787 to register/login

🛠️ Adicionando Ferramentas e Rotas

Tudo começa a partir de src/index.ts:

// Register MCP tools
backend
  .registerTool(registerAddTool)
  .registerTool(registerGreetingTool)
  .registerTool(registerPremiumMathTool);

// Add REST API routes
backend
  .route('GET', '/api/status', (c) => c.json({ status: 'ok' }))
  .authRoute('GET', '/api/profile', (c, userContext) => 
    c.json({ user: userContext })
  );

Consulte o Guia de Ferramentas e o Guia de Rotas para detalhes.

Visualizações Personalizadas

Vá além do MCP com páginas personalizadas:

// Add privacy policy, terms of service, documentation
backend
  .route('GET', '/privacy', (c) => c.html(generatePrivacyPage()))
  .route('GET', '/terms', (c) => c.html(generateTermsPage()))
  .route('GET', '/docs', (c) => c.html(generateDocsPage()));

Consulte o Guia de Visualizações para criar páginas personalizadas.

🚀 Implantação

# Set production secrets
wrangler secret put JWT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put STRIPE_SECRET_KEY

# Set custom price IDs per paid tool
wrangler secret put STRIPE_PRICE_ID_FOR_PREMIUM_MATH

# Deploy to Cloudflare
npm run deploy

Consulte o Guia de Implantação para instruções completas.

🔗 Opções de Integração

Usando claude.ai (Plano Pro)

Para usuários do claude.ai Pro, você pode integrar diretamente:

  1. Navegue até configurações do claude.ai
  2. Clique em "Adicionar Integração"
  3. Insira a URL do seu servidor: https://your-domain.workers.dev/sse
  4. Complete o fluxo OAuth

Usando Claude Desktop

Para o aplicativo local Claude Desktop:

1. Instale o Cliente Remoto MCP

npm install -g mcp-remote

2. Configure o Claude Desktop

Abra as configurações do Claude Desktop: Configurações > Desenvolvedor > Editar Config

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "my-startup": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-domain.workers.dev/mcp"
      ]
    }
  }
}

3. Reinicie o Claude Desktop

Após salvar, reinicie o Claude Desktop. Suas ferramentas MCP aparecerão na interface de chat.

Opções de Transporte

O framework suporta múltiplos protocolos de transporte:

  • HTTP Streamable (padrão) - endpoint /mcp
  • Server-Sent Events (SSE) - endpoint /sse

Ambos funcionam perfeitamente com mcp-remote para desenvolvimento local e uso em produção.

🌐 Flexibilidade de Plataforma

Embora otimizado para Cloudflare Workers, este framework roda em qualquer lugar:

  • Vercel: Implante com o runtime @vercel/node
  • Railway: Implantação com um clique com PostgreSQL integrado
  • AWS Lambda: Use com RDS ou Aurora Serverless
  • Google Cloud Run: Implante com Cloud SQL
  • Self-hosted: Execute com Docker em qualquer VPS

Basta atualizar sua conexão de banco de dados e configuração de implantação!

Banco de Dados de Produção

O framework funciona com qualquer provedor PostgreSQL:

  • Neon - PostgreSQL serverless com autoescalonamento
  • Supabase - PostgreSQL com recursos em tempo real
  • Railway - PostgreSQL gerenciado com backups automáticos
  • Amazon RDS - PostgreSQL de nível empresarial
  • Cloudflare Hyperdrive - Connection pooling para desempenho ideal

Todos os provedores suportam a escalabilidade necessária para servidores MCP em produção.

📚 Documentação

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.