Ejemplo de servidor y cliente MCP (TypeScript)

Este proyecto demuestra la creación e interacción de un servidor de Protocolo de Contexto de Modelo (MCP) simple y un cliente MCP independiente utilizando TypeScript y @modelcontextprotocol/sdk .

La configuración incluye:

1. my-mcp-greeter-server : un servidor MCP que proporciona herramientas, recursos y avisos relacionados con los saludos.

2. my-mcp-client-script : un script de cliente de línea de comandos simple que inicia el servidor, se conecta a él e interactúa con sus capacidades mediante programación.

La comunicación entre el cliente y el servidor en este ejemplo utiliza el mecanismo de transporte stdio (entrada/salida estándar) .

Descripción general del proceso seguido

Este proyecto se construyó siguiendo estas fases principales:

1. Desarrollo del servidor : creación del proveedor de servicios MCP.

2. Desarrollo de cliente : Creación de un script para consumir los servicios del servidor.

3. Prueba e interacción : ejecución del script del cliente, que inicia el servidor y demuestra la comunicación.

4. (Opcional) Integración : se analiza cómo integrar el servidor con clientes MCP existentes, como las extensiones de VS Code.

Related MCP server: TypeScript MCP Server Boilerplate

Prerrequisitos

Antes de comenzar, asegúrese de tener instalado lo siguiente:

• Node.js (se recomienda v16 o superior)

• npm (generalmente incluido con Node.js)

• Un editor de texto o IDE (como VS Code)

• npx (generalmente incluido con npm): útil para realizar pruebas con MCP Inspector.

Fase 1: Construcción del servidor MCP ( my-mcp-greeter-server )

1. Configuración del proyecto :

   • Se creó el directorio my-mcp-greeter-server .

   • Se inicializó un proyecto npm: npm init -y .

   • Dependencias necesarias instaladas: npm install @modelcontextprotocol/sdk zod .

   • Dependencias de desarrollo instaladas: npm install -D typescript @types/node .

   • Configuración de TypeScript inicializada: npx tsc --init .

   • Se configuró tsconfig.json (configuración "module": "Node16" , "target": "ES2022" , "outDir": "./build" , "rootDir": "./src" , etc.).

   • Se actualizó package.json para incluir "type": "module" y se agregaron scripts build / start .

   • Se creó el archivo fuente src/index.ts .

2. Implementación del servidor ( src/index.ts ) :

   • Módulos necesarios importados ( McpServer , StdioServerTransport , z ).

   • Constantes definidas para name y version del servidor.

   • Se crea una instancia McpServer , pasando el nombre, la versión y declarando sus capacidades (herramientas, recursos, indicaciones).

   • Se definió una herramienta ( greet ) : Se usó server.tool() para crear una función que los clientes puedan llamar. Se incluyó una descripción, se definieron parámetros de entrada con Zod ( name , politeness ) y se implementó el controlador para devolver una cadena de saludo personalizada.

   • Se definió un recurso ( server-info ) : Se usó server.resource() para exponer datos estáticos. Se proporcionó una URI única ( info://greeter/about ) y se implementó el controlador para devolver el nombre y la versión del servidor.

   • Se definió un mensaje ( suggest-greeting ) : Se usó server.prompt() para crear una plantilla de interacción reutilizable. Se incluyó una descripción y se implementó el controlador para devolver un conjunto predefinido de mensajes de usuario/asistente para guiar una interacción LLM.

   • Transporte Stdio utilizado : StdioServerTransport instanciado como método de comunicación.

   • Conectado : se llama await server.connect(transport) para preparar el servidor.

   • Registro : se agregaron declaraciones console.error para mayor visibilidad durante la ejecución, especialmente importante para el transporte stdio donde se utiliza stdout para mensajes de protocolo.

   • Mantenido activo : se garantizó que el proceso Node.js no saliera inmediatamente después de la conexión.

3. Construcción y reparación :

   • Ejecuté npm run build para compilar TypeScript en JavaScript en el directorio build .

   • Se corrigió un error de TypeScript relacionado con el acceso directo a la versión del servidor, optando por utilizar constantes predefinidas en su lugar.

Fase 2: Creación del script del cliente MCP ( my-mcp-client-script )

1. Configuración del proyecto :

   • Se creó un directorio separado my-mcp-client-script .

   • Se inicializó un proyecto npm: npm init -y .

   • Dependencias necesarias instaladas: npm install @modelcontextprotocol/sdk .

   • Dependencias de desarrollo instaladas: npm install -D typescript @types/node .

   • Se inicializó y configuró tsconfig.json de manera similar al proyecto del servidor.

   • Se actualizó package.json con "type": "module" y los scripts build / start .

   • Se creó el archivo fuente src/client-script.ts .

2. Implementación del cliente ( src/client-script.ts ) :

   • Se importaron los módulos necesarios ( Client , StdioClientTransport , path , url ).

   • Ruta del servidor determinada : calcula la ruta al archivo index.js compilado del servidor (relativa o absoluta).

   • Transporte de Stdio configurado : StdioClientTransport instanciado, que proporciona el command ( node ) y args (la ruta al script del servidor). Esta configuración es clave, ya que el transporte del cliente inicia el proceso del servidor.

   • Cliente instanciado : se crea una instancia Client , se le otorga una identidad y se declara su intención de utilizar herramientas y recursos.

   • Conectado : se llamó await client.connect(transport) , que lanzó el proceso del servidor y estableció la conexión MCP a través de sus flujos stdio.

   • Interactuó con el servidor :

     • Se llama a la herramienta greet usando await client.callTool() .

     • Lea el recurso server-info usando await client.readResource() .

     • Se obtuvo el mensaje de suggest-greeting usando await client.getPrompt() .

   • Resultados registrados : se utilizó console.log para mostrar las respuestas recibidas del servidor.

   • Conexión cerrada : se utiliza await client.close() en un bloque finally para cerrar limpiamente la conexión y finalizar el proceso del servidor.

Fase 3: Construcción y funcionamiento

1. Construir ambos proyectos :

   • cd my-mcp-greeter-server && npm run build

   • cd ../my-mcp-client-script && npm run build

2. Ejecutar el cliente :

   • cd my-mcp-client-script

   • npm run start (o node build/client-script.js )

   • Se observó la salida intercalada tanto del cliente ( console.log ) como del servidor ( console.error ), lo que confirma la comunicación exitosa y la ejecución de herramientas/recursos/avisos.

Explicación de los roles

• El servidor ( GreeterServer ) :

  • Proporciona servicios : expone capacidades específicas (herramienta de saludo, información del servidor, plantilla de mensaje).

  • Oyente pasivo (en stdio) : espera a que un cliente se conecte a través de sus transmisiones estándar.

  • Ejecuta lógica : ejecuta el código asociado con una herramienta/recurso/mensaje cuando lo solicita el cliente.

  • Envía resultados : formatea los resultados según las especificaciones de MCP y los envía de vuelta al cliente.

• El cliente ( client-script.ts ) :

  • Consume Servicios : Utiliza las capacidades que ofrece el servidor.

  • Iniciador (en stdio) : inicia el proceso del servidor y establece la conexión.

  • Envía solicitudes : decide qué herramienta llamar, recurso leer o solicitud obtener y envía la solicitud MCP adecuada.

  • Recibe resultados : procesa las respuestas enviadas por el servidor.

  • Controla el flujo : administra la secuencia de interacciones y decide cuándo cerrar la conexión.

Probar el servidor de forma interactiva

Mientras el script del cliente prueba la interacción programática, puede probar las capacidades del servidor individualmente utilizando el Inspector MCP:

# Make sure the server is NOT already running
# Replace /path/to/... with the actual absolute path
npx @modelcontextprotocol/inspector node /path/to/my-mcp-greeter-server/build/index.js