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

这是一个使用TypeScript实现的最小模型上下文协议（MCP）服务器，主要用于作为测试替身/模拟服务器。

核心目的：提供一个轻量级、可控且可预测的MCP服务器环境，用于单元测试或集成测试需要与MCP服务器交互的客户端代码。

注意：此项目不适合生产环境或部署为通用的MCP服务器。

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

当测试与MCP客户端相关的代码时，通常不希望依赖于实际的、可能复杂且响应不可预测的人工智能后端服务。使用mcp-hello-world作为测试替身提供了几个优点：

1. 隔离性：专注于客户端逻辑的测试，无需担心网络问题或实际服务器的可用性。
2. 可预测性：提供的echo和debug工具具有简单固定的特性，使得编写断言变得容易。
3. 速度：快速启动和响应时间，适合频繁用于单元测试。
4. 轻量级：依赖项少，易于集成到测试环境中。
5. 协议覆盖：支持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等工具连接到进程。

要在您的MCP客户端配置中设置此服务器，请添加以下内容：

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

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('我的MCP客户端（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('应接收回声响应', async () => {
    const request = {
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/invoke',
      params: { name: 'echo', parameters: { message: '测试消息' } },
    };

    const response = await client.sendRequest(request); // 假设您的客户端有这个方法

    expect(response).toEqual({
      jsonrpc: '2.0',
      id: 1,
      result: { content: [{ type: 'text', text: 'Hello 测试消息' }] },
    });
  });

  it('应获取问候资源', 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!' }, // 根据实际实现确认返回格式
    });
  });

  // ...其他测试案例
});

示例：使用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
  • 参数：URI中包含name，例如greeting://Bob。
  • 返回：{ data: 'Hello {name}!' }（例如，{ data: 'Hello Bob!' }）

工具

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

提示

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

许可证

MIT