结论先说
- 官方 TypeScript 包名是
@modelcontextprotocol/sdk,搭配zod做参数校验,要求 Node.js 18 及以上版本。 - 高层开发直接用
McpServer类:调用registerTool暴露可执行工具,调用registerResource暴露只读 URI 数据,不用自己手写底层 JSON-RPC 分发逻辑。 - 项目需开启 ES Modules 且导入路径带
.js后缀:package.json设"type": "module",tsconfig.json设"moduleResolution": "Node16"。 - 本地 stdio 服务器严禁调用
console.log():标准输出只允许传输协议消息,调试日志一律改写到console.error()。 - 先过 Inspector 再挂客户端:用
npx @modelcontextprotocol/inspector在网页里调通工具后,再填进 Claude Code 或桌面端配置。 - 主力模型订阅与账号配套入口:跑通 MCP 工具链与多文件智能体编码依赖稳定的底层大模型配额,国内免境外卡自助开通可见本站 Claude Code 订阅页、ChatGPT Plus 充值页 与 AI 会员充值总览。

图:本站根据 modelcontextprotocol/typescript-sdk 官方文档 整理的示意图
本文根据 MCP 官方仓库《modelcontextprotocol/typescript-sdk》、官方文档《Build an MCP server》与《MCP Inspector》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 或 MCP 官方网站。
适用于谁
- 熟悉前端或 Node.js,搜「typescript 开发 mcp server」想把内部接口封装成工具的开发者;
- 照着旧博客写代码遇到子路径导入报错、编译不过或客户端一连就断的人;
- 想同时搞懂
registerTool和registerResource标准写法的工程师。
如果你更习惯用 Python 写服务端,可以直接看另一篇 MCP Server 开发入门(Python)。
一、初始化项目与 TypeScript 配置
新建项目目录,安装官方 SDK、Zod 以及编译依赖:
bash
mkdir my-ts-mcp && cd my-ts-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
mkdir src
打开 package.json,确保加上 "type": "module" 与构建脚本:
json
{
"name": "my-ts-mcp",
"version": "1.0.0",
"type": "module",
"scripts": {
"build": "tsc"
}
}
接着在根目录新建 tsconfig.json。按官方《Build an MCP server》要求,module 和 moduleResolution 都要设为 Node16,否则编译器认不出 SDK 的子路径导出:
json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*"]
}
二、编写第一个服务器:注册 Tool 与 Resource
新建 src/index.ts。注意导入 SDK 模块时,末尾必须保留 .js 扩展名(这是 TypeScript 在 Node16 模块模式下的标准要求):
typescript
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({
name: "order-helper",
version: "1.0.0",
});
// 1. 注册可执行工具(Tool)
server.registerTool(
"calc-discount",
{
title: "折扣价计算器",
description: "根据原价和折扣率计算折后金额,折率填 0 到 1 之间的小数",
inputSchema: {
price: z.number().positive().describe("商品原价,必须大于 0"),
rate: z.number().min(0).max(1).describe("折扣比例,例如 0.85 表示八五折"),
},
},
async ({ price, rate }) => {
const finalPrice = (price * rate).toFixed(2);
return {
content: [
{
type: "text",
text: `折后金额为:${finalPrice}`,
},
],
};
}
);
// 2. 注册动态资源(Resource)
server.registerResource(
"env-guide",
new ResourceTemplate("guide://{topic}", { list: undefined }),
{
title: "内部开发规范片段",
description: "按主题名读取团队内部简明规范",
},
async (uri, { topic }) => ({
contents: [
{
uri: uri.href,
text: `主题 [${topic}] 的规范说明:接口超时统一设为 10 秒。`,
},
],
})
);
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("order-helper MCP Server 已通过 stdio 启动");
}
main().catch((err) => {
console.error("启动失败:", err);
process.exit(1);
});
写这段代码时重点盯住四个细节:
- 每个 Zod 参数都加上
.describe(...):模型看不到你的函数体源码,只能读编译出来的 JSON Schema 描述。把单位、取值范围和格式示例写在描述里,能大幅减少模型乱传参。 - 静态资源与模板资源的区别:上面示例用了
ResourceTemplate处理带变量的地址(如guide://api);如果你的资源是固定文件或固定说明页,第二个参数直接传字符串地址(如"config://app")即可,无需包一层模板对象。 - 善用工具安全注解(Annotations):如果某个工具只查数据不改状态,可以在配置对象里补充
annotations: { readOnlyHint: true };如果涉及删库或覆盖文件,可标上destructiveHint: true,支持该特性的客户端会据此调整审批提示强度。 - 切记用
console.error打日志:只要代码里或引用的第三方包往stdout打了一行普通文本,客户端解析 JSON-RPC 帧就会立刻报错断开。密钥读取同理,统一走process.env.YOUR_API_KEY,由客户端配置的env字段注入,不要硬编码在源码里。
如果需要把服务部署到公网供多人连接,只需把 StdioServerTransport 换成官方提供的 Streamable HTTP 传输层,两种协议的选型见 MCP 的 stdio、SSE 和 Streamable HTTP 有什么区别。
编程订阅与高配额省心方案:在 Cursor、Claude Code 或 Codex 里挂载外部工具做长链路开发时,固定月费订阅通常比纯按量 API 更易控成本。本站支持支付宝、微信支付与 AlipayHK 免密自助兑换 Claude Pro、Claude Max 与 ChatGPT Pro,团队协作亦可定制 ChatGPT Business 团队版。
三、编译、Inspector 联调与挂载客户端

图:本站根据 MCP 官方文档:Build an MCP server 整理的排错示意图
代码写完后,按下面三步从单机测试走到正式接入:
- 编译生成 JS 文件:在项目根目录运行
npm run build,检查是否生成了build/index.js,确认没有 TypeScript 类型报错。 - 用官方 Inspector 单测:先不要急着改客户端配置,直接在终端拉起可视化调试器,把服务端单独跑通:
bash
npx @modelcontextprotocol/inspector node build/index.js
浏览器打开终端提示的本地端口后,先看左侧连接状态是否为绿色已连接;接着切到 Tools 标签点击 List Tools,选中 calc-discount 填入测试数字看返回结构是否正确;再切到 Resources 标签读取 guide://api。面板具体功能见 MCP Inspector 怎么用。
- 挂载到常用客户端并处理路径问题:
- 接入 Claude Code:在终端执行
claude mcp add order-helper -- node /你的绝对路径/my-ts-mcp/build/index.js。需要传环境变量时加上-e API_KEY=xxx。如果你想让 AI 直接帮你写完整套 MCP 业务代码并边写边测,开通 Claude Code 在仓库里直接跑终端循环会快很多,配置细节见 Claude Code MCP 配置教程。 - 接入 Claude Desktop:在
claude_desktop_config.json里填入"command": "node","args": ["/你的绝对路径/my-ts-mcp/build/index.js"],保存后完全退出并重开客户端。注意 macOS 上如果用nvm或fnm装了多个 Node 版本,桌面端启动时往往读不到 Shell 配置文件里的环境变量,容易报spawn node ENOENT;此时在终端跑which node(Windows 跑where.exe node)拿到完整可执行文件路径填进command即可解决,详见 Claude Desktop MCP 配置教程。
常见问题
问:不想每次改完代码都跑 npm run build,开发期能直接运行 .ts 吗?
答:本地调试时可以装 tsx(npm install -D tsx),把启动命令写成 npx tsx src/index.ts。但交付正式使用或打包分发前,仍建议用 tsc 编译成纯 JS,启动更快且减少运行时依赖。
问:看到有些旧文章写的是 server.tool(...),和 registerTool 有区别吗?
答:server.tool 是 SDK 早期提供的重载简写;官方最新文档主推 registerTool,它把工具元数据(title、description、inputSchema、outputSchema)统一收进配置对象,可读性和类型推导都更清晰。
问:工具执行出错时应该直接 throw Error 还是返回文本?
答:业务侧可预期的错误(例如查无此单、参数组合不合理),官方建议在返回值里加上 isError: true 并附上清晰的文字原因,这样模型读到错误提示后能自己修正参数重试,而不会把整个会话卡住。
问:配置好开发环境后,国内没有外币卡怎么开通 Claude 或 ChatGPT 编程订阅?
答:可在 本站充值中心 自助选购卡密开通 Claude Code(Pro / Max) 或 ChatGPT Plus / Pro,全程无需交出账号密码,支持开具增值税发票;实时价格与售后边界(封号不在质保范围)以对应商品页为准。
相关教程
- MCP Server 开发入门(Python):用官方 SDK 写第一个 MCP 服务器并调试
- MCP Inspector 怎么用:安装、启动命令、调试 MCP 服务器与 v2 的变化
- Claude Code MCP 配置教程:claude mcp add、配置文件位置与常用 MCP
- Claude Desktop MCP 配置教程:claude_desktop_config.json 在哪、怎么写、不生效怎么查
- MCP 的 stdio、SSE 和 Streamable HTTP 有什么区别:本地与远程 MCP 怎么选
参考资料
- MCP TypeScript SDK 官方仓库:https://github.com/modelcontextprotocol/typescript-sdk
- MCP 官方文档:Build an MCP server — https://modelcontextprotocol.io/docs/develop/build-server
- MCP 官方文档:MCP Inspector — https://modelcontextprotocol.io/docs/tools/inspector
0 条评论
还没有评论,来抢沙发~