1. 項(xiàng)目緣起為什么我們需要一個(gè)“本地文件讀取工具服務(wù)”在開發(fā)者的日常工作中與本地文件系統(tǒng)打交道是家常便飯。無論是讀取配置文件、解析日志、加載靜態(tài)資源還是處理用戶上傳的臨時(shí)文件我們總是在重復(fù)編寫類似的代碼打開文件、讀取流、處理編碼、關(guān)閉資源還要小心翼翼地處理各種異常。當(dāng)項(xiàng)目從單體應(yīng)用演進(jìn)到微服務(wù)架構(gòu)或者需要構(gòu)建一個(gè)前后端分離的、需要安全訪問服務(wù)器特定目錄文件的應(yīng)用時(shí)這個(gè)問題就變得更加棘手。你可能會(huì)遇到這樣的場景一個(gè)數(shù)據(jù)分析后臺(tái)需要?jiǎng)討B(tài)讀取服務(wù)器上生成的報(bào)表文件一個(gè)內(nèi)部文檔管理系統(tǒng)需要安全地預(yù)覽用戶上傳的各類文檔或者你只是想為團(tuán)隊(duì)構(gòu)建一個(gè)統(tǒng)一的、安全的文件訪問網(wǎng)關(guān)避免每個(gè)服務(wù)都直接操作敏感的服務(wù)器路徑。直接暴露文件系統(tǒng)路徑給前端或不信任的服務(wù)是危險(xiǎn)的而重復(fù)編寫文件IO代碼又是低效的。這時(shí)一個(gè)標(biāo)準(zhǔn)的、協(xié)議化的“文件讀取工具服務(wù)”就顯得尤為必要。它就像一個(gè)配備了標(biāo)準(zhǔn)接口和嚴(yán)格安保的文件管家外部請(qǐng)求通過定義好的協(xié)議“下單”管家根據(jù)指令安全地取回文件內(nèi)容并封裝成標(biāo)準(zhǔn)格式返回。而MCPModel Context Protocol協(xié)議正是為這類“工具”與“大腦”通常是AI智能體或核心服務(wù)之間的協(xié)作提供了一套優(yōu)秀的“工作語言”。本次實(shí)踐我們就來親手打造這樣一個(gè)基于MCP協(xié)議的本地文件讀取工具服務(wù)讓你在需要安全、高效、標(biāo)準(zhǔn)化地暴露文件讀取能力時(shí)能有一個(gè)現(xiàn)成的、可復(fù)用的解決方案。2. 理解MCP協(xié)議工具與智能體間的“標(biāo)準(zhǔn)插座”在開始動(dòng)手之前我們必須先搞清楚MCP是什么以及它為何適合這個(gè)場景。你可以把MCP想象成電器上的“標(biāo)準(zhǔn)插座”。你的房子核心服務(wù)或AI智能體里有電力計(jì)算和決策能力但你需要電熱水壺文件讀取、電視機(jī)數(shù)據(jù)庫查詢等工具來執(zhí)行具體任務(wù)。MCP就是墻上那個(gè)統(tǒng)一的插座標(biāo)準(zhǔn)任何符合這個(gè)標(biāo)準(zhǔn)的工具都能即插即用房子無需為每個(gè)工具定制一套供電接口。MCP協(xié)議的核心思想是標(biāo)準(zhǔn)化工具的描述、調(diào)用和結(jié)果返回。它主要包含幾個(gè)關(guān)鍵部分工具聲明每個(gè)工具都需要向“大腦”注冊(cè)告訴大腦“我叫什么名字”、“我能干什么描述”、“你需要給我提供哪些參數(shù)”。對(duì)于我們的文件讀取工具就需要聲明一個(gè)名為read_file的工具描述為“讀取指定路徑的文本文件內(nèi)容”并定義一個(gè)必需的參數(shù)file_path。標(biāo)準(zhǔn)化調(diào)用“大腦”通過一個(gè)統(tǒng)一的JSON-RPC接口來調(diào)用工具。它不需要知道工具內(nèi)部是用Python、Go還是Rust實(shí)現(xiàn)的它只需要按照協(xié)議格式發(fā)送請(qǐng)求即可。結(jié)構(gòu)化結(jié)果工具執(zhí)行完畢后必須按照協(xié)議規(guī)定的格式返回結(jié)果。這通常包括執(zhí)行狀態(tài)成功/失敗、返回的內(nèi)容如文件文本以及可能的結(jié)構(gòu)化數(shù)據(jù)如元信息。MCP支持返回純文本、圖片甚至HTML片段非常靈活。資源管理MCP還定義了“資源”Resources的概念可以用于動(dòng)態(tài)列出可用的文件列表這對(duì)于實(shí)現(xiàn)一個(gè)文件瀏覽器式的工具非常有用。選擇MCP來實(shí)現(xiàn)我們的文件服務(wù)有以下幾個(gè)壓倒性優(yōu)勢(shì)解耦與標(biāo)準(zhǔn)化服務(wù)端工具實(shí)現(xiàn)和客戶端調(diào)用者完全解耦。只要遵循MCP協(xié)議你可以用任何語言重寫工具端或用任何兼容MCP的客戶端如Claude Desktop、Cline IDE、自研AI智能體框架來調(diào)用它無需修改對(duì)方代碼。安全性內(nèi)建協(xié)議層不關(guān)心傳輸安全這允許我們?cè)诘讓幼杂蛇x擇最安全的通信方式例如在本地使用SSEServer-Sent Events或WebSocket over localhost在生產(chǎn)環(huán)境使用帶認(rèn)證的HTTPS。生態(tài)友好MCP正在成為AI智能體工具生態(tài)的事實(shí)標(biāo)準(zhǔn)之一。基于它開發(fā)工具意味著你的工具能輕松接入一個(gè)快速增長的智能體生態(tài)圈潛力巨大。3. 技術(shù)選型與項(xiàng)目初始化打造我們的“工具車間”明確了目標(biāo)和藍(lán)圖后我們開始搭建“車間”。技術(shù)選型需要平衡開發(fā)效率、性能、協(xié)議兼容性和部署便利性。服務(wù)端語言我們選擇Node.js。原因有三一是MCP協(xié)議官方提供了完善的Node.js SDKmodelcontextprotocol/sdk能極大降低開發(fā)復(fù)雜度二是JavaScript/TypeScript在處理IO、JSON和網(wǎng)絡(luò)請(qǐng)求方面非常高效三是其輕量級(jí)和龐大的npm生態(tài)便于快速集成和后期擴(kuò)展。通信協(xié)議選擇SSE。MCP支持多種傳輸方式stdio, SSE, WebSocket。對(duì)于本地的工具服務(wù)SSE是一個(gè)簡單而高效的選擇。它基于HTTP易于理解和調(diào)試并且SDK提供了開箱即用的支持。項(xiàng)目初始化mkdir mcp-file-server cd mcp-file-server npm init -y npm install modelcontextprotocol/sdk核心依賴除了MCP SDK我們還需要fsNode.js內(nèi)置用于文件操作和path內(nèi)置用于安全地處理路徑。為了更好的開發(fā)體驗(yàn)我們可以安裝TypeScript及相關(guān)類型定義npm install -D typescript types/node npx tsc --init在生成的tsconfig.json中確保target設(shè)置為ES2022或更高module設(shè)置為commonjs或NodeNext。4. 核心工具實(shí)現(xiàn)read_file的完整邏輯與安全邊界這是本次實(shí)踐最核心的部分。我們將實(shí)現(xiàn)一個(gè)健壯、安全的read_file工具。創(chuàng)建一個(gè)src/server.ts文件。4.1 工具聲明與參數(shù)定義首先我們需要導(dǎo)入SDK并聲明我們的工具。MCP SDK的核心是Server類我們通過它來注冊(cè)工具。import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ToolSchema, } from modelcontextprotocol/sdk/types.js; import * as fs from fs/promises; import * as path from path; // 1. 創(chuàng)建MCP服務(wù)器實(shí)例 const server new Server( { name: local-file-reader, version: 0.1.0, }, { capabilities: { tools: {}, // 聲明我們將提供工具 }, } ); // 2. 定義 read_file 工具 const readFileTool: ToolSchema { name: read_file, description: 讀取指定路徑的文本文件內(nèi)容。支持常見文本編碼如utf-8。, inputSchema: { type: object, properties: { file_path: { type: string, description: 要讀取的文件的絕對(duì)路徑或相對(duì)于指定根目錄的路徑。, }, }, required: [file_path], }, };這里的關(guān)鍵是inputSchema它嚴(yán)格定義了客戶端調(diào)用時(shí)必須傳遞的參數(shù)。我們只要求一個(gè)file_path。描述寫得清晰能幫助調(diào)用者尤其是AI正確使用。4.2 實(shí)現(xiàn)工具處理函數(shù)安全是第一位接下來我們?yōu)楣ぞ邔?shí)現(xiàn)處理邏輯并將其注冊(cè)到服務(wù)器上。// 3. 設(shè)置一個(gè)安全的工作根目錄非常重要 const SAFE_ROOT_DIR process.env.FILE_SERVER_ROOT || path.resolve(process.cwd(), safe_data); // 確保安全目錄存在 await fs.mkdir(SAFE_ROOT_DIR, { recursive: true }); // 4. 實(shí)現(xiàn)工具處理函數(shù) server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name ! readFileTool.name) { throw new Error(Unknown tool: ${request.params.name}); } const args request.params.arguments as { file_path: string }; const userProvidedPath args.file_path; // **安全核心步驟1路徑規(guī)范化與解析** // 防止目錄遍歷攻擊如 ../../../etc/passwd const normalizedPath path.normalize(userProvidedPath); // 如果路徑是絕對(duì)的直接使用如果是相對(duì)的則相對(duì)于安全根目錄 const targetPath path.isAbsolute(normalizedPath) ? normalizedPath : path.resolve(SAFE_ROOT_DIR, normalizedPath); // **安全核心步驟2路徑邊界檢查** // 確保目標(biāo)路徑在安全根目錄之內(nèi)對(duì)于相對(duì)路徑情況 if (!targetPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { return { content: [ { type: text, text: 錯(cuò)誤訪問路徑 ${userProvidedPath} 被拒絕。出于安全考慮只能訪問指定根目錄下的文件。, }, ], }; } // **安全核心步驟3路徑存在性與類型檢查** let stats; try { stats await fs.stat(targetPath); } catch (error: any) { if (error.code ENOENT) { return { content: [ { type: text, text: 錯(cuò)誤文件 ${userProvidedPath} 不存在于路徑 ${targetPath}。, }, ], }; } throw error; // 拋出其他未知錯(cuò)誤 } if (!stats.isFile()) { return { content: [ { type: text, text: 錯(cuò)誤路徑 ${userProvidedPath} 指向的不是一個(gè)普通文件可能是目錄。, }, ], }; } // **安全核心步驟4文件大小限制防止讀取超大文件導(dǎo)致內(nèi)存溢出** const MAX_FILE_SIZE 10 * 1024 * 1024; // 10MB if (stats.size MAX_FILE_SIZE) { return { content: [ { type: text, text: 錯(cuò)誤文件 ${userProvidedPath} 大小${stats.size}字節(jié)超過限制${MAX_FILE_SIZE}字節(jié)。, }, ], }; } // 5. 執(zhí)行安全的文件讀取 try { const content await fs.readFile(targetPath, { encoding: utf-8 }); return { content: [ { type: text, // 可以附加一些元信息如文件路徑和大小 text: 成功讀取文件${targetPath}\n文件大小${stats.size}字節(jié)\n--- 內(nèi)容開始 ---\n${content}\n--- 內(nèi)容結(jié)束 ---, }, ], }; } catch (error: any) { // 處理讀取錯(cuò)誤如權(quán)限不足、編碼錯(cuò)誤等 return { content: [ { type: text, text: 讀取文件時(shí)發(fā)生錯(cuò)誤${error.message}, }, ], }; } });這段代碼是工具安全性的基石。我強(qiáng)烈建議你理解每一步path.normalize(): 處理掉路徑中的..和.但僅靠它不夠。path.resolve()和startsWith()檢查這是防御目錄遍歷攻擊的關(guān)鍵。我們將所有訪問限制在SAFE_ROOT_DIR或其子目錄下。文件類型和大小檢查防止誤操作目錄和內(nèi)存耗盡攻擊。詳細(xì)的錯(cuò)誤返回給調(diào)用者明確的錯(cuò)誤信息而不是一個(gè)晦澀的異常。4.3 注冊(cè)工具并啟動(dòng)服務(wù)器最后將工具聲明給服務(wù)器并啟動(dòng)傳輸層。// 6. 在服務(wù)器能力中注冊(cè)工具聲明 server.setRequestHandler(ListToolsRequestSchema, async () { return { tools: [readFileTool], }; }); // 7. 創(chuàng)建傳輸層并連接這里使用Stdio適合被Claude Desktop等進(jìn)程調(diào)用 const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Local File Reader server running on stdio...);如果你希望作為一個(gè)獨(dú)立的HTTP/SSE服務(wù)器運(yùn)行可以使用new SSEServerTransport(server, options)。為了測(cè)試我們先用Stdio。5. 進(jìn)階功能實(shí)現(xiàn)“資源”與“列表”能力一個(gè)只能讀取已知路徑文件的工具還不夠智能。我們經(jīng)常需要先“瀏覽”某個(gè)目錄下有什么文件。MCP的“資源”Resources和“列表”List能力正是為此而生。這能讓我們的工具服務(wù)更像一個(gè)文件瀏覽器。5.1 定義目錄列表資源我們?cè)趕rc/server.ts中增加以下代碼import { ListResourcesRequestSchema, ReadResourceRequestSchema, ResourceSchema, } from modelcontextprotocol/sdk/types.js; // 聲明一個(gè)“目錄列表”資源模板 server.setRequestHandler(ListResourcesRequestSchema, async (request) { // 我們可以定義一個(gè)資源模式例如 directory://{path} // 這里簡單返回一個(gè)根目錄資源 const resources: ResourceSchema[] [ { uri: directory://${SAFE_ROOT_DIR}, mimeType: application/json, // 我們將返回JSON格式的列表 name: 目錄列表: ${SAFE_ROOT_DIR}, description: 顯示安全根目錄 ${SAFE_ROOT_DIR} 下的文件和子目錄, }, ]; return { resources }; });5.2 實(shí)現(xiàn)資源內(nèi)容讀取列出文件當(dāng)客戶端請(qǐng)求讀取directory:///some/path資源時(shí)我們返回該路徑下的文件列表。server.setRequestHandler(ReadResourceRequestSchema, async (request) { const uri request.params.uri; if (uri.startsWith(directory://)) { const dirPath uri.slice(directory://.length); const safeDirPath path.resolve(SAFE_ROOT_DIR, dirPath); // 再次進(jìn)行安全邊界檢查 if (!safeDirPath.startsWith(path.resolve(SAFE_ROOT_DIR))) { throw new Error(Access denied.); } try { const items await fs.readdir(safeDirPath, { withFileTypes: true }); const list items.map((item) ({ name: item.name, type: item.isDirectory() ? directory : file, path: path.join(dirPath, item.name), })); // 以結(jié)構(gòu)化文本JSON字符串返回便于AI解析 return { contents: [{ uri, mimeType: application/json, text: JSON.stringify(list, null, 2), }], }; } catch (error: any) { return { contents: [{ uri, mimeType: text/plain, text: 無法讀取目錄 ${dirPath}: ${error.message}, }], }; } } // 如果不是我們處理的資源URI返回空 return { contents: [] }; });現(xiàn)在你的工具服務(wù)不僅可以通過read_file工具讀取文件內(nèi)容還能讓客戶端先“瀏覽”directory:///資源來獲取文件列表然后再用獲取到的路徑去調(diào)用工具。這種組合極大地提升了工具的可用性和智能程度。6. 配置、運(yùn)行與調(diào)試讓服務(wù)轉(zhuǎn)起來6.1 構(gòu)建與運(yùn)行腳本在package.json中添加腳本{ scripts: { build: tsc, start: node dist/server.js, dev: tsx watch src/server.ts } }如果你使用tsx或ts-node進(jìn)行開發(fā)時(shí)熱重載需要先安裝npm install -D tsx。6.2 配置MCP客戶端以Claude Desktop為例要讓AI桌面應(yīng)用如Claude Desktop發(fā)現(xiàn)并使用你的工具你需要?jiǎng)?chuàng)建一個(gè)MCP配置文件。在Claude Desktop的配置目錄下macOS:~/Library/Application Support/Claude/claude_desktop_config.json Windows:%APPDATA%\Claude\claude_desktop_config.json添加你的工具服務(wù)器配置{ mcpServers: { local-file-reader: { command: node, args: [/ABSOLUTE/PATH/TO/YOUR/PROJECT/dist/server.js], env: { FILE_SERVER_ROOT: /ABSOLUTE/PATH/TO/YOUR/SAFE/DATA } } } }關(guān)鍵點(diǎn)command和args告訴Claude如何啟動(dòng)你的服務(wù)器。env設(shè)置了環(huán)境變量FILE_SERVER_ROOT這會(huì)被我們代碼中的SAFE_ROOT_DIR使用。務(wù)必使用絕對(duì)路徑。配置完成后重啟Claude Desktop。6.3 測(cè)試與調(diào)試直接測(cè)試服務(wù)器你可以先不通過Claude直接運(yùn)行npm run dev觀察服務(wù)器是否正常啟動(dòng)沒有報(bào)錯(cuò)。在Claude中驗(yàn)證重啟Claude后新建一個(gè)對(duì)話。你應(yīng)該能在Claude的“附件”或工具使用區(qū)域看到可用的工具。你可以嘗試讓Claude“使用 read_file 工具讀取某個(gè)文件”。例如在SAFE_ROOT_DIR下創(chuàng)建一個(gè)test.txt文件然后對(duì)Claude說“請(qǐng)讀取 test.txt 文件的內(nèi)容?！闭{(diào)試技巧在工具處理函數(shù)中添加console.error()打印日志這些日志會(huì)輸出到Claude Desktop的控制臺(tái)或你啟動(dòng)服務(wù)器的終端。使用try...catch仔細(xì)捕獲所有可能的異常并返回友好的錯(cuò)誤信息。測(cè)試邊界情況不存在的文件、目錄、符號(hào)鏈接、超大文件、包含特殊字符的路徑等。7. 生產(chǎn)環(huán)境考量與安全加固將這樣一個(gè)服務(wù)用于生產(chǎn)環(huán)境需要更周全的考慮。7.1 傳輸安全與認(rèn)證本地Stdio通信是安全的因?yàn)樗窃谕粰C(jī)器上的進(jìn)程間通信。但如果你部署為網(wǎng)絡(luò)服務(wù)SSE/HTTP則必須考慮HTTPS使用Nginx或Caddy反向代理配置SSL/TLS證書。認(rèn)證MCP協(xié)議本身不處理認(rèn)證。你需要在服務(wù)器端實(shí)現(xiàn)。一種簡單方式是通過HTTP Basic Auth或Bearer Token。在SSE連接初始化時(shí)檢查請(qǐng)求頭中的認(rèn)證信息。// 偽代碼在創(chuàng)建SSE傳輸時(shí) import { SSEServerTransport } from modelcontextprotocol/sdk/server/sse.js; const transport new SSEServerTransport(server, { authCallback: async (req) { const token req.headers[authorization]?.replace(Bearer , ); if (token ! EXPECTED_TOKEN) { throw new Error(Unauthorized); } } });7.2 性能與擴(kuò)展性大文件處理我們代碼中設(shè)置了10MB限制。對(duì)于需要處理大文件的場景如日志文件不應(yīng)一次性讀入內(nèi)存?？梢钥紤]實(shí)現(xiàn)流式讀取或者增加一個(gè)read_file_chunk工具支持指定偏移量和讀取長度。并發(fā)與限流Node.js是單線程異步IO能處理較高并發(fā)。但對(duì)于公開服務(wù)仍需實(shí)施限流rate limiting防止濫用。可以使用express-rate-limit等中間件。擴(kuò)展更多工具M(jìn)CP服務(wù)器的優(yōu)勢(shì)在于可以輕松擴(kuò)展。你可以基于相同模式添加write_file需極其謹(jǐn)慎、list_directory我們已通過資源實(shí)現(xiàn)、get_file_info等工具構(gòu)建一個(gè)功能完整的文件管理服務(wù)。7.3 監(jiān)控與日志使用winston或pino等日志庫結(jié)構(gòu)化記錄所有工具調(diào)用請(qǐng)求、參數(shù)、執(zhí)行結(jié)果和耗時(shí)。監(jiān)控服務(wù)器的內(nèi)存和CPU使用情況。記錄所有失敗訪問的路徑和來源用于安全審計(jì)。8. 踩坑實(shí)錄從開發(fā)到部署的常見問題在實(shí)際開發(fā)和測(cè)試中我遇到了幾個(gè)典型問題這里分享出來幫你避坑坑1路徑解析導(dǎo)致的權(quán)限逃逸最初我直接使用了用戶提供的路徑path.resolve(userProvidedPath)。如果用戶輸入/etc/passwd這個(gè)絕對(duì)路徑會(huì)直接通過path.isAbsolute()檢查導(dǎo)致安全邊界失效。教訓(xùn)即使對(duì)于絕對(duì)路徑也應(yīng)該將其與安全根目錄進(jìn)行解析和比較或者干脆禁止使用絕對(duì)路徑強(qiáng)制所有路徑都相對(duì)于SAFE_ROOT_DIR。我們最終的方案是更安全的相對(duì)路徑基于安全根目錄解析絕對(duì)路徑也必須通過安全邊界檢查。坑2環(huán)境變量路徑中的波浪號(hào)~在配置FILE_SERVER_ROOT時(shí)我習(xí)慣性地寫了~/projects/safe_data。Node.js的path.resolve()和fs模塊不會(huì)自動(dòng)解析波浪號(hào)為家目錄。這導(dǎo)致服務(wù)器啟動(dòng)時(shí)找不到目錄。解決方案要么在配置中使用絕對(duì)路徑/Users/username/projects/safe_data要么在代碼中手動(dòng)處理const rootDir process.env.FILE_SERVER_ROOT.replace(/^~(?$|\/|\\)/, require(os).homedir());坑3Claude Desktop 緩存了舊的工具列表在開發(fā)過程中你修改了工具的名稱或參數(shù)但Claude Desktop似乎還在使用舊的工具列表。這是因?yàn)榭蛻舳丝赡芫彺媪朔?wù)器的工具聲明。解決方法重啟Claude Desktop通?？梢越鉀Q。更徹底的方式是在開發(fā)時(shí)修改claude_desktop_config.json中服務(wù)器的args比如加一個(gè)虛擬參數(shù)[“dist/server.js”, “--dev”]然后重啟Claude強(qiáng)制它重新獲取工具列表?？?文件編碼問題我們使用fs.readFile(..., utf-8)。如果文件不是UTF-8編碼比如Windows下常見的GBK編碼的文本文件讀取就會(huì)產(chǎn)生亂碼。更健壯的做法可以嘗試使用jschardet這類庫檢測(cè)編碼或者提供一個(gè)可選的encoding參數(shù)給工具調(diào)用者。對(duì)于生產(chǎn)環(huán)境明確文檔說明支持的編碼或統(tǒng)一要求UTF-8。通過這個(gè)基于MCP協(xié)議的本地文件讀取工具服務(wù)開發(fā)實(shí)踐我們不僅得到了一個(gè)實(shí)用的工具更深入理解了如何設(shè)計(jì)一個(gè)安全、標(biāo)準(zhǔn)化的服務(wù)接口。MCP協(xié)議的魅力在于它的簡潔和通用性這套模式可以復(fù)用到任何你想暴露給AI或其它服務(wù)的本地能力上比如數(shù)據(jù)庫查詢、調(diào)用內(nèi)部API、發(fā)送郵件等。關(guān)鍵在于嚴(yán)謹(jǐn)?shù)陌踩O(shè)計(jì)和清晰的工具定義。當(dāng)你下次再需要讓AI安全地觸達(dá)你的本地環(huán)境時(shí)不妨考慮用MCP來搭這座橋。