MCP Server Starter

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

Documentación

¿Qué es MCP?

El Protocolo de Contexto de Modelos (MCP) es un marco especializado diseñado para optimizar el proceso de permitir que los agentes de IA interactúen 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 los servidores para consultar datos o realizar acciones. Los clientes MCP usan SDKs de TypeScript, garantizando interacciones seguras en cuanto a tipos y un enfoque uniforme en 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 así 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: {},      // Enable tools capability
    resources: {},  // Enable resource access
    prompts: {},    // Enable prompt handling
    streaming: true // Enable streaming responses
  }
});

// Connect transport
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 poner en marcha rápidamente un entorno de desarrollo reproducible, facilitando la colaboración y haciéndola más 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 agiliza 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:

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

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

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

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

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

Clona esta plantilla: Recupera los archivos del repositorio desde tu fuente preferida.
Á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.
Instala las dependencias:
```
npm install
```
Este comando obtiene e instala todos los paquetes necesarios para el servidor MCP.
Compila el proyecto:
```
npm run build
```
Esto compila tu código TypeScript a JavaScript, preparándolo para su 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 el 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: "Operation completed successfully"
    },
    {
      type: "code",
      text: "console.log('Hello, World!')",
      mimeType: "application/javascript"
    }
  ]
};

Mejores Prácticas de Seguridad

Al desarrollar herramientas MCP, sigue estas pautas de seguridad:

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 evitar propiedades adicionales
Manejo de Errores:
- Nunca expongas detalles internos de errores a los clientes
  - Implementa límites de error adecuados
  - Registra errores de forma segura
  - Devuelve mensajes de error amigables para el usuario
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
Seguridad de la 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 {
      // Implement rate limiting
      await rateLimiter.checkLimit();

      // Process validated input
      const result = await processSecurely(params.input);

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

      // Return safe error message
      return {
        content: [{
          type: "text",
          text: "An error occurred processing your request"
        }],
        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

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

Registro (Logging):

function logMessage(level: 'info' | 'warn' | 'error', message: string) {
  console.error(\`[${level.toUpperCase()}] ${message}\`);
}

Seguimiento de Errores:

process.on('uncaughtException', (error: Error) => {
  logMessage('error', \`Uncaught error: ${error.message}\`);
  // Implement error reporting
});

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 {
  // Implement transport methods
}

Capacidades del Servidor

Configura las capacidades del servidor:

const server = new McpServer({
  name: "mcp-server",
  version: "1.0.0",
  capabilities: {
    tools: {}, // Enable tools capability
    streaming: true, // Enable streaming support
    customContent: ["myFormat"], // Define custom content types
    metadata: true // Enable metadata support
  }
});

Integración con Hosts MCP

Soporte Multi-Cliente

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

Claude Desktop:
- Proporciona un entorno basado en chat
  - Admite todas las capacidades de MCP
  - Ideal para interacciones conversacionales de IA
Cursor:
- Entorno de desarrollo impulsado por IA
  - Soporte completo de integración de herramientas
  - Perfecto para asistencia en codificación
Windsurf:
- Plataforma moderna de desarrollo de IA
  - Soporte completo del protocolo MCP
  - Integración optimizada del flujo de trabajo
Cline:
- Interfaz de IA de línea de comandos
  - Interacciones centradas en herramientas
  - Uso eficiente basado en terminal
TypeScript:
- Soporte nativo de TypeScript
  - Desarrollo de herramientas seguro en cuanto a tipos
  - Integración fluida 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 diversos flujos de trabajo de IA.

Ejecución Rápida

Puedes ejecutar inmediatamente este servidor mediante la 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:

Crea una cuenta en Smithery.
Sigue sus instrucciones de despliegue para empaquetar y publicar tu servidor MCP.
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 configuraciones repetitivas.
Un enfoque impulsado por la comunidad donde los desarrolladores contribuyen con herramientas diversas.
Integración fácil con hosts de IA populares.

Para orientación adicional:

Integración con Cursor

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

Compila tu servidor:
```
npm run build
```
Asegúrate de que se genere un index.js ejecutable en el directorio build.
En Cursor, ve a Settings > Features > MCP: Añade un nuevo servidor MCP.
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.
Guarda tu configuración.

Cursor detecta y lista tus herramientas. Durante sesiones de codificación asistidas 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:

Compila tu servidor:
```
npm run build
```
Confirma que no ocurran errores y que el script principal se genere en build.

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.

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 coincide con la funcionalidad de alguna de tus herramientas, Claude te pedirá usar esa herramienta.

Mejores Prácticas de Desarrollo

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

Aprende Más

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

Documentación del Protocolo de Contexto de Modelos: Cobertura detallada de la arquitectura de MCP, principios de diseño y ejemplos de uso más avanzados.
Smithery - Registro de Servidores MCP: Pautas 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.
Pautas de Seguridad de MCP: Mejores prácticas y recomendaciones de seguridad detalladas.

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 garantiza 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:

Sitio web: https://www.sethrose.dev
𝕏 (Twitter): https://x.com/TheSethRose
🦋 (Bluesky): https://bsky.app/profile/sethrose.dev

Mejores Prácticas

Seguridad de tipos:
- Aprovecha el sistema de tipos de TypeScript para definiciones de herramientas robustas
  - Usa esquemas de Zod para la validación en tiempo de ejecución
  - Define interfaces claras para los parámetros y respuestas de las herramientas
Selección de transporte:
- Usa StdioServerTransport para la comunicación con procesos locales
  - Implementa WebSocketServerTransport para herramientas basadas en red
  - Considera transportes personalizados para casos de uso específicos
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
Consideraciones de seguridad:
- Implementa flujos de consentimiento del usuario para operaciones sensibles
  - Valida todas las entradas usando tipos de TypeScript y esquemas de Zod
  - Maneja los errores de forma segura sin exponer detalles internos