MCP Hello World

MCP Hello World - Servidor MCP Mock para Testes

Este é um servidor mínimo de Model Context Protocol (MCP) implementado em TypeScript, destinado principalmente a servir como um Test Double / Servidor Mock.

Propósito Principal: Fornecer um ambiente de servidor MCP leve, controlável e previsível para testes unitários ou testes de integração de código de cliente que precisa interagir com um servidor MCP.

Observação: Este projeto não é adequado para ambientes de produção nem para implantação como um servidor MCP de uso geral.

Por que usar mcp-hello-world em Testes?

Ao testar código relacionado a clientes MCP, normalmente você não quer depender de um serviço de backend de IA real, potencialmente complexo e com respostas imprevisíveis. Usar mcp-hello-world como um test double oferece várias vantagens:

1. Isolamento: Concentre seus testes na lógica do cliente sem se preocupar com problemas de rede ou com a disponibilidade do servidor real.
2. Previsibilidade: As ferramentas fornecidas echo e debug têm comportamentos simples e fixos, facilitando a escrita de asserções.
3. Velocidade: Inicialização e tempos de resposta rápidos, adequados para uso frequente em testes unitários.
4. Leve: Poucas dependências, fácil de integrar em ambientes de teste.
5. Cobertura de Protocolo: Suporta ambos os protocolos de transporte MCP STDIO e HTTP/SSE, permitindo testar o comportamento do cliente sob diferentes métodos de conexão.

Instalação

Adicione este pacote como uma dependência de desenvolvimento ao seu projeto:

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

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

Execução Manual (para Depuração de Testes)

Você pode querer executar o servidor manualmente às vezes para depurar seus testes ou o comportamento do cliente.

Modo STDIO

Esta é a maneira mais simples de executar, especialmente durante o desenvolvimento e a depuração local.

# 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

O servidor escutará na entrada padrão e enviará respostas MCP para a saída padrão. Você pode usar ferramentas como o MCP Inspector para se conectar ao processo.

Para configurar este servidor no seu cliente MCP, adicione o seguinte à sua configuração:

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

Modo HTTP/SSE

Se você precisar depurar por meio de uma interface de rede ou testar clientes MCP baseados em 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

O servidor iniciará em http://localhost:3000 e fornecerá:

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

Uso em Testes

Você pode iniciar e parar programaticamente o servidor mcp-hello-world dentro do seu framework de testes (como Jest, Vitest, Mocha, etc.) para testes automatizados.

Exemplo: Testando com 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
});

Exemplo: Testando com Modo HTTP/SSE

Para HTTP/SSE, você pode precisar:

1. Usar exec ou spawn em beforeAll para iniciar pnpm start:http ou bun run start:http.
2. Usar um cliente HTTP (como axios, node-fetch ou o cliente integrado do seu framework de testes) para conectar-se a http://localhost:3000/sse e /messages para testes.
3. Garantir que você encerre o processo do servidor iniciado em afterAll.

Capacidades MCP Fornecidas (para Asserções de Teste)

mcp-hello-world fornece as seguintes capacidades fixas para interação e asserção em seus testes:

Recursos

• hello://world
  • Descrição: Um recurso estático Hello World.
  • Método: resources/get
  • Parâmetros: Nenhum
  • Retorna: { data: 'Hello World!' }
• greeting://{name}
  • Descrição: Um recurso de saudação dinâmico.
  • Método: resources/get
  • Parâmetros: name incluído no URI, por exemplo, greeting://Bob.
  • Retorna: { data: 'Hello {name}!' } (por exemplo, { data: 'Hello Bob!' })

Ferramentas

• echo
  • Descrição: Ecoa a mensagem de entrada, prefixada com "Hello ".
  • Método: tools/invoke
  • Parâmetros: { name: 'echo', parameters: { message: string } }
  • Retorna: { content: [{ type: 'text', text: 'Hello {message}' }] } (por exemplo, { content: [{ type: 'text', text: 'Hello test' }] })
• debug
  • Descrição: Lista todas as definições de métodos MCP disponíveis no servidor.
  • Método: tools/invoke
  • Parâmetros: { name: 'debug', parameters: {} }
  • Retorna: Uma estrutura JSON contendo definições para todos os recursos, ferramentas e prompts registrados.

Prompts

• helpful-assistant
  • Descrição: Uma definição básica de prompt de assistente.
  • Método: prompts/get
  • Parâmetros: Nenhum
  • Retorna: Uma estrutura JSON para o prompt com papéis predefinidos de system e user.

Licença

MIT