1. 從一個(gè)接線板說(shuō)起MCP Server 到底在解決什么問(wèn)題如果你手里只有一臺(tái)設(shè)備、一個(gè)模型、一個(gè)數(shù)據(jù)源那根本不需要 MCP。麻煩的是現(xiàn)實(shí)世界你有 3 個(gè) AI 客戶端比如桌面助手、IDE 插件、命令行工具又有 5 個(gè)數(shù)據(jù)源或工具本地文件系統(tǒng)、數(shù)據(jù)庫(kù)、某個(gè)內(nèi)部 API、Git 倉(cāng)庫(kù)、日歷服務(wù)。如果每個(gè)客戶端都要單獨(dú)對(duì)接每個(gè)工具那就是 3×515 套適配代碼。每加一個(gè)客戶端就要重寫 5 遍每加一個(gè)工具就要在 3 個(gè)客戶端里各改一次。這就是典型的N×M 集成地獄。MCPModel Context ProtocolServer 的核心價(jià)值就是把這 15 條連線收斂成 358 條客戶端只認(rèn) MCP 這一種協(xié)議工具只暴露 MCP 這一種接口。N×M 變成 NM這不是營(yíng)銷話術(shù)而是實(shí)打?qū)嵉募軜?gòu)收益。我最早接觸這套東西的時(shí)候第一反應(yīng)是又一個(gè)協(xié)議標(biāo)準(zhǔn)但真正動(dòng)手寫了一個(gè) stdio 模式的 Server 之后才明白它解決的痛點(diǎn)非常具體讓工具提供方和工具消費(fèi)方徹底解耦。這篇文章適合三類人看一是想給自己常用的 AI 客戶端接私有工具的后端工程師二是需要把內(nèi)部系統(tǒng)暴露給 AI 但又不想改客戶端代碼的平臺(tái)開(kāi)發(fā)者三是單純想搞懂 MCP Server 通信機(jī)制、想自己從零寫一個(gè)的技術(shù)愛(ài)好者。我會(huì)從架構(gòu)思路講到 stdio 與 JSON-RPC 的細(xì)節(jié)再給出一份可以直接抄的 Python SDK 實(shí)操流程最后把我踩過(guò)的坑整理成排查表。全程按為什么這么設(shè)計(jì)來(lái)講而不是丟一堆 API 文檔讓你自己猜。需要先明確一個(gè)概念邊界MCP 里的Host是發(fā)起方比如你的 AI 應(yīng)用Server是能力提供方你的工具兩者之間通過(guò)標(biāo)準(zhǔn)化的消息協(xié)議通信。Host 內(nèi)部可能管理多個(gè) Client每個(gè) Client 連一個(gè) Server。這個(gè)層級(jí)關(guān)系搞清楚了后面所有配置和調(diào)試都會(huì)順很多。2. 架構(gòu)拆解為什么是 NM而不是別的方案2.1 傳統(tǒng)點(diǎn)對(duì)點(diǎn)集成的三重代價(jià)在沒(méi)有統(tǒng)一協(xié)議之前給 AI 客戶端接工具通常有三種做法每一種都有硬傷。第一種是硬編碼適配?？蛻舳死镏苯訉懰勒{(diào)用某個(gè)工具的代碼。好處是簡(jiǎn)單直接壞處是工具一多客戶端代碼就變成一鍋粥任何工具接口變動(dòng)都要重新發(fā)版。第二種是自定義插件系統(tǒng)?？蛻舳硕x一套插件規(guī)范工具方按規(guī)范實(shí)現(xiàn)。這比硬編碼好但每個(gè)客戶端都有自己的插件規(guī)范工具方要維護(hù) N 份實(shí)現(xiàn)。第三種是中間網(wǎng)關(guān)。所有工具先注冊(cè)到一個(gè)網(wǎng)關(guān)客戶端只連網(wǎng)關(guān)。這其實(shí)已經(jīng)很接近 MCP 的思路了但網(wǎng)關(guān)往往是私有協(xié)議換個(gè)客戶端生態(tài)就不通用。這三者的共同代價(jià)是耦合點(diǎn)數(shù)量隨規(guī)模平方增長(zhǎng)。N 個(gè)客戶端、M 個(gè)工具最壞情況下要維護(hù) N×M 個(gè)適配層。團(tuán)隊(duì)規(guī)模小的時(shí)候還能靠人力扛一旦工具超過(guò)十個(gè)、客戶端超過(guò)三個(gè)維護(hù)成本就會(huì)失控。2.2 MCP 的收斂邏輯MCP 的做法是把適配這件事標(biāo)準(zhǔn)化?？蛻舳酥恍枰獙?shí)現(xiàn)一次 MCP Client就能連接任意符合規(guī)范的 Server工具方只需要實(shí)現(xiàn)一次 MCP Server就能被任意符合規(guī)范的 Host 調(diào)用。適配層的數(shù)量從 N×M 降到 NM。這個(gè)收斂能成立靠的是三個(gè)設(shè)計(jì)決策協(xié)議與傳輸分離。MCP 定義了消息的語(yǔ)義JSON-RPC 2.0 格式的方法調(diào)用但傳輸方式可以是 stdio、也可以是其他通道。這意味著同一套 Server 邏輯換個(gè)傳輸層就能適配不同部署環(huán)境。能力聲明式暴露。Server 啟動(dòng)后會(huì)告訴 Host我有哪些工具、哪些資源、哪些提示模板Host 不需要提前知道 Server 的內(nèi)部實(shí)現(xiàn)。這就是所謂的 capability negotiation。生命周期標(biāo)準(zhǔn)化。初始化、能力協(xié)商、正常調(diào)用、關(guān)閉每個(gè)階段都有明確的握手流程避免了連上了但不知道對(duì)方支持什么的尷尬。我個(gè)人的判斷是MCP 真正的聰明之處不在于發(fā)明了新東西而在于把已有的成熟模式JSON-RPC 能力協(xié)商 傳輸抽象組合成了一個(gè)剛好夠用的最小集合。它沒(méi)有過(guò)度設(shè)計(jì)也沒(méi)有留太多模糊地帶。2.3 什么場(chǎng)景該用 MCP Server什么場(chǎng)景不該用不是所有工具集成都值得上 MCP。我的經(jīng)驗(yàn)判斷標(biāo)準(zhǔn)是這樣的場(chǎng)景特征建議理由工具數(shù)量 ≥ 3客戶端 ≥ 2用 MCP收斂收益明顯維護(hù)成本驟降只有 1 個(gè)客戶端、1 個(gè)工具直接調(diào)用引入?yún)f(xié)議層是過(guò)度設(shè)計(jì)工具需要被多個(gè)團(tuán)隊(duì)復(fù)用用 MCP標(biāo)準(zhǔn)化接口降低協(xié)作成本對(duì)延遲極度敏感毫秒級(jí)謹(jǐn)慎評(píng)估協(xié)議層會(huì)引入額外序列化開(kāi)銷工具邏輯頻繁變動(dòng)用 MCP改 Server 不影響 Host解耦價(jià)值大這張表不是絕對(duì)的但能幫你快速判斷要不要?jiǎng)邮?。我?jiàn)過(guò)有人為了一個(gè)讀取當(dāng)前時(shí)間的工具專門寫了個(gè) MCP Server這就屬于殺雞用牛刀了。3. stdio 傳輸最樸素也最容易被低估的通道3.1 stdio 為什么是默認(rèn)首選MCP Server 支持多種傳輸方式但stdio標(biāo)準(zhǔn)輸入輸出是最常見(jiàn)、最容易上手的一種。它的原理非常樸素Host 啟動(dòng) Server 進(jìn)程通過(guò) Server 的標(biāo)準(zhǔn)輸入發(fā)送 JSON-RPC 請(qǐng)求通過(guò)標(biāo)準(zhǔn)輸出讀取響應(yīng)。沒(méi)有網(wǎng)絡(luò)端口沒(méi)有額外的服務(wù)發(fā)現(xiàn)進(jìn)程即服務(wù)。這種設(shè)計(jì)的好處很直接。第一零網(wǎng)絡(luò)配置。不用開(kāi)端口、不用配防火墻、不用擔(dān)心端口沖突本地開(kāi)發(fā)體驗(yàn)極佳。第二生命周期天然綁定。Host 進(jìn)程結(jié)束Server 子進(jìn)程跟著結(jié)束不會(huì)留下孤兒進(jìn)程。第三安全性好。沒(méi)有監(jiān)聽(tīng)端口就意味著沒(méi)有遠(yuǎn)程攻擊面工具只在本地被調(diào)用。但 stdio 也有它的脾氣最大的坑就是標(biāo)準(zhǔn)輸出是協(xié)議通道任何非協(xié)議內(nèi)容寫進(jìn)去都會(huì)破壞通信。我見(jiàn)過(guò)太多人調(diào)試時(shí)習(xí)慣性print(debug)結(jié)果 Host 直接報(bào)解析錯(cuò)誤。這個(gè)坑后面會(huì)專門講。3.2 stdio 通信的字節(jié)級(jí)細(xì)節(jié)理解 stdio 通信關(guān)鍵要記住一條消息以換行分隔每條消息是一個(gè)完整的 JSON-RPC 對(duì)象。Host 寫入一行 JSONServer 讀取一行、解析、處理、再寫回一行 JSON。就這么簡(jiǎn)單。一個(gè)典型的請(qǐng)求長(zhǎng)這樣{jsonrpc:2.0,id:1,method:tools/list,params:{}}對(duì)應(yīng)的響應(yīng){jsonrpc:2.0,id:1,result:{tools:[{name:read_file,description:讀取本地文件,inputSchema:{type:object,properties:{path:{type:string}},required:[path]}}]}}注意幾個(gè)細(xì)節(jié)。id字段用于請(qǐng)求與響應(yīng)的配對(duì)Host 可以并發(fā)發(fā)多個(gè)請(qǐng)求靠 id 區(qū)分。method是方法名MCP 定義了一套標(biāo)準(zhǔn)方法比如initialize、tools/list、tools/call。params是參數(shù)對(duì)象不同方法結(jié)構(gòu)不同。注意stdio 模式下Server 的標(biāo)準(zhǔn)錯(cuò)誤stderr是安全的調(diào)試通道。所有日志、調(diào)試信息都應(yīng)該走 stderr而不是 stdout。這是新手最容易犯的錯(cuò)誤沒(méi)有之一。3.3 為什么不用 HTTP 而用 stdio有人會(huì)問(wèn)既然要通信為什么不用 HTTP答案在于部署形態(tài)。MCP Server 大多數(shù)情況下是本地工具跟 Host 跑在同一臺(tái)機(jī)器上甚至同一個(gè)容器里。這種場(chǎng)景下HTTP 的額外開(kāi)銷端口管理、連接池、序列化格式協(xié)商都是負(fù)擔(dān)。stdio 用進(jìn)程管道直接通信延遲更低部署更簡(jiǎn)單。當(dāng)然如果 Server 需要被遠(yuǎn)程調(diào)用或者需要同時(shí)服務(wù)多個(gè) Host那就該考慮其他傳輸方式了。傳輸方式的選擇本質(zhì)上是部署拓?fù)錄Q定的不是技術(shù)優(yōu)劣決定的。這一點(diǎn)想通了選型就不會(huì)糾結(jié)。4. JSON-RPC 2.0MCP 消息層的骨架4.1 為什么選 JSON-RPC 而不是 REST 或 gRPCMCP 的消息層用的是 JSON-RPC 2.0這個(gè)選擇很值得說(shuō)道。REST 是面向資源的適合 CRUD 場(chǎng)景但 MCP 的調(diào)用更像遠(yuǎn)程方法調(diào)用用 REST 表達(dá)會(huì)很別扭。gRPC 性能好、有強(qiáng)類型但需要 proto 編譯、依賴 HTTP/2對(duì)本地小工具來(lái)說(shuō)太重了。JSON-RPC 2.0 剛好卡在中間輕量、人類可讀、無(wú)需代碼生成、天然支持雙向調(diào)用。它的規(guī)范非常短核心就三種消息類型請(qǐng)求request、響應(yīng)response、通知notification。請(qǐng)求有 id響應(yīng)有對(duì)應(yīng) id通知沒(méi)有 id 也不需要響應(yīng)。這套模型簡(jiǎn)單到可以手寫也簡(jiǎn)單到任何語(yǔ)言都能快速實(shí)現(xiàn)。4.2 三種消息類型的實(shí)戰(zhàn)用法請(qǐng)求-響應(yīng)是最常見(jiàn)的模式。Host 發(fā)請(qǐng)求Server 處理后返回結(jié)果或錯(cuò)誤。比如調(diào)用一個(gè)工具{jsonrpc:2.0,id:42,method:tools/call,params:{name:read_file,arguments:{path:/tmp/a.txt}}}通知用于不需要回應(yīng)的場(chǎng)景比如日志上報(bào)、進(jìn)度更新。Server 可以主動(dòng)發(fā)通知給 Host{jsonrpc:2.0,method:notifications/progress,params:{progressToken:abc,progress:50}}錯(cuò)誤響應(yīng)遵循固定結(jié)構(gòu)code是數(shù)字錯(cuò)誤碼message是簡(jiǎn)短描述data可以放詳細(xì)信息{jsonrpc:2.0,id:42,error:{code:-32602,message:Invalid params,data:path is required}}標(biāo)準(zhǔn)錯(cuò)誤碼里-32700是解析錯(cuò)誤-32600是無(wú)效請(qǐng)求-32601是方法不存在-32602是參數(shù)無(wú)效-32603是內(nèi)部錯(cuò)誤。自定義錯(cuò)誤建議用-32000到-32099區(qū)間。4.3 能力協(xié)商initialize 握手到底在談什么Server 啟動(dòng)后Host 第一件事是發(fā)initialize請(qǐng)求。這個(gè)握手決定了后續(xù)能調(diào)用哪些能力。請(qǐng)求里包含 Host 的協(xié)議版本和客戶端信息響應(yīng)里 Server 聲明自己支持的能力{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:my-host,version:1.0}}}Server 的響應(yīng)會(huì)列出tools、resources、prompts等能力。Host 拿到這份清單后才知道該向用戶展示哪些功能。這個(gè)設(shè)計(jì)的好處是前向兼容新版本 Server 增加了能力老版本 Host 不認(rèn)識(shí)就忽略不會(huì)崩潰。提示initialize 之后Host 通常會(huì)發(fā)一個(gè)notifications/initialized通知表示握手完成。有些實(shí)現(xiàn)會(huì)漏掉這一步導(dǎo)致 Server 一直等待。如果你自己寫 Host記得補(bǔ)上。5. Python SDK 實(shí)操?gòu)牧銓懸粋€(gè)能跑的 Server5.1 環(huán)境準(zhǔn)備與依賴安裝Python SDK 是目前最成熟的 MCP 實(shí)現(xiàn)之一適合快速驗(yàn)證想法。環(huán)境準(zhǔn)備很簡(jiǎn)單python -m venv mcp-env source mcp-env/bin/activate pip install mcpWindows 下激活命令換成mcp-env\Scripts\activate。建議用虛擬環(huán)境因?yàn)?MCP SDK 的依賴更新比較頻繁全局安裝容易污染其他項(xiàng)目。裝完之后驗(yàn)證一下python -c import mcp; print(mcp.__version__)能打印版本號(hào)就說(shuō)明裝好了。如果報(bào)ModuleNotFoundError八成是虛擬環(huán)境沒(méi)激活或者 pip 裝到了別的 Python 解釋器下。這種情況用which python和which pip確認(rèn)一下路徑是否一致。5.2 最小可運(yùn)行 Server 的完整代碼下面這份代碼是我實(shí)際用過(guò)的精簡(jiǎn)版本去掉了花哨功能只保留核心結(jié)構(gòu)import asyncio from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(demo-server) app.list_tools() async def list_tools(): return [ Tool( nameread_file, description讀取指定路徑的文本文件內(nèi)容, inputSchema{ type: object, properties: { path: {type: string, description: 文件絕對(duì)路徑} }, required: [path] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name read_file: path arguments[path] try: with open(path, r, encodingutf-8) as f: content f.read() return [TextContent(typetext, textcontent)] except FileNotFoundError: return [TextContent(typetext, textf文件不存在: {path})] raise ValueError(f未知工具: {name}) async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())這段代碼有幾個(gè)關(guān)鍵點(diǎn)值得拆開(kāi)講。app.list_tools()裝飾器注冊(cè)的是工具清單處理器Host 調(diào)用tools/list時(shí)會(huì)觸發(fā)它。app.call_tool()注冊(cè)的是工具執(zhí)行處理器Host 調(diào)用tools/call時(shí)觸發(fā)。inputSchema用的是 JSON Schema 格式Host 會(huì)用它來(lái)校驗(yàn)參數(shù)、生成 UI。5.3 參數(shù)校驗(yàn)與錯(cuò)誤處理的最佳實(shí)踐上面代碼里參數(shù)校驗(yàn)其實(shí)做得比較粗糙。生產(chǎn)環(huán)境建議用 Pydantic 做嚴(yán)格校驗(yàn)from pydantic import BaseModel, Field class ReadFileArgs(BaseModel): path: str Field(..., description文件絕對(duì)路徑) app.call_tool() async def call_tool(name: str, arguments: dict): if name read_file: try: args ReadFileArgs(**arguments) except Exception as e: return [TextContent(typetext, textf參數(shù)錯(cuò)誤: {e})] # 后續(xù)處理錯(cuò)誤處理有個(gè)原則能返回給 Host 的錯(cuò)誤就不要拋異常。因?yàn)楫惓?huì)中斷整個(gè)調(diào)用鏈而返回錯(cuò)誤文本能讓 Host 優(yōu)雅地展示給用戶。只有真正無(wú)法恢復(fù)的錯(cuò)誤比如 Server 內(nèi)部狀態(tài)損壞才應(yīng)該拋異常。注意工具執(zhí)行時(shí)間過(guò)長(zhǎng)會(huì)導(dǎo)致 Host 超時(shí)。如果某個(gè)工具可能跑幾十秒建議實(shí)現(xiàn)進(jìn)度通知機(jī)制或者把長(zhǎng)任務(wù)拆成提交任務(wù) 查詢狀態(tài)兩步。6. 調(diào)試與排查那些文檔里不會(huì)寫的坑6.1 stdout 污染頭號(hào)殺手前面提過(guò)一次這里再?gòu)?qiáng)調(diào)因?yàn)樗亲罡哳l的問(wèn)題。stdio 模式下任何寫入 stdout 的非 JSON 內(nèi)容都會(huì)導(dǎo)致 Host 解析失敗。常見(jiàn)的污染源包括print()調(diào)試語(yǔ)句第三方庫(kù)的日志輸出有些庫(kù)默認(rèn)打到 stdout進(jìn)度條庫(kù)tqdm 之類某些框架的啟動(dòng)橫幅排查方法很簡(jiǎn)單把 Server 單獨(dú)跑起來(lái)手動(dòng)喂一條 JSON 進(jìn)去看輸出是不是干凈的 JSON。如果輸出里混了別的東西順著找污染源。修復(fù)方法通常是重定向日志到 stderrimport sys import logging logging.basicConfig(streamsys.stderr, levellogging.DEBUG)6.2 常見(jiàn)問(wèn)題速查表我把實(shí)際調(diào)試中遇到的問(wèn)題整理成了一張表方便對(duì)照排查現(xiàn)象可能原因排查方向Host 報(bào) JSON 解析錯(cuò)誤stdout 被污染檢查 print 和日志輸出工具列表為空l(shuí)ist_tools 未注冊(cè)或拋異常單獨(dú)調(diào)用 tools/list 看響應(yīng)調(diào)用工具無(wú)響應(yīng)死鎖或阻塞在同步 IO檢查是否有同步阻塞調(diào)用參數(shù)校驗(yàn)失敗inputSchema 與實(shí)際不符對(duì)比 schema 和解析邏輯進(jìn)程啟動(dòng)即退出入口未調(diào)用 asyncio.run檢查_(kāi)_main__塊中文亂碼編碼未指定 utf-8顯式指定 encoding連接后立即斷開(kāi)initialize 握手失敗檢查協(xié)議版本兼容性6.3 用命令行手動(dòng)測(cè)試 Server在接入 Host 之前強(qiáng)烈建議先用命令行手動(dòng)測(cè)一遍。方法很簡(jiǎn)單把 Server 跑起來(lái)然后手動(dòng)輸入 JSONecho {jsonrpc:2.0,id:1,method:tools/list,params:{}} | python server.py如果能看到正確的工具列表響應(yīng)說(shuō)明 Server 基本正常。如果報(bào)錯(cuò)錯(cuò)誤信息會(huì)直接顯示出來(lái)比在 Host 里調(diào)試方便得多。這個(gè)習(xí)慣能幫你省下大量時(shí)間。提示手動(dòng)測(cè)試時(shí)注意每條 JSON 后面要有換行符否則 Server 可能一直等待消息結(jié)束。7. 從能跑到好用幾個(gè)提升質(zhì)量的經(jīng)驗(yàn)7.1 工具描述的寫法直接影響調(diào)用準(zhǔn)確率工具能不能被正確調(diào)用很大程度上取決于description寫得好不好。我踩過(guò)的坑是描述寫得太簡(jiǎn)略模型不知道該在什么場(chǎng)景下調(diào)用這個(gè)工具。后來(lái)改成功能 適用場(chǎng)景 參數(shù)說(shuō)明的結(jié)構(gòu)調(diào)用準(zhǔn)確率明顯提升。比如讀取文件這種描述就太弱了。改成讀取指定路徑的文本文件內(nèi)容適用于需要查看本地文件內(nèi)容的場(chǎng)景僅支持 UTF-8 編碼的文本文件模型就能更準(zhǔn)確地判斷何時(shí)該用。7.2 工具粒度寧小勿大一個(gè)工具只做一件事這是基本原則。我見(jiàn)過(guò)有人把讀文件、寫文件、列目錄、刪文件塞進(jìn)一個(gè)工具靠參數(shù)區(qū)分操作。這種設(shè)計(jì)看起來(lái)省事實(shí)際上讓模型很難判斷該傳什么參數(shù)出錯(cuò)率很高。拆成四個(gè)獨(dú)立工具每個(gè)工具的 schema 都清晰模型反而更容易用對(duì)。7.3 冪等性設(shè)計(jì)如果工具會(huì)被重復(fù)調(diào)用比如網(wǎng)絡(luò)重試一定要保證冪等。讀操作天然冪等寫操作就要小心了。我的做法是給寫操作加一個(gè)可選的idempotency_key參數(shù)Server 側(cè)記錄已處理的 key重復(fù)請(qǐng)求直接返回上次結(jié)果。這個(gè)設(shè)計(jì)在分布式場(chǎng)景下尤其重要。8. 關(guān)于 Host 配置與跨平臺(tái)的那些事8.1 Host 如何找到并啟動(dòng) ServerHost 啟動(dòng) Server 的方式通常是配置一條命令。以常見(jiàn)的配置文件為例結(jié)構(gòu)大致是這樣{ mcpServers: { demo: { command: python, args: [/path/to/server.py], env: {PYTHONUNBUFFERED: 1} } } }command是可執(zhí)行文件args是參數(shù)列表env是環(huán)境變量。這里有個(gè)細(xì)節(jié)PYTHONUNBUFFERED1建議加上否則 Python 的輸出可能被緩沖導(dǎo)致 Host 遲遲收不到響應(yīng)。這個(gè)坑我在 Windows 上遇到過(guò)好幾次。8.2 跨平臺(tái)路徑與編碼問(wèn)題Windows 和 Unix 在路徑分隔符、編碼默認(rèn)值上都有差異。寫 Server 時(shí)要注意路徑處理統(tǒng)一用pathlib.Path不要手動(dòng)拼字符串文件讀寫顯式指定encodingutf-8換行符處理用newline避免自動(dòng)轉(zhuǎn)換這些細(xì)節(jié)看起來(lái)瑣碎但跨平臺(tái)部署時(shí)能省掉大量排查時(shí)間。我個(gè)人的習(xí)慣是任何涉及文件路徑和編碼的地方都顯式寫清楚不依賴默認(rèn)行為。8.3 進(jìn)程生命周期管理Host 關(guān)閉時(shí)Server 子進(jìn)程應(yīng)該被正確清理。stdio 模式下Host 關(guān)閉管道Server 讀取到 EOF 后應(yīng)該主動(dòng)退出。如果 Server 里有后臺(tái)任務(wù)記得在退出前取消它們否則可能留下僵尸進(jìn)程。Python SDK 的stdio_server上下文管理器會(huì)處理大部分清理工作但自定義的后臺(tái)任務(wù)需要自己管。9. 我踩過(guò)的幾個(gè)真實(shí)坑第一個(gè)坑是異步與同步混用。我一開(kāi)始在call_tool里用了同步的文件讀取結(jié)果并發(fā)調(diào)用時(shí)整個(gè) Server 卡住。原因是同步 IO 阻塞了事件循環(huán)。后來(lái)改成asyncio.to_thread包裝問(wèn)題解決。這個(gè)坑的教訓(xùn)是異步函數(shù)里不要直接做同步阻塞操作。第二個(gè)坑是工具名沖突。我同時(shí)注冊(cè)了兩個(gè)名字相似的工具模型經(jīng)常調(diào)錯(cuò)。后來(lái)統(tǒng)一了命名規(guī)范用動(dòng)詞_名詞格式比如read_file、write_file、list_dir沖突就少了。第三個(gè)坑是錯(cuò)誤信息不透明。早期我的工具出錯(cuò)時(shí)只返回操作失敗模型和用戶都不知道為什么。后來(lái)改成返回具體錯(cuò)誤原因比如文件不存在: /tmp/a.txt排查效率高了很多。錯(cuò)誤信息是給模型看的越具體越好。第四個(gè)坑是忘記處理空參數(shù)。有些工具的參數(shù)是可選的但我的代碼假設(shè)參數(shù)一定存在結(jié)果 Host 不傳時(shí)就崩潰。后來(lái)統(tǒng)一用.get()加默認(rèn)值健壯性提升明顯。10. 后續(xù)可以怎么擴(kuò)展這套基礎(chǔ)框架搭好之后擴(kuò)展方向其實(shí)很多。可以接入更多工具比如數(shù)據(jù)庫(kù)查詢、HTTP 請(qǐng)求、代碼執(zhí)行。也可以實(shí)現(xiàn)資源resources能力讓 Host 能讀取 Server 暴露的數(shù)據(jù)。還可以加提示模板prompts把常用操作封裝成一鍵調(diào)用。我個(gè)人比較看好的方向是把內(nèi)部系統(tǒng)包裝成 MCP Server。很多團(tuán)隊(duì)有自己的一套內(nèi)部工具鏈如果能統(tǒng)一暴露成 MCP 接口AI 客戶端就能直接調(diào)用省去大量重復(fù)對(duì)接工作。這個(gè)投入產(chǎn)出比相當(dāng)高。最后分享一個(gè)小技巧寫 Server 時(shí)先寫一個(gè)echo工具把收到的參數(shù)原樣返回。這個(gè)工具能幫你快速驗(yàn)證通信鏈路是否正常比任何調(diào)試手段都直接。等 echo 通了再逐個(gè)加真實(shí)工具出問(wèn)題時(shí)也容易定位是通信層還是業(yè)務(wù)層的問(wèn)題。