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