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:
my-mcp-greeter-server : un servidor MCP que proporciona herramientas, recursos y avisos relacionados con los saludos.
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) .
Este proyecto se construyó siguiendo estas fases principales:
Desarrollo del servidor : creación del proveedor de servicios MCP.
Desarrollo de cliente : Creación de un script para consumir los servicios del servidor.
Prueba e interacción : ejecución del script del cliente, que inicia el servidor y demuestra la comunicación.
(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
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.
my-mcp-greeter-server )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 .
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.
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.
my-mcp-client-script )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 .
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.
Construir ambos proyectos :
cd my-mcp-greeter-server && npm run build
cd ../my-mcp-client-script && npm run build
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.
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.
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.jsGenerates a personalized greeting.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the person to greet. | |
| politeness | No | Desired politeness level. | informal |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'personalized greeting' but doesn't explain what that entails (e.g., format, length, language), whether it's idempotent, or any side effects. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence that directly states the tool's purpose. There is no wasted language, and it is front-loaded with the essential information, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks details on the greeting format or any behavioral context, which would be helpful for an agent to use it effectively, especially without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already fully documents both parameters (name and politeness). The description adds no additional meaning beyond what the schema provides, such as examples or edge cases, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Generates') and resource ('a personalized greeting'), making it immediately understandable. However, since there are no sibling tools, it doesn't need to differentiate from alternatives, which prevents a perfect score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, prerequisites, or any contextual constraints. It simply states what the tool does without offering usage instructions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0greetScored across 1 tool
With only one tool, there is no possibility of confusion or overlap between tools, making disambiguation perfect. The tool's purpose is clearly distinct by default.
A single tool inherently follows a consistent naming pattern, as there are no other tools to compare it against. The name 'greet' is straightforward and appropriate.
One tool is too few for most server purposes, as it limits functionality and suggests an incomplete or trivial implementation. This is borderline for a meaningful MCP server scope.
The server's purpose is unclear from the single tool, but 'greet' alone suggests severe incompleteness for any practical domain. There are obvious gaps, as no other operations are supported, making the surface inadequate.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools