MCP básico con TypeScript

Ejemplo pequeño pero completo de Model Context Protocol (MCP): un servidor local, un cliente y una demostración ejecutable de las tres primitivas principales del servidor.

• Tools: acciones que un modelo puede decidir invocar.

• Resources: datos de solo lectura que una aplicación cliente obtiene por URI.

• Prompts: plantillas de mensajes que el usuario o cliente puede seleccionar.

El proyecto evita deliberadamente bases de datos, frameworks web, autenticación y llamadas a un LLM. El objetivo es que se vea el protocolo sin ruido adicional y que el código pueda servir como punto de partida.

Requisitos

• Node.js 20 o posterior

• npm

Related MCP server: MCP AI Chat LangChain

Ejecutar la demo

npm install
npm run demo

No hay que iniciar el servidor aparte. El cliente lo lanza como subproceso, se conecta por stdio, hace el handshake MCP y lo cierra al terminar.

La salida incluye, en este orden:

1. Descubrimiento de sumar mediante listTools() y ejecución con callTool().

2. Descubrimiento de info://app mediante listResources() y lectura con readResource().

3. Descubrimiento de explicar-concepto mediante listPrompts() y renderizado con getPrompt().

También se puede comprobar el tipado y generar JavaScript:

npm run check
npm run build

Mapa del proyecto

src/
├── server.ts  # declara tools, resources y prompts; atiende por stdio
└── client.ts  # inicia el server, descubre capacidades y las consume

Qué ocurre al ejecutar el cliente

npm run demo
     │
     ▼
Client + StdioClientTransport
     │  crea el proceso y usa stdin/stdout
     ▼
McpServer + transporte stdio
     │
     ├── tools/list      ──► definición y JSON Schema de `sumar`
     ├── tools/call      ──► ejecuta `sumar`
     ├── resources/list  ──► metadatos de `info://app`
     ├── resources/read  ──► contenido del resource
     ├── prompts/list    ──► metadatos de `explicar-concepto`
     └── prompts/get     ──► mensajes de la plantilla

client.connect(transport) realiza primero el handshake initialize: cliente y servidor intercambian versión, identidad y capacidades. Después, el SDK presenta métodos TypeScript de alto nivel; por debajo viajan mensajes JSON-RPC de MCP.

Tool

sumar ilustra una operación. Su esquema Zod tiene tres trabajos: documenta los argumentos, genera el JSON Schema que descubre el cliente y valida el input antes de ejecutar el handler.

En un sistema real, un tool podría consultar una API, crear un ticket o ejecutar una operación de negocio. Debe tener un nombre estable, una descripción precisa y un esquema estricto.

Resource

info://app ilustra información direccionable y de solo lectura. La lista contiene metadatos; el contenido se obtiene en una llamada separada usando la URI.

En un sistema real, un resource podría representar documentación, configuración, el esquema de una base de datos o un registro. Para colecciones variables, el SDK también ofrece ResourceTemplate con URIs como customer://{id}.

Prompt

explicar-concepto recibe argumentos y produce mensajes. No llama por sí mismo a un LLM: un host con un modelo podría tomar esos mensajes y enviárselos.

En un sistema real, un prompt puede estandarizar flujos como “analizar incidente”, “resumir cliente” o “preparar revisión”. A diferencia de un tool, normalmente lo selecciona explícitamente el usuario o la aplicación.

Responsabilidades: host, cliente y servidor

• El servidor MCP publica capacidades y ejecuta sus handlers.

• El cliente MCP mantiene una conexión y traduce operaciones del protocolo a métodos como listTools().

• El host es la aplicación completa (un IDE o asistente, por ejemplo). Puede contener el cliente, mostrar resources/prompts y permitir que un modelo elija tools.

Este repositorio implementa servidor y cliente, pero no un host con LLM. Por eso la demo llama sumar directamente: hace visible el mecanismo MCP sin depender de una API de IA.

Cómo extender este template

1. Mantener createServer() independiente del transporte.

2. Registrar cada capacidad con un nombre, una descripción y schemas claros.

3. Mover integraciones reales a módulos de dominio; los handlers MCP deberían ser adaptadores pequeños.

4. Añadir manejo de errores esperado con resultados que incluyan isError: true.

5. Añadir tests del servidor con un transporte en memoria antes de introducir HTTP.

6. Usar Streamable HTTP cuando el servidor deje de ser un proceso local y deba atender conexiones remotas; ahí también habrá que diseñar autenticación, sesiones y despliegue.

Regla importante de stdio

stdout es el canal del protocolo. Cualquier console.log() en el servidor puede corromper los mensajes JSON-RPC. Los logs del servidor deben enviarse a stderr con console.error(). El cliente sí puede imprimir normalmente su propia salida.

Referencias oficiales

• SDK oficial de TypeScript

• Guía para construir servidores

• Guía para construir clientes

• Especificación MCP