MCP Hello World - 用于测试的 MCP 服务端模拟

这是一个基于 TypeScript 实现的 极简模型上下文协议 (MCP) 服务端，其主要目的是作为测试替身 (Test Double) / 模拟服务器 (Mock Server)。

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

注意： 本项目不适用于生产环境或作为通用的 MCP 服务端部署。

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

在测试与 MCP 客户端相关的代码时，你通常不希望依赖一个真实的、可能复杂的、响应不确定的 AI 后端服务。使用 mcp-hello-world 作为测试替身有以下好处：

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

安装

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

# 使用 pnpm
pnpm add --save-dev mcp-hello-world

# 或者使用 bun
bun add --dev mcp-hello-world

手动运行 (用于调试测试)

有时你可能想手动运行服务来调试你的测试或客户端行为。

STDIO 模式

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

# 确保已安装
# 使用 npx (通用)
npx mcp-hello-world

# 或者使用 pnpm dlx
pnpm dlx mcp-hello-world

# 或者使用 bunx
bunx mcp-hello-world

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

HTTP/SSE 模式

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

# 1. 克隆仓库 (如果尚未在项目中安装)
# git clone https://github.com/lobehub/mcp-hello-world.git
# cd mcp-hello-world
# pnpm install / bun install

# 2. 构建项目
# 使用 pnpm
pnpm build
# 或者使用 bun
bun run build

# 3. 启动 HTTP 服务
# 使用 pnpm
pnpm start:http
# 或者使用 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 (示例使用 Jest)
import { spawn } from 'child_process';
import { MCPClient } from '../src/my-mcp-client'; // 假设这是你要测试的客户端

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

  beforeAll(() => {
    // 在测试开始前启动 mcp-hello-world 进程
    // 使用 npx (或 pnpm dlx / bunx) 确保能找到并执行命令
    mcpServerProcess = spawn('npx', ['mcp-hello-world']);

    // 实例化你的客户端，并连接到子进程的 stdio
    client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);
  });

  afterAll(() => {
    // 测试结束后关闭 mcp-hello-world 进程
    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); // 假设你的客户端有此方法

    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: 'resourc