結論先說
- 官方 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 條評論
還沒有評論,來搶沙發~