MCP Hello World

Un servidor MCP mínimo simulado en TypeScript para probar clientes MCP, compatible con los protocolos STDIO y HTTP/SSE.

GitHub
22
Prueba este MCPPatrocinado

Documentación

MCP Hello World - Servidor MCP Simulado para Pruebas

Este es un servidor de Model Context Protocol (MCP) mínimo implementado en TypeScript, destinado principalmente a servir como un Doble de Prueba / Servidor Simulado.

Propósito principal: Proporcionar un entorno de servidor MCP ligero, controlable y predecible para pruebas unitarias o pruebas de integración de código de cliente que necesita interactuar con un servidor MCP.

Nota: Este proyecto no es adecuado para entornos de producción ni para su despliegue como servidor MCP de propósito general.

MCP Badge

¿Por qué usar mcp-hello-world en las pruebas?

Al probar código relacionado con clientes MCP, normalmente no quieres depender de un servicio backend de IA real, potencialmente complejo y con respuestas impredecibles. Usar mcp-hello-world como doble de prueba ofrece varias ventajas:

  1. Aislamiento: Centra tus pruebas en la lógica del cliente sin preocuparte por problemas de red o la disponibilidad del servidor real.
  2. Previsibilidad: Las herramientas proporcionadas echo y debug tienen comportamientos simples y fijos, lo que facilita escribir aserciones.
  3. Velocidad: Inicio y tiempos de respuesta rápidos, adecuados para uso frecuente en pruebas unitarias.
  4. Ligereza: Pocas dependencias, fácil de integrar en entornos de prueba.
  5. Cobertura de protocolo: Soporta ambos protocolos de transporte MCP STDIO y HTTP/SSE, lo que te permite probar el comportamiento del cliente bajo diferentes métodos de conexión.

Instalación

Añade este paquete como dependencia de desarrollo a tu proyecto:

# Using pnpm
pnpm add --save-dev mcp-hello-world

# Or using bun
bun add --dev mcp-hello-world

Ejecución Manual (para Depurar Pruebas)

A veces es posible que quieras ejecutar el servidor manualmente para depurar tus pruebas o el comportamiento del cliente.

Modo STDIO

Esta es la forma más sencilla de ejecutarlo, especialmente durante el desarrollo local y la depuración.

# Ensure it's installed (globally or in the project)
# Using npx (universal)
npx mcp-hello-world

# Or using pnpm dlx
pnpm dlx mcp-hello-world

# Or using bunx
bunx mcp-hello-world

El servidor escuchará en la entrada estándar y enviará respuestas MCP a la salida estándar. Puedes usar herramientas como MCP Inspector para conectarte al proceso.

Para configurar este servidor en tu cliente MCP, añade lo siguiente a tu configuración:

{
  "mcpServers": {
    "mcp-hello-world": {
      "command": "npx",
      "args": ["mcp-hello-world"]
    }
  }
}

Modo HTTP/SSE

Si necesitas depurar a través de una interfaz de red o probar clientes MCP basados en HTTP.

# 1. Clone the repository (if not already installed in the project)
# git clone https://github.com/lobehub/mcp-hello-world.git
# cd mcp-hello-world
# pnpm install / bun install

# 2. Build the project
# Using pnpm
pnpm build
# Or using bun
bun run build

# 3. Start the HTTP server
# Using pnpm
pnpm start:http
# Or using bun
bun run start:http

El servidor se iniciará en http://localhost:3000 y proporcionará:

  • Endpoint SSE: /sse
  • Endpoint de mensajes: /messages

Uso en Pruebas

Puedes iniciar y detener programáticamente el servidor mcp-hello-world dentro de tu framework de pruebas (como Jest, Vitest, Mocha, etc.) para pruebas automatizadas.

Ejemplo: Pruebas con Modo STDIO (Node.js)

// test/my-mcp-client.test.ts (Example using Jest)
import { spawn } from 'child_process';
import { MCPClient } from '../src/my-mcp-client'; // Assuming this is your client code

describe('My MCP Client (STDIO)', () => {
  let mcpServerProcess;
  let client: MCPClient;

  beforeAll(() => {
    // Start the mcp-hello-world process before tests
    // Using npx (or pnpm dlx / bunx) ensures the command is found and executed
    mcpServerProcess = spawn('npx', ['mcp-hello-world']);

    // Instantiate your client and connect to the subprocess's stdio
    client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);
  });

  afterAll(() => {
    // Shut down the mcp-hello-world process after tests
    mcpServerProcess.kill();
  });

  it('should receive echo response', async () => {
    const request = {
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/invoke',
      params: { name: 'echo', parameters: { message: 'test message' } },
    };

    const response = await client.sendRequest(request); // Assuming your client has this method

    expect(response).toEqual({
      jsonrpc: '2.0',
      id: 1,
      result: { content: [{ type: 'text', text: 'Hello test message' }] },
    });
  });

  it('should get greeting resource', async () => {
    const request = {
      jsonrpc: '2.0',
      id: 2,
      method: 'resources/get',
      params: { uri: 'greeting://Alice' },
    };
    const response = await client.sendRequest(request);
    expect(response).toEqual({
      jsonrpc: '2.0',
      id: 2,
      result: { data: 'Hello Alice!' }, // Confirm return format based on actual implementation
    });
  });

  // ... other test cases
});

Ejemplo: Pruebas con Modo HTTP/SSE

Para HTTP/SSE, es posible que necesites:

  1. Usar exec o spawn en beforeAll para iniciar pnpm start:http o bun run start:http.
  2. Usar un cliente HTTP (como axios, node-fetch o el cliente integrado de tu framework de pruebas) para conectarte a http://localhost:3000/sse y /messages para las pruebas.
  3. Asegúrate de detener el proceso del servidor iniciado en afterAll.

Capacidades MCP Proporcionadas (para Aserciones de Prueba)

mcp-hello-world proporciona las siguientes capacidades fijas para interacción y aserción en tus pruebas:

Recursos

  • hello://world
    • Descripción: Un recurso estático de Hello World.
    • Método: resources/get
    • Parámetros: Ninguno
    • Devuelve: { data: 'Hello World!' }
  • greeting://{name}
    • Descripción: Un recurso de saludo dinámico.
    • Método: resources/get
    • Parámetros: name incluido en la URI, por ejemplo, greeting://Bob.
    • Devuelve: { data: 'Hello {name}!' } (por ejemplo, { data: 'Hello Bob!' })

Herramientas

  • echo
    • Descripción: Repite el mensaje de entrada, con el prefijo "Hello ".
    • Método: tools/invoke
    • Parámetros: { name: 'echo', parameters: { message: string } }
    • Devuelve: { content: [{ type: 'text', text: 'Hello {message}' }] } (por ejemplo, { content: [{ type: 'text', text: 'Hello test' }] })
  • debug
    • Descripción: Lista todas las definiciones de métodos MCP disponibles en el servidor.
    • Método: tools/invoke
    • Parámetros: { name: 'debug', parameters: {} }
    • Devuelve: Una estructura JSON que contiene definiciones de todos los recursos, herramientas y prompts registrados.

Prompts

  • helpful-assistant
    • Descripción: Una definición básica de prompt de asistente.
    • Método: prompts/get
    • Parámetros: Ninguno
    • Devuelve: Una estructura JSON para el prompt con roles predefinidos system y user.

Licencia

MIT