lobehubMCP Hello World - 用于测试的 MCP 服务端模拟
这是一个基于 TypeScript 实现的 极简模型上下文协议 (MCP) 服务端，其主要目的是作为测试替身 (Test Double) / 模拟服务器 (Mock Server)。
核心用途：在针对需要与 MCP 服务端交互的客户端代码进行单元测试或集成测试时，提供一个轻量级、可控且行为可预测的 MCP 服务端环境。
注意： 本项目不适用于生产环境或作为通用的 MCP 服务端部署。
为什么在测试中使用 mcp-hello-world？
在测试与 MCP 客户端相关的代码时，你通常不希望依赖一个真实的、可能复杂的、响应不确定的 AI 后端服务。使用 mcp-hello-world 作为测试替身有以下好处：
- 隔离性 (Isolation)：让你的测试专注于客户端逻辑，而无需关心网络问题或真实服务端的可用性。
- 可预测性 (Predictability)：提供的
echo和debug工具行为简单且固定，方便编写断言。 - 速度 (Speed)：启动和响应速度快，适合在单元测试中频繁使用。
- 轻量级 (Lightweight)：依赖少，易于在测试环境中集成。
- 协议覆盖 (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: '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，你可能需要：
- 在
beforeAll中使用exec或spawn启动pnpm start:http或bun run start:http。 - 使用 HTTP 客户端 (如
axios,node-fetch, 或测试框架内置的) 连接到http://localhost:3000/sse和/messages端点进行测试。 - 在
afterAll中确保关闭启动的服务器进程。
提供的 MCP 能力 (用于测试断言)
mcp-hello-world 提供以下固定的能力，供你在测试中进行交互和断言：
资源 (Resources)
hello://world- 描述: 一个静态的 Hello World 资源。
- 方法:
resources/get - 参数: 无
- 返回:
{ data: 'Hello World!' }
greeting://{name}- 描述: 一个动态的问候资源。
- 方法:
resources/get - 参数: URI 中包含
name，例如greeting://Bob。 - 返回:
{ data: 'Hello {name}!' }(例如:{ data: 'Hello Bob!' })
工具 (Tools)
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: {} } - 返回: 包含所有已注册的 resources, tools, prompts 定义的 JSON 结构。
提示词 (Prompts)
helpful-assistant- 描述: 一个基础的助手提示词定义。
- 方法:
prompts/get - 参数: 无
- 返回: 一个包含预定义
system和user角色的提示词结构 JSON。
许可证
MIT
