MCP Startup Framework

Un framework para construir servidores MCP en Cloudflare Workers con OAuth,

GitHub
128
Prueba este MCPPatrocinado

Documentación

MCP Startup Framework

Un framework completo para construir servidores remotos de Model Context Protocol (MCP) en Cloudflare Workers con autenticación OAuth, base de datos PostgreSQL y herramientas de pago impulsadas por Stripe.

🚀 Características

  • 🔐 Proveedor OAuth 2.1 - Autenticación completa con registro/inicio de sesión de usuarios
  • 🗄️ Integración con PostgreSQL - Base de datos escalable lista para producción con agrupación de conexiones
  • 💳 Framework de Herramientas de Pago - Herramientas premium impulsadas por Stripe con soporte de suscripciones
  • 🌐 Agnóstico de Plataforma - Optimizado para Cloudflare Workers pero desplegable en cualquier lugar (Vercel, Railway, AWS, autoalojado)
  • 🛠️ Framework de Herramientas MCP - Sistema modular de herramientas con contexto de usuario
  • 🔌 Rutas de API REST - Sistema fácil de usar para añadir endpoints personalizados
  • 🎨 Vistas Personalizadas - Sistema de UI extensible para políticas de privacidad, términos de servicio y páginas de documentación
  • 📡 Transporte Streamable HTTP - Funciona con mcp-remote para integración local con Claude Desktop
  • 📱 Multiplataforma - Funciona en clientes MCP de escritorio, web y móvil

⚡ Inicio Rápido

Requisitos Previos

Instalación

# 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

Configuración

Edita .dev.vars con tus ajustes:

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"

Desarrollo

# 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

🛠️ Añadir Herramientas y Rutas

Todo comienza desde 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 })
  );

Consulta la Guía de Herramientas y la Guía de Rutas para más detalles.

Vistas Personalizadas

Ve más allá de MCP con 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()));

Consulta la Guía de Vistas para crear páginas personalizadas.

🚀 Despliegue

# 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

Consulta la Guía de Despliegue para instrucciones completas.

🔗 Opciones de Integración

Usando claude.ai (Plan Pro)

Para usuarios de claude.ai Pro, puedes integrarte directamente:

  1. Navega a configuración de claude.ai
  2. Haz clic en "Añadir Integración"
  3. Introduce la URL de tu servidor: https://your-domain.workers.dev/sse
  4. Completa el flujo de OAuth

Usando Claude Desktop

Para la aplicación local de Claude Desktop:

1. Instalar el Cliente Remoto MCP

npm install -g mcp-remote

2. Configurar Claude Desktop

Abre la configuración de Claude Desktop: Configuración > Desarrollador > Editar Config

Añade a tu claude_desktop_config.json:

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

3. Reiniciar Claude Desktop

Después de guardar, reinicia Claude Desktop. Tus herramientas MCP aparecerán en la interfaz de chat.

Opciones de Transporte

El framework soporta múltiples protocolos de transporte:

  • Streamable HTTP (predeterminado) - endpoint /mcp
  • Server-Sent Events (SSE) - endpoint /sse

Ambos funcionan perfectamente con mcp-remote para desarrollo local y uso en producción.

🌐 Flexibilidad de Plataforma

Aunque está optimizado para Cloudflare Workers, este framework funciona en cualquier lugar:

  • Vercel: Despliega con el runtime @vercel/node
  • Railway: Despliegue con un clic con PostgreSQL integrado
  • AWS Lambda: Úsalo con RDS o Aurora Serverless
  • Google Cloud Run: Despliega con Cloud SQL
  • Autoalojado: Ejecútalo con Docker en cualquier VPS

¡Simplemente actualiza tu conexión de base de datos y tu configuración de despliegue!

Base de Datos de Producción

El framework funciona con cualquier proveedor de PostgreSQL:

  • Neon - PostgreSQL serverless con autoescalado
  • Supabase - PostgreSQL con funciones en tiempo real
  • Railway - PostgreSQL gestionado con copias de seguridad automáticas
  • Amazon RDS - PostgreSQL de nivel empresarial
  • Cloudflare Hyperdrive - Agrupación de conexiones para un rendimiento óptimo

Todos los proveedores soportan la escalabilidad necesaria para servidores MCP de producción.

📚 Documentación

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.