用 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 條評論

登入 後參與評論

還沒有評論,來搶沙發~