1. 為什么我要自己動(dòng)手寫(xiě)一個(gè) MCP1.1 從一次崩潰的 Excel 處理經(jīng)歷說(shuō)起上個(gè)月幫朋友處理一批銷售數(shù)據(jù)二十多個(gè) Excel 文件每個(gè)文件里七八個(gè) Sheet需要把指定列抽出來(lái)、做透視、再合并成一張總表。我一開(kāi)始想的是寫(xiě)個(gè) Python 腳本批量跑一遍就完事了結(jié)果打開(kāi)文件一看傻眼了——表頭位置不固定有的在第三行有的在第五行還有兩個(gè)文件里夾著合并單元格列名還帶換行符。更離譜的是有幾個(gè) Sheet 的名字每個(gè)月都在變腳本里寫(xiě)死的 Sheet 名直接匹配不上。那天晚上我改腳本改到凌晨?jī)牲c(diǎn)改完發(fā)現(xiàn)下個(gè)月數(shù)據(jù)格式又變了。這種“一次性腳本”的痛點(diǎn)太明顯了規(guī)則是死的數(shù)據(jù)是活的。你永遠(yuǎn)無(wú)法用一套固定的 if-else 覆蓋所有臟數(shù)據(jù)的形態(tài)。后來(lái)我接觸到 MCP 這個(gè)概念才意識(shí)到問(wèn)題的解法可能不在“寫(xiě)更復(fù)雜的腳本”而在于把 AI 的語(yǔ)義理解能力接進(jìn)我的 Excel 處理流程里。讓模型去看表頭、判斷哪一列是“銷售額”、哪一列是“日期”而不是靠我寫(xiě)正則去猜。這就是我決定開(kāi)發(fā)自己第一個(gè) MCP 的直接動(dòng)機(jī)。1.2 MCP 到底是什么用大白話講清楚MCP 全稱是 Model Context Protocol翻譯過(guò)來(lái)叫“模型上下文協(xié)議”。很多人第一次聽(tīng)到“協(xié)議”兩個(gè)字就頭大覺(jué)得又是那種要啃 RFC 文檔的東西。其實(shí)你可以把它理解成一個(gè)標(biāo)準(zhǔn)化的插座。打個(gè)比方你家里有各種電器——臺(tái)燈、電腦、充電器它們的插頭形狀都一樣所以能插進(jìn)同一個(gè)插座。MCP 干的事情就是給 AI 模型定義了一個(gè)“插座標(biāo)準(zhǔn)”任何符合這個(gè)標(biāo)準(zhǔn)的工具比如讀寫(xiě) Excel 的工具、查數(shù)據(jù)庫(kù)的工具、調(diào) API 的工具都能被 AI 直接“插上”使用。模型不需要為每個(gè)工具單獨(dú)寫(xiě)適配代碼工具也不需要為每個(gè)模型單獨(dú)做對(duì)接。這里要區(qū)分一個(gè)容易混淆的點(diǎn)MCP 是軟件層面的協(xié)議不是硬件協(xié)議。它規(guī)定的是“模型怎么發(fā)現(xiàn)工具、怎么調(diào)用工具、工具怎么把結(jié)果返回給模型”這一套交互規(guī)則。你可以把它類比成 USB 協(xié)議——USB 規(guī)定了設(shè)備怎么和電腦通信但 USB 本身不是一根具體的線也不是某個(gè)具體的設(shè)備。MCP 也一樣它是一個(gè)規(guī)范具體的實(shí)現(xiàn)可以是 Python 寫(xiě)的也可以是其他語(yǔ)言寫(xiě)的。對(duì)我這種做數(shù)據(jù)處理的人來(lái)說(shuō)MCP 最大的價(jià)值在于我可以把 Excel 處理的專業(yè)邏輯封裝成一個(gè) MCP 工具然后讓 AI 在需要的時(shí)候自動(dòng)調(diào)用它。AI 負(fù)責(zé)“理解意圖”我的工具負(fù)責(zé)“精確執(zhí)行”各干各擅長(zhǎng)的事。1.3 這個(gè)項(xiàng)目適合誰(shuí)來(lái)參考如果你符合下面任意一條這篇內(nèi)容應(yīng)該能幫到你經(jīng)常和 Excel 打交道被各種不規(guī)范的表格折磨過(guò)想用 AI 提效但不知道從哪下手有 Python 基礎(chǔ)聽(tīng)說(shuō)過(guò) MCP 但沒(méi)實(shí)際寫(xiě)過(guò)想找一個(gè)完整的入門(mén)項(xiàng)目練手已經(jīng)在用某些 AI 工作流平臺(tái)但覺(jué)得平臺(tái)內(nèi)置的 Excel 節(jié)點(diǎn)不夠靈活想自己擴(kuò)展單純好奇“AI Agent 到底怎么調(diào)用外部工具”這件事的底層機(jī)制。不需要你是 AI 專家也不需要你懂什么大模型原理。只要你會(huì)裝 Python、能看懂基本的函數(shù)定義剩下的我一步步拆給你看。2. 整體設(shè)計(jì)思路與方案選型2.1 為什么選 Excel 作為第一個(gè) MCP 的切入點(diǎn)MCP 能做的事情很多為什么我第一個(gè)項(xiàng)目選 Excel原因很實(shí)際第一Excel 是最高頻的痛點(diǎn)場(chǎng)景。不管你是做運(yùn)營(yíng)、財(cái)務(wù)、銷售還是研發(fā)幾乎沒(méi)有人能完全繞開(kāi) Excel。而且 Excel 的數(shù)據(jù)形態(tài)極其多樣——有規(guī)整的數(shù)據(jù)庫(kù)導(dǎo)出表也有手工填的亂七八糟的報(bào)表。這種“半結(jié)構(gòu)化”的數(shù)據(jù)恰恰是 AI 最擅長(zhǎng)處理的因?yàn)樗枰Z(yǔ)義理解而不是純粹的模式匹配。第二Excel 處理有明確的“工具邊界”。讀文件、寫(xiě)文件、篩選、排序、透視、合并——這些操作都是定義清晰的原子動(dòng)作非常適合封裝成 MCP 工具。不像有些場(chǎng)景比如“幫我分析一下這份報(bào)告”邊界模糊很難定義工具該做什么。第三調(diào)試成本低。Excel 文件你可以隨時(shí)打開(kāi)看處理結(jié)果對(duì)不對(duì)一眼就知道。不像有些后端服務(wù)出了問(wèn)題要翻日志、查鏈路排查成本高。2.2 技術(shù)棧選擇Python openpyxl MCP SDK技術(shù)選型這塊我沒(méi)有糾結(jié)太久基本是順著生態(tài)走的組件選擇理由編程語(yǔ)言PythonExcel 處理生態(tài)最成熟MCP 官方 SDK 支持好Excel 讀寫(xiě)openpyxl支持 .xlsx 格式能讀寫(xiě)樣式和公式比 pandas 更底層可控MCP 框架官方 Python SDK文檔齊全社區(qū)活躍出問(wèn)題好查數(shù)據(jù)校驗(yàn)pydanticMCP SDK 本身就依賴它順手用來(lái)做參數(shù)校驗(yàn)日志logging標(biāo)準(zhǔn)庫(kù)夠用不引入額外依賴這里重點(diǎn)說(shuō)一下為什么用 openpyxl 而不是 pandas。pandas 確實(shí)方便read_excel一行代碼就能讀進(jìn)來(lái)。但 pandas 的問(wèn)題是它會(huì)把 Excel 當(dāng)成一個(gè)“數(shù)據(jù)矩陣”來(lái)處理丟失了很多 Excel 特有的信息——比如單元格的合并狀態(tài)、公式、樣式、批注。而我的場(chǎng)景里恰恰需要判斷“這個(gè)表頭是不是合并單元格”“這一列是不是公式算出來(lái)的”。openpyxl 雖然 API 啰嗦一點(diǎn)但控制粒度更細(xì)適合做工具層的封裝。至于 MCP SDK官方提供了mcp這個(gè)包安裝之后用裝飾器就能定義工具非常省事。后面實(shí)操部分我會(huì)詳細(xì)講。2.3 架構(gòu)設(shè)計(jì)三層分離整個(gè)項(xiàng)目的架構(gòu)我設(shè)計(jì)成三層這樣職責(zé)清晰后面擴(kuò)展也方便第一層是 MCP 工具層。這一層只負(fù)責(zé)“暴露能力”定義工具的名稱、描述、參數(shù) schema。它不關(guān)心具體怎么實(shí)現(xiàn)只告訴 AI“我能做這些事”。第二層是業(yè)務(wù)邏輯層。這一層是真正的 Excel 處理邏輯比如“智能識(shí)別表頭”“按列名模糊匹配”“合并多個(gè) Sheet”。這一層是純 Python 函數(shù)可以單獨(dú)測(cè)試不依賴 MCP。第三層是數(shù)據(jù)訪問(wèn)層。這一層封裝 openpyxl 的讀寫(xiě)操作比如“打開(kāi)文件”“讀取指定區(qū)域”“寫(xiě)入單元格”。把 openpyxl 的 API 包一層好處是以后如果要換成其他庫(kù)比如 xlwings只需要改這一層。為什么要這么分因?yàn)槲也冗^(guò)一個(gè)坑一開(kāi)始我把所有邏輯都寫(xiě)在 MCP 工具函數(shù)里結(jié)果想單獨(dú)測(cè)試“表頭識(shí)別”這個(gè)功能時(shí)發(fā)現(xiàn)必須啟動(dòng)整個(gè) MCP 服務(wù)才能測(cè)。后來(lái)拆成三層之后業(yè)務(wù)邏輯層可以直接用 pytest 跑單元測(cè)試效率高多了。2.4 核心設(shè)計(jì)原則讓 AI 做判斷讓代碼做執(zhí)行這是整個(gè)項(xiàng)目最核心的一條原則也是我想強(qiáng)調(diào)的重點(diǎn)。很多人做 AI 工具容易走兩個(gè)極端要么全讓 AI 干讓模型直接輸出處理后的數(shù)據(jù)要么全讓代碼干寫(xiě)死規(guī)則AI 只是個(gè)傳話的。這兩種都不對(duì)。全讓 AI 干的問(wèn)題是模型輸出不穩(wěn)定同樣的輸入可能給你不同的結(jié)果而且處理大批量數(shù)據(jù)時(shí) token 消耗巨大成本扛不住。全讓代碼干的問(wèn)題是規(guī)則太死數(shù)據(jù)格式一變就失效又回到了我開(kāi)頭說(shuō)的那個(gè)凌晨?jī)牲c(diǎn)的困境。我的方案是分工AI 負(fù)責(zé)“看”和“判斷”——看這個(gè)表的表頭在哪一行、判斷哪一列是金額、決定用哪種合并策略代碼負(fù)責(zé)“算”和“寫(xiě)”——精確地讀取單元格、執(zhí)行計(jì)算、寫(xiě)入結(jié)果。AI 的輸出是一個(gè)“決策指令”而不是“最終數(shù)據(jù)”。這樣既利用了 AI 的語(yǔ)義理解能力又保證了執(zhí)行的精確性和穩(wěn)定性。舉個(gè)例子用戶說(shuō)“把每個(gè)文件里的銷售金額匯總一下”。AI 需要判斷的是“哪個(gè) Sheet 是銷售數(shù)據(jù)”“哪一列是銷售金額”然后輸出一個(gè)結(jié)構(gòu)化的指令比如{sheet: 銷售明細(xì), column: 金額, operation: sum}。我的代碼拿到這個(gè)指令后精確地去執(zhí)行求和。整個(gè)過(guò)程 AI 只輸出了幾十個(gè) token 的判斷結(jié)果而不是把整個(gè)表格數(shù)據(jù)都吐一遍。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 MCP 工具的注冊(cè)機(jī)制裝飾器背后的邏輯MCP Python SDK 注冊(cè)工具的方式很簡(jiǎn)潔用mcp.tool()裝飾器就行。但簡(jiǎn)潔的背后有幾個(gè)細(xì)節(jié)必須搞清楚否則容易踩坑。from mcp.server.fastmcp import FastMCP mcp FastMCP(excel-processor) mcp.tool() def read_excel_sheet(file_path: str, sheet_name: str) - str: 讀取指定 Excel 文件的指定 Sheet 內(nèi)容 # 實(shí)現(xiàn)邏輯 ...這個(gè)裝飾器干了三件事第一把函數(shù)注冊(cè)到 MCP 服務(wù)的工具列表里這樣 AI 就能“看到”這個(gè)工具第二從函數(shù)的類型注解和 docstring 里自動(dòng)生成參數(shù)的 JSON SchemaAI 根據(jù)這個(gè) schema 知道該傳什么參數(shù)第三把函數(shù)的返回值包裝成 MCP 協(xié)議規(guī)定的響應(yīng)格式。這里有個(gè)關(guān)鍵點(diǎn)docstring 極其重要。AI 判斷該不該調(diào)用這個(gè)工具、該傳什么參數(shù)主要依據(jù)就是工具的名稱和 docstring。我一開(kāi)始 docstring 寫(xiě)得很隨意就寫(xiě)了個(gè)“讀取 Excel”結(jié)果 AI 經(jīng)常在不需要讀文件的時(shí)候也調(diào)這個(gè)工具。后來(lái)我把 docstring 改成“讀取指定 Excel 文件中指定名稱的 Sheet 的全部?jī)?nèi)容返回二維數(shù)組格式的字符串。僅在需要查看表格原始數(shù)據(jù)時(shí)調(diào)用”調(diào)用準(zhǔn)確率明顯提升。提示docstring 要寫(xiě)清楚三件事——這個(gè)工具做什么、什么時(shí)候該用、參數(shù)是什么含義。不要嫌啰嗦這是給 AI 看的“使用說(shuō)明書(shū)”。3.2 參數(shù)校驗(yàn)別讓臟參數(shù)把服務(wù)搞崩MCP 工具被 AI 調(diào)用時(shí)傳進(jìn)來(lái)的參數(shù)是不可控的。AI 可能傳一個(gè)不存在的文件路徑可能傳一個(gè)空字符串甚至可能傳一個(gè)類型不對(duì)的值。如果不做校驗(yàn)輕則報(bào)錯(cuò)重則把服務(wù)搞崩。我的做法是用 pydantic 做參數(shù)校驗(yàn)。雖然 MCP SDK 本身會(huì)做基礎(chǔ)的類型檢查但業(yè)務(wù)層面的校驗(yàn)還得自己來(lái)from pydantic import BaseModel, field_validator import os class ReadSheetParams(BaseModel): file_path: str sheet_name: str field_validator(file_path) classmethod def check_file_exists(cls, v): if not os.path.exists(v): raise ValueError(f文件不存在: {v}) if not v.endswith((.xlsx, .xlsm)): raise ValueError(只支持 .xlsx 和 .xlsm 格式) return v field_validator(sheet_name) classmethod def check_sheet_name(cls, v): if not v or not v.strip(): raise ValueError(Sheet 名稱不能為空) return v.strip()這樣做的好處是校驗(yàn)失敗時(shí)返回的是清晰的錯(cuò)誤信息AI 能看懂并調(diào)整參數(shù)重試。比如 AI 傳了一個(gè)不存在的路徑工具返回“文件不存在: xxx”AI 就知道要換個(gè)路徑再試。如果直接拋一個(gè) Python 的FileNotFoundError堆棧信息一大堆AI 反而懵了。3.3 表頭智能識(shí)別這個(gè)功能是整個(gè)項(xiàng)目的靈魂前面說(shuō)了Excel 處理最頭疼的就是表頭位置不固定。傳統(tǒng)做法是寫(xiě)死“表頭在第 N 行”但實(shí)際數(shù)據(jù)里 N 可能是 1、2、3、5 任意一個(gè)。我的方案是讓 AI 來(lái)判斷。具體怎么做的我封裝了一個(gè)detect_header工具它接收文件路徑和 Sheet 名返回表頭所在的行號(hào)。實(shí)現(xiàn)邏輯是先讀取前 10 行的內(nèi)容把它們拼成一段文本然后讓 AI 判斷“哪一行最可能是表頭”。mcp.tool() def detect_header_row(file_path: str, sheet_name: str) - int: 檢測(cè)指定 Sheet 的表頭所在行號(hào)。 讀取前10行內(nèi)容通過(guò)語(yǔ)義分析判斷哪一行是表頭。 當(dāng)你不確定表頭位置時(shí)調(diào)用此工具。 # 讀取前10行 preview read_first_n_rows(file_path, sheet_name, n10) # 構(gòu)造提示詞讓 AI 判斷 prompt f以下是 Excel 前10行的內(nèi)容請(qǐng)判斷哪一行是表頭。 表頭的特征包含列名如姓名金額日期通常是文字而非數(shù)字。 只返回行號(hào)數(shù)字不要其他內(nèi)容。 內(nèi)容 {preview} # 調(diào)用模型判斷 row_num call_llm(prompt) return int(row_num)這里有個(gè)實(shí)操心得不要一次性把整個(gè)表格丟給 AI 判斷。我試過(guò)把 1000 行數(shù)據(jù)全傳進(jìn)去讓 AI 找表頭結(jié)果 token 消耗巨大不說(shuō)準(zhǔn)確率反而下降了——因?yàn)楦蓴_信息太多。只傳前 10 行準(zhǔn)確率最高成本也最低。還有一個(gè)細(xì)節(jié)判斷結(jié)果要做二次校驗(yàn)。AI 返回行號(hào)后我會(huì)檢查這一行是否真的包含至少兩個(gè)非空單元格且非空單元格中文字占比超過(guò)一半。如果校驗(yàn)不通過(guò)就回退到默認(rèn)值通常是第 1 行并記錄警告日志。這樣即使 AI 判斷失誤也不會(huì)導(dǎo)致整個(gè)流程崩潰。3.4 列名模糊匹配解決“同義詞”難題表頭識(shí)別出來(lái)之后下一個(gè)問(wèn)題是用戶說(shuō)的“銷售額”和表里的“銷售金額”“營(yíng)收”“GMV”可能是同一個(gè)意思。傳統(tǒng)做法是維護(hù)一個(gè)同義詞詞典但維護(hù)成本高而且永遠(yuǎn)覆蓋不全。我的方案還是讓 AI 來(lái)做映射。封裝一個(gè)match_column工具接收“用戶想要的列名”和“表頭列表”返回最匹配的列索引mcp.tool() def match_column(target_name: str, headers: list[str]) - int: 在表頭列表中查找與目標(biāo)名稱語(yǔ)義最匹配的列返回列索引。 支持同義詞匹配如銷售額可匹配銷售金額營(yíng)收等。 當(dāng)需要根據(jù)用戶描述定位具體列時(shí)調(diào)用。 prompt f目標(biāo)列名{target_name} 可選表頭{headers} 請(qǐng)返回與目標(biāo)列名語(yǔ)義最匹配的表頭索引從0開(kāi)始。 如果沒(méi)有匹配項(xiàng)返回-1。只返回?cái)?shù)字。 idx call_llm(prompt) return int(idx)實(shí)測(cè)下來(lái)這個(gè)方案的匹配準(zhǔn)確率比同義詞詞典高不少。比如“客戶名稱”能匹配到“客戶”“客戶名”“甲方”“下單時(shí)間”能匹配到“訂單日期”“創(chuàng)建時(shí)間”。而且不需要我維護(hù)任何詞典AI 自己就懂這些語(yǔ)義關(guān)系。注意模糊匹配一定要設(shè)置“置信度兜底”。如果 AI 返回 -1表示沒(méi)匹配上或者返回的索引對(duì)應(yīng)的表頭與目標(biāo)名稱差異過(guò)大要提示用戶確認(rèn)而不是硬著頭皮往下走。我吃過(guò)這個(gè)虧——AI 把“利潤(rùn)”匹配到了“成本”列因?yàn)閮烧咴谡Z(yǔ)義上有關(guān)聯(lián)但業(yè)務(wù)含義完全相反。后來(lái)我加了一條規(guī)則匹配結(jié)果的表頭文字與目標(biāo)名稱不能有反義詞關(guān)系這個(gè)靠一個(gè)簡(jiǎn)單的反義詞列表來(lái)兜底。3.5 批量處理的并發(fā)控制處理多個(gè)文件時(shí)如果串行處理速度慢如果無(wú)腦并發(fā)又可能把內(nèi)存撐爆。我的做法是用concurrent.futures做一個(gè)帶并發(fā)上限的線程池from concurrent.futures import ThreadPoolExecutor, as_completed def batch_process(files: list[str], max_workers: int 4): results [] with ThreadPoolExecutor(max_workersmax_workers) as executor: future_to_file { executor.submit(process_single_file, f): f for f in files } for future in as_completed(future_to_file): file_path future_to_file[future] try: result future.result() results.append(result) except Exception as e: logger.error(f處理 {file_path} 失敗: {e}) results.append({file: file_path, error: str(e)}) return resultsmax_workers設(shè)多少合適我的經(jīng)驗(yàn)值是CPU 核心數(shù)的一半。因?yàn)?Excel 處理是 IO 密集和 CPU 密集混合型的讀文件是 IO解析和計(jì)算是 CPU。設(shè)太大反而會(huì)因?yàn)樯舷挛那袚Q導(dǎo)致效率下降。我實(shí)測(cè)過(guò)4 核機(jī)器上設(shè) 4 個(gè) worker 比設(shè) 8 個(gè)快大約 15%。另外每個(gè)文件的處理結(jié)果要獨(dú)立記錄成功或失敗不能因?yàn)橐粋€(gè)文件報(bào)錯(cuò)就中斷整個(gè)批次。這在處理幾十個(gè)文件時(shí)特別重要——你總不希望第 3 個(gè)文件格式有問(wèn)題導(dǎo)致后面 20 個(gè)文件都不處理了吧。4. 完整實(shí)操流程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 環(huán)境準(zhǔn)備從零搭好開(kāi)發(fā)環(huán)境先把環(huán)境搭起來(lái)。我假設(shè)你用的是 Windows 或者 macOSLinux 也一樣命令稍微改改就行。第一步確認(rèn) Python 版本。MCP SDK 要求 Python 3.10 以上我建議直接用 3.11 或 3.12兼容性最好python --version # 如果低于 3.10去 python.org 下載新版安裝第二步創(chuàng)建虛擬環(huán)境。這一步別省我見(jiàn)過(guò)太多人因?yàn)槿汁h(huán)境里包版本沖突排查半天python -m venv mcp-excel-env # Windows mcp-excel-env\Scripts\activate # macOS/Linux source mcp-excel-env/bin/activate第三步安裝依賴pip install mcp openpyxl pydantic如果你在國(guó)內(nèi)pip 下載慢的話可以加個(gè)鏡像源參數(shù)這個(gè)大家都懂我就不多說(shuō)了。第四步驗(yàn)證安裝python -c import mcp; import openpyxl; print(OK)看到 OK 就說(shuō)明環(huán)境沒(méi)問(wèn)題了。提示如果你用 VSCode 開(kāi)發(fā)記得在 VSCode 里把 Python 解釋器切換到剛才創(chuàng)建的虛擬環(huán)境。快捷鍵 CtrlShiftP輸入“Python: Select Interpreter”選 mcp-excel-env 那個(gè)。不切換的話VSCode 的代碼提示會(huì)找不到 mcp 包寫(xiě)代碼時(shí)一堆紅色波浪線很影響心情。4.2 項(xiàng)目結(jié)構(gòu)文件怎么組織我的項(xiàng)目結(jié)構(gòu)是這樣的你可以直接照著建mcp-excel/ ├── server.py # MCP 服務(wù)入口注冊(cè)工具 ├── tools/ │ ├── __init__.py │ ├── reader.py # 讀取相關(guān)工具 │ ├── writer.py # 寫(xiě)入相關(guān)工具 │ └── analyzer.py # 分析相關(guān)工具 ├── core/ │ ├── __init__.py │ ├── excel_ops.py # openpyxl 封裝 │ └── llm_client.py # 模型調(diào)用封裝 ├── tests/ │ └── test_reader.py └── requirements.txt為什么要分這么細(xì)因?yàn)?MCP 工具會(huì)越來(lái)越多全堆在一個(gè)文件里超過(guò) 500 行之后就很難維護(hù)了。按功能分模塊每個(gè)模塊 100-200 行改起來(lái)清爽。server.py只做一件事導(dǎo)入各個(gè)模塊的工具注冊(cè)到 MCP 實(shí)例上然后啟動(dòng)服務(wù)。業(yè)務(wù)邏輯全在tools/和core/里。4.3 核心工具實(shí)現(xiàn)讀取 Excel 的完整代碼這是最基礎(chǔ)也最常用的工具我把完整實(shí)現(xiàn)貼出來(lái)關(guān)鍵地方加注釋# tools/reader.py from mcp.server.fastmcp import FastMCP from core.excel_ops import load_workbook_safe, get_sheet_names from pydantic import BaseModel, field_validator import os mcp FastMCP(excel-reader) class ReadParams(BaseModel): file_path: str sheet_name: str max_rows: int 100 field_validator(file_path) classmethod def validate_path(cls, v): if not os.path.exists(v): raise ValueError(f文件不存在: {v}) return v field_validator(max_rows) classmethod def validate_rows(cls, v): if v 1 or v 10000: raise ValueError(max_rows 必須在 1-10000 之間) return v mcp.tool() def read_sheet(file_path: str, sheet_name: str , max_rows: int 100) - str: 讀取 Excel 文件的指定 Sheet 內(nèi)容。 參數(shù) - file_path: Excel 文件的完整路徑 - sheet_name: Sheet 名稱留空則讀取第一個(gè) Sheet - max_rows: 最多讀取的行數(shù)默認(rèn)100避免返回?cái)?shù)據(jù)過(guò)大 返回二維數(shù)組格式的字符串每行用換行分隔單元格用 | 分隔。 僅在需要查看表格具體內(nèi)容時(shí)調(diào)用此工具。 params ReadParams( file_pathfile_path, sheet_namesheet_name, max_rowsmax_rows ) wb load_workbook_safe(params.file_path) if params.sheet_name: if params.sheet_name not in wb.sheetnames: available , .join(wb.sheetnames) return f錯(cuò)誤Sheet {params.sheet_name} 不存在。可用的 Sheet{available} ws wb[params.sheet_name] else: ws wb.active rows [] for i, row in enumerate(ws.iter_rows(values_onlyTrue)): if i params.max_rows: rows.append(f...已截?cái)喙?{ws.max_row} 行) break cells [str(c) if c is not None else for c in row] rows.append( | .join(cells)) wb.close() return \n.join(rows)這段代碼有幾個(gè)設(shè)計(jì)決策值得說(shuō)明為什么返回字符串而不是 JSON因?yàn)?MCP 工具的返回值最終是給 AI 看的字符串格式對(duì) AI 更友好token 消耗也更低。JSON 的括號(hào)、引號(hào)會(huì)浪費(fèi)不少 token。為什么默認(rèn)只讀 100 行因?yàn)?AI 通常只需要看個(gè)大概就能做判斷不需要全量數(shù)據(jù)。讀太多行不僅浪費(fèi) token還可能超出模型的上下文窗口。如果 AI 確實(shí)需要更多數(shù)據(jù)它可以再調(diào)一次把max_rows調(diào)大。為什么用values_onlyTrue這樣 openpyxl 直接返回單元格的值而不是 Cell 對(duì)象。Cell 對(duì)象包含樣式、公式等一堆信息序列化起來(lái)麻煩而且大部分場(chǎng)景用不上。4.4 核心工具實(shí)現(xiàn)智能寫(xiě)入與格式保留寫(xiě)入比讀取復(fù)雜因?yàn)橐幚砀袷絾?wèn)題。我的原則是只改數(shù)據(jù)不動(dòng)格式。用戶原來(lái)的表格長(zhǎng)什么樣寫(xiě)入之后還是什么樣只是數(shù)據(jù)更新了。# tools/writer.py from mcp.server.fastmcp import FastMCP from core.excel_ops import load_workbook_safe from openpyxl.utils import column_index_from_string import shutil import os mcp FastMCP(excel-writer) mcp.tool() def write_cell(file_path: str, sheet_name: str, cell: str, value: str) - str: 向 Excel 指定單元格寫(xiě)入值保留原有格式。 參數(shù) - file_path: Excel 文件路徑 - sheet_name: Sheet 名稱 - cell: 單元格坐標(biāo)如 B3 - value: 要寫(xiě)入的值 返回操作結(jié)果描述。 注意此操作會(huì)直接修改原文件建議先備份。 # 自動(dòng)備份 backup_path file_path .bak if not os.path.exists(backup_path): shutil.copy2(file_path, backup_path) wb load_workbook_safe(file_path) if sheet_name not in wb.sheetnames: return f錯(cuò)誤Sheet {sheet_name} 不存在 ws wb[sheet_name] ws[cell] value wb.save(file_path) wb.close() return f已寫(xiě)入 {sheet_name}!{cell} {value}原文件已備份至 {backup_path}這里有個(gè)實(shí)操心得寫(xiě)入操作一定要做自動(dòng)備份。我踩過(guò)一次坑——AI 判斷失誤把數(shù)據(jù)寫(xiě)到了錯(cuò)誤的列結(jié)果原文件被覆蓋了只能從回收站找。后來(lái)我加了自動(dòng)備份邏輯第一次寫(xiě)入時(shí)生成.bak文件后續(xù)寫(xiě)入不再重復(fù)備份。這樣既保證了安全又不會(huì)產(chǎn)生一堆備份文件。還有一個(gè)細(xì)節(jié)shutil.copy2而不是shutil.copy。copy2會(huì)保留文件的元數(shù)據(jù)創(chuàng)建時(shí)間、修改時(shí)間等copy不會(huì)。雖然對(duì)功能沒(méi)影響但保留元數(shù)據(jù)更規(guī)范。4.5 把工具串起來(lái)一個(gè)完整的處理流程單個(gè)工具實(shí)現(xiàn)完了現(xiàn)在看怎么把它們串成一個(gè)完整的工作流。假設(shè)用戶的需求是“把 data 目錄下所有 Excel 文件的銷售數(shù)據(jù)匯總到一張表里”。整個(gè)流程分五步第一步掃描文件。用一個(gè)list_excel_files工具列出目錄下所有 Excel 文件返回文件路徑列表。第二步逐個(gè)分析結(jié)構(gòu)。對(duì)每個(gè)文件先調(diào)read_sheet讀取前幾行再調(diào)detect_header_row判斷表頭位置再調(diào)match_column找到“銷售金額”對(duì)應(yīng)的列。第三步提取數(shù)據(jù)。根據(jù)前面判斷出的表頭行號(hào)和列索引精確讀取數(shù)據(jù)區(qū)域。第四步匯總計(jì)算。把所有文件的數(shù)據(jù)合并按用戶要求做匯總。第五步寫(xiě)入結(jié)果。調(diào)write_cell或?qū)ｉT(mén)的寫(xiě)入工具把結(jié)果寫(xiě)到新文件里。這個(gè)流程里AI 的參與點(diǎn)主要在第二步——判斷表頭位置和列匹配。其他步驟都是確定性的代碼執(zhí)行。這樣設(shè)計(jì)的好處是即使 AI 判斷有誤也只影響第二步不會(huì)導(dǎo)致整個(gè)流程崩潰。而且第二步的判斷結(jié)果可以緩存同一個(gè)文件第二次處理時(shí)直接用緩存不用再調(diào) AI。提示緩存判斷結(jié)果時(shí)要用文件的修改時(shí)間做 key 的一部分。如果文件被修改過(guò)緩存就失效需要重新判斷。我一開(kāi)始沒(méi)加這個(gè)邏輯結(jié)果用戶更新了文件之后程序還在用舊的判斷結(jié)果數(shù)據(jù)全錯(cuò)了。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 工具調(diào)用失敗排查速查表實(shí)際開(kāi)發(fā)和使用過(guò)程中我遇到了不少問(wèn)題整理成一張速查表方便你對(duì)照排查現(xiàn)象可能原因排查方法解決方案AI 不調(diào)用工具docstring 描述不清檢查工具描述是否說(shuō)明了使用場(chǎng)景補(bǔ)充“何時(shí)調(diào)用”的說(shuō)明調(diào)用時(shí)參數(shù)錯(cuò)誤參數(shù) schema 不明確查看 AI 傳入的實(shí)際參數(shù)在 docstring 里寫(xiě)清參數(shù)格式和示例文件讀取報(bào)錯(cuò)路徑含中文或空格打印實(shí)際路徑用os.path.abspath規(guī)范化路徑表頭識(shí)別錯(cuò)誤前10行干擾信息多打印傳給 AI 的預(yù)覽內(nèi)容減少預(yù)覽行數(shù)或增加篩選條件列匹配錯(cuò)誤存在語(yǔ)義相近的列打印匹配結(jié)果和候選列表增加反義詞校驗(yàn)和置信度閾值寫(xiě)入后格式丟失直接賦值破壞了樣式對(duì)比寫(xiě)入前后的單元格樣式只改 value不動(dòng) style大批量處理內(nèi)存溢出一次性加載所有文件監(jiān)控內(nèi)存占用分批處理及時(shí)釋放 workbook并發(fā)處理結(jié)果錯(cuò)亂共享了可變狀態(tài)檢查是否有全局變量每個(gè)任務(wù)用獨(dú)立的數(shù)據(jù)結(jié)構(gòu)5.2 三個(gè)我踩過(guò)的坑和解決方法坑一AI 把“日期”列識(shí)別成了“編號(hào)”列。有一次處理員工信息表表頭里有“入職日期”和“工號(hào)”兩列。我讓 AI 匹配“日期”結(jié)果它匹配到了“工號(hào)”因?yàn)楣ぬ?hào)的格式是“20230101”這種數(shù)字AI 誤以為是日期。后來(lái)我在匹配邏輯里加了一條如果目標(biāo)列名包含“日期”“時(shí)間”等時(shí)間關(guān)鍵詞候選列的值必須能解析為日期格式。加了這條校驗(yàn)之后再?zèng)]出過(guò)這個(gè)問(wèn)題?？佣penpyxl 讀取大文件時(shí)內(nèi)存暴漲。有個(gè)文件有 50 萬(wàn)行數(shù)據(jù)用load_workbook直接加載內(nèi)存瞬間飆到 2GB。后來(lái)改用read_onlyTrue模式wb load_workbook(file_path, read_onlyTrue, data_onlyTrue)read_only模式下 openpyxl 不會(huì)把整個(gè)文件加載到內(nèi)存而是流式讀取。data_onlyTrue表示只讀值不讀公式。這兩個(gè)參數(shù)一加內(nèi)存占用降到了 200MB 左右。但要注意read_only模式下不能隨機(jī)訪問(wèn)單元格只能順序遍歷所以適合“讀取全部數(shù)據(jù)”的場(chǎng)景不適合“讀取指定單元格”?？尤齅CP 服務(wù)啟動(dòng)后 AI 找不到工具。這個(gè)問(wèn)題困擾了我半天。后來(lái)發(fā)現(xiàn)是工具注冊(cè)的模塊沒(méi)有被導(dǎo)入。MCP 服務(wù)啟動(dòng)時(shí)只會(huì)掃描顯式導(dǎo)入的模塊如果server.py里沒(méi)有import tools.reader那reader.py里注冊(cè)的工具就不會(huì)生效。解決方法很簡(jiǎn)單在server.py里把所有工具模塊都導(dǎo)入一遍# server.py from tools import reader, writer, analyzer # noqa: F401 from mcp.server.fastmcp import FastMCP mcp FastMCP(excel-processor) if __name__ __main__: mcp.run()那個(gè)# noqa: F401是告訴代碼檢查工具“我知道這個(gè)導(dǎo)入沒(méi)被直接使用但它是必要的”避免 IDE 報(bào)未使用導(dǎo)入的警告。5.3 性能優(yōu)化的幾個(gè)實(shí)用技巧技巧一批量讀取代替逐單元格讀取。openpyxl 的ws.cell(row, col)每次調(diào)用都有開(kāi)銷讀 1000 個(gè)單元格就是 1000 次調(diào)用。用ws.iter_rows()一次性遍歷速度快 5-10 倍。技巧二寫(xiě)入時(shí)先收集再一次性寫(xiě)。不要每算出一個(gè)值就寫(xiě)一次文件而是把所有結(jié)果收集到內(nèi)存里最后統(tǒng)一wb.save()。頻繁 save 會(huì)導(dǎo)致文件反復(fù)讀寫(xiě)速度極慢。技巧三AI 調(diào)用結(jié)果做緩存。表頭識(shí)別和列匹配的結(jié)果用functools.lru_cache或者自己寫(xiě)個(gè)簡(jiǎn)單的字典緩存。同一個(gè)文件多次處理時(shí)直接讀緩存省掉 AI 調(diào)用。我實(shí)測(cè)過(guò)加了緩存之后重復(fù)處理同一批文件的耗時(shí)從 45 秒降到了 8 秒。技巧四大文件分塊處理。如果單個(gè) Sheet 超過(guò) 10 萬(wàn)行不要一次性讀進(jìn)來(lái)。用iter_rows配合分塊邏輯每 1 萬(wàn)行處理一次處理完就釋放。這樣內(nèi)存占用恒定不會(huì)隨文件增大而增長(zhǎng)。5.4 安全性與穩(wěn)定性注意事項(xiàng)第一文件路徑要做白名單校驗(yàn)。不要讓 AI 傳入任意路徑否則可能讀到系統(tǒng)敏感文件。我的做法是限定一個(gè)工作目錄所有文件操作都必須在這個(gè)目錄下WORK_DIR os.path.abspath(./data) def validate_path(path): abs_path os.path.abspath(path) if not abs_path.startswith(WORK_DIR): raise ValueError(f路徑必須在 {WORK_DIR} 目錄下) return abs_path第二寫(xiě)入操作要加確認(rèn)機(jī)制。對(duì)于會(huì)修改原文件的操作我加了一個(gè)dry_run參數(shù)。默認(rèn)dry_runTrue只返回“將要執(zhí)行什么操作”而不實(shí)際寫(xiě)入。AI 確認(rèn)無(wú)誤后再傳dry_runFalse真正執(zhí)行。這個(gè)機(jī)制避免了很多誤操作。第三異常要捕獲并返回友好信息。MCP 工具里不要拋未捕獲的異常否則整個(gè)服務(wù)可能掛掉。所有可能出錯(cuò)的地方都用 try-except 包起來(lái)返回結(jié)構(gòu)化的錯(cuò)誤信息try: result do_something() return {status: success, data: result} except Exception as e: logger.exception(操作失敗) return {status: error, message: str(e)}這樣 AI 拿到錯(cuò)誤信息后可以決定是重試、換參數(shù)還是告知用戶。6. 后續(xù)擴(kuò)展方向與個(gè)人體會(huì)6.1 這個(gè)項(xiàng)目還能怎么玩第一個(gè) MCP 跑通之后我陸續(xù)加了不少擴(kuò)展這里列幾個(gè)我覺(jué)得最有價(jià)值的方向方向一接入更多數(shù)據(jù)源。Excel 只是起點(diǎn)同樣的架構(gòu)可以擴(kuò)展到 CSV、JSON、數(shù)據(jù)庫(kù)查詢結(jié)果。只要把“讀取”這一層抽象好上層邏輯基本不用改。方向二增加圖表生成能力。用 openpyxl 的圖表功能讓 AI 根據(jù)數(shù)據(jù)自動(dòng)生成柱狀圖、折線圖。用戶說(shuō)“把銷售趨勢(shì)畫(huà)出來(lái)”AI 判斷用折線圖代碼負(fù)責(zé)生成。方向三做數(shù)據(jù)校驗(yàn)規(guī)則引擎。讓 AI 根據(jù)數(shù)據(jù)內(nèi)容自動(dòng)生成校驗(yàn)規(guī)則比如“金額不能為負(fù)”“日期不能晚于今天”然后代碼執(zhí)行校驗(yàn)。這比人工寫(xiě)校驗(yàn)規(guī)則靈活多了。方向四和現(xiàn)有工作流平臺(tái)集成。我試過(guò)把這個(gè) MCP 服務(wù)接到一些工作流工具里作為自定義節(jié)點(diǎn)使用。這樣既保留了工作流平臺(tái)的編排能力又用上了自己寫(xiě)的專業(yè)工具。6.2 我個(gè)人的幾點(diǎn)真實(shí)體會(huì)做這個(gè)項(xiàng)目最大的收獲不是學(xué)會(huì)了 MCP 這個(gè)技術(shù)而是想清楚了一件事AI 和代碼的邊界在哪里。我一開(kāi)始總想著讓 AI 多干點(diǎn)覺(jué)得這樣才“智能”。后來(lái)發(fā)現(xiàn)AI 擅長(zhǎng)的是模糊判斷和語(yǔ)義理解代碼擅長(zhǎng)的是精確執(zhí)行和批量處理。把這兩者混在一起反而兩邊都做不好。真正好用的 AI 工具是讓 AI 做它擅長(zhǎng)的判斷讓代碼做它擅長(zhǎng)的執(zhí)行中間用一個(gè)清晰的接口隔開(kāi)。另一個(gè)體會(huì)是不要追求一步到位。我第一版 MCP 只有三個(gè)工具讀文件、寫(xiě)單元格、列匹配。功能很簡(jiǎn)陋但已經(jīng)能解決我 80% 的問(wèn)題了。后面遇到新需求再加新工具慢慢就豐富起來(lái)了。如果一開(kāi)始就想設(shè)計(jì)一個(gè)“萬(wàn)能 Excel 處理框架”大概率會(huì)陷入過(guò)度設(shè)計(jì)的泥潭最后什么都做不出來(lái)。最后一個(gè)建議多寫(xiě)日志。AI 調(diào)用工具的過(guò)程是黑盒你只能通過(guò)日志看到它調(diào)了什么、傳了什么參數(shù)、返回了什么結(jié)果。我每個(gè)工具入口和出口都打了日志排查問(wèn)題時(shí)直接看日志比猜快多了。日志級(jí)別用 INFO 就行DEBUG 太啰嗦ERROR 又漏信息。這個(gè)項(xiàng)目我還在持續(xù)迭代后面如果有什么新的踩坑經(jīng)驗(yàn)再找機(jī)會(huì)分享。如果你也在做類似的東西歡迎交流。