技能介绍

这个技能解决什么问题

用 TypeScript 写 MCP server 看起来门槛不高，实际有几个坑会反复出现：console.log 混入 stdout 直接打断 JSON-RPC 通信；手写的 Zod schema 和 execute 里实际使用的字段对不上，运行时才报错；fastmcp dev 只提供交互式 Web UI，没法写进脚本做回归测试；同一个 server 想同时服务本地客户端和 Web 端，又得维护两份入口代码。这份文档把这类高频问题整理成一条固定流程，照着走即可。

核心能力与工作方式

运行时与框架：用 Bun 原生执行 TypeScript，省去编译步骤；框架选 TypeScript 版 fastmcp，基于官方 MCP SDK 封装，通过 server.addTool() 注册工具。
参数校验：默认用 Zod（任何实现 Standard Schema 的库均可），配合 .describe() 写清每个参数的含义与取值范围。
日志隔离：在 src/lib/logger.ts 中把日志重定向到 stderr，每个入口文件第一行 import "./lib/logger.ts";，stdout 只留给协议。
开发闭环：先 tsc --noEmit 做类型检查，再 fastmcp dev 人工核对 schema 与返回值，最后用 inspector --cli 写自动化用例——该命令阻塞执行、返回结构化 JSON 后退出，正好适合脚本断言与 CI。
错误分层：业务错误用 isError: true 返回文本，让模型据此重试或调整参数；只有协议级错误才抛 McpError。
双传输模式：把 server 创建与 tool 注册抽到共享模块，index.ts 走 stdio、index-http.ts 走 httpStream，tool 代码只写一遍。

适用边界与注意点

文档基于 bun ^1.3.x 与 fastmcp ^4.x，两者迭代很快。写认证、sampling、roots、流式进度等复杂功能前，务必用 web_search/web_fetch 核对最新 README，不要凭记忆写 API。
fastmcp dev / inspect 是交互式界面，定位是开发期人工核对，不能替代 inspector --cli 做自动化回归。
HTTP 模式下 FastMCP 默认开启的 CORS 只方便本地调试，暴露到团队以外前必须在反向代理或配置层加鉴权。
MCP 规范正从 SSE 迁移到 Streamable HTTP，部署前确认当前版本的端点路径是 /sse 还是 /mcp，以及客户端是否需要 transport: "streamable-http"。