議詳解：構(gòu)建AI應(yīng)用工具生態(tài)，實(shí)現(xiàn)模型與外部系統(tǒng)安全交互)
1. 項(xiàng)目概述為什么MCP是AI應(yīng)用開發(fā)的下一個(gè)關(guān)鍵拼圖最近在折騰AI應(yīng)用開發(fā)的朋友可能都遇到過(guò)這樣的困境你有一個(gè)功能強(qiáng)大的大語(yǔ)言模型比如GPT-4或者Claude你想讓它幫你處理公司內(nèi)部的數(shù)據(jù)庫(kù)、調(diào)用某個(gè)特定的API、或者讀取你本地的一個(gè)特殊格式的文件。結(jié)果你發(fā)現(xiàn)模型對(duì)這些“外部世界”的信息一無(wú)所知它就像一個(gè)被困在信息孤島里的天才空有強(qiáng)大的推理能力卻無(wú)法觸及完成任務(wù)所需的關(guān)鍵數(shù)據(jù)。傳統(tǒng)的做法是開發(fā)者需要寫大量的膠水代碼把數(shù)據(jù)轉(zhuǎn)換成模型能理解的文本再把模型的輸出解析成系統(tǒng)能執(zhí)行的指令這個(gè)過(guò)程繁瑣、脆弱且難以復(fù)用。這就是“模型上下文協(xié)議”要解決的核心問(wèn)題。MCP全稱Model Context Protocol你可以把它理解為AI世界里的“USB協(xié)議”。在硬件世界USB協(xié)議定義了鍵盤、鼠標(biāo)、U盤等外設(shè)如何與電腦通信。在AI世界MCP則定義了大語(yǔ)言模型如何安全、標(biāo)準(zhǔn)化地與各種工具、數(shù)據(jù)源和服務(wù)進(jìn)行交互。它不是一個(gè)具體的產(chǎn)品而是一套開放的標(biāo)準(zhǔn)和規(guī)范。簡(jiǎn)單來(lái)說(shuō)MCP讓模型擁有了“可插拔”的手和眼睛。通過(guò)它模型可以動(dòng)態(tài)地發(fā)現(xiàn)、調(diào)用外部工具比如執(zhí)行一個(gè)計(jì)算、查詢數(shù)據(jù)庫(kù)或者按需加載外部數(shù)據(jù)比如讀取一個(gè)文件、獲取實(shí)時(shí)天氣而無(wú)需在模型訓(xùn)練時(shí)就將所有這些信息硬編碼進(jìn)去。這背后的價(jià)值巨大。對(duì)于開發(fā)者而言它意味著你可以為你的AI應(yīng)用構(gòu)建一個(gè)標(biāo)準(zhǔn)化的“工具生態(tài)”不同的工具可以即插即用極大地提升了開發(fā)效率和系統(tǒng)的可維護(hù)性。對(duì)于模型提供商和用戶而言它解決了上下文窗口有限的問(wèn)題——模型不必將所有可能用到的知識(shí)都塞進(jìn)提示詞而是可以在需要時(shí)通過(guò)MCP協(xié)議精準(zhǔn)地獲取一小段最相關(guān)的上下文這既節(jié)省了token也提升了響應(yīng)的準(zhǔn)確性和時(shí)效性。我花了相當(dāng)一段時(shí)間研究和實(shí)踐MCP發(fā)現(xiàn)它正在悄然改變AI應(yīng)用架構(gòu)的設(shè)計(jì)思路。接下來(lái)我會(huì)帶你深入拆解MCP的核心設(shè)計(jì)、實(shí)操搭建一個(gè)MCP服務(wù)器并分享在集成過(guò)程中那些官方文檔不會(huì)告訴你的“坑”和技巧。2. MCP協(xié)議核心設(shè)計(jì)思想與架構(gòu)拆解要理解MCP不能只停留在“它是一個(gè)協(xié)議”的層面我們需要深入其設(shè)計(jì)哲學(xué)和架構(gòu)組件。MCP的設(shè)計(jì)目標(biāo)非常明確在模型客戶端和資源服務(wù)器之間建立一個(gè)松耦合、強(qiáng)類型、可擴(kuò)展的通信橋梁。2.1 核心組件客戶端、服務(wù)器與傳輸層MCP的架構(gòu)清晰地分為三個(gè)部分理解這三者的關(guān)系是上手的關(guān)鍵。MCP 客戶端通常就是大語(yǔ)言模型應(yīng)用本身或者是一個(gè)封裝了模型調(diào)用邏輯的框架比如LangChain、LlamaIndex?？蛻舳说暮诵穆氊?zé)是發(fā)起請(qǐng)求。它不關(guān)心工具具體如何實(shí)現(xiàn)只關(guān)心“有什么工具可用”以及“如何調(diào)用它們”。例如一個(gè)AI代碼助手客戶端它會(huì)通過(guò)MCP詢問(wèn)服務(wù)器“你能提供哪些代碼相關(guān)的工具” 服務(wù)器回答“我可以提供‘搜索代碼庫(kù)’、‘執(zhí)行單元測(cè)試’、‘格式化代碼’三個(gè)工具?！?然后客戶端在需要時(shí)就會(huì)構(gòu)造一個(gè)格式化的請(qǐng)求給服務(wù)器“請(qǐng)調(diào)用‘搜索代碼庫(kù)’工具參數(shù)是query‘用戶登錄邏輯’?！盡CP 服務(wù)器這是協(xié)議中真正“干活”的部分。一個(gè)MCP服務(wù)器就是一個(gè)對(duì)外提供特定能力集合的進(jìn)程。它可以是一個(gè)簡(jiǎn)單的腳本封裝了對(duì)本地文件系統(tǒng)的讀寫也可以是一個(gè)復(fù)雜的后端服務(wù)連接著公司的CRM數(shù)據(jù)庫(kù)和天氣API。服務(wù)器的職責(zé)是廣告能力在連接建立時(shí)主動(dòng)告訴客戶端“我有哪些工具Tools可用”和“我有哪些資源Resources可讀”。執(zhí)行請(qǐng)求接收客戶端發(fā)來(lái)的工具調(diào)用請(qǐng)求執(zhí)行真正的業(yè)務(wù)邏輯比如查詢數(shù)據(jù)庫(kù)、調(diào)用第三方API并將結(jié)果返回。提供資源當(dāng)客戶端請(qǐng)求某個(gè)資源如file:///path/to/doc.md時(shí)服務(wù)器讀取內(nèi)容并返回。傳輸層這是客戶端和服務(wù)器通信的管道。MCP協(xié)議本身是傳輸無(wú)關(guān)的它定義了消息的格式JSON-RPC但不管消息怎么送。目前最主流的實(shí)現(xiàn)方式是標(biāo)準(zhǔn)輸入/輸出。服務(wù)器作為一個(gè)獨(dú)立的進(jìn)程啟動(dòng)客戶端通過(guò)stdin向服務(wù)器發(fā)送JSON-RPC請(qǐng)求通過(guò)stdout讀取服務(wù)器的JSON-RPC響應(yīng)。這種方式極其簡(jiǎn)單和通用任何能啟動(dòng)子進(jìn)程的編程語(yǔ)言都能輕松實(shí)現(xiàn)。此外理論上也可以通過(guò)HTTP、WebSocket等方式傳輸?shù)玸tdio因其無(wú)依賴和易調(diào)試性成為首選。這種架構(gòu)帶來(lái)了巨大的靈活性。你可以用Python寫一個(gè)服務(wù)器提供數(shù)據(jù)科學(xué)工具用Go寫另一個(gè)服務(wù)器提供系統(tǒng)運(yùn)維工具然后用同一個(gè)TypeScript寫的AI客戶端來(lái)統(tǒng)一調(diào)用它們?？蛻舳撕头?wù)器可以獨(dú)立開發(fā)、部署和更新。2.2 核心概念工具、資源與提示詞模板MCP協(xié)議定義了三種核心的概念它們是客戶端與服務(wù)器交互的“貨幣”。工具代表了一個(gè)可執(zhí)行的操作。每個(gè)工具必須有唯一的名稱、描述和參數(shù)模式。參數(shù)模式使用JSON Schema嚴(yán)格定義這確保了客戶端模型在生成調(diào)用參數(shù)時(shí)能遵循正確的結(jié)構(gòu)和類型。例如{ name: get_weather, description: 獲取指定城市的當(dāng)前天氣, inputSchema: { type: object, properties: { city: { type: string, description: 城市名稱例如北京 } }, required: [city] } }當(dāng)模型決定要獲取天氣時(shí)它會(huì)輸出一個(gè)結(jié)構(gòu)化的調(diào)用請(qǐng)求其中包含工具名get_weather和參數(shù){city: 北京}。資源代表一個(gè)可讀的數(shù)據(jù)單元。資源由統(tǒng)一資源標(biāo)識(shí)符URI來(lái)定位例如file:///projects/report.md或db://sales/quarterly_summary。服務(wù)器會(huì)告訴客戶端它提供了哪些資源“模板”比如file:///projects/{name}.md當(dāng)客戶端需要某個(gè)具體資源時(shí)就向服務(wù)器發(fā)起read_resource請(qǐng)求。這解決了“如何把外部數(shù)據(jù)安全、可控地注入模型上下文”的問(wèn)題。模型不需要知道文件的物理路徑它只需要請(qǐng)求一個(gè)URI。提示詞模板這是一個(gè)非常有用的抽象。它允許服務(wù)器預(yù)定義一些常用的提示詞片段客戶端可以組合或直接使用這些模板來(lái)構(gòu)建最終的用戶提示。例如一個(gè)代碼服務(wù)器可以提供一個(gè)名為“code_review”的提示詞模板里面包含了代碼審查的步驟和標(biāo)準(zhǔn)?？蛻舳丝梢灾苯诱{(diào)用這個(gè)模板并傳入具體的代碼內(nèi)容從而獲得一個(gè)結(jié)構(gòu)化的審查提示。這促進(jìn)了最佳實(shí)踐的共享和復(fù)用。2.3 協(xié)議通信流程剖析一次典型的MCP交互流程如下了解這個(gè)流程對(duì)調(diào)試至關(guān)重要初始化客戶端啟動(dòng)服務(wù)器進(jìn)程建立stdio通信管道。能力交換客戶端發(fā)送initialize請(qǐng)求。服務(wù)器回復(fù)在result字段的capabilities中詳細(xì)列出自己支持的所有工具、資源和提示詞模板。這是客戶端了解服務(wù)器能力的唯一途徑。工具調(diào)用用戶向AI應(yīng)用提問(wèn)“北京今天天氣怎么樣”客戶端應(yīng)用將問(wèn)題傳給大語(yǔ)言模型。模型根據(jù)對(duì)話歷史和服務(wù)器廣告的工具列表判斷需要調(diào)用get_weather工具并生成參數(shù){city: 北京}。客戶端向服務(wù)器發(fā)送tools/call請(qǐng)求。服務(wù)器執(zhí)行真正的天氣查詢邏輯可能是調(diào)用一個(gè)天氣API然后返回tools/call響應(yīng)內(nèi)容中包含查詢結(jié)果如{temperature: 22°C, condition: 晴朗}?？蛻舳藢⒐ぞ邎?zhí)行結(jié)果作為上下文再次交給模型模型生成最終回答“北京今天天氣晴朗氣溫22攝氏度?！辟Y源讀取如果模型在思考過(guò)程中認(rèn)為需要參考file:///docs/api.md這個(gè)文件客戶端會(huì)向服務(wù)器發(fā)送read_resource請(qǐng)求服務(wù)器返回文件內(nèi)容客戶端將其作為上下文提供給模型。整個(gè)過(guò)程中模型始終處于“決策者”和“解釋者”的角色而具體的執(zhí)行和危險(xiǎn)操作則由受控的MCP服務(wù)器來(lái)完成。這本質(zhì)上是一種權(quán)限隔離和安全設(shè)計(jì)。3. 動(dòng)手搭建你的第一個(gè)MCP服務(wù)器從理論到實(shí)踐理解了架構(gòu)最好的學(xué)習(xí)方式就是動(dòng)手構(gòu)建。我們將使用官方推薦的TypeScript/JavaScript SDK來(lái)創(chuàng)建一個(gè)最簡(jiǎn)單的MCP服務(wù)器它提供一個(gè)工具和一個(gè)資源。即使你不熟悉TypeScript其邏輯也完全適用于其他語(yǔ)言。3.1 環(huán)境準(zhǔn)備與項(xiàng)目初始化首先確保你的環(huán)境有Node.js版本18或以上和npm。# 創(chuàng)建一個(gè)新的項(xiàng)目目錄 mkdir my-first-mcp-server cd my-first-mcp-server # 初始化npm項(xiàng)目 npm init -y # 安裝MCP核心SDK和類型定義 npm install modelcontextprotocol/sdk npm install --save-dev typescript types/node # 初始化TypeScript配置 npx tsc --init編輯生成的tsconfig.json確保包含以下關(guān)鍵配置這對(duì)于生成兼容的代碼很重要{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }在package.json中添加一個(gè)啟動(dòng)腳本方便后續(xù)運(yùn)行{ scripts: { build: tsc, start: node dist/index.js } }3.2 實(shí)現(xiàn)核心服務(wù)器邏輯在src目錄下創(chuàng)建index.ts這是服務(wù)器的入口文件。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 創(chuàng)建Server實(shí)例 const server new Server( { name: my-first-mcp-server, version: 0.1.0, }, { capabilities: { // 聲明本服務(wù)器支持哪些功能 tools: {}, // 支持工具列表 resources: {}, // 支持資源列表 // 注意我們沒(méi)有實(shí)現(xiàn)提示詞模板所以這里不聲明 }, } ); // 2. 定義一個(gè)工具計(jì)算階乘 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: calculate_factorial, description: 計(jì)算一個(gè)正整數(shù)的階乘。, inputSchema: { type: object, properties: { n: { type: integer, description: 需要計(jì)算階乘的正整數(shù), minimum: 0, // 允許0的階乘 }, }, required: [n], }, }, ], }; }); // 3. 處理工具調(diào)用請(qǐng)求 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! calculate_factorial) { throw new Error(未知的工具: ${request.params.name}); } const args request.params.arguments as { n: number }; const n args.n; // 簡(jiǎn)單的階乘計(jì)算對(duì)于大的n實(shí)際應(yīng)用中應(yīng)考慮使用BigInt和優(yōu)化算法 function factorial(num: number): number { if (num 1) return 1; return num * factorial(num - 1); } const result factorial(n); return { content: [ { type: text, text: 階乘 ${n}! 的計(jì)算結(jié)果是${result}, }, ], }; }); // 4. 定義一個(gè)資源服務(wù)器當(dāng)前時(shí)間 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: current://time, mimeType: text/plain, name: 當(dāng)前服務(wù)器時(shí)間, description: 返回服務(wù)器當(dāng)前的ISO格式時(shí)間戳, }, ], }; }); // 5. 處理資源讀取請(qǐng)求 server.setRequestHandler(ReadResourceRequestSchema, async (request) { if (request.params.uri ! current://time) { throw new Error(未知的資源URI: ${request.params.uri}); } const currentTime new Date().toISOString(); return { contents: [ { uri: request.params.uri, mimeType: text/plain, text: 服務(wù)器當(dāng)前時(shí)間UTC為${currentTime}, }, ], }; }); // 6. 錯(cuò)誤處理非常重要 server.onerror (error) { console.error([MCP Server Error], error); }; // 7. 啟動(dòng)服務(wù)器使用stdio傳輸層 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(My First MCP Server 已啟動(dòng)并等待連接...); } main().catch((error) { console.error(啟動(dòng)失敗:, error); process.exit(1); });3.3 編譯、運(yùn)行與測(cè)試編寫完代碼后我們需要編譯并運(yùn)行它。# 編譯TypeScript代碼 npm run build # 運(yùn)行服務(wù)器 npm start運(yùn)行后你會(huì)發(fā)現(xiàn)程序沒(méi)有退出而是掛起了并在標(biāo)準(zhǔn)錯(cuò)誤輸出stderr打印了“已啟動(dòng)...”。這是正常的因?yàn)樗谕ㄟ^(guò)stdin/stdout等待客戶端的連接。如何進(jìn)行測(cè)試我們可以使用一個(gè)強(qiáng)大的官方測(cè)試工具M(jìn)CP Inspector。它是一個(gè)圖形化客戶端可以方便地連接和測(cè)試任何MCP服務(wù)器。首先你需要安裝MCP Inspector。通常可以通過(guò)npm全局安裝npm install -g modelcontextprotocol/inspector然后在一個(gè)新的終端窗口運(yùn)行以下命令來(lái)連接我們剛剛啟動(dòng)的服務(wù)器mcp-inspector node /absolute/path/to/your/project/dist/index.js請(qǐng)將/absolute/path/to/your/project替換為你項(xiàng)目dist/index.js的絕對(duì)路徑。Inspector啟動(dòng)后通常會(huì)打開一個(gè)瀏覽器窗口。在這里你可以在“Tools”標(biāo)簽頁(yè)看到我們廣告的calculate_factorial工具。點(diǎn)擊該工具在右側(cè)輸入{n: 5}然后點(diǎn)擊“Call”。你應(yīng)該在下方看到結(jié)果“階乘 5! 的計(jì)算結(jié)果是120”。在“Resources”標(biāo)簽頁(yè)看到current://time資源。點(diǎn)擊該資源旁的“Read”按鈕你會(huì)看到返回的當(dāng)前時(shí)間字符串。這個(gè)過(guò)程直觀地驗(yàn)證了你的MCP服務(wù)器工作正常。通過(guò)Inspector你可以在不編寫客戶端代碼的情況下完整地測(cè)試服務(wù)器的所有功能這對(duì)于開發(fā)和調(diào)試階段來(lái)說(shuō)是不可或缺的。4. 集成MCP到真實(shí)AI應(yīng)用以Claude Desktop為例讓服務(wù)器跑起來(lái)只是第一步真正的價(jià)值在于將其集成到我們?nèi)粘Ｊ褂玫腁I助手如Claude Desktop、Cursor等中。這里以Claude Desktop為例因?yàn)樗鼘?duì)MCP有原生且友好的支持。4.1 配置Claude Desktop連接自定義MCP服務(wù)器Claude Desktop允許通過(guò)配置文件來(lái)添加自定義的MCP服務(wù)器。這個(gè)配置文件的路徑因操作系統(tǒng)而異macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果這個(gè)文件或目錄不存在你需要手動(dòng)創(chuàng)建它。編輯這個(gè)JSON配置文件其核心結(jié)構(gòu)是定義一個(gè)mcpServers對(duì)象。我們需要將之前寫的服務(wù)器腳本配置進(jìn)去。這里的關(guān)鍵是command字段它告訴Claude如何啟動(dòng)你的服務(wù)器。{ mcpServers: { my-math-server: { command: node, args: [ /absolute/path/to/your/project/dist/index.js ] } } }重要提示my-math-server是你給這個(gè)服務(wù)器起的任意名字。command必須是能在系統(tǒng)PATH中找到的可執(zhí)行文件這里是node。args的第一個(gè)元素必須是已編譯的JavaScript文件的絕對(duì)路徑。使用相對(duì)路徑很可能導(dǎo)致Claude找不到文件而啟動(dòng)失敗。4.2 驗(yàn)證集成與實(shí)戰(zhàn)對(duì)話保存配置文件后完全重啟Claude Desktop應(yīng)用不是關(guān)閉聊天窗口而是徹底退出并重新啟動(dòng)應(yīng)用。這是加載新配置的必要步驟。重啟后新建一個(gè)對(duì)話。如果你配置成功Claude在回復(fù)時(shí)其思考過(guò)程如果開啟或最終回復(fù)中就會(huì)體現(xiàn)出它“知道”可用的工具了。你可以嘗試提問(wèn)“請(qǐng)幫我計(jì)算10的階乘。”“現(xiàn)在服務(wù)器時(shí)間是什么”觀察Claude的回復(fù)。一個(gè)正確集成的表現(xiàn)是Claude會(huì)識(shí)別出你的意圖在后臺(tái)通過(guò)MCP協(xié)議調(diào)用相應(yīng)的工具并將工具返回的結(jié)果融入到它的回答中。例如對(duì)于階乘問(wèn)題它不會(huì)直接輸出一個(gè)數(shù)字而是可能會(huì)說(shuō)“我調(diào)用計(jì)算工具得到了結(jié)果10的階乘是3628800?！睂?shí)操心得路徑與權(quán)限的坑這是集成時(shí)最容易出錯(cuò)的地方。首先args中的路徑一定要用絕對(duì)路徑。其次確保運(yùn)行Claude Desktop的用戶有權(quán)限執(zhí)行node命令和讀取你的腳本文件。在macOS或Linux上如果遇到權(quán)限問(wèn)題可以檢查腳本文件是否有可執(zhí)行權(quán)限或者嘗試使用which node確認(rèn)node的完整路徑有時(shí)可能需要將command改為類似/usr/local/bin/node的完整路徑。在Windows上注意路徑中使用反斜杠\或雙反斜杠\\進(jìn)行轉(zhuǎn)義。4.3 擴(kuò)展添加更多實(shí)用工具一個(gè)只會(huì)算階乘和報(bào)時(shí)的服務(wù)器顯然不夠?qū)嵱?。讓我們擴(kuò)展它添加一個(gè)更實(shí)用的工具獲取指定GitHub倉(cāng)庫(kù)的最新Issue。這需要調(diào)用GitHub的公開API。首先安裝node-fetch如果你使用Node.js 18可以使用內(nèi)置的fetch但為了兼容性這里示例使用axios更常用npm install axios然后在src/index.ts中我們添加新的工具定義和處理邏輯。在ListToolsRequestSchema的處理函數(shù)中增加一個(gè)新工具server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ // ... 原有的 calculate_factorial 工具 { name: get_github_issues, description: 獲取指定GitHub倉(cāng)庫(kù)的最新公開Issue列表。, inputSchema: { type: object, properties: { owner: { type: string, description: 倉(cāng)庫(kù)所有者的用戶名或組織名例如modelcontextprotocol }, repo: { type: string, description: 倉(cāng)庫(kù)名稱例如spec }, count: { type: integer, description: 想要獲取的Issue數(shù)量默認(rèn)5條最多30條, minimum: 1, maximum: 30, default: 5 } }, required: [owner, repo] } } ], }; });接著在CallToolRequestSchema的處理函數(shù)中添加對(duì)新工具調(diào)用的分支處理server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name calculate_factorial) { // ... 原有的階乘計(jì)算邏輯 } else if (request.params.name get_github_issues) { const args request.params.arguments as { owner: string; repo: string; count?: number }; const { owner, repo, count 5 } args; // 使用axios調(diào)用GitHub API const axios (await import(axios)).default; const url https://api.github.com/repos/${owner}/${repo}/issues; try { const response await axios.get(url, { params: { state: open, per_page: count, sort: created, direction: desc }, headers: { Accept: application/vnd.github.v3json, // 注意公開倉(cāng)庫(kù)通常不需要token但頻繁調(diào)用可能需要。如果需要可以在這里添加。 // Authorization: token YOUR_GITHUB_TOKEN } }); const issues response.data; if (issues.length 0) { return { content: [{ type: text, text: 倉(cāng)庫(kù) ${owner}/${repo} 目前沒(méi)有打開的Issue。 }] }; } const issueList issues.map((issue: any) - #${issue.number}: ${issue.title} (創(chuàng)建于: ${new Date(issue.created_at).toLocaleDateString()}) ).join(\n); return { content: [{ type: text, text: 倉(cāng)庫(kù) ${owner}/${repo} 最新的 ${issues.length} 個(gè)公開Issue\n${issueList} }] }; } catch (error: any) { // 更友好的錯(cuò)誤處理 let errorMessage 獲取GitHub Issue失敗。; if (error.response) { errorMessage API返回狀態(tài)碼${error.response.status}。; if (error.response.status 404) { errorMessage 倉(cāng)庫(kù) ${owner}/${repo} 可能不存在或無(wú)權(quán)訪問(wèn)。; } } else { errorMessage 網(wǎng)絡(luò)或請(qǐng)求錯(cuò)誤${error.message}; } throw new Error(errorMessage); } } else { throw new Error(未知的工具: ${request.params.name}); } });重新編譯 (npm run build) 并重啟你的服務(wù)器和Claude Desktop?，F(xiàn)在你就可以在Claude中提問(wèn)“幫我看看 modelcontextprotocol/spec 這個(gè)倉(cāng)庫(kù)最近有什么新Issue嗎” Claude會(huì)調(diào)用這個(gè)新工具并返回格式化后的Issue列表。通過(guò)這個(gè)例子你可以舉一反三將任何API、數(shù)據(jù)庫(kù)查詢、內(nèi)部系統(tǒng)調(diào)用封裝成MCP工具極大地?cái)U(kuò)展AI助手的能力邊界。關(guān)鍵在于設(shè)計(jì)好工具的描述和輸入模式讓模型能準(zhǔn)確理解何時(shí)以及如何調(diào)用它。5. 高級(jí)主題性能優(yōu)化、錯(cuò)誤處理與安全考量當(dāng)你的MCP服務(wù)器從玩具走向生產(chǎn)環(huán)境或者開始承載復(fù)雜業(yè)務(wù)時(shí)以下幾個(gè)方面的考量就變得至關(guān)重要。5.1 性能優(yōu)化策略MCP服務(wù)器在每次工具調(diào)用時(shí)都可能涉及網(wǎng)絡(luò)I/O、數(shù)據(jù)庫(kù)查詢等耗時(shí)操作優(yōu)化不當(dāng)會(huì)成為AI應(yīng)用響應(yīng)的瓶頸。1. 連接池與資源復(fù)用對(duì)于數(shù)據(jù)庫(kù)、第三方API客戶端等重量級(jí)資源不要在每次工具調(diào)用時(shí)都創(chuàng)建新連接。應(yīng)該在服務(wù)器啟動(dòng)時(shí)初始化連接池并在整個(gè)服務(wù)器生命周期內(nèi)復(fù)用。// 示例在服務(wù)器啟動(dòng)時(shí)初始化數(shù)據(jù)庫(kù)連接池 import { createPool } from mysql2/promise; let dbPool; async function main() { dbPool createPool({ host: localhost, user: root, database: mcp_app, waitForConnections: true, connectionLimit: 10, // 連接池大小 queueLimit: 0 }); // ... 后續(xù)連接transport } // 在工具處理函數(shù)中使用 pool.getConnection() 獲取連接2. 異步處理與超時(shí)控制所有工具處理函數(shù)都應(yīng)該是async的。務(wù)必為可能長(zhǎng)時(shí)間運(yùn)行的操作設(shè)置超時(shí)。server.setRequestHandler(CallToolRequestSchema, async (request) { const timeoutMs 10000; // 10秒超時(shí) const timeoutPromise new Promise((_, reject) setTimeout(() reject(new Error(工具調(diào)用超時(shí))), timeoutMs) ); // 將你的業(yè)務(wù)邏輯包裝成Promise與超時(shí)Promise競(jìng)速 const logicPromise (async () { // ... 你的工具邏輯 })(); return Promise.race([logicPromise, timeoutPromise]); });3. 結(jié)果緩存對(duì)于頻繁請(qǐng)求且結(jié)果變化不頻繁的工具如某些數(shù)據(jù)查詢可以考慮實(shí)現(xiàn)簡(jiǎn)單的緩存機(jī)制避免重復(fù)計(jì)算或請(qǐng)求。import NodeCache from node-cache; const cache new NodeCache({ stdTTL: 300 }); // 默認(rèn)緩存5分鐘 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name get_weather) { const args request.params.arguments as { city: string }; const cacheKey weather:${args.city}; let result cache.get(cacheKey); if (!result) { // 調(diào)用真實(shí)API獲取天氣 result await fetchWeatherFromAPI(args.city); cache.set(cacheKey, result); } return { content: [{ type: text, text: result }] }; } });5.2 健壯的錯(cuò)誤處理MCP服務(wù)器必須優(yōu)雅地處理各種錯(cuò)誤并向客戶端返回清晰、有用的錯(cuò)誤信息而不是直接崩潰或輸出晦澀的技術(shù)棧。1. 結(jié)構(gòu)化錯(cuò)誤響應(yīng)MCP協(xié)議允許在工具調(diào)用返回錯(cuò)誤時(shí)提供結(jié)構(gòu)化的錯(cuò)誤信息。利用好這一點(diǎn)。try { // ... 業(yè)務(wù)邏輯 } catch (error: any) { // 不要直接 throw error而是返回一個(gè)包含錯(cuò)誤信息的響應(yīng) return { content: [{ type: text, text: 執(zhí)行工具“${request.params.name}”時(shí)出錯(cuò)。 }], // 可選的錯(cuò)誤信息客戶端可以解析并展示給用戶或開發(fā)者 isError: true, // 可以攜帶更詳細(xì)的診斷信息注意不要泄露敏感信息 ...(process.env.NODE_ENV development { diagnostic: error.message }) }; }2. 輸入驗(yàn)證即使在JSON Schema層面做了定義在業(yè)務(wù)邏輯入口處進(jìn)行二次驗(yàn)證也是好習(xí)慣防止意外數(shù)據(jù)導(dǎo)致下游服務(wù)出錯(cuò)。const args request.params.arguments as { userId: string }; if (!isValidUserId(args.userId)) { throw new Error(無(wú)效的用戶ID格式: ${args.userId}); }3. 服務(wù)器全局錯(cuò)誤監(jiān)聽(tīng)確保監(jiān)聽(tīng)了服務(wù)器的onerror事件并將錯(cuò)誤日志記錄到適當(dāng)?shù)牡胤饺缥募蛉罩痉?wù)而不是僅僅打印到stderr。server.onerror (error) { // 使用專業(yè)的日志庫(kù)如winston或pino logger.error(MCP服務(wù)器發(fā)生未捕獲錯(cuò)誤:, { error: error.message, stack: error.stack }); };5.3 安全與權(quán)限管控MCP服務(wù)器本質(zhì)上是為AI模型開了一個(gè)執(zhí)行特定操作的“后門”安全是重中之重。1. 最小權(quán)限原則每個(gè)MCP服務(wù)器應(yīng)該只擁有完成其宣稱功能所必需的最小權(quán)限。例如一個(gè)“文件閱讀器”服務(wù)器其運(yùn)行進(jìn)程的權(quán)限應(yīng)該只能讀取特定的目錄而不是整個(gè)文件系統(tǒng)。在配置Claude Desktop時(shí)可以通過(guò)包裝腳本或使用容器來(lái)限制權(quán)限。2. 輸入凈化與防注入如果工具參數(shù)會(huì)用于構(gòu)造命令、SQL語(yǔ)句或文件路徑必須進(jìn)行嚴(yán)格的凈化和驗(yàn)證。命令執(zhí)行絕對(duì)避免直接拼接用戶輸入來(lái)執(zhí)行系統(tǒng)命令。如果必須使用參數(shù)化調(diào)用如child_process.spawn的args數(shù)組。文件路徑將用戶輸入限制在某個(gè)安全目錄沙箱內(nèi)并使用路徑解析庫(kù)如Node.js的path.resolve防止目錄遍歷攻擊如../../../etc/passwd。SQL查詢使用參數(shù)化查詢或ORM永遠(yuǎn)不要拼接SQL字符串。3. 敏感信息管理API密鑰、數(shù)據(jù)庫(kù)密碼等敏感信息絕不應(yīng)硬編碼在代碼中。使用環(huán)境變量或安全的配置管理服務(wù)。// 從環(huán)境變量讀取GitHub Token const GITHUB_TOKEN process.env.GITHUB_API_TOKEN; if (!GITHUB_TOKEN needToken) { throw new Error(GitHub API Token未配置。); } // 在請(qǐng)求頭中使用 headers: { Authorization: token ${GITHUB_TOKEN} }在啟動(dòng)Claude Desktop或服務(wù)器時(shí)確保環(huán)境變量已正確設(shè)置。4. 審計(jì)與日志記錄所有工具調(diào)用的元數(shù)據(jù)如工具名、參數(shù)、調(diào)用時(shí)間、調(diào)用者標(biāo)識(shí)如果可能但不記錄敏感的結(jié)果數(shù)據(jù)。這對(duì)于事后審查和問(wèn)題排查至關(guān)重要。踩坑實(shí)錄生產(chǎn)環(huán)境部署的教訓(xùn)我曾將一個(gè)查詢內(nèi)部用戶數(shù)據(jù)的MCP服務(wù)器部署上線。初期一切正常直到某天發(fā)現(xiàn)響應(yīng)變慢。排查后發(fā)現(xiàn)由于沒(méi)有設(shè)置查詢超時(shí)和連接池限制當(dāng)AI助手同時(shí)發(fā)起多個(gè)復(fù)雜查詢時(shí)數(shù)據(jù)庫(kù)連接被占滿導(dǎo)致服務(wù)器僵死。教訓(xùn)是即使是內(nèi)部工具也必須像對(duì)待外部API一樣考慮并發(fā)、限流和資源管理。后來(lái)我們?yōu)槊總€(gè)工具增加了超時(shí)控制并為數(shù)據(jù)庫(kù)查詢類工具增加了基于用戶或會(huì)話的簡(jiǎn)單限流邏輯問(wèn)題才得以解決。另一個(gè)教訓(xùn)是關(guān)于錯(cuò)誤信息最初服務(wù)器拋出的原生數(shù)據(jù)庫(kù)錯(cuò)誤會(huì)直接返回給客戶端其中包含了表結(jié)構(gòu)等內(nèi)部信息。我們隨后統(tǒng)一了錯(cuò)誤處理中間件將內(nèi)部錯(cuò)誤轉(zhuǎn)換為對(duì)用戶友好的通用提示并僅在開發(fā)環(huán)境的日志中保留詳細(xì)錯(cuò)誤堆棧。構(gòu)建一個(gè)健壯、安全、高效的MCP服務(wù)器是將其應(yīng)用于生產(chǎn)環(huán)境的基礎(chǔ)。這些考量點(diǎn)雖然增加了前期的復(fù)雜度但能避免后期無(wú)數(shù)頭疼的問(wèn)題確保你的AI擴(kuò)展能力穩(wěn)定可靠。 MCP協(xié)議詳解：構(gòu)建AI應(yīng)用工具生態(tài)，實(shí)現(xiàn)模型與外部系統(tǒng)安全交互
1. 項(xiàng)目概述為什么MCP是AI應(yīng)用開發(fā)的下一個(gè)關(guān)鍵拼圖最近在折騰AI應(yīng)用開發(fā)的朋友可能都遇到過(guò)這樣的困境你有一個(gè)功能強(qiáng)大的大語(yǔ)言模型比如GPT-4或者Claude你想讓它幫你處理公司內(nèi)部的數(shù)據(jù)庫(kù)、調(diào)用某個(gè)特定的API、或者讀取你本地的一個(gè)特殊格式的文件。結(jié)果你發(fā)現(xiàn)模型對(duì)這些“外部世界”的信息一無(wú)所知它就像一個(gè)被困在信息孤島里的天才空有強(qiáng)大的推理能力卻無(wú)法觸及完成任務(wù)所需的關(guān)鍵數(shù)據(jù)。傳統(tǒng)的做法是開發(fā)者需要寫大量的膠水代碼把數(shù)據(jù)轉(zhuǎn)換成模型能理解的文本再把模型的輸出解析成系統(tǒng)能執(zhí)行的指令這個(gè)過(guò)程繁瑣、脆弱且難以復(fù)用。這就是“模型上下文協(xié)議”要解決的核心問(wèn)題。MCP全稱Model Context Protocol你可以把它理解為AI世界里的“USB協(xié)議”。在硬件世界USB協(xié)議定義了鍵盤、鼠標(biāo)、U盤等外設(shè)如何與電腦通信。在AI世界MCP則定義了大語(yǔ)言模型如何安全、標(biāo)準(zhǔn)化地與各種工具、數(shù)據(jù)源和服務(wù)進(jìn)行交互。它不是一個(gè)具體的產(chǎn)品而是一套開放的標(biāo)準(zhǔn)和規(guī)范。簡(jiǎn)單來(lái)說(shuō)MCP讓模型擁有了“可插拔”的手和眼睛。通過(guò)它模型可以動(dòng)態(tài)地發(fā)現(xiàn)、調(diào)用外部工具比如執(zhí)行一個(gè)計(jì)算、查詢數(shù)據(jù)庫(kù)或者按需加載外部數(shù)據(jù)比如讀取一個(gè)文件、獲取實(shí)時(shí)天氣而無(wú)需在模型訓(xùn)練時(shí)就將所有這些信息硬編碼進(jìn)去。這背后的價(jià)值巨大。對(duì)于開發(fā)者而言它意味著你可以為你的AI應(yīng)用構(gòu)建一個(gè)標(biāo)準(zhǔn)化的“工具生態(tài)”不同的工具可以即插即用極大地提升了開發(fā)效率和系統(tǒng)的可維護(hù)性。對(duì)于模型提供商和用戶而言它解決了上下文窗口有限的問(wèn)題——模型不必將所有可能用到的知識(shí)都塞進(jìn)提示詞而是可以在需要時(shí)通過(guò)MCP協(xié)議精準(zhǔn)地獲取一小段最相關(guān)的上下文這既節(jié)省了token也提升了響應(yīng)的準(zhǔn)確性和時(shí)效性。我花了相當(dāng)一段時(shí)間研究和實(shí)踐MCP發(fā)現(xiàn)它正在悄然改變AI應(yīng)用架構(gòu)的設(shè)計(jì)思路。接下來(lái)我會(huì)帶你深入拆解MCP的核心設(shè)計(jì)、實(shí)操搭建一個(gè)MCP服務(wù)器并分享在集成過(guò)程中那些官方文檔不會(huì)告訴你的“坑”和技巧。2. MCP協(xié)議核心設(shè)計(jì)思想與架構(gòu)拆解要理解MCP不能只停留在“它是一個(gè)協(xié)議”的層面我們需要深入其設(shè)計(jì)哲學(xué)和架構(gòu)組件。MCP的設(shè)計(jì)目標(biāo)非常明確在模型客戶端和資源服務(wù)器之間建立一個(gè)松耦合、強(qiáng)類型、可擴(kuò)展的通信橋梁。2.1 核心組件客戶端、服務(wù)器與傳輸層MCP的架構(gòu)清晰地分為三個(gè)部分理解這三者的關(guān)系是上手的關(guān)鍵。MCP 客戶端通常就是大語(yǔ)言模型應(yīng)用本身或者是一個(gè)封裝了模型調(diào)用邏輯的框架比如LangChain、LlamaIndex?？蛻舳说暮诵穆氊?zé)是發(fā)起請(qǐng)求。它不關(guān)心工具具體如何實(shí)現(xiàn)只關(guān)心“有什么工具可用”以及“如何調(diào)用它們”。例如一個(gè)AI代碼助手客戶端它會(huì)通過(guò)MCP詢問(wèn)服務(wù)器“你能提供哪些代碼相關(guān)的工具” 服務(wù)器回答“我可以提供‘搜索代碼庫(kù)’、‘執(zhí)行單元測(cè)試’、‘格式化代碼’三個(gè)工具?！?然后客戶端在需要時(shí)就會(huì)構(gòu)造一個(gè)格式化的請(qǐng)求給服務(wù)器“請(qǐng)調(diào)用‘搜索代碼庫(kù)’工具參數(shù)是query‘用戶登錄邏輯’?！盡CP 服務(wù)器這是協(xié)議中真正“干活”的部分。一個(gè)MCP服務(wù)器就是一個(gè)對(duì)外提供特定能力集合的進(jìn)程。它可以是一個(gè)簡(jiǎn)單的腳本封裝了對(duì)本地文件系統(tǒng)的讀寫也可以是一個(gè)復(fù)雜的后端服務(wù)連接著公司的CRM數(shù)據(jù)庫(kù)和天氣API。服務(wù)器的職責(zé)是廣告能力在連接建立時(shí)主動(dòng)告訴客戶端“我有哪些工具Tools可用”和“我有哪些資源Resources可讀”。執(zhí)行請(qǐng)求接收客戶端發(fā)來(lái)的工具調(diào)用請(qǐng)求執(zhí)行真正的業(yè)務(wù)邏輯比如查詢數(shù)據(jù)庫(kù)、調(diào)用第三方API并將結(jié)果返回。提供資源當(dāng)客戶端請(qǐng)求某個(gè)資源如file:///path/to/doc.md時(shí)服務(wù)器讀取內(nèi)容并返回。傳輸層這是客戶端和服務(wù)器通信的管道。MCP協(xié)議本身是傳輸無(wú)關(guān)的它定義了消息的格式JSON-RPC但不管消息怎么送。目前最主流的實(shí)現(xiàn)方式是標(biāo)準(zhǔn)輸入/輸出。服務(wù)器作為一個(gè)獨(dú)立的進(jìn)程啟動(dòng)客戶端通過(guò)stdin向服務(wù)器發(fā)送JSON-RPC請(qǐng)求通過(guò)stdout讀取服務(wù)器的JSON-RPC響應(yīng)。這種方式極其簡(jiǎn)單和通用任何能啟動(dòng)子進(jìn)程的編程語(yǔ)言都能輕松實(shí)現(xiàn)。此外理論上也可以通過(guò)HTTP、WebSocket等方式傳輸?shù)玸tdio因其無(wú)依賴和易調(diào)試性成為首選。這種架構(gòu)帶來(lái)了巨大的靈活性。你可以用Python寫一個(gè)服務(wù)器提供數(shù)據(jù)科學(xué)工具用Go寫另一個(gè)服務(wù)器提供系統(tǒng)運(yùn)維工具然后用同一個(gè)TypeScript寫的AI客戶端來(lái)統(tǒng)一調(diào)用它們?？蛻舳撕头?wù)器可以獨(dú)立開發(fā)、部署和更新。2.2 核心概念工具、資源與提示詞模板MCP協(xié)議定義了三種核心的概念它們是客戶端與服務(wù)器交互的“貨幣”。工具代表了一個(gè)可執(zhí)行的操作。每個(gè)工具必須有唯一的名稱、描述和參數(shù)模式。參數(shù)模式使用JSON Schema嚴(yán)格定義這確保了客戶端模型在生成調(diào)用參數(shù)時(shí)能遵循正確的結(jié)構(gòu)和類型。例如{ name: get_weather, description: 獲取指定城市的當(dāng)前天氣, inputSchema: { type: object, properties: { city: { type: string, description: 城市名稱例如北京 } }, required: [city] } }當(dāng)模型決定要獲取天氣時(shí)它會(huì)輸出一個(gè)結(jié)構(gòu)化的調(diào)用請(qǐng)求其中包含工具名get_weather和參數(shù){city: 北京}。資源代表一個(gè)可讀的數(shù)據(jù)單元。資源由統(tǒng)一資源標(biāo)識(shí)符URI來(lái)定位例如file:///projects/report.md或db://sales/quarterly_summary。服務(wù)器會(huì)告訴客戶端它提供了哪些資源“模板”比如file:///projects/{name}.md當(dāng)客戶端需要某個(gè)具體資源時(shí)就向服務(wù)器發(fā)起read_resource請(qǐng)求。這解決了“如何把外部數(shù)據(jù)安全、可控地注入模型上下文”的問(wèn)題。模型不需要知道文件的物理路徑它只需要請(qǐng)求一個(gè)URI。提示詞模板這是一個(gè)非常有用的抽象。它允許服務(wù)器預(yù)定義一些常用的提示詞片段客戶端可以組合或直接使用這些模板來(lái)構(gòu)建最終的用戶提示。例如一個(gè)代碼服務(wù)器可以提供一個(gè)名為“code_review”的提示詞模板里面包含了代碼審查的步驟和標(biāo)準(zhǔn)?？蛻舳丝梢灾苯诱{(diào)用這個(gè)模板并傳入具體的代碼內(nèi)容從而獲得一個(gè)結(jié)構(gòu)化的審查提示。這促進(jìn)了最佳實(shí)踐的共享和復(fù)用。2.3 協(xié)議通信流程剖析一次典型的MCP交互流程如下了解這個(gè)流程對(duì)調(diào)試至關(guān)重要初始化客戶端啟動(dòng)服務(wù)器進(jìn)程建立stdio通信管道。能力交換客戶端發(fā)送initialize請(qǐng)求。服務(wù)器回復(fù)在result字段的capabilities中詳細(xì)列出自己支持的所有工具、資源和提示詞模板。這是客戶端了解服務(wù)器能力的唯一途徑。工具調(diào)用用戶向AI應(yīng)用提問(wèn)“北京今天天氣怎么樣”客戶端應(yīng)用將問(wèn)題傳給大語(yǔ)言模型。模型根據(jù)對(duì)話歷史和服務(wù)器廣告的工具列表判斷需要調(diào)用get_weather工具并生成參數(shù){city: 北京}。客戶端向服務(wù)器發(fā)送tools/call請(qǐng)求。服務(wù)器執(zhí)行真正的天氣查詢邏輯可能是調(diào)用一個(gè)天氣API然后返回tools/call響應(yīng)內(nèi)容中包含查詢結(jié)果如{temperature: 22°C, condition: 晴朗}?？蛻舳藢⒐ぞ邎?zhí)行結(jié)果作為上下文再次交給模型模型生成最終回答“北京今天天氣晴朗氣溫22攝氏度?！辟Y源讀取如果模型在思考過(guò)程中認(rèn)為需要參考file:///docs/api.md這個(gè)文件客戶端會(huì)向服務(wù)器發(fā)送read_resource請(qǐng)求服務(wù)器返回文件內(nèi)容客戶端將其作為上下文提供給模型。整個(gè)過(guò)程中模型始終處于“決策者”和“解釋者”的角色而具體的執(zhí)行和危險(xiǎn)操作則由受控的MCP服務(wù)器來(lái)完成。這本質(zhì)上是一種權(quán)限隔離和安全設(shè)計(jì)。3. 動(dòng)手搭建你的第一個(gè)MCP服務(wù)器從理論到實(shí)踐理解了架構(gòu)最好的學(xué)習(xí)方式就是動(dòng)手構(gòu)建。我們將使用官方推薦的TypeScript/JavaScript SDK來(lái)創(chuàng)建一個(gè)最簡(jiǎn)單的MCP服務(wù)器它提供一個(gè)工具和一個(gè)資源。即使你不熟悉TypeScript其邏輯也完全適用于其他語(yǔ)言。3.1 環(huán)境準(zhǔn)備與項(xiàng)目初始化首先確保你的環(huán)境有Node.js版本18或以上和npm。# 創(chuàng)建一個(gè)新的項(xiàng)目目錄 mkdir my-first-mcp-server cd my-first-mcp-server # 初始化npm項(xiàng)目 npm init -y # 安裝MCP核心SDK和類型定義 npm install modelcontextprotocol/sdk npm install --save-dev typescript types/node # 初始化TypeScript配置 npx tsc --init編輯生成的tsconfig.json確保包含以下關(guān)鍵配置這對(duì)于生成兼容的代碼很重要{ compilerOptions: { target: ES2022, module: NodeNext, moduleResolution: NodeNext, outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true }, include: [src/**/*], exclude: [node_modules] }在package.json中添加一個(gè)啟動(dòng)腳本方便后續(xù)運(yùn)行{ scripts: { build: tsc, start: node dist/index.js } }3.2 實(shí)現(xiàn)核心服務(wù)器邏輯在src目錄下創(chuàng)建index.ts這是服務(wù)器的入口文件。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from modelcontextprotocol/sdk/types.js; // 1. 創(chuàng)建Server實(shí)例 const server new Server( { name: my-first-mcp-server, version: 0.1.0, }, { capabilities: { // 聲明本服務(wù)器支持哪些功能 tools: {}, // 支持工具列表 resources: {}, // 支持資源列表 // 注意我們沒(méi)有實(shí)現(xiàn)提示詞模板所以這里不聲明 }, } ); // 2. 定義一個(gè)工具計(jì)算階乘 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ { name: calculate_factorial, description: 計(jì)算一個(gè)正整數(shù)的階乘。, inputSchema: { type: object, properties: { n: { type: integer, description: 需要計(jì)算階乘的正整數(shù), minimum: 0, // 允許0的階乘 }, }, required: [n], }, }, ], }; }); // 3. 處理工具調(diào)用請(qǐng)求 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! calculate_factorial) { throw new Error(未知的工具: ${request.params.name}); } const args request.params.arguments as { n: number }; const n args.n; // 簡(jiǎn)單的階乘計(jì)算對(duì)于大的n實(shí)際應(yīng)用中應(yīng)考慮使用BigInt和優(yōu)化算法 function factorial(num: number): number { if (num 1) return 1; return num * factorial(num - 1); } const result factorial(n); return { content: [ { type: text, text: 階乘 ${n}! 的計(jì)算結(jié)果是${result}, }, ], }; }); // 4. 定義一個(gè)資源服務(wù)器當(dāng)前時(shí)間 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: current://time, mimeType: text/plain, name: 當(dāng)前服務(wù)器時(shí)間, description: 返回服務(wù)器當(dāng)前的ISO格式時(shí)間戳, }, ], }; }); // 5. 處理資源讀取請(qǐng)求 server.setRequestHandler(ReadResourceRequestSchema, async (request) { if (request.params.uri ! current://time) { throw new Error(未知的資源URI: ${request.params.uri}); } const currentTime new Date().toISOString(); return { contents: [ { uri: request.params.uri, mimeType: text/plain, text: 服務(wù)器當(dāng)前時(shí)間UTC為${currentTime}, }, ], }; }); // 6. 錯(cuò)誤處理非常重要 server.onerror (error) { console.error([MCP Server Error], error); }; // 7. 啟動(dòng)服務(wù)器使用stdio傳輸層 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(My First MCP Server 已啟動(dòng)并等待連接...); } main().catch((error) { console.error(啟動(dòng)失敗:, error); process.exit(1); });3.3 編譯、運(yùn)行與測(cè)試編寫完代碼后我們需要編譯并運(yùn)行它。# 編譯TypeScript代碼 npm run build # 運(yùn)行服務(wù)器 npm start運(yùn)行后你會(huì)發(fā)現(xiàn)程序沒(méi)有退出而是掛起了并在標(biāo)準(zhǔn)錯(cuò)誤輸出stderr打印了“已啟動(dòng)...”。這是正常的因?yàn)樗谕ㄟ^(guò)stdin/stdout等待客戶端的連接。如何進(jìn)行測(cè)試我們可以使用一個(gè)強(qiáng)大的官方測(cè)試工具M(jìn)CP Inspector。它是一個(gè)圖形化客戶端可以方便地連接和測(cè)試任何MCP服務(wù)器。首先你需要安裝MCP Inspector。通常可以通過(guò)npm全局安裝npm install -g modelcontextprotocol/inspector然后在一個(gè)新的終端窗口運(yùn)行以下命令來(lái)連接我們剛剛啟動(dòng)的服務(wù)器mcp-inspector node /absolute/path/to/your/project/dist/index.js請(qǐng)將/absolute/path/to/your/project替換為你項(xiàng)目dist/index.js的絕對(duì)路徑。Inspector啟動(dòng)后通常會(huì)打開一個(gè)瀏覽器窗口。在這里你可以在“Tools”標(biāo)簽頁(yè)看到我們廣告的calculate_factorial工具。點(diǎn)擊該工具在右側(cè)輸入{n: 5}然后點(diǎn)擊“Call”。你應(yīng)該在下方看到結(jié)果“階乘 5! 的計(jì)算結(jié)果是120”。在“Resources”標(biāo)簽頁(yè)看到current://time資源。點(diǎn)擊該資源旁的“Read”按鈕你會(huì)看到返回的當(dāng)前時(shí)間字符串。這個(gè)過(guò)程直觀地驗(yàn)證了你的MCP服務(wù)器工作正常。通過(guò)Inspector你可以在不編寫客戶端代碼的情況下完整地測(cè)試服務(wù)器的所有功能這對(duì)于開發(fā)和調(diào)試階段來(lái)說(shuō)是不可或缺的。4. 集成MCP到真實(shí)AI應(yīng)用以Claude Desktop為例讓服務(wù)器跑起來(lái)只是第一步真正的價(jià)值在于將其集成到我們?nèi)粘Ｊ褂玫腁I助手如Claude Desktop、Cursor等中。這里以Claude Desktop為例因?yàn)樗鼘?duì)MCP有原生且友好的支持。4.1 配置Claude Desktop連接自定義MCP服務(wù)器Claude Desktop允許通過(guò)配置文件來(lái)添加自定義的MCP服務(wù)器。這個(gè)配置文件的路徑因操作系統(tǒng)而異macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果這個(gè)文件或目錄不存在你需要手動(dòng)創(chuàng)建它。編輯這個(gè)JSON配置文件其核心結(jié)構(gòu)是定義一個(gè)mcpServers對(duì)象。我們需要將之前寫的服務(wù)器腳本配置進(jìn)去。這里的關(guān)鍵是command字段它告訴Claude如何啟動(dòng)你的服務(wù)器。{ mcpServers: { my-math-server: { command: node, args: [ /absolute/path/to/your/project/dist/index.js ] } } }重要提示my-math-server是你給這個(gè)服務(wù)器起的任意名字。command必須是能在系統(tǒng)PATH中找到的可執(zhí)行文件這里是node。args的第一個(gè)元素必須是已編譯的JavaScript文件的絕對(duì)路徑。使用相對(duì)路徑很可能導(dǎo)致Claude找不到文件而啟動(dòng)失敗。4.2 驗(yàn)證集成與實(shí)戰(zhàn)對(duì)話保存配置文件后完全重啟Claude Desktop應(yīng)用不是關(guān)閉聊天窗口而是徹底退出并重新啟動(dòng)應(yīng)用。這是加載新配置的必要步驟。重啟后新建一個(gè)對(duì)話。如果你配置成功Claude在回復(fù)時(shí)其思考過(guò)程如果開啟或最終回復(fù)中就會(huì)體現(xiàn)出它“知道”可用的工具了。你可以嘗試提問(wèn)“請(qǐng)幫我計(jì)算10的階乘。”“現(xiàn)在服務(wù)器時(shí)間是什么”觀察Claude的回復(fù)。一個(gè)正確集成的表現(xiàn)是Claude會(huì)識(shí)別出你的意圖在后臺(tái)通過(guò)MCP協(xié)議調(diào)用相應(yīng)的工具并將工具返回的結(jié)果融入到它的回答中。例如對(duì)于階乘問(wèn)題它不會(huì)直接輸出一個(gè)數(shù)字而是可能會(huì)說(shuō)“我調(diào)用計(jì)算工具得到了結(jié)果10的階乘是3628800?！睂?shí)操心得路徑與權(quán)限的坑這是集成時(shí)最容易出錯(cuò)的地方。首先args中的路徑一定要用絕對(duì)路徑。其次確保運(yùn)行Claude Desktop的用戶有權(quán)限執(zhí)行node命令和讀取你的腳本文件。在macOS或Linux上如果遇到權(quán)限問(wèn)題可以檢查腳本文件是否有可執(zhí)行權(quán)限或者嘗試使用which node確認(rèn)node的完整路徑有時(shí)可能需要將command改為類似/usr/local/bin/node的完整路徑。在Windows上注意路徑中使用反斜杠\或雙反斜杠\\進(jìn)行轉(zhuǎn)義。4.3 擴(kuò)展添加更多實(shí)用工具一個(gè)只會(huì)算階乘和報(bào)時(shí)的服務(wù)器顯然不夠?qū)嵱?。讓我們擴(kuò)展它添加一個(gè)更實(shí)用的工具獲取指定GitHub倉(cāng)庫(kù)的最新Issue。這需要調(diào)用GitHub的公開API。首先安裝node-fetch如果你使用Node.js 18可以使用內(nèi)置的fetch但為了兼容性這里示例使用axios更常用npm install axios然后在src/index.ts中我們添加新的工具定義和處理邏輯。在ListToolsRequestSchema的處理函數(shù)中增加一個(gè)新工具server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [ // ... 原有的 calculate_factorial 工具 { name: get_github_issues, description: 獲取指定GitHub倉(cāng)庫(kù)的最新公開Issue列表。, inputSchema: { type: object, properties: { owner: { type: string, description: 倉(cāng)庫(kù)所有者的用戶名或組織名例如modelcontextprotocol }, repo: { type: string, description: 倉(cāng)庫(kù)名稱例如spec }, count: { type: integer, description: 想要獲取的Issue數(shù)量默認(rèn)5條最多30條, minimum: 1, maximum: 30, default: 5 } }, required: [owner, repo] } } ], }; });接著在CallToolRequestSchema的處理函數(shù)中添加對(duì)新工具調(diào)用的分支處理server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name calculate_factorial) { // ... 原有的階乘計(jì)算邏輯 } else if (request.params.name get_github_issues) { const args request.params.arguments as { owner: string; repo: string; count?: number }; const { owner, repo, count 5 } args; // 使用axios調(diào)用GitHub API const axios (await import(axios)).default; const url https://api.github.com/repos/${owner}/${repo}/issues; try { const response await axios.get(url, { params: { state: open, per_page: count, sort: created, direction: desc }, headers: { Accept: application/vnd.github.v3json, // 注意公開倉(cāng)庫(kù)通常不需要token但頻繁調(diào)用可能需要。如果需要可以在這里添加。 // Authorization: token YOUR_GITHUB_TOKEN } }); const issues response.data; if (issues.length 0) { return { content: [{ type: text, text: 倉(cāng)庫(kù) ${owner}/${repo} 目前沒(méi)有打開的Issue。 }] }; } const issueList issues.map((issue: any) - #${issue.number}: ${issue.title} (創(chuàng)建于: ${new Date(issue.created_at).toLocaleDateString()}) ).join(\n); return { content: [{ type: text, text: 倉(cāng)庫(kù) ${owner}/${repo} 最新的 ${issues.length} 個(gè)公開Issue\n${issueList} }] }; } catch (error: any) { // 更友好的錯(cuò)誤處理 let errorMessage 獲取GitHub Issue失敗。; if (error.response) { errorMessage API返回狀態(tài)碼${error.response.status}。; if (error.response.status 404) { errorMessage 倉(cāng)庫(kù) ${owner}/${repo} 可能不存在或無(wú)權(quán)訪問(wèn)。; } } else { errorMessage 網(wǎng)絡(luò)或請(qǐng)求錯(cuò)誤${error.message}; } throw new Error(errorMessage); } } else { throw new Error(未知的工具: ${request.params.name}); } });重新編譯 (npm run build) 并重啟你的服務(wù)器和Claude Desktop?，F(xiàn)在你就可以在Claude中提問(wèn)“幫我看看 modelcontextprotocol/spec 這個(gè)倉(cāng)庫(kù)最近有什么新Issue嗎” Claude會(huì)調(diào)用這個(gè)新工具并返回格式化后的Issue列表。通過(guò)這個(gè)例子你可以舉一反三將任何API、數(shù)據(jù)庫(kù)查詢、內(nèi)部系統(tǒng)調(diào)用封裝成MCP工具極大地?cái)U(kuò)展AI助手的能力邊界。關(guān)鍵在于設(shè)計(jì)好工具的描述和輸入模式讓模型能準(zhǔn)確理解何時(shí)以及如何調(diào)用它。5. 高級(jí)主題性能優(yōu)化、錯(cuò)誤處理與安全考量當(dāng)你的MCP服務(wù)器從玩具走向生產(chǎn)環(huán)境或者開始承載復(fù)雜業(yè)務(wù)時(shí)以下幾個(gè)方面的考量就變得至關(guān)重要。5.1 性能優(yōu)化策略MCP服務(wù)器在每次工具調(diào)用時(shí)都可能涉及網(wǎng)絡(luò)I/O、數(shù)據(jù)庫(kù)查詢等耗時(shí)操作優(yōu)化不當(dāng)會(huì)成為AI應(yīng)用響應(yīng)的瓶頸。1. 連接池與資源復(fù)用對(duì)于數(shù)據(jù)庫(kù)、第三方API客戶端等重量級(jí)資源不要在每次工具調(diào)用時(shí)都創(chuàng)建新連接。應(yīng)該在服務(wù)器啟動(dòng)時(shí)初始化連接池并在整個(gè)服務(wù)器生命周期內(nèi)復(fù)用。// 示例在服務(wù)器啟動(dòng)時(shí)初始化數(shù)據(jù)庫(kù)連接池 import { createPool } from mysql2/promise; let dbPool; async function main() { dbPool createPool({ host: localhost, user: root, database: mcp_app, waitForConnections: true, connectionLimit: 10, // 連接池大小 queueLimit: 0 }); // ... 后續(xù)連接transport } // 在工具處理函數(shù)中使用 pool.getConnection() 獲取連接2. 異步處理與超時(shí)控制所有工具處理函數(shù)都應(yīng)該是async的。務(wù)必為可能長(zhǎng)時(shí)間運(yùn)行的操作設(shè)置超時(shí)。server.setRequestHandler(CallToolRequestSchema, async (request) { const timeoutMs 10000; // 10秒超時(shí) const timeoutPromise new Promise((_, reject) setTimeout(() reject(new Error(工具調(diào)用超時(shí))), timeoutMs) ); // 將你的業(yè)務(wù)邏輯包裝成Promise與超時(shí)Promise競(jìng)速 const logicPromise (async () { // ... 你的工具邏輯 })(); return Promise.race([logicPromise, timeoutPromise]); });3. 結(jié)果緩存對(duì)于頻繁請(qǐng)求且結(jié)果變化不頻繁的工具如某些數(shù)據(jù)查詢可以考慮實(shí)現(xiàn)簡(jiǎn)單的緩存機(jī)制避免重復(fù)計(jì)算或請(qǐng)求。import NodeCache from node-cache; const cache new NodeCache({ stdTTL: 300 }); // 默認(rèn)緩存5分鐘 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name get_weather) { const args request.params.arguments as { city: string }; const cacheKey weather:${args.city}; let result cache.get(cacheKey); if (!result) { // 調(diào)用真實(shí)API獲取天氣 result await fetchWeatherFromAPI(args.city); cache.set(cacheKey, result); } return { content: [{ type: text, text: result }] }; } });5.2 健壯的錯(cuò)誤處理MCP服務(wù)器必須優(yōu)雅地處理各種錯(cuò)誤并向客戶端返回清晰、有用的錯(cuò)誤信息而不是直接崩潰或輸出晦澀的技術(shù)棧。1. 結(jié)構(gòu)化錯(cuò)誤響應(yīng)MCP協(xié)議允許在工具調(diào)用返回錯(cuò)誤時(shí)提供結(jié)構(gòu)化的錯(cuò)誤信息。利用好這一點(diǎn)。try { // ... 業(yè)務(wù)邏輯 } catch (error: any) { // 不要直接 throw error而是返回一個(gè)包含錯(cuò)誤信息的響應(yīng) return { content: [{ type: text, text: 執(zhí)行工具“${request.params.name}”時(shí)出錯(cuò)。 }], // 可選的錯(cuò)誤信息客戶端可以解析并展示給用戶或開發(fā)者 isError: true, // 可以攜帶更詳細(xì)的診斷信息注意不要泄露敏感信息 ...(process.env.NODE_ENV development { diagnostic: error.message }) }; }2. 輸入驗(yàn)證即使在JSON Schema層面做了定義在業(yè)務(wù)邏輯入口處進(jìn)行二次驗(yàn)證也是好習(xí)慣防止意外數(shù)據(jù)導(dǎo)致下游服務(wù)出錯(cuò)。const args request.params.arguments as { userId: string }; if (!isValidUserId(args.userId)) { throw new Error(無(wú)效的用戶ID格式: ${args.userId}); }3. 服務(wù)器全局錯(cuò)誤監(jiān)聽(tīng)確保監(jiān)聽(tīng)了服務(wù)器的onerror事件并將錯(cuò)誤日志記錄到適當(dāng)?shù)牡胤饺缥募蛉罩痉?wù)而不是僅僅打印到stderr。server.onerror (error) { // 使用專業(yè)的日志庫(kù)如winston或pino logger.error(MCP服務(wù)器發(fā)生未捕獲錯(cuò)誤:, { error: error.message, stack: error.stack }); };5.3 安全與權(quán)限管控MCP服務(wù)器本質(zhì)上是為AI模型開了一個(gè)執(zhí)行特定操作的“后門”安全是重中之重。1. 最小權(quán)限原則每個(gè)MCP服務(wù)器應(yīng)該只擁有完成其宣稱功能所必需的最小權(quán)限。例如一個(gè)“文件閱讀器”服務(wù)器其運(yùn)行進(jìn)程的權(quán)限應(yīng)該只能讀取特定的目錄而不是整個(gè)文件系統(tǒng)。在配置Claude Desktop時(shí)可以通過(guò)包裝腳本或使用容器來(lái)限制權(quán)限。2. 輸入凈化與防注入如果工具參數(shù)會(huì)用于構(gòu)造命令、SQL語(yǔ)句或文件路徑必須進(jìn)行嚴(yán)格的凈化和驗(yàn)證。命令執(zhí)行絕對(duì)避免直接拼接用戶輸入來(lái)執(zhí)行系統(tǒng)命令。如果必須使用參數(shù)化調(diào)用如child_process.spawn的args數(shù)組。文件路徑將用戶輸入限制在某個(gè)安全目錄沙箱內(nèi)并使用路徑解析庫(kù)如Node.js的path.resolve防止目錄遍歷攻擊如../../../etc/passwd。SQL查詢使用參數(shù)化查詢或ORM永遠(yuǎn)不要拼接SQL字符串。3. 敏感信息管理API密鑰、數(shù)據(jù)庫(kù)密碼等敏感信息絕不應(yīng)硬編碼在代碼中。使用環(huán)境變量或安全的配置管理服務(wù)。// 從環(huán)境變量讀取GitHub Token const GITHUB_TOKEN process.env.GITHUB_API_TOKEN; if (!GITHUB_TOKEN needToken) { throw new Error(GitHub API Token未配置。); } // 在請(qǐng)求頭中使用 headers: { Authorization: token ${GITHUB_TOKEN} }在啟動(dòng)Claude Desktop或服務(wù)器時(shí)確保環(huán)境變量已正確設(shè)置。4. 審計(jì)與日志記錄所有工具調(diào)用的元數(shù)據(jù)如工具名、參數(shù)、調(diào)用時(shí)間、調(diào)用者標(biāo)識(shí)如果可能但不記錄敏感的結(jié)果數(shù)據(jù)。這對(duì)于事后審查和問(wèn)題排查至關(guān)重要。踩坑實(shí)錄生產(chǎn)環(huán)境部署的教訓(xùn)我曾將一個(gè)查詢內(nèi)部用戶數(shù)據(jù)的MCP服務(wù)器部署上線。初期一切正常直到某天發(fā)現(xiàn)響應(yīng)變慢。排查后發(fā)現(xiàn)由于沒(méi)有設(shè)置查詢超時(shí)和連接池限制當(dāng)AI助手同時(shí)發(fā)起多個(gè)復(fù)雜查詢時(shí)數(shù)據(jù)庫(kù)連接被占滿導(dǎo)致服務(wù)器僵死。教訓(xùn)是即使是內(nèi)部工具也必須像對(duì)待外部API一樣考慮并發(fā)、限流和資源管理。后來(lái)我們?yōu)槊總€(gè)工具增加了超時(shí)控制并為數(shù)據(jù)庫(kù)查詢類工具增加了基于用戶或會(huì)話的簡(jiǎn)單限流邏輯問(wèn)題才得以解決。另一個(gè)教訓(xùn)是關(guān)于錯(cuò)誤信息最初服務(wù)器拋出的原生數(shù)據(jù)庫(kù)錯(cuò)誤會(huì)直接返回給客戶端其中包含了表結(jié)構(gòu)等內(nèi)部信息。我們隨后統(tǒng)一了錯(cuò)誤處理中間件將內(nèi)部錯(cuò)誤轉(zhuǎn)換為對(duì)用戶友好的通用提示并僅在開發(fā)環(huán)境的日志中保留詳細(xì)錯(cuò)誤堆棧。構(gòu)建一個(gè)健壯、安全、高效的MCP服務(wù)器是將其應(yīng)用于生產(chǎn)環(huán)境的基礎(chǔ)。這些考量點(diǎn)雖然增加了前期的復(fù)雜度但能避免后期無(wú)數(shù)頭疼的問(wèn)題確保你的AI擴(kuò)展能力穩(wěn)定可靠。