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