Custom MCP Server

Un servidor MCP versátil construido con Next.js, que proporciona una variedad de herramientas y utilidades con gestión de estado en Redis.

GitHubPrueba este MCPPatrocinado

Documentación

Custom MCP Server 🤖

Un servidor de Protocolo de Contexto de Modelo (MCP) construido con Next.js, que proporciona herramientas y utilidades útiles a través de transportes HTTP y Eventos Enviados por el Servidor (SSE).

🚀 Características

🔧 Herramientas Disponibles

  • echo - Devuelve cualquier mensaje (perfecto para pruebas)
  • get-current-time - Obtiene la marca de tiempo actual y la fecha ISO
  • calculate - Realiza cálculos matemáticos básicos de forma segura

🌐 Métodos de Transporte

  • Transporte HTTP (/mcp) - Solicitudes HTTP sin estado (funciona sin Redis)
  • Transporte SSE (/sse) - Eventos Enviados por el Servidor con Redis para gestión de estado

🔒 Características de Seguridad

  • Límite de solicitudes (100 solicitudes por minuto)
  • Evaluación segura de expresiones matemáticas
  • Sanitización y validación de entradas

🏃‍♂️ Inicio Rápido

Requisitos Previos

  • Node.js 18+
  • npm o yarn
  • Docker (opcional, para Redis local)

Configuración

  1. Clonar e instalar dependencias:

    npm install

  2. Ejecutar la configuración automatizada:

    npm run setup

    Esto hará lo siguiente:

    • Crear la configuración del entorno
    • Configurar Redis (Docker) si está disponible
    • Iniciar el servidor de desarrollo automáticamente

  3. Inicio manual (alternativa):

    npm run dev

El servidor estará disponible en http://localhost:3000

🧪 Pruebas

Pruebas Rápidas

# Test HTTP transport
npm run test:http

# Test SSE transport (requires Redis)
npm run test:sse

# Test with Claude Desktop protocol
npm run test:stdio

# Comprehensive tool testing
npm run test:tools

Pruebas Manuales

Puedes probar el servidor MCP manualmente usando curl:

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call the echo tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello World!"
      }
    }
  }'

# Calculate an expression
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "expression": "15 * 4 + 10"
      }
    }
  }'

🔧 Configuración

Variables de Entorno

Crea un archivo .env.local:

# Local Redis (Docker)
REDIS_URL=redis://localhost:6379

# Upstash Redis (Production)
UPSTASH_REDIS_REST_URL=your-upstash-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-token

Configuración de Redis

El servidor detecta y utiliza Redis automáticamente en este orden de prioridad:

  1. Upstash Redis (si UPSTASH_REDIS_REST_URL y UPSTASH_REDIS_REST_TOKEN están configurados)
  2. Redis local (si REDIS_URL está configurado)
  3. Sin Redis (solo transporte HTTP)

Redis local con Docker

# The setup script handles this automatically, but you can also run manually:
docker run -d --name redis-mcp -p 6379:6379 redis:alpine

Upstash Redis (Recomendado para Producción)

  1. Crea una base de datos Upstash Redis en upstash.com
  2. Agrega los detalles de conexión a tu .env.local
  3. El servidor la detectará y utilizará automáticamente

🖥️ Integración con Herramientas de IA

Claude Desktop

Agrega a tu configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

Ubicaciones de los archivos de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

IDE Cursor

Para Cursor 0.48.0 o posterior (soporte directo de SSE):

{
  "mcpServers": {
    "custom-mcp": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Para versiones anteriores de Cursor:

{
  "mcpServers": {
    "custom-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/mcp"
      ]
    }
  }
}

🛠️ Desarrollo

Estructura del Proyecto

custom-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts          # Main MCP server logic
│   ├── layout.tsx            # Root layout
│   └── page.tsx              # Home page
├── lib/
│   └── redis.ts              # Redis utilities
├── scripts/
│   ├── setup.mjs             # Automated setup
│   ├── test-http-client.mjs  # HTTP transport tests
│   ├── test-sse-client.mjs   # SSE transport tests
│   └── test-tools.mjs        # Comprehensive tool tests
├── package.json
├── next.config.ts
└── README.md

Agregar Nuevas Herramientas

  1. Define la herramienta en app/[transport]/route.ts:
const tools = {
  // ... existing tools
  myNewTool: {
    name: "my-new-tool",
    description: "Description of what your tool does",
    inputSchema: {
      type: "object",
      properties: {
        param1: {
          type: "string",
          description: "Description of parameter"
        }
      },
      required: ["param1"]
    }
  }
};
  1. Agrega el manejador:
const toolHandlers = {
  // ... existing handlers
  "my-new-tool": async ({ param1 }: { param1: string }) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: `Result: ${param1}`
        }
      ]
    };
  }
};

Pruebas de tus Cambios

# Run all tests
npm run test:tools

# Test specific functionality
npm run test:http
npm run test:sse

📝 Referencia de la API

Tools/List

Obtén todas las herramientas disponibles:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Tools/Call

Llama a una herramienta específica:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "tool-name",
    "arguments": {
      "param": "value"
    }
  }
}

🚀 Despliegue

Vercel (Recomendado)

  1. Despliega en Vercel:

    vercel

  2. Agrega las variables de entorno en el panel de Vercel:

    • UPSTASH_REDIS_REST_URL
    • UPSTASH_REDIS_REST_TOKEN

  3. Actualiza las configuraciones de tus herramientas de IA para usar la URL desplegada:

    https://your-app.vercel.app/mcp
https://your-app.vercel.app/sse

Otras Plataformas

El servidor es una aplicación Next.js estándar y se puede desplegar en cualquier plataforma que admita Node.js:

  • Netlify
  • Railway
  • Render
  • Plataforma de aplicaciones de DigitalOcean

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características: git checkout -b feature/my-new-feature
  3. Realiza tus cambios y agrega pruebas
  4. Ejecuta el conjunto de pruebas: npm run test:tools
  5. Confirma tus cambios: git commit -am 'Add some feature'
  6. Sube la rama: git push origin feature/my-new-feature
  7. Envía una solicitud de extracción

📄 Licencia

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

🆘 Solución de Problemas

Problemas Comunes

El servidor no se inicia:

  • Verifica si el puerto 3000 está disponible
  • Asegúrate de que todas las dependencias estén instaladas: npm install

Problemas de conexión con Redis:

  • Verifica que Docker esté ejecutándose: docker ps
  • Comprueba el estado del contenedor de Redis: docker ps -a | grep redis-mcp
  • Reinicia Redis: docker restart redis-mcp

La herramienta de IA no detecta el servidor:

  • Asegúrate de que el servidor esté ejecutándose y sea accesible
  • Verifica la sintaxis del archivo de configuración (JSON válido)
  • Reinicia tu herramienta de IA después de los cambios de configuración
  • Verifica que la URL del servidor sea correcta

Las llamadas a herramientas fallan:

  • Revisa los registros del servidor para ver mensajes de error
  • Prueba las herramientas manualmente con npm run test:tools
  • Verifica que los parámetros de la herramienta coincidan con el esquema esperado

Modo de Depuración

Habilita el registro de depuración configurando la variable de entorno:

DEBUG=1 npm run dev

📞 Soporte

  • Crea un issue en GitHub para informar errores
  • Revisa los issues existentes para problemas comunes
  • Consulta los scripts de prueba para ver ejemplos de uso