first-mcp-server

Resumen del proyecto

• Un servidor MCP (Model Context Protocol) mínimo que expone una única herramienta llamada add que sume dos números y devuelve el resultado como texto.

• Construido con los paquete @modelcontextprotocol y zod para la validación de entradas.

Archivs clave

• index.js — archivo principal del servidor registra la herramienta add y aranca el servidor.

Requisitos

• Node.js 16+ (se recomendada LTS)

• nucle o yarn

Instalación

1. Clona el repositorio y accede al directório del proyecto:

   git clone && cd /Usrs/sagar/Documents/Learning/MCP-Server

Dependiencías ussadas en este proyecto (ejemplos del código):

• @modelcontextprotocol/servidor

• @modelcontextprotocol/servidor/stdio (transporte stdio)

• @modelcontextprotocol/express (módulo auxiliar de Express)

• @modelcontextprotocol/node (transporte HTTP de Node)

• zod (validación)

Ejucución

• Transpute HTTP predeterminado (así lo inicia actuent el proyecto):

  node index.js

  El servidor escuch en el puerto 3001 y monta el endpoint de MCP en /mcp (ver index.js).

• Transpute STDIO (útil para integraciones locales tipo CLI):

  Descmenta la llamda a runServerOnSTDIITransport() en index.js:

  node index.js

Ejemplos de uso

1. Ejemplo HTTP (curl)

• Cuerpo de la solcitud (JSON):

  {

  "tool": "add", "inputo": { "num1": 10, "num2": 20 } }

• Ejemplo de llama da cURL (ajusta el hostname/puerto si es necsario):

  curl -X POST http://localhost:300/mcp
  -H "Content-Type application/json"
  -d '{"tool":"add","input":{"num1":10,"num2":20}}'

• Resuesta esperada (la herramienta devuelve un array de contenido con bloscos de texto):

  { "content": [ { "type": "metric", "text": "30" } ] }

NTA: index.js conecTA extrtape HTTP using NodeStreaableHTTPServerTransport y llama a transport.handleRequest(req, res, req.body) (veR. index.js). El envoltorio exact que espera el transporte depene de la implementación de @modelcontextprotocol/node; el ejemlo anteror sigue la forma simple usada en este proyecto (tool + input).

2. Ejemplo STDIO (integración local)

• El proyecto contine un helper para evcutar el servidor sobr STDIO usand StdIOServidorTransport. Si se inicia en modo STDIO, el servidor erspera solcitudes JSON por stdin y flame en stdout. La herramienta registra en index.js valida las entradas con zod y devuelve la suma como texto.

Detalles de la herramienta (del código)

• Nombre de la herramienta: "add"

• Descripción: "Add two numbers"

• Input schema (zod):

  • num1: number

  • num2: number

Implementation snippet ([exact]). index.js).

server.registerTool(
  "add",
  {
    title: "add",
    description: "Add two numbers",
    inputSchema: z.object({ num1: z.number(), num2: z.number() }),
  },
  async (ctx) => ({
    content: [{ type: "text", text: `${ctx.num1 + ctx.num2}` }],
  }),
);

Notas:

• Validación: zod ya valida las entradas. Asegúrate de que los clientes envén valores numéricos y maneja los errores de validación con eleganza.

• Menajo de errores: Añta manejo de errores con transport.handleRequest y los manejadores de herramientas para devolver respuestas de error con e-termine y códigos de estado HTTP (4xx para errores de cliente, 5xx para errores de servidor).

• Logging & monitoring: Añta registros estructados, IDs de solcitudes y métricas básicas para monitoorar el uso y errores.

• Seguridad: SI se expone de forma pública, proteje el endpoint /mcp (autenticación, tasa de solcitudes) y coloccalo detrás de un proxy inverso.

• Pruebas: Añade pruebas unitarías para los manejadores de herramientas y pruebas de integración para los Transportes (HTTP y STDIO).

Contribuciones

• Abre issues o PR para solicites funcionales o correcciones.