构建 Bifrost MCP 集成测试的标准 STDIO 测试服务器：test-tools-server 深入解析

• 人工智能
• LLM 网关
• API网关
• 后端

本篇技术指南围绕 Bifrost 开源仓库中用于 MCP 集成测试的标准测试服务器test-tools-server展开，介绍其定位、五个内置测试工具的设计意图、TypeScript 源码实现架构以及如何在 Bifrost 中以 STDIO 传输方式接入使用。读完本文，你将掌握一个可复用的 MCP 测试工具服务器模板，并能将其接入 Bifrost 的 MCP 客户端配置，用于验证工具发现、超时、错误处理、参数校验等典型链路。

一、什么是 test-tools-server

test-tools-server是 Bifrost 仓库examples/mcps/目录下提供的一个标准 MCP（Model Context Protocol）STDIO 服务器，定位是为集成测试提供一组常见、稳定、可预期的测试工具。它由 TypeScript 编写，基于官方@modelcontextprotocol/sdk构建，运行在标准输入输出（STDIO）传输层之上，因此不需要暴露网络端口，可以被 Bifrost 等 MCP 客户端以本地子进程方式直接拉起。

与仓库examples/mcps/下的其他示例服务器（如 remote-test-server、error-test-server、parallel-test-server、go-test-server）不同，test-tools-server刻意保持“小而全”：五个工具分别覆盖了 MCP 工具调用中最常见的行为分支，是编写 MCP 集成测试时的理想沙箱。

二、五个内置测试工具一览

test-tools-server通过tools/list协议方法对外暴露以下五个工具（源码定义见 src/index.ts）：

这五个工具的设计具有明显的“测试探针”意图：

• echo是最基本的正向路径工具，用于验证 MCP 工具发现与调用的最小闭环是否打通；
• calculator覆盖了带枚举参数的多输入工具，其除零分支用于验证错误结果（isError）在 Bifrost 链路中的传递；
• get_weather模拟真实世界 API 的典型形态（必填 + 可选参数），且返回的是结构化 JSON 字符串，可验证工具结果解析与内容封装；
• delay专门用于触发请求超时、重试或并发控制逻辑；
• throw_error则用于验证错误响应、错误分类与错误标记在整个网关链路上的行为。

三、源码架构剖析

3.1 项目结构与依赖

仓库中的完整文件布局如下：

examples/mcps/test-tools-server/ ├── README.md # 项目说明 ├── package.json # 依赖与构建脚本 ├── package-lock.json # 锁文件 ├── tsconfig.json # TypeScript 编译配置 └── src/ └── index.ts # 服务器唯一实现入口

package.json 声明了运行时依赖@modelcontextprotocol/sdk@1.29.0与zod@3.24.1，开发依赖为typescript@5.3.3与@types/node@20.10.0，并设置了bin字段test-tools-server -> ./dist/index.js，这意味着构建后可直接通过npx test-tools-server或在 STDIO 配置中作为command使用。

3.2 参数 Schema：Zod 先行

源码使用zod为每个工具声明输入参数的运行时 Schema，这是整个实现的核心设计——先定义 Schema，再用于参数解析。例如：

const CalculatorSchema = z.object({ operation: z.enum(["add", "subtract", "multiply", "divide"]).describe("The operation to perform"), x: z.number().describe("First number"), y: z.number().describe("Second number"), });

在CallToolRequestSchema处理器中，通过EchoSchema.parse(request.params.arguments)对调用方传入的参数进行校验，一旦参数不符合 Schema（例如缺少必填字段、类型错误），parse会抛出异常，被外层try/catch捕获后统一转换为isError: true的工具错误响应。这一模式展示了 MCP 服务器端如何用一套 Schema 同时完成“声明”与“校验”两件事。

3.3 服务器与能力声明

服务器实例通过Server构造器创建，声明了名称、版本与能力：

const server = new Server( { name: "test-tools-server", version: "1.0.0" }, { capabilities: { tools: {} } } );

capabilities.tools声明该服务器只暴露 tools 能力，不涉及 resources 或 prompts。随后通过server.setRequestHandler(ListToolsRequestSchema, ...)注册tools/list处理器，返回每个工具的名称、描述与 JSON Schema 格式的inputSchema（type: "object"、properties、required字段），与 MCP 规范要求的工具发现协议完全对齐。

3.4 工具执行分发与错误处理

CallToolRequestSchema处理器使用switch (toolName)按工具名分发，每个分支均调用对应的 Zod Schema 解析参数并执行逻辑。值得关注的两个错误分支：

• 除零错误：calculator在args.y === 0时返回带isError: true的文本响应，而不是抛出异常；
• 主动抛错：throw_error返回isError: true且内容为用户指定的error_message；
• 兜底捕获：整个switch包裹在try/catch中，任何未知工具名或参数解析失败都会被捕获，统一返回Error: ...的isError: true响应。

这种“双层错误模型”（业务级错误响应 + 异常兜底）与 Bifrost 对 MCP 工具错误结果的处理逻辑相呼应——错误结果会携带isError标记，便于上游 Agent 区分“工具执行失败”与“协议层异常”。

3.5 STDIO 启动与主函数

启动逻辑位于main()函数：

const transport = new StdioServerTransport(); await server.connect(transport); console.error("Test Tools MCP Server running on stdio");

使用StdioServerTransport将服务器连接到标准输入输出，客户端通过子进程的标准 I/O 与该服务器进行 JSON-RPC 消息交换。console.error用于输出日志而不会污染 STDIO 协议通道——这是 STDIO 传输的一个关键约定：协议消息走 stdout，日志必须走 stderr。

四、构建与运行

原文档给出了三步操作流程，结合 package.json 的脚本定义可进一步说明：

# 1. 安装依赖 npm install # 2. 构建（tsc 编译 + 为产物添加可执行权限） npm run build # 3. 运行（以 STDIO 模式启动，等待客户端连接） node dist/index.js

其中build脚本为tsc && chmod +x dist/index.js，即先由 tsconfig.json（target: ES2022、module: Node16、outDir: ./dist、strict: true）编译 TypeScript，再为入口文件赋予可执行位，使其可以作为命令直接调用。package.json还定义了prepare: npm run build，在npm install阶段会自动完成构建，因此首次安装依赖后即可直接运行。

五、接入 Bifrost：STDIO 客户端配置

test-tools-server被设计为通过 STDIO 传输与 Bifrost 的 MCP 集成测试配合使用（见原文档 Integration Testing 一节）。Bifrost 的 MCP 客户端管理支持connection_type: "stdio"的外部服务器接入，这在 docs/mcp/agent-mode.mdx 中给出了标准配置形态：

{ "name": "test-tools", "connection_type": "stdio", "stdio_config": { "command": "node", "args": ["/path/to/examples/mcps/test-tools-server/dist/index.js"] }, "tools_to_execute": ["*"], "tools_to_auto_execute": ["*"] }

对应地，在 Bifrost 的配置文件中通过mcp.client_configs数组声明 STDIO 客户端，例如 examples/configs/v1compat/config.json 中展示的配置结构（该示例使用http连接类型，STDIO 场景将connection_type换为stdio并补充stdio_config即可）：

"mcp": { "client_configs": [ { "name": "internal_tools", "connection_type": "stdio", "stdio_config": { "command": "node", "args": ["examples/mcps/test-tools-server/dist/index.js"] }, "tools_to_execute": ["*"], "allow_by_default": false } ] }

从源码结构看，Bifrost 的 MCP 测试基础设施（core/internal/mcptests 目录）广泛使用了外部 STDIO 测试服务器：agent_test_helpers.go中的SetupMultiClientAgentTest接收stdioClients参数用于构造多客户端 Agent 测试场景（agent_test_helpers.go），而 agent_multiconnection_test.go 的注释明确说明测试场景包括“External MCP servers via stdio (go-test-server, parallel-test-server)”。这印证了examples/mcps/下各测试服务器与core/internal/mcptests的配套关系。

六、典型集成测试场景

结合五个工具的能力，可以构造以下典型的 Bifrost MCP 链路测试：

1. 工具发现测试：通过tools/list确认 Bifrost 聚合了echo、calculator、get_weather、delay、throw_error五个工具，且 Schema 描述与名称、必填字段正确透传；
2. 正向调用测试：调用echo验证消息回显、调用calculator验证四则运算结果，检查工具结果 JSON 是否被正确封装进 Agent 对话；
3. 参数校验测试：向calculator传入缺失的operation或非数字x，验证 Zod 解析失败后返回的isError: true错误是否在 Bifrost 层被正确标记与分类；
4. 超时与延迟测试：调用delay（如seconds: 30）触发网关请求超时、重试或流式回退逻辑；
5. 错误链路测试：调用throw_error验证错误消息从工具结果到 Agent 提示词的完整传递，以及错误工具输出是否被正确识别（Bifrost 仓库中存在专门的toolmessageiserror_test.go、toolerrormarker_test.go等测试文件佐证这类关注点）。

七、延伸阅读与相关资源

• 服务器完整实现：src/index.ts
• 项目配置：package.json、tsconfig.json
• Bifrost STDIO 客户端配置：docs/mcp/agent-mode.mdx
• Bifrost MCP 配置文件示例：examples/configs/v1compat/config.json
• Bifrost MCP 测试基础设施：core/internal/mcptests

总而言之，test-tools-server是一个轻量但覆盖全面的 MCP 测试工具服务器：五个工具对应了 MCP 集成测试中最关键的五个行为分支，源码中“Zod Schema 声明 + JSON Schema 透传 + isError 双层错误处理 + STDIO 传输”的实现模式，既是接入 Bifrost 进行集成测试的现成沙箱，也是一份优秀的 MCP 服务器开发参考模板。

• 人工智能
• LLM 网关
• API网关
• 后端