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

人工智能LLM 网关API网关后端【免费下载链接】bifrostFastest enterprise AI gateway (50x faster than LiteLLM) with adaptive load balancer, cluster mode, guardrails, 1000 models support 100 µs overhead at 5k RPS.项目地址https://gitcode.com/gh_mirrors/bifrost31/bifrost点击查看免费下载本篇技术指南围绕 Bifrost 开源仓库中用于 MCP 集成测试的标准测试服务器test-tools-server展开介绍其定位、五个内置测试工具的设计意图、TypeScript 源码实现架构以及如何在 Bifrost 中以 STDIO 传输方式接入使用。读完本文你将掌握一个可复用的 MCP 测试工具服务器模板并能将其接入 Bifrost 的 MCP 客户端配置用于验证工具发现、超时、错误处理、参数校验等典型链路。一、什么是 test-tools-servertest-tools-server是 Bifrost 仓库examples/mcps/目录下提供的一个标准 MCPModel Context ProtocolSTDIO 服务器定位是为集成测试提供一组常见、稳定、可预期的测试工具。它由 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回声测试messagestring必填原样返回消息calculator基本算术运算operation枚举add/subtract/multiply/divide、x、ynumber必填返回计算结果除零时返回isError: trueget_weather模拟天气数据locationstring必填、unitsstring可选返回固定的模拟天气 JSONdelay延迟执行secondsnumber必填阻塞指定秒数后返回用于测试超时throw_error主动抛出错误error_messagestring必填返回isError: true的错误响应这五个工具的设计具有明显的“测试探针”意图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/sdk1.29.0与zod3.24.1开发依赖为typescript5.3.3与types/node20.10.0并设置了bin字段test-tools-server - ./dist/index.js这意味着构建后可直接通过npx test-tools-server或在 STDIO 配置中作为command使用。3.2 参数 SchemaZod 先行源码使用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 格式的inputSchematype: 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.jsontarget: ES2022、module: Node16、outDir: ./dist、strict: true编译 TypeScript再为入口文件赋予可执行位使其可以作为命令直接调用。package.json还定义了prepare: npm run build在npm install阶段会自动完成构建因此首次安装依赖后即可直接运行。五、接入 BifrostSTDIO 客户端配置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 链路测试工具发现测试通过tools/list确认 Bifrost 聚合了echo、calculator、get_weather、delay、throw_error五个工具且 Schema 描述与名称、必填字段正确透传正向调用测试调用echo验证消息回显、调用calculator验证四则运算结果检查工具结果 JSON 是否被正确封装进 Agent 对话参数校验测试向calculator传入缺失的operation或非数字x验证 Zod 解析失败后返回的isError: true错误是否在 Bifrost 层被正确标记与分类超时与延迟测试调用delay如seconds: 30触发网关请求超时、重试或流式回退逻辑错误链路测试调用throw_error验证错误消息从工具结果到 Agent 提示词的完整传递以及错误工具输出是否被正确识别Bifrost 仓库中存在专门的toolmessageiserror_test.go、toolerrormarker_test.go等测试文件佐证这类关注点。七、延伸阅读与相关资源服务器完整实现src/index.ts项目配置package.json、tsconfig.jsonBifrost STDIO 客户端配置docs/mcp/agent-mode.mdxBifrost MCP 配置文件示例examples/configs/v1compat/config.jsonBifrost MCP 测试基础设施core/internal/mcptests总而言之test-tools-server是一个轻量但覆盖全面的 MCP 测试工具服务器五个工具对应了 MCP 集成测试中最关键的五个行为分支源码中“Zod Schema 声明 JSON Schema 透传 isError 双层错误处理 STDIO 传输”的实现模式既是接入 Bifrost 进行集成测试的现成沙箱也是一份优秀的 MCP 服务器开发参考模板。赞分享人工智能LLM 网关API网关后端【免费下载链接】bifrostFastest enterprise AI gateway (50x faster than LiteLLM) with adaptive load balancer, cluster mode, guardrails, 1000 models support 100 µs overhead at 5k RPS.项目地址https://gitcode.com/gh_mirrors/bifrost31/bifrost点击查看免费下载相关推荐Blackbird在600社交平台搜索用户名与邮箱带免费AI画像Blackbird在600社交平台搜索用户名与邮箱带免费AI画像 手里只有一个用户ID想确认它还在哪些平台注册过Blackbird 能帮你省掉逐站翻找网络安全网页爬虫CLICloudCLI UI 如何给 Claude 会话设置定时发送的消息并确认它按时触发CloudCLI UI 如何给 Claude 会话设置定时发送的消息并确认它按时触发 场景是你已经有一个 CloudCLIClaude Code UI里的人工智能LLM 网关API网关后端Ktor 集成测试服务器 ktor-test-server 完全指南配置、端口与测试端点解析Ktor 集成测试服务器 ktor test server 完全指南配置、端口与测试端点解析 本篇技术指南围绕 Ktor 仓库中的 ktor test ser后端Web框架微服务上一篇Loonflow与主流系统集成微信、钉钉、飞书完美对接下一篇TensorFlow-Course模型压缩技术终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考