MCP Hello World - MCP Server Mock for Testing

MCP Hello World - 用于测试的 MCP 服务 Mock

这是一个使用 TypeScript 实现的极简 Model Context Protocol（MCP）服务，主要用作测试替身 / Mock 服务。

核心用途：提供轻量、可控且行为可预测的 MCP 服务环境，用于对需要与 MCP 服务交互的客户端代码进行单元测试或集成测试。

注意：此项目不适用于生产环境，也不适合作为通用 MCP 服务进行部署。

为什么在测试中使用 mcp-hello-world？

测试 MCP 客户端相关代码时，通常不希望依赖真实、可能很复杂且响应行为难以预测的 AI 后端服务。将 mcp-hello-world 用作测试替身有以下优势：

1. 隔离性：专注于测试客户端逻辑，无需担心网络问题或真实服务是否可用。
2. 可预测性：提供的 echo 和 debug 工具行为简单且固定，便于编写断言。
3. 速度：启动和响应速度快，适合频繁用于单元测试。
4. 轻量：依赖较少，易于集成到测试环境中。
5. 协议覆盖：支持 STDIO 和 HTTP/SSE 两种 MCP 传输协议，可测试客户端在不同连接方式下的行为。

安装

将此软件包作为开发依赖项添加到项目中：

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

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

手动运行（用于调试测试）

有时，你可能需要手动运行服务，以调试测试或客户端行为。

STDIO 模式

这是最简单的运行方式，尤其适用于本地开发和调试。

# 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

服务会监听标准输入，并将 MCP 响应输出到标准输出。你可以使用 MCP Inspector 等工具连接此进程。

要在 MCP 客户端中配置此服务，请将以下内容添加到配置中：

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

HTTP/SSE 模式

如果你需要通过网络接口调试，或测试基于 HTTP 的 MCP 客户端。

# 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

服务将在 http://localhost:3000 启动，并提供：

• SSE 端点：/sse
• 消息端点：/messages

在测试中使用

你可以在测试框架（如 Jest、Vitest、Mocha 等）中以编程方式启动和停止 mcp-hello-world 服务，进行自动化测试。

示例：使用 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
});

示例：使用 HTTP/SSE 模式进行测试

对于 HTTP/SSE，你可能需要：

1. 在 beforeAll 中使用 exec 或 spawn 启动 pnpm start:http 或 bun run start:http。
2. 使用 HTTP 客户端（如 axios、node-fetch 或测试框架内置的客户端）连接到 http://localhost:3000/sse 和 /messages 进行测试。
3. 确保在 afterAll 中关闭已启动的服务进程。

提供的 MCP 能力（用于测试断言）

mcp-hello-world 提供以下固定能力，供你在测试中交互和断言：

资源

• hello://world
  • 描述：静态的 Hello World 资源。
  • 方法：resources/get
  • 参数：无
  • 返回：{ data: 'Hello World!' }
• greeting://{name}
  • 描述：动态问候资源。
  • 方法：resources/get
  • 参数：name 包含在 URI 中，例如 greeting://Bob。
  • 返回：{ data: 'Hello {name}!' }（例如，{ data: 'Hello Bob!' }）

工具

• echo
  • 描述：回显输入的消息，并在前面加上 "Hello "。
  • 方法：tools/invoke
  • 参数：{ name: 'echo', parameters: { message: string } }
  • 返回：{ content: [{ type: 'text', text: 'Hello {message}' }] }（例如，{ content: [{ type: 'text', text: 'Hello test' }] }）
• debug
  • 描述：列出服务上所有可用的 MCP 方法定义。
  • 方法：tools/invoke
  • 参数：{ name: 'debug', parameters: {} }
  • 返回：包含所有已注册资源、工具和提示词定义的 JSON 结构。

提示词

• helpful-assistant
  • 描述：基础助手提示词定义。
  • 方法：prompts/get
  • 参数：无
  • 返回：包含预定义 system 和 user 角色的提示词 JSON 结构。

许可证

MIT