开发工具MCP Clients调试器【免费下载链接】inspectorVisual testing tool for MCP servers项目地址https://gitcode.com/gh_mirrors/inspector1/inspector点击查看免费下载本篇技术指南以仓库规格文档 specification/v2_server.md 为骨架完整拆解 MCP Inspector一款面向 MCP Server 的可视化测试工具V2 服务端的技术选型与落地实现为什么在 Node TypeScript 运行时上选择 Hono 作为 HTTP 传输框架、选择 Pino 作为日志引擎以及日志文件如何同时承担服务器诊断与请求/响应历史回放的双重职责。读者读完后将掌握服务端路由面/api/*会话与存储接口、鉴权中间件、x-mcp-remote-auth令牌机制与 Pino NDJSON 日志链路的具体设计与源码位置可直接对照 core/mcp/remote/node/server.ts 等实现进行二次开发或集成。一、技术栈总览TypeScript NodeV2 服务端在运行时与语言层面没有悬念TypeScript Node。这不是一次重写而是把原本分散在各客户端中的服务端能力收敛到core/mcp/remote共享内核中供 Web 客户端、CLI、TUI 与 Launcher 共同复用整体架构可参考 specification/diagrams/shared-code-architecture.png 与 specification/v2_scope.md。服务端核心模块的仓库落点非常集中职责仓库路径Hono 远程服务端createRemoteApp全部/api/*路由core/mcp/remote/node/server.ts远程会话生命周期transport 持有、事件队列、requestId 关联core/mcp/remote/node/remote-session.ts浏览器侧日志转发pino/browser transmit →/api/logcore/mcp/remote/createRemoteLogger.ts环境变量命名鉴权令牌、旧名兼容core/mcp/remote/constants.ts生产 Hono 服务器入口startHonoServer静态资源 SPA fallbackclients/web/server/server.ts服务端配置装配端口、绑定主机、日志文件、允许来源clients/web/server/web-server-config.ts命令行启动入口--catalog/--config/ ad-hoc serverclients/web/server/run-web.ts二、传输层选型为什么是 Hono规格文档把候选框架的取舍状态明确标注为Hono 已选定-[x]Express 与 Node 原生http未采用-[ ]。选型依据是社区共识PR #945 讨论与现代化 Web 标准对齐并契合 TypeScript SDK v2 的方向。Hono 与 Express 的对比需求项HonoExpressBundle 体积12kb约 1mbWeb 标准Request/Response是原生支持否需要 shim 垫片TypeScript 原生是否依赖 types 包可 Tree-shaking是完全支持否HTTP/2 支持是否SPDY 已放弃内置中间件是Body 解析、认证等否需要插件Edge/Serverless 部署是原生支持部分支持需要适配器Hono 的五项核心收益Web 标准对齐直接使用原生Request/Response对象可在 Node、Deno、Bun、Serverless 与 Edge 环境间无缝部署TypeScript 原生无需外部类型包即获得完整类型安全不需要对请求对象做 monkey-patching面向未来HTTP/2 支持为潜在的 gRPC 传输留出空间并与 TypeScript SDK v2 的计划一致开发者体验API 更简单、上下文类型安全、学习曲线更平缓包体效率显著更小的体积同时惠及开发与部署环节。源码印证Hono 在仓库中的实际落点规格并非停留在纸面。在 core/mcp/remote/node/server.ts 中createRemoteApp()直接new HonoEnv()并注册了完整路由面GET /api/config返回客户端初始配置默认命令/参数/传输类型、环境变量、版本号、可写性标志、沙箱地址POST /api/mcp/connect/POST /api/mcp/send/GET /api/mcp/eventsSSE 流/POST /api/mcp/disconnect/POST /api/mcp/auth-stateMCP 远程会话的完整生命周期POST /api/fetch服务端代发 HTTP 请求带内容类型探测text/event-stream与application/x-ndjson直接透传不缓存 bodyPOST /api/log接收客户端转发的日志事件GET/POST/DELETE /api/storage/:storeId键值存储含client专用 storeGET/POST/PUT/DELETE /api/servers与PUT /api/servers/order、GET /api/servers/events服务器目录mcp.json的 CRUD、排序与文件监听GET /api/import-source读取其他 MCP 客户端Claude Desktop、Cursor、Cline、VSCode的配置文件用于导入。生产服务器入口 clients/web/server/server.ts 则用hono/node-server的serve()启动 HTTP 服务配合serveStatic提供静态资源并将/api/*前缀代理给createRemoteApp返回的 Hono app其余路径走 SPA 深链接 fallbackindex.html注入鉴权令牌后返回Cache-Control: no-store防止令牌过期页面被缓存。三、日志选型Pino 与双用途日志架构规格文档同样用勾选状态明确Pino 已选定-[x]Winston、Morgan、Log4js、Bunyan 未采用-[ ]。选型理由并非单纯快而是为了与History Screen历史记录屏功能协同日志文件同时承担两个职责——服务器标准诊断日志、以及请求/响应回放的历史数据源。Pino 与 Winston 的对比需求项PinoWinston默认 JSON 格式是NDJSON否文本需要配置逐行解析是原生支持否需要额外工作高吞吐日志是非常快部分支持较慢日志轮转是pino-roll是winston-daily-rotate开发友好输出是pino-pretty是内置日志架构┌─────────────────────────────────────────────────────────────────┐ │ Server │ │ │ │ MCP Request ──▶ Pino Logger ──┬──▶ history.ndjson (file) │ │ │ │ │ └──▶ Console (pino-pretty) │ │ │ │ History API: GET /api/history?methodtools/calllimit50 │ │ (parses history.ndjson, returns filtered JSON) │ └─────────────────────────────────────────────────────────────────┘日志条目 Schema每次 MCP 操作记录一对请求/响应日志{ts:1732987200000,level:info,type:mcp_request,method:tools/call,target:echo,params:{message:hello},requestId:abc123,serverId:my-server} {ts:1732987200045,level:info,type:mcp_response,requestId:abc123,result:{content:[{type:text,text:hello}]},duration:45,success:true}字段说明tsUnix 时间戳毫秒level日志级别info、error 等typemcp_request或mcp_responsemethodMCP 方法名tools/call、resources/read、prompts/get 等target工具名、资源 URI 或提示词名params请求参数requestId关联 ID用于把请求与响应配对serverId服务器标识result响应数据仅mcp_responseerror错误信息失败请求duration响应耗时毫秒success成功/失败布尔标志依赖清单pino核心日志器pino-pretty开发环境控制台格式化pino-roll日志轮转可选pino-httpExpress 集成说明规格文档列出的pino-http面向 Express 生态在当前仓库的 Hono 实现中日志接入点改为路由层与转发函数完成见下文pino-http并未被引入。日志轮转类能力属于可选增强当前落地以文件追加与轮转前的核心链路为主。源码印证日志链路的真实实现当前仓库已经把双用途的骨架落地但实现路径比规格更简洁客户端把日志事件 POST 回服务端由服务端统一写入 pino 文件 logger。服务端日志文件开关在 clients/web/server/web-server-config.ts 的buildWebServerConfig()中当设置环境变量MCP_LOG_FILE时会用pinopino.destination({ dest, append: true, mkdir: true })创建文件 logger自动追加、自动建目录并通过RemoteServerOptions.logger传给createRemoteApplet logger: Logger | undefined; if (process.env.MCP_LOG_FILE) { logger pino( { level: info }, pino.destination({ dest: process.env.MCP_LOG_FILE, append: true, mkdir: true }), ); }浏览器侧转发core/mcp/remote/createRemoteLogger.ts 用pino/browser的transmit机制把浏览器内产生的日志事件封装为POST {baseUrl}/api/log请求头携带Content-Type: application/json并在配置了令牌时附带x-mcp-remote-auth: Bearer token投递失败静默忽略保证日志链路不干扰主流程transmit: { level, send: (_level: unknown, logEvent: LogEvent) { const headers: Recordstring, string { Content-Type: application/json }; if (options.authToken) headers[x-mcp-remote-auth] Bearer ${options.authToken}; fetchFn(${baseUrl}/api/log, { method: POST, headers, body: JSON.stringify(logEvent), }).catch(() { /* Silently ignore log delivery failures */ }); }, }服务端接收与转发POST /api/log路由收到事件后调用forwardLogEvent()位于 core/mcp/remote/node/server.ts把LogEvent的 bindings 与 message 重组为对应级别的 pino 调用最终落到MCP_LOG_FILE指定的文件里。这与规格中日志文件 服务器诊断 历史持久化数据源的设计一脉相承Node 模式与浏览器模式最终写进同一个文件 logger天然形成 NDJSON 历史流后续 History Screen 只需按行解析并过滤如GET /api/history?methodtools/calllimit50即可回放。四、安全与鉴权令牌、Origin 校验与例外开关服务端在选型之外还内置了两层安全中间件同样在 core/mcp/remote/node/server.ts 中注册先过 Origin 校验、再过鉴权Origin 校验DNS rebinding 防护createOriginMiddleware(allowedOrigins)在配置了allowedOrigins时逐请求校验Origin头预检OPTIONS放行并回写 CORS 头非法来源直接返回 403 并提示Configure allowed origins via allowedOrigins option。默认来源由 clients/web/server/web-server-config.ts 的defaultAllowedOrigins()按绑定主机推导loopback 绑定返回localhost/127.0.0.1/[::1]三种等价形态适配 IPv6 解析的不确定性全接口绑定0.0.0.0/::Docker 镜像采用额外附加通配来源显式ALLOWED_ORIGINS环境变量可覆盖非法条目opaque origin、通配符会被警告并丢弃。令牌鉴权createAuthMiddleware(authToken)要求请求头x-mcp-remote-auth: Bearer token并做长度预检 timingSafeEqual恒定时间比较从根上规避时序侧信道攻击。令牌的取值优先级为显式传入authToken参数 → 环境变量MCP_INSPECTOR_API_TOKEN旧名MCP_PROXY_AUTH_TOKEN兼容见 core/mcp/remote/constants.ts→ 每次启动randomBytes(32)自动生成。生产服务器把令牌注入到index.html的window.__INSPECTOR_API_TOKEN__全局变量中见 clients/web/server/inject-auth-token.ts浏览器据此免去手动传递。危险开关DANGEROUSLY_OMIT_AUTH通过环境变量开启后跳过令牌鉴权Origin 校验仍然生效供本地开发或受控环境使用官方注释明确不推荐用于任何暴露在公网的部署。令牌生成逻辑中的空字符串即为该模式的信号。五、远程会话与 MCP 传输生命周期远程服务端的核心是把浏览器中的 MCP 客户端与真正的上游 transport 桥接起来。POST /api/mcp/connect用crypto.randomUUID()创建会话调用createTransportNode见 core/mcp/node/transport.ts生成实际 transport并装配RemoteSessioncore/mcp/remote/node/remote-session.ts事件队列transport 的消息、stderr、fetch 请求记录先进会话的事件队列浏览器打开GET /api/mcp/eventsSSE后一次性排空transport 死亡时子进程崩溃会先推送transport_error事件错误码-32000并保留 30 秒的宽限期让事件端点把真实错误吐给客户端requestId 关联/api/mcp/send通过requestIdForSendWait()判定是否等待 JSON-RPC 响应其中subscriptions/listen现代协议时代issue #1630这类长连接流式请求被显式豁免——它永不产生 JSON-RPC 响应等待会让/api/mcp/send卡满整个超时协议版本透传applyProtocolVersion()把浏览器 SDK 协商出的Mcp-Protocol-Version打到上游 transport 上issue #1935并用正则^[A-Za-z0-9._-]{1,64}$校验防止客户端把任意字节塞进上游请求头Firefox 兼容性两个 SSE 端点/api/mcp/events与/api/servers/events在流打开瞬间写入一个:\n\n注释行作为priming见SSE_PRIMING_COMMENTissue #1858——Firefox 要等到第一个 body 字节才把fetch()交给 JS不注入该行会导致浏览器永远卡在Connecting…按发送限制请求头mcpParamHeadersOnly()只允许客户端把Mcp-Param-*前缀的字符串头透传到上游杜绝Authorization等敏感头被注入SEP-2243。服务端同时承担服务器目录的持久化/api/servers读写mcp.json默认~/.mcp-inspector/mcp.json带写锁串行化读改写、chokidar文件监听 SSE 广播外部编辑、首次读取自动播种默认配置并对历史遗留的嵌套settings节点、畸形字段做规范化清洗writable: false--config只读会话或 ad-hoc 启动会以 403 拒绝所有目录变更。详情可对照 specification/v2_storage.md。六、规格与实现的对照哪些已落地、哪些是蓝图规格项当前仓库落地状态TypeScript Node 运行时已落地core/mcp/remote全部为 TSHono 作为 HTTP 框架已落地core/mcp/remote/node/server.ts、clients/web/server/server.tsPino 文件日志MCP_LOG_FILE已落地clients/web/server/web-server-config.ts浏览器 →/api/log日志转发已落地core/mcp/remote/createRemoteLogger.tshistory.ndjson文件与GET /api/history历史回放 API规格蓝图。经仓库检索该端点与文件名目前仅出现在本规格文档中尚未在服务端源码实现当前的历史数据沉淀由MCP_LOG_FILE指向的 pino NDJSON 文件承担七、如何查看与运行服务端开发模式在仓库根目录执行npm run devVite CLI Hono 开发插件等价于--dev路径生产模式通过 Launcher 或 CLI 以--web启动走 clients/web/server/run-web.ts 的runWeb()缺失dist时会先执行ensureWebBuild自动构建前端再启动 Hono 服务器常用环境变量CLIENT_PORT默认 6274必须是 1–65535 的固定端口因为 Origin 白名单与沙箱 CSP 都依赖它、MCP_LOG_FILE日志文件路径、MCP_INSPECTOR_API_TOKEN鉴权令牌、MCP_PROXY_AUTH_TOKEN旧名兼容、ALLOWED_ORIGINS逗号分隔来源白名单、DANGEROUSLY_OMIT_AUTH、MCP_AUTO_OPEN_ENABLED、MCP_CATALOG_PATH/MCP_STORAGE_DIRLauncher 参数--catalog path可写目录文件、--config path只读会话文件、--server-url/命令ad-hoc 单服务器、纯内存、不落盘、--header Header: ValueHTTP/SSE 传输的自定义头stdio 会报错拒绝。结语MCP Inspector 的 V2 服务端选型思路清晰用 12kb 的 Hono 换取 Web 标准与多运行时部署弹性用 NDJSON 原生的 Pino 换取诊断 回放一鱼两吃的日志架构再叠加令牌鉴权、Origin 校验、SSE 会话桥接与 mcp.json 目录管理构成一个单机可跑、标准可读、结构可扩展的远程服务内核。后续演进方向history.ndjson解析、/api/history过滤回放、pino-roll 轮转、HTTP/2/gRPC 传输都可在这个骨架上平滑生长。想继续深入建议按序阅读 specification/v2_server.md本文依据、specification/v2_web_client.md客户端如何消费这些 API与 specification/v2_storage.md存储层细节并对照 core/mcp/remote/node/server.ts 逐路由研读。赞分享开发工具MCP Clients调试器【免费下载链接】inspectorVisual testing tool for MCP servers项目地址https://gitcode.com/gh_mirrors/inspector1/inspector点击查看免费下载相关推荐OpenStatus 服务端架构解析Hono on Deno 的四面路由、API Key 双层权限与 MCP 作用域门控OpenStatus 服务端架构解析Hono on Deno 的四面路由、API Key 双层权限与 MCP 作用域门控 OpenStatus 的 API 服可观测性运维后端告警OpenHuman MCP 模块深度解析静态 TOML 服务器注册表、双传输客户端与 openhuman mcp 服务器OpenHuman MCP 模块深度解析静态 TOML 服务器注册表、双传输客户端与 openhuman mcp 服务器 本篇以 OpenHuman 仓库中人工智能AI 应用本地部署AI Agent交互助手深度研究如何快速掌握ModelContextProtocol Inspector的HTTP传输架构完整指南如何快速掌握ModelContextProtocol Inspector的HTTP传输架构完整指南 ModelContextProtocol Inspecto开发工具MCP Clients调试器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
