如果你手頭有一臺帶串口指令的 IoT Power 功耗計(jì)又天天盯著 AI 寫代碼的能力流口水這個項(xiàng)目應(yīng)該正合胃口。我用一個下午給功耗計(jì)寫了一個 MCPModel Context Protocol服務(wù)端把它接進(jìn)了 AI 對話流——現(xiàn)在我在對話框里問“當(dāng)前輸出功率多少”AI 會自己去讀串口、解析報(bào)文然后把電壓、電流、功率整理好回給我。這種“讓 AI 自己看功耗計(jì)”的體驗(yàn)一旦跑通就回不去了而且它不挑客戶端Claude Desktop、Cursor、Codex 這些支持 MCP 的軟件都能直接用。這篇就按我實(shí)際踩坑的路線來寫從整體設(shè)計(jì)、MCP 協(xié)議怎么和串口設(shè)備對接到完整代碼、客戶端配置和排錯經(jīng)驗(yàn)都一并攤開。適合手頭有 IoT Power 或類似串口功耗設(shè)備、想深入理解 MCP 服務(wù)端寫法、或者想給 AI Agent 接真實(shí)硬件的開發(fā)者。1. 項(xiàng)目全貌與關(guān)鍵設(shè)計(jì)決策1.1 為什么是 MCP而不是讓 AI 自己寫串口代碼最開始我面臨三個方案簡單對比一下就能明白為什么最終選 MCP方案優(yōu)點(diǎn)缺點(diǎn)結(jié)論讓 AI 現(xiàn)場寫一段 Python 串口讀取代碼零開發(fā)量AI 每次生成的代碼不一樣依賴也難裝硬件通信還容易踩權(quán)限坑不穩(wěn)定僅適合演示自己寫一個 REST 服務(wù)讓 AI 通過 HTTP 調(diào)用接口清晰可控要額外部署服務(wù)、處理鑒權(quán)、做進(jìn)程管理本地場景過于重量可行但沒必要寫一個 MCP 服務(wù)端聲明工具給 AI 直接調(diào)客戶端原生支持一次寫好到處復(fù)用需要理解 MCP 協(xié)議和 SDK選它MCP 解決的核心問題是“模型上下文協(xié)議”它定義了一套標(biāo)準(zhǔn)化的消息格式讓 AI 應(yīng)用能發(fā)現(xiàn)外部工具、調(diào)用外部工具、讀取外部資源。協(xié)議本身不關(guān)心底層設(shè)備是串口、藍(lán)牙還是 USB只負(fù)責(zé)傳輸“這個工具叫什么、參數(shù)是什么、返回什么”。所以我把功耗計(jì)封裝成幾個小工具AI 只要看到工具描述和參數(shù) schema就知道怎么調(diào)用、怎么解讀返回結(jié)果。這個取舍背后還有一個實(shí)際原因我經(jīng)常需要在不同客戶端之間切換。給 Claude Desktop 寫的服務(wù)端如果協(xié)議是私有 JSON-RPC那換到 Cursor 又得重寫一套。而 MCP 現(xiàn)在已經(jīng)成為 AI 客戶端的公共協(xié)議寫一次服務(wù)端配置 JSON 里改一行地址就能到處接。這個“一次封裝、到處復(fù)用”的價值在真正維護(hù)過三套客戶端接入后會覺得特別香。1.2 服務(wù)端架構(gòu)與工具粒度設(shè)計(jì)項(xiàng)目整體結(jié)構(gòu)一句話說就是AI 客戶端通過標(biāo)準(zhǔn)輸入輸出stdio啟動我的 Python 進(jìn)程進(jìn)程內(nèi)部維護(hù)一個串口連接收到 AI 發(fā)來的工具調(diào)用請求后翻譯成功耗計(jì)的 ASCII 指令讀完回復(fù)再打包成 MCP 格式返回。我選的工具棧是 Python FastMCP pySerial。FastMCP 是目前封裝 MCP 協(xié)議最舒服的 Python 庫幾行裝飾器就能把一個普通函數(shù)暴露成工具底層 JSON-RPC 握手全部遮掉。pySerial 則是 Python 操作串口的標(biāo)準(zhǔn)庫跨平臺Windows 下用 COM 口、Linux 下用 /dev/ttyUSB0行為一致。工具粒度是設(shè)計(jì)里最容易被忽略的地方。一開始我想按電壓、電流、功率分成三個工具讓 AI 分別調(diào)用。后來實(shí)測發(fā)現(xiàn)AI 問“當(dāng)前功率”時會先調(diào) voltage 又調(diào) current來回折騰而且多次調(diào)用之間設(shè)備狀態(tài)可能有變化讀出來的數(shù)據(jù)三個時間點(diǎn)對不上。最終我收斂成三個核心工具read_snapshot一次讀取電壓、電流、功率三組實(shí)時數(shù)據(jù)適合大多數(shù)問答場景。read_series按照設(shè)定次數(shù)和間隔連續(xù)采樣返回一組帶時間戳的記錄適合讓 AI 做均值、波動分析。raw_query透傳任意指令給設(shè)備適合調(diào)試和覆蓋我沒預(yù)設(shè)到的功能。工具不是越細(xì)越好而是越貼合 AI 的“思考習(xí)慣”越好。如果 AI 只需要知道一個整機(jī)功耗值你卻只讓它讀某一路電流它還得自己乘電壓容易出錯。把常用動作封裝成完整語義的原子操作AI 調(diào)用一次就拿到完整答案是服務(wù)端設(shè)計(jì)里很關(guān)鍵的一點(diǎn)。2. MCP 協(xié)議與功耗計(jì)協(xié)議的對接原理2.1 MCP 服務(wù)端在協(xié)議棧里的位置MCP 是一個應(yīng)用層軟件協(xié)議跟設(shè)備側(cè)指令集完全是兩碼事。功耗計(jì)說話用的是串口 ASCII 指令MCP 服務(wù)端是夾在 AI 和硬件之間的翻譯官。它要做兩件事向上用 MCP 協(xié)議和 AI 客戶端對話向下用設(shè)備協(xié)議和功耗計(jì)對話。MCP 有三個開發(fā)者最常用的原語tools、resources、prompts。本項(xiàng)目核心是 tools也就是把功耗計(jì)的能力暴露成可執(zhí)行的函數(shù)。resources 適合暴露不需要參數(shù)的數(shù)據(jù)內(nèi)容比如設(shè)備信息prompts 適合預(yù)置常用操作模板比如“幫我測一下充電器紋波”。理解 MCP 服務(wù)端時不用把這三個原語想得太玄就當(dāng)成三種和 AI 交互的方式能執(zhí)行的動作是 tool能讀取的狀態(tài)是 resource能填好的對話模板是 prompt。協(xié)議傳輸層上本地這類工具服務(wù)優(yōu)先用 stdio。MCP 客戶端啟動時把我的 Python 進(jìn)程作為子進(jìn)程運(yùn)行通過 stdin/stdout 傳遞 JSON-RPC 2.0 消息。stdio 傳輸最大的好處是免鑒權(quán)、免端口、環(huán)境隔離好——服務(wù)端不會在網(wǎng)絡(luò)里裸奔也不會被別的機(jī)器掃到端口。這也是 MCP 設(shè)計(jì)里“本地優(yōu)先”的體現(xiàn)。2.2 一次完整調(diào)用的生命周期剛開始調(diào) MCP 服務(wù)端時最困惑的是“AI 怎么知道我的工具存在”。實(shí)際上整個流程是這樣的客戶端啟動我的 Python 進(jìn)程先發(fā)一個initialize請求雙方確認(rèn) MCP 版本和協(xié)議能力。客戶端發(fā)notifications/initialized通知服務(wù)端已就緒?？蛻舳税l(fā)送tools/list我的服務(wù)端返回所有用 FastMCP 裝飾器注冊的工具列表包括每個工具的描述、參數(shù)類型和必需項(xiàng)。用戶提問后客戶端判斷需要調(diào)用哪個工具發(fā)送tools/call請求里面帶工具名和參數(shù)。我的服務(wù)端執(zhí)行函數(shù)訪問串口讀數(shù)據(jù)把結(jié)果組裝成 MCP 的 content 數(shù)組返回。客戶端把返回文本交給大模型大模型整理成自然語言回答用戶。這個生命周期里有一個容易被忽略的細(xì)節(jié)AI 判斷“該用哪個工具”依賴的是工具描述和參數(shù)名而不是你代碼里的函數(shù)名注釋。也就是說docstring 里寫什么直接影響 AI 能不能正確調(diào)用。比如我在read_snapshot的 docstring 里明確寫了“返回電壓(V)、電流(A)、功率(W)單位分別是伏特、安培、瓦特”AI 就不會把數(shù)值誤讀成其他單位。這在后面實(shí)戰(zhàn)里還會體會到重要性。2.3 串口側(cè)協(xié)議設(shè)計(jì)功耗計(jì)這邊的協(xié)議并不復(fù)雜但每個設(shè)備都不太一樣。我目前用的這臺 IoT Power 默認(rèn)波特率 115200指令以 ASCII 文本行為單位典型命令長這樣*IDN?查詢設(shè)備身份信息。MEAS:VOLT?讀電壓。MEAS:CURR?讀電流。MEAS:POW?讀功率。OUTPut:STATe ON打開輸出。如果你的設(shè)備是 SCPI 風(fēng)格基本能無縫對接如果是 Modbus 風(fēng)格需要把讀寫 PDU 封裝一下。我這邊先按 SCPI 風(fēng)格設(shè)計(jì)因?yàn)檫@類指令人眼可讀、調(diào)試方便也符合 MCP 工具“語義清晰”的要求。串口通信的幾個要點(diǎn)要提前想清楚否則后面全是坑第一指令必須以\r\n結(jié)尾很多設(shè)備對換行符敏感只發(fā)\n可能導(dǎo)致它一直不回包。第二每次查詢前最好清一次輸入緩沖。設(shè)備偶爾會殘留上一次的響應(yīng)碎片不清緩沖會出現(xiàn)“把上次的尾巴當(dāng)成這次的結(jié)果”這種詭異問題。第三串口是獨(dú)占資源MCP 工具被 AI 并發(fā)調(diào)用時必須用線程鎖保護(hù)否則兩個查詢同時寫指令響應(yīng)就交叉錯亂了。第四超時處理要比想象中更嚴(yán)格。AI 客戶端等待工具返回有時間窗口如果串口沒接對或設(shè)備沒上電函數(shù)一直阻塞AI 就會認(rèn)為工具無響應(yīng)。所以每次 query 都要設(shè)置超時超時后拋異常讓 AI 看到明確錯誤而不是干等。3. 實(shí)操從零寫一個可運(yùn)行的 MCP 服務(wù)端3.1 環(huán)境準(zhǔn)備先把 Python 環(huán)境準(zhǔn)備好。建議用虛擬環(huán)境避免污染系統(tǒng)環(huán)境python -m venv .venv source .venv/bin/activate pip install fastmcp pyserial如果你是 Windows激活命令是.venv\Scripts\activate如果你要使用 MCP Inspector 調(diào)試工具再裝一個官方 CLIpip install mcp硬件方面IoT Power 一般通過 USB 轉(zhuǎn) TTL 串口接電腦。連接時注意幾個引腳TXD 接設(shè)備的 RXD、RXD 接設(shè)備的 TXD、GND 接 GND。接錯 TX/RX 不會燒設(shè)備但你會發(fā)現(xiàn)“指令發(fā)出去沒反應(yīng)”因?yàn)閮烧咴诨ハ嗟却龑Ψ秸f話。Linux 下插入 USB 轉(zhuǎn)串口后大概率會出現(xiàn)/dev/ttyUSB0或/dev/ttyCH340Windows 下通常是 COM3 這類端口名。可以用串口助手先手動發(fā)一條*IDN?確認(rèn)通信鏈路正常再進(jìn)行下一步——這一步能省掉后面一半的排查時間。3.2 服務(wù)端完整代碼代碼量不多核心就一個設(shè)備類加三個工具函數(shù)。先把串口設(shè)備封裝成獨(dú)立類這樣 MCP 工具層只是薄薄一層轉(zhuǎn)發(fā)import threading import time import serial from fastmcp import FastMCP from pydantic import Field mcp FastMCP(iot-power) class PowerMeter: def __init__(self, port: str /dev/ttyUSB0, baudrate: int 115200): self.ser serial.Serial( portport, baudratebaudrate, bytesize8, parityN, stopbits1, timeout1.0, ) self._lock threading.Lock() def query(self, command: str) - str: with self._lock: self.ser.reset_input_buffer() self.ser.write((command \r\n).encode(ascii)) line self.ser.readline().decode(ascii, errorsreplace).strip() if not line: raise RuntimeError(fCommand timeout: {command}) return line def snapshot(self) - dict: voltage float(self.query(MEAS:VOLT?)) current float(self.query(MEAS:CURR?)) power float(self.query(MEAS:POW?)) return { voltage_v: voltage, current_a: current, power_w: power, timestamp: time.time(), } dev PowerMeter(port/dev/ttyUSB0, baudrate115200) mcp.tool() def read_snapshot() - dict: 讀取功耗計(jì)當(dāng)前快照返回電壓(V)、電流(A)、功率(W)。當(dāng)用戶詢問當(dāng)前電壓、電流或功耗時調(diào)用。 return dev.snapshot() mcp.tool() def read_series( samples: int Field(ge1, le30, description采樣次數(shù)最大 30), interval_ms: int Field(ge100, le5000, description采樣間隔毫秒最小 100), ) - list: 按固定間隔連續(xù)采樣返回一組電壓電流功率數(shù)據(jù)適合分析平均值和波動。 result [] for _ in range(samples): result.append(dev.snapshot()) if _ samples - 1: time.sleep(interval_ms / 1000.0) return result mcp.tool() def raw_query(command: str) - str: 透傳一條原始指令給功耗計(jì)返回設(shè)備原始響應(yīng)文本。僅調(diào)試時使用。 return dev.query(command) if __name__ __main__: mcp.run(transportstdio)代碼講幾個關(guān)鍵位置。PowerMeter.query里那把threading.Lock是必須的——FastMCP 默認(rèn)按請求分發(fā)如果 AI 在一次對話里同時調(diào)用了多個工具沒有鎖的話兩條指令會同時往串口里寫讀回來的數(shù)據(jù)就亂了。snapshot里直接float()解析設(shè)備返回值功耗計(jì)返回的都是純數(shù)字字符串比如5.0123解析失敗時異常會沿著 MCP 通道傳回給 AIAI 會告訴你“設(shè)備響應(yīng)解析失敗”這比靜默吞掉錯誤好得多。FastMCP實(shí)例化時傳入的字符串iot-power是服務(wù)端名稱會顯示在客戶端 MCP 服務(wù)器列表里。工具函數(shù)用mcp.tool()注冊函數(shù)名就是工具名docstring 就是工具描述參數(shù)類型和 Field 約束會自動生成 JSON Schema。Field(ge1, le30)把采樣次數(shù)限制在 1 到 30 之間否則用戶讓 AI 采樣一萬次工具會長時間阻塞很可能超過客戶端等待時限。3.3 本地調(diào)試先用 MCP Inspector 驗(yàn)證工具寫完代碼別急著直接接客戶端先跑一遍 MCP Inspector。這個工具會以圖形界面加載你的服務(wù)端列出所有注冊的工具你可以手動點(diǎn)擊調(diào)用不用經(jīng)過大模型推理。運(yùn)行方式python -m mcp dev server.py瀏覽器里打開它給的地址左側(cè)能看到read_snapshot、read_series、raw_query三個工具。點(diǎn)read_snapshot的 Call 按鈕如果返回{voltage_v: 5.12, current_a: 1.35, power_w: 6.91}這類數(shù)據(jù)說明你的服務(wù)端協(xié)議沒問題設(shè)備鏈路也正常。這一步特別值得養(yǎng)成習(xí)慣。因?yàn)?MCP Inspector 幫你剝離了“AI 會不會用”這個變量只驗(yàn)證“服務(wù)端能不能返回”。如果工具在 Inspector 里能跑通后面接入 AI 客戶端就只剩配置問題如果不行你也不需要去讀大模型日志直接看串口和函數(shù)邏輯就行。實(shí)測下來這個工作流至少幫我省掉了兩小時無意義的“和 AI 對話式排查”。4. 接入 AI 客戶端與實(shí)測效果4.1 客戶端配置以 Claude Desktop 為例配置文件路徑在claude_desktop_config.json里加一個mcpServers節(jié)點(diǎn){ mcpServers: { iot-power: { command: /home/user/projects/iot-power-mcp/.venv/bin/python, args: [ /home/user/projects/iot-power-mcp/server.py ] } } }這里有個我實(shí)測踩過的大坑command字段一定要寫虛擬環(huán)境里 Python 的絕對路徑不要寫python。原因是桌面客戶端啟動進(jìn)程時不會加載你的 shell 配置PATH 環(huán)境變量很可能不指向虛擬環(huán)境如果寫成裸python服務(wù)端可能用系統(tǒng) Python 啟動然后報(bào)ModuleNotFoundError: fastmcp。Linux 和 macOS 都有這個問題Windows 上則要注意寫清python.exe的完整路徑。Cursor 的配置位置稍有不同在項(xiàng)目根目錄.cursor/mcp.jsonCodex 可以通過命令行添加。但本質(zhì)相同都是給客戶端提供“命令 參數(shù)”客戶端負(fù)責(zé)拉起服務(wù)端子進(jìn)程。配置完成后重啟客戶端如果一切正常MCP 服務(wù)器列表里會出現(xiàn)iot-power和它下面的幾個工具。4.2 實(shí)測對話效果配置好后我通常先問一句“你現(xiàn)在能讀到什么設(shè)備信息嗎”AI 會調(diào)用raw_query(*IDN?)拿到設(shè)備廠商和型號然后回我一句“連接到了 IoT Power波特率 115200”。這種“AI 自己探索設(shè)備身份”的過程很能確認(rèn)鏈路已經(jīng)跑通。再試真正的功率讀取。我問“幫我讀一下當(dāng)前負(fù)載的輸出電壓和功率。”AI 會調(diào)用read_snapshot返回類似{ voltage_v: 5.121, current_a: 1.352, power_w: 6.917 }它接著會把數(shù)值翻譯成自然語言“當(dāng)前輸出電壓 5.121V電流 1.352A功率約 6.92W。”如果問它“連續(xù)采樣 10 次間隔 200 毫秒算一下平均功率”它會用read_series拿到 10 條記錄然后用代碼解釋器算平均值和標(biāo)準(zhǔn)差最后給你一份波動情況總結(jié)。這種“讀儀表 數(shù)據(jù)分析 語言總結(jié)”的組合能力正是單靠指令集交互很難實(shí)現(xiàn)的體驗(yàn)。4.3 可選的擴(kuò)展工具如果你的設(shè)備支持控制類指令再封裝一兩個寫操作也很順手。比如我這臺支持OUTPut:STATe就可以加一個工具mcp.tool() def set_output_enabled(enabled: bool Field(description是否打開輸出)) - dict: 開關(guān)功耗計(jì)輸出通道返回操作后的輸出狀態(tài)。 state ON if enabled else OFF response dev.query(fOUTPut:STATe {state}) return {output_enabled: enabled, device_response: response}加上這個工具后AI 就不只是“看功耗計(jì)”還能“操作功耗計(jì)”。比如你可以讓它做一輪完整的電源測試開輸出采樣功率關(guān)輸出生成一條時間線。這個場景對測試電源適配器、驗(yàn)證充電協(xié)議非常有用。不過要強(qiáng)調(diào)寫操作工具必須有清晰的 docstring并且最好加一層參數(shù)校驗(yàn)AI 有時會誤解自然語言比如你說“幫我關(guān)一下”它可能把 enabled 傳成False所以返回里帶上device_response能讓你追蹤設(shè)備側(cè)真實(shí)狀態(tài)。5. 常見問題與排錯實(shí)錄5.1 串口層問題現(xiàn)象可能原因解決辦法啟動服務(wù)端時報(bào)serial.serialutil.SerialException串口被占用或權(quán)限不足Linux 下把用戶加入dialout組或加 udev 規(guī)則Windows 下確認(rèn)串口助手已關(guān)閉能發(fā)指令但讀不到響應(yīng)TX/RX 接反或設(shè)備未上電先用串口助手手動發(fā)*IDN?測試檢查 GND 是否連接返回內(nèi)容亂碼波特率不匹配或換行符不對翻設(shè)備手冊確認(rèn)波特率嘗試\n與\r\n兩種結(jié)尾串口問題的排查思路很簡單先用排除法確認(rèn)設(shè)備本身是好的。我會用串口助手把波特率調(diào)到 115200發(fā)*IDN?看有沒有可讀響應(yīng)。如果串口助手里都沒響應(yīng)那就不是 MCP 的事是接線、供電或端口配置問題如果串口助手里正常但 MCP 服務(wù)端讀不到問題在代碼的換行符或超時設(shè)置上。5.2 MCP 協(xié)議與客戶端配置問題我自己遇到最 spooky 的問題是服務(wù)端在命令行里跑得好好的但客戶端就是連不上工具列表加載不出來。查了半天發(fā)現(xiàn)是有個調(diào)試日志用print寫到了 stdout。MCP 使用 stdio 傳輸時stdout 是協(xié)議通道任何非協(xié)議內(nèi)容的輸出都會讓客戶端解析 JSON 失敗。解決方法是把日志全部改道到 stderr比如import sys print([debug] query: MEAS:VOLT?, filesys.stderr)或者干脆用logging模塊配置一個 StreamHandler 指向sys.stderr。凡是走 stdio transport 的 MCP 服務(wù)端一律不要向 stdout 寫日志這條能記一輩子。另一個常見問題是啟動后客戶端顯示“工具執(zhí)行失敗”但 Inspector 里正常。這種情況多半是工具函數(shù)里拋了異常而異常信息沒有被結(jié)構(gòu)化返回。FastMCP 默認(rèn)會捕獲異常并把錯誤信息作為文本返回但如果異常發(fā)生在serial.Serial初始化階段服務(wù)端進(jìn)程直接退出客戶端就只顯示“連接失敗”。所以設(shè)備連接動作不要在 import 時執(zhí)行最好放在工具首次調(diào)用時惰性初始化或者用 try/except 包起來把錯誤文本拋給 MCP 層。5.3 從踩坑中總結(jié)的經(jīng)驗(yàn)最后分享兩條我實(shí)際使用下來的體會。第一條經(jīng)驗(yàn)是 docstring 要寫成“給 AI 看的說明文檔”而不是“給人看的技術(shù)注釋”。我說的不是代碼風(fēng)格而是像“返回電壓(V)、電流(A)、功率(W)”這種明確帶單位、帶調(diào)用時機(jī)的描述。AI 選擇工具的準(zhǔn)確度高度依賴這段文本我曾經(jīng)把 docstring 寫成read current voltage and current and power結(jié)果 AI 分不清該調(diào)read_snapshot還是read_series經(jīng)常隨機(jī)選一個。后來把描述改成“當(dāng)用戶詢問當(dāng)前電壓、電流或功耗時調(diào)用”準(zhǔn)確率立刻上來了。第二條經(jīng)驗(yàn)是保留一個raw_query入口但只存在于調(diào)試階段。它一方面讓我能手動探索設(shè)備固件支持哪些指令另一方面也給 AI 留了一條“自己嘗試新指令”的路。不過這個工具權(quán)限很大比如如果設(shè)備支持SYSTem:REBootAI 可能在你毫無防備情況下重啟設(shè)備。所以正式使用時我會把它從注冊表里刪掉只保留語義清晰的業(yè)務(wù)工具。這算是我給所有 MCP 服務(wù)端定下的規(guī)矩寧可少一個工具也不要給 AI 過大的底層自由。