用 TypeScript 官方 SDK(@modelcontextprotocol/sdk)开发第一个 MCP Server:Tools、Resources 与本地联调

想用 Node.js 和 TypeScript 写自己的 MCP 服务器?按官方 @modelcontextprotocol/sdk 文档整理 ESM 项目初始化、McpServer 注册工具与资源、stdio 禁打 console.log 铁律及 Inspector 本地联调。

NNathaniel bigo··原创首发·AI 辅助撰写
13 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

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

TypeScript 开发 MCP 四步流程

图:本站根据 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 联调与挂载客户端

TypeScript MCP 本地联调排错

图:本站根据 MCP 官方文档:Build an MCP server 整理的排错示意图

代码写完后,按下面三步从单机测试走到正式接入:

  1. 编译生成 JS 文件:在项目根目录运行 npm run build,检查是否生成了 build/index.js,确认没有 TypeScript 类型报错。
  2. 用官方 Inspector 单测:先不要急着改客户端配置,直接在终端拉起可视化调试器,把服务端单独跑通:
bash
npx @modelcontextprotocol/inspector node build/index.js

浏览器打开终端提示的本地端口后,先看左侧连接状态是否为绿色已连接;接着切到 Tools 标签点击 List Tools,选中 calc-discount 填入测试数字看返回结构是否正确;再切到 Resources 标签读取 guide://api。面板具体功能见 MCP Inspector 怎么用。

  1. 挂载到常用客户端并处理路径问题:
  • 接入 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 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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 速读英文产品手册、开源文档与 GitHub Issue 并沉淀团队中文内训手册

    团队引入海外 SaaS 工具或开源框架时,全英文文档晦涩冗长、真正的坑全藏在几十页 GitHub Issue 讨论里。本文分享速读拆解英文手册、归类 Issue 排障库以及重构团队中文内训 SOP 的完整实战流程。

    ChatGPT其他 AI 工具0
  2. 02

    用 ChatGPT 写油猴脚本(Tampermonkey)与浏览器书签小工具解决网页繁琐重复操作实战

    每天在后台系统里重复勾选几十个复选框、手工复制网页表格或清理遮挡阅读的侧边栏,既枯燥又浪费时间。本文分享不会写 JS 也能用 F12 配合 ChatGPT 写出油猴脚本与书签小工具的完整实战流程。

    ChatGPT其他 AI 工具0
  3. 03

    用 ChatGPT 写高质量 SQL 窗口函数(RANK / LAG / SUM OVER)做留存与漏斗分析实战

    做用户留存率、复购间隔与有序转化漏斗时,多层自连接既难读又拖垮数据库,窗口函数则是高效解法。本文整理数据库方言喂数规范、CTE 分层提示词以及用内置沙盒先验证再上线的完整实战流程。

    ChatGPT其他 AI 工具0
  4. 04

    ChatGPT 连接 Canva、Figma、Linear、Jira、Dropbox 等第三方应用搜不到数据或授权失效怎么办

    在 ChatGPT 接入 Canva、Figma、Linear、Jira 或 Dropbox 后,明明显示已连接却搜不到文件工单,或老提示授权失效怎么办?本文拆解账号错绑、OAuth 范围漏选、权限继承与管理员拦截 5 步排障法。

    ChatGPT其他 AI 工具0
  5. 05

    Anthropic Contextual Retrieval(上下文增强检索)是什么、怎么实现:给文档块自动补背景摘要结合缓存降失误率

    长文档切成小块后丢了公司名、年份和主语指代导致 RAG 频频搜错?本文按 Anthropic 官方技术文章详解 Contextual Retrieval 原理、官方公开评测失误率下降 49% 至 67% 的组合架构,以及用 Claude 提示词缓存低成本批量生成切片背景的完整 Python 代码。

    Claude其他 AI 工具0
  6. 06

    RAG 知识库回答不准怎么调优:切片大小(Chunking)、BM25 + 向量混合检索与 Rerank 重排序三步排查法

    搭好的 RAG 企业知识库一问具体型号、报错码或跨行表格就答非所问?本文按 OpenAI 与 Anthropic 官方检索文档,给出先隔离检索与生成故障、再按结构化切片(Chunking)、BM25 加向量混合召回(RRF)与 Rerank 重排序逐层调优的三步法。

    Claude其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~