MCP Server Starter

Una plantilla inicial en TypeScript para construir servidores del Protocolo de Contexto de Modelo (MCP).

GitHub
34
Prueba este MCPPatrocinado

Documentación

¿Qué es MCP?

smithery badge

El Protocolo de Contexto de Modelos (MCP) es un marco especializado diseñado para optimizar el proceso de habilitar agentes de IA para interactuar con una amplia variedad de herramientas. Esta plantilla de inicio te ayuda a construir rápidamente un servidor MCP usando TypeScript. Proporciona una base sólida que puedes extender fácilmente para crear herramientas MCP avanzadas e integrarlas sin problemas con diversas plataformas de IA.

Componentes Principales

  • Servidores MCP: Estos servidores actúan como puentes, exponiendo APIs, bases de datos y bibliotecas de código a hosts de IA externos. Al implementar un servidor MCP en TypeScript, los desarrolladores pueden compartir fuentes de datos o lógica computacional de manera estandarizada usando JSON-RPC 2.0.
  • Clientes MCP: Son el lado orientado al consumidor de MCP, comunicándose con servidores para consultar datos o realizar acciones. Los clientes MCP usan SDKs de TypeScript, garantizando interacciones seguras de tipos y un enfoque uniforme para el uso de herramientas.
  • Hosts MCP: Sistemas como Claude, Cursor, Windsurf, Cline y otras plataformas basadas en TypeScript coordinan solicitudes entre servidores y clientes, asegurando un flujo de datos fluido. Un solo servidor MCP puede ser accedido por múltiples hosts de IA sin integraciones personalizadas.

Implementación en TypeScript

El SDK de TypeScript para MCP proporciona clases principales para construir servidores:

import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "mcp-server-starter", version: "1.0.0", capabilities: { tools: {}, // Habilitar capacidad de herramientas resources: {}, // Habilitar acceso a recursos prompts: {}, // Habilitar manejo de prompts streaming: true // Habilitar respuestas en streaming } });

// Conectar transporte const transport = new StdioServerTransport(); await server.connect(transport);

Al usar MCP, los desarrolladores ya no necesitan código personalizado complejo para integrar nuevas herramientas o servicios. En su lugar, construyen un servidor MCP y lo ponen a disposición de los hosts compatibles.

Requisitos Previos

  • Node.js (v18 o posterior): Una versión moderna de Node.js que aprovecha las últimas características de JavaScript y mejoras de rendimiento.
  • npm (v7 o posterior): Garantiza compatibilidad para instalar y gestionar paquetes.
  • VS Code con la extensión Dev Containers: Te permite crear rápidamente un entorno de desarrollo reproducible, haciendo la colaboración más fácil y eficiente.

Estructura del Proyecto

Un diseño de archivos típico para la plantilla del servidor MCP puede verse así:

mcp-server/
├── .devcontainer/        # Dev container configuration
│   └── devcontainer.json
├── src/
│   ├── index.ts         # MCP Server main entry point
│   └── examples/        # Example tool implementations
│       ├── calculator.ts # Calculator tool example
│       └── rest-api.ts  # REST API tool example
├── package.json         # Project configuration
└── tsconfig.json        # TypeScript configuration

El directorio .devcontainer optimiza el desarrollo basado en contenedores, mientras que la carpeta src/ alberga la lógica principal del servidor y ejemplos de herramientas personalizadas. Esta estructura mantiene tu proyecto organizado y fácil de navegar.

Inicio Rápido

Instalación mediante Smithery

Para instalar MCP Server Starter en cualquier cliente compatible:

Para Claude

npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client claude

Para Cursor

npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cursor

Para Windsurf

npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client windsurf

Para Cline

npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cline

Para TypeScript

npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client typescript

  1. Clona esta plantilla: Recupera los archivos del repositorio desde tu fuente preferida.
  2. Ábrela en VS Code con Dev Containers: Si tienes la extensión Dev Containers instalada, se te pedirá abrir este proyecto dentro de un contenedor.
  3. Instala las dependencias:
    npm install
    Este comando obtiene e instala todos los paquetes necesarios para el servidor MCP.
  4. Compila el proyecto:
    npm run build
    Esto compila tu código TypeScript a JavaScript, preparándolo para la ejecución.

Scripts de Desarrollo

  • Compilar el proyecto:
    npm run build
    Compila tu código fuente TypeScript y establece permisos de archivo para el punto de entrada principal.
  • Modo de observación:
    npm run watch
    Recompila automáticamente los archivos TypeScript cuando se realizan cambios, ideal para desarrollo activo.
  • Ejecutar con inspector:
    npm run inspector
    Lanza el servidor junto con una herramienta de depuración, permitiéndote rastrear problemas, establecer puntos de interrupción e inspeccionar variables en tiempo real.

Formato de Respuesta de Herramientas

Las herramientas MCP deben devolver respuestas en un formato específico para garantizar una comunicación adecuada con los hosts de IA. Aquí está la estructura:

interface ToolResponse { content: ContentItem[]; isError?: boolean; metadata?: Record<string, unknown>; }

interface ContentItem { type: string; text?: string; mimeType?: string; data?: unknown; }

Los tipos de contenido compatibles incluyen:

  • text: Contenido de texto plano
  • code: Fragmentos de código con especificación de lenguaje opcional
  • image: Imágenes codificadas en Base64 con tipo MIME
  • file: Contenido de archivo con tipo MIME
  • error: Mensajes de error (cuando isError es verdadero)

Ejemplo de respuesta:

return { content: [ { type: "text", text: "Operación completada exitosamente" }, { type: "code", text: "console.log('Hello, World!')", mimeType: "application/javascript" } ] };

Mejores Prácticas de Seguridad

Al desarrollar herramientas MCP, sigue estas pautas de seguridad:

  1. Validación de Entrada:
    • Valida siempre los parámetros de entrada usando esquemas Zod
    • Implementa verificación estricta de tipos
    • Sanea las entradas del usuario antes de procesarlas
    • Usa la opción strict() en los esquemas para prevenir propiedades extra
  2. Manejo de Errores:
    • Nunca expongas detalles de errores internos a los clientes
    • Implementa límites de error adecuados
    • Registra errores de forma segura
    • Devuelve mensajes de error amigables para el usuario
  3. Gestión de Recursos:
    • Implementa procedimientos de limpieza adecuados
    • Maneja señales de terminación de procesos
    • Cierra conexiones y libera recursos
    • Implementa tiempos de espera para operaciones de larga duración
  4. Seguridad de API:
    • Usa protocolos de transporte seguros
    • Implementa limitación de velocidad
    • Almacena datos sensibles de forma segura
    • Usa variables de entorno para la configuración

Ejemplo de implementación segura de herramienta:

const SecureSchema = z.object({ input: z.string() .min(1) .max(1000) .transform(str => str.trim()) .pipe(z.string().regex(/^[a-zA-Z0-9\s]+$/)) });

server.tool( "secure_tool", SecureSchema.shape, async (params) => { try { // Implementar limitación de velocidad await rateLimiter.checkLimit();

  // Procesar entrada validada
  const result = await processSecurely(params.input);

  return {
    content: [{
      type: "text",
      text: result
    }]
  };
} catch (error) {
  // Registrar error internamente
  logger.error(error);

  // Devolver mensaje de error seguro
  return {
    content: [{
      type: "text",
      text: "Ocurrió un error al procesar tu solicitud"
    }],
    isError: true
  };
}

} );

Características Avanzadas

Respuestas en Streaming

MCP admite respuestas en streaming para operaciones de larga duración:

server.tool( "stream_data", StreamSchema.shape, async function* (params) { for (const chunk of dataStream) { yield { content: [{ type: "text", text: chunk }] }; } } );

Tipos de Contenido Personalizados

Puedes definir tipos de contenido personalizados para datos especializados:

interface CustomContent extends ContentItem { type: "custom"; data: { format: string; value: unknown; }; }

Ejecución Asíncrona de Herramientas

Implementa un manejo asíncrono adecuado:

server.tool( "async_operation", AsyncSchema.shape, async (params) => { const operation = await startAsyncOperation();

while (!operation.isComplete()) {
  await operation.wait();
}

return {
  content: [{
    type: "text",
    text: await operation.getResult()
  }]
};

} );

Pruebas y Depuración

Pruebas Unitarias

Usa Jest para probar tus herramientas:

describe('Calculator Tool', () => { let server: McpServer;

beforeEach(() => { server = new McpServer({ name: "test-server", version: "1.0.0" }); registerCalculatorTool(server); });

test('adds numbers correctly', async () => { const result = await server.executeTool('calculate', { a: 5, b: 3, operation: 'add' });

expect(result.content[0].text).toBe('8');

}); });

Herramientas de Depuración

  1. Inspector MCP:
    npm run inspector
    Proporciona inspección en tiempo real de:
    • Registro de herramientas
    • Flujo de solicitudes/respuestas
    • Manejo de errores
    • Métricas de rendimiento
  2. Registro de eventos:
    function logMessage(level: 'info' | 'warn' | 'error', message: string) {
    console.error([${level.toUpperCase()}] ${message});
    }
  3. Seguimiento de errores:
    process.on('uncaughtException', (error: Error) => {
    logMessage('error', Uncaught error: ${error.message});
    // Implementar reporte de errores
    });

Configuración de Transporte

MCP admite múltiples protocolos de transporte:

Transporte stdio

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport(); await server.connect(transport);

Transporte WebSocket

import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js";

const transport = new WebSocketServerTransport({ port: 3000 }); await server.connect(transport);

Transporte Personalizado

import { Transport } from "@modelcontextprotocol/sdk/server/transport.js";

class CustomTransport implements Transport { // Implementar métodos de transporte }

Capacidades del Servidor

Configura las capacidades del servidor:

const server = new McpServer({ name: "mcp-server", version: "1.0.0", capabilities: { tools: {}, // Habilitar capacidad de herramientas streaming: true, // Habilitar soporte de streaming customContent: ["myFormat"], // Definir tipos de contenido personalizados metadata: true // Habilitar soporte de metadatos } });

Integración con Hosts MCP

Soporte Multi-Cliente

Esta plantilla de servidor MCP admite múltiples plataformas de IA de forma nativa:

  1. Claude Desktop:
    • Proporciona un entorno basado en chat
    • Admite todas las capacidades de MCP
    • Ideal para interacciones conversacionales de IA
  2. Cursor:
    • Entorno de desarrollo impulsado por IA
    • Soporte completo de integración de herramientas
    • Perfecto para asistencia de codificación
  3. Windsurf:
    • Plataforma moderna de desarrollo de IA
    • Soporte completo del protocolo MCP
    • Integración optimizada del flujo de trabajo
  4. Cline:
    • Interfaz de IA de línea de comandos
    • Interacciones centradas en herramientas
    • Uso eficiente basado en terminal
  5. TypeScript:
    • Soporte nativo de TypeScript
    • Desarrollo de herramientas con seguridad de tipos
    • Integración perfecta con el SDK

Cada cliente puede configurarse usando el comando CLI de Smithery apropiado:

npx -y @smithery/cli run @TheSethRose/mcp-server-starter --client [client-name]

Reemplaza [client-name] con uno de: claude, cursor, windsurf, cline, o typescript.

Integración con Smithery

Una forma conveniente de ejecutar este servidor MCP es a través de Smithery, una plataforma centralizada para descubrir y publicar servidores MCP. Smithery simplifica el despliegue y garantiza que tu servidor pueda integrarse en varios flujos de trabajo de IA.

Ejecución Rápida

Puedes ejecutar inmediatamente este servidor a través del CLI de Smithery:

npx -y @smithery/cli@latest run mcp-server-template --config "{}"

Smithery obtiene, instala y ejecuta automáticamente el servidor desde su última versión, requiriendo una configuración mínima de tu parte.

Publicar Tu Propia Versión

Si has desarrollado nuevas herramientas o realizado modificaciones locales y deseas compartirlas, considera publicar tu servidor personalizado:

  1. Crea una cuenta en Smithery.
  2. Sigue sus instrucciones de despliegue para empaquetar y publicar tu servidor MCP.
  3. Otros usuarios pueden entonces ejecutar tu servidor a través de Smithery haciendo referencia a tu nombre de paquete único.

Smithery ofrece:

  • Un registro centralizado para descubrir y compartir servidores MCP.
  • Despliegue simplificado, eliminando configuración repetitiva.
  • Un enfoque impulsado por la comunidad donde los desarrolladores contribuyen con diversas herramientas.
  • Integración fácil con hosts de IA populares.

Para obtener orientación adicional:

  • Documentación de Smithery
  • Smithery GitHub

Integración con Cursor

Cursor es otro entorno de desarrollo de IA que soporta MCP. Para incorporar tu servidor en Cursor:

  1. Compila tu servidor:
    npm run build
    Asegúrate de que se genere un ejecutable index.js en el directorio build.
  2. En Cursor, ve a Settings > Features > MCP: Agrega un nuevo servidor MCP.
  3. Registra tu servidor:
    • Selecciona stdio como tipo de transporte.
    • Proporciona un Name descriptivo.
    • Establece el comando, por ejemplo: node /path/to/your/mcp-server/build/index.js.
  4. Guarda tu configuración.

Cursor entonces detecta y lista tus herramientas. Durante sesiones de codificación asistida por IA o interacciones basadas en prompts, llamará a tus herramientas MCP cuando sea relevante. También puedes indicar a la IA que use una herramienta específica por nombre.

Integración con Claude Desktop

Claude Desktop proporciona un entorno basado en chat donde puedes aprovechar las herramientas MCP. Para incluir tu servidor:

  1. Compila tu servidor:
    npm run build
    Confirma que no ocurran errores y que el script principal se genere en build.
  2. Modifica claude_desktop_config.json:
    {
    "mcpServers": {
    "mcp-server": {
    "command": "node",
    "args": [
    "/path/to/your/mcp-server/build/index.js"
    ]
    }
    }
    }
    Proporciona la ruta a tu archivo principal compilado junto con cualquier argumento adicional.
  3. Reinicia Claude Desktop para cargar la nueva configuración.

Cuando interactúes con Claude Desktop, ahora puede invocar las herramientas MCP que has registrado. Si la solicitud de un usuario se alinea con la funcionalidad de alguna de tus herramientas, Claude te pedirá usar esa herramienta.

Mejores Prácticas de Desarrollo

  1. Usa TypeScript para un mejor chequeo de tipos, una organización de código más clara y un mantenimiento más fácil con el tiempo.
  2. Adopta patrones consistentes para implementar herramientas:
    • Mantén cada herramienta en su propio archivo
    • Usa esquemas descriptivos con documentación adecuada
    • Implementa un manejo de errores integral
    • Devuelve contenido correctamente formateado
  3. Incluye documentación exhaustiva:
    • Agrega comentarios JSDoc para explicar la funcionalidad
    • Documenta parámetros y tipos de retorno
    • Incluye ejemplos donde sea útil
  4. Aprovecha el inspector para depurar:
    npm run inspector
    Esto te ayuda a:
    • Probar la funcionalidad de las herramientas
    • Depurar el flujo de solicitud/respuesta
    • Verificar la validación de esquemas
    • Revisar el manejo de errores
  5. Prueba exhaustivamente antes del despliegue:
    • Verifica la validación de entrada
    • Prueba escenarios de error
    • Revisa el formato de las respuestas
    • Asegura una integración adecuada con los hosts
  6. Sigue las mejores prácticas de MCP:
    • Usa tipos de contenido adecuados
    • Implementa un manejo de errores apropiado
    • Valida todas las entradas y salidas
    • Maneja las solicitudes de red de forma segura
    • Formatea las respuestas de manera consistente

Aprende Más

Para más información sobre el ecosistema MCP, consulta:

  • Documentación del Model Context Protocol: Cobertura detallada de la arquitectura de MCP, principios de diseño y ejemplos de uso más avanzados.
  • Smithery - Registro de Servidores MCP: Guías para publicar tus herramientas en Smithery y mejores prácticas para su registro.
  • Documentación del SDK de TypeScript para MCP: Documentación completa del SDK de TypeScript.
  • Guías de Seguridad de MCP: Prácticas y recomendaciones detalladas de seguridad.

Conclusión

Siguiendo esta plantilla y las mejores prácticas, puedes construir rápidamente un servidor MCP robusto que abre tus herramientas a una amplia gama de hosts de IA. Este enfoque ampliado asegura un mantenimiento más fácil, una mejor seguridad de tipos y una experiencia de usuario fluida al aprovechar las capacidades de los sistemas de IA modernos.

Créditos

Plantilla creada por Seth Rose:

Mejores Prácticas

  1. Seguridad de Tipos:
    • Aprovecha el sistema de tipos de TypeScript para definiciones de herramientas robustas
    • Usa esquemas Zod para validación en tiempo de ejecución
    • Define interfaces claras para parámetros y respuestas de herramientas
  2. Selección de Transporte:
    • Usa StdioServerTransport para comunicación de procesos locales
    • Implementa WebSocketServerTransport para herramientas basadas en red
    • Considera transportes personalizados para casos de uso específicos
  3. Gestión de Capacidades:
    • Define claramente las capacidades del servidor durante la inicialización
    • Implementa una negociación de capacidades adecuada
    • Maneja los errores específicos de capacidades con elegancia
  4. Consideraciones de Seguridad:
    • Implementa flujos de consentimiento del usuario para operaciones sensibles
    • Valida todas las entradas usando tipos de TypeScript y esquemas Zod
    • Maneja los errores de forma segura sin exponer detalles internos