1. 项目概述为什么我们需要一个MCP文件读取服务器最近在和一些做AI应用开发的朋友聊天大家普遍遇到一个头疼的问题如何让大语言模型LLM稳定、安全地读取本地文件系统里的各种文档无论是PDF报告、Word合同还是Excel表格、Markdown笔记直接让模型去“看”文件内容总绕不开权限、格式、路径这些琐碎但关键的细节。这正是Model Context ProtocolMCP要解决的核心痛点之一。MCP你可以把它理解为一套标准化的“翻译官”协议它定义了AI助手如Claude、Cursor等如何与外部工具和数据源进行安全、高效的对话。而这个“手把手教你实现一个MCP文件读取服务器”的项目就是让我们亲手打造这样一个“翻译官”。它不是一个简单的文件读取脚本而是一个遵循MCP标准、具备完整生命周期管理的后台服务。通过实现它你不仅能透彻理解MCP协议的工作机制——包括资源Resources的定义、工具Tools的注册、提示Prompts的构建更能掌握如何将协议规范落地为可运行的代码。无论是想为自己的AI助手增加一个可靠的“文件管家”还是想深入理解AI Agent与外部环境交互的底层逻辑这个项目都是一个绝佳的切入点。接下来我将以一个全栈开发者的视角带你从协议解读到代码实现完整走一遍构建过程并分享其中容易踩坑的细节。2. MCP协议核心概念与我们的服务器设计思路在动手写代码之前我们必须先吃透MCP协议的基本模型。MCP采用客户端-服务器架构但这里的“客户端”通常是AI助手或AI应用“服务器”则是我们即将实现的、提供特定能力如文件读取的后台服务。通信基于JSON-RPC 2.0 over stdio标准输入输出或SSE服务器发送事件这意味着我们的服务器需要持续监听标准输入并按要求向标准输出写入JSON-RPC响应。协议的核心抽象有三个它们构成了我们服务器的骨架2.1 资源Resources数据的静态视图资源代表一个可供读取的、带有元数据的实体比如一个文件。每个资源有唯一的uri如file:///path/to/doc.pdf、一个mimeType和可选的name、description。在我们的文件服务器里每一个被允许访问的文件或目录都将被建模为一个资源。关键点在于资源列表是通过listResources和readResource这两个标准方法暴露给客户端的客户端不能随意指定路径读取必须从服务器公布的资源列表中选择这构成了第一道安全屏障。2.2 工具Tools动态执行的操作工具代表服务器可以执行的动作每个工具都有名称、描述和输入参数的JSON Schema定义。对于文件读取服务器我们至少需要两个核心工具list_directory列出指定目录下的文件和子目录返回结构化的列表。read_file读取指定文件的文本内容。这里的设计考量是是否要支持二进制文件通常我们优先处理文本文件.txt,.md,.json等对于PDF、Word等可以在服务器内部集成解析库如pdfplumber,python-docx将内容转换为纯文本后再返回。2.3 提示Prompts预定义的交互模板提示是可重用的对话模板可以包含参数。对于文件服务器一个实用的提示可以是summarize_document它接收一个文件资源URI作为参数然后引导AI客户端去读取该文件并生成摘要。这展示了MCP如何将复杂操作封装成简单的指令。我们的服务器设计思路 基于以上概念我们的服务器将这样工作初始化服务器启动通过标准输入输出与客户端建立连接。握手交换初始化信息服务器宣告自己支持的能力即实现了哪些MCP方法。接收请求客户端调用listResources获取可访问的文件列表或调用list_directory工具进行浏览。处理与响应服务器根据请求执行相应的文件系统操作严格在预设的根目录下进行将结果封装成MCP协议规定的格式返回。安全边界所有文件操作必须限制在服务器启动时配置的根目录内防止目录遍历攻击。这是服务器可靠性的生命线。3. 开发环境搭建与项目初始化我们选择Python作为实现语言因为它有丰富的库支持和清晰的语法。确保你的Python版本在3.8以上。3.1 创建项目结构与虚拟环境首先创建一个干净的项目目录并初始化虚拟环境这是保持依赖隔离的好习惯。mkdir mcp-file-server cd mcp-file-server python -m venv venv # 激活虚拟环境 # 在Windows上: venv\Scripts\activate # 在Mac/Linux上: source venv/bin/activate接下来创建核心项目文件mcp-file-server/ ├── server.py # 服务器主程序 ├── mcp_protocol.py # MCP协议相关的数据模型和编解码 ├── file_handlers.py # 不同文件类型的读取处理器 ├── config.py # 配置文件如允许的根目录 ├── requirements.txt # 项目依赖 └── README.md3.2 安装核心依赖编辑requirements.txt加入以下依赖pydantic2.0.0 # 用于数据验证和模型定义处理协议数据结构非常顺手 pyyaml6.0 # 可选用于读取YAML格式的配置文件 pdfplumber0.10.0 # 用于提取PDF文本 python-docx1.1.0 # 用于读取Word文档然后安装它们pip install -r requirements.txt。注意关于依赖选择pydantic几乎是必选项它能极大简化JSON-RPC请求/响应的数据验证和序列化。对于文件解析库如果你确定只需要处理纯文本可以先不安装pdfplumber和python-docx保持服务器轻量。但考虑到实用性建议一并安装。3.3 配置安全根目录在config.py中我们定义服务器的基本配置最重要的是ALLOWED_ROOT_PATH。绝对不要使用用户输入的路径或相对路径“.”作为根目录必须使用配置的绝对路径。import os from pathlib import Path from typing import Optional class ServerConfig: # 使用环境变量或硬编码指定一个安全的根目录 # 例如 ALLOWED_ROOT Path(os.environ.get(MCP_FILE_ROOT, /safe/data)) ALLOWED_ROOT: Path Path(/Users/yourname/SafeDocuments) # 请修改为你的安全目录 # 是否允许列出隐藏文件以.开头的文件 SHOW_HIDDEN_FILES: bool False # 支持的文件扩展名及对应的MIME类型映射 SUPPORTED_EXTENSIONS: dict { .txt: text/plain, .md: text/markdown, .json: application/json, .pdf: application/pdf, .docx: application/vnd.openxmlformats-officedocument.wordprocessingml.document, } classmethod def is_path_safe(cls, user_path: str) - bool: 检查用户请求的路径是否在允许的根目录之下防止目录遍历攻击 try: requested_path (cls.ALLOWED_ROOT / user_path.lstrip(/)).resolve() # 关键安全校验解析后的路径必须以ALLOWED_ROOT开头 return str(requested_path).startswith(str(cls.ALLOWED_ROOT.resolve())) except Exception: return False这个is_path_safe函数是服务器的“守门员”任何来自客户端的文件路径请求都必须先通过这个函数的校验否则立即拒绝。4. 实现MCP协议层数据模型与JSON-RPC处理器MCP协议定义了一系列标准的请求和响应格式。我们需要用代码来定义它们。4.1 定义协议数据模型mcp_protocol.py使用Pydantic来定义数据结构能自动处理JSON序列化和验证。from pydantic import BaseModel, Field from typing import Any, Dict, List, Optional, Union from enum import Enum class JSONRPCRequest(BaseModel): jsonrpc: str 2.0 id: Optional[Union[int, str]] None method: str params: Optional[Union[Dict[str, Any], List[Any]]] None class JSONRPCResponse(BaseModel): jsonrpc: str 2.0 id: Optional[Union[int, str]] None result: Optional[Any] None error: Optional[Dict[str, Any]] None # MCP特定的模型 class Resource(BaseModel): 代表一个可读的资源如一个文件 uri: str # 例如: file:///path/to/file.md name: str mimeType: Optional[str] None description: Optional[str] None class Tool(BaseModel): 代表一个可调用的工具 name: str description: str inputSchema: Dict[str, Any] # JSON Schema class Prompt(BaseModel): 代表一个可重用的提示模板 name: str description: str arguments: Optional[List[Dict[str, Any]]] None这些模型对应了MCP协议中核心的数据结构。当客户端请求listResources时我们就返回一个Resource对象的列表。4.2 构建JSON-RPC请求路由器服务器需要解析从stdin来的JSON-RPC请求并根据method字段路由到对应的处理函数。 在server.py中我们创建核心的服务器类import sys import json import asyncio from typing import Dict, Callable, Any from mcp_protocol import JSONRPCRequest, JSONRPCResponse class MCPFileServer: def __init__(self): self.method_handlers: Dict[str, Callable] {} self._register_handlers() def _register_handlers(self): 注册MCP标准方法及自定义工具的处理函数 self.method_handlers[initialize] self._handle_initialize self.method_handlers[tools/list] self._handle_list_tools self.method_handlers[tools/call] self._handle_call_tool self.method_handlers[resources/list] self._handle_list_resources self.method_handlers[resources/read] self._handle_read_resource # 提示相关的方法可以后续添加 # self.method_handlers[prompts/list] ... async def _handle_initialize(self, params: Dict) - Dict: 处理初始化请求宣告服务器能力 return { protocolVersion: 2024-11-05, # 使用最新的协议版本 capabilities: { resources: {listChanged: False}, # 我们暂不实现资源变更通知 tools: {}, prompts: {} }, serverInfo: { name: mcp-file-server, version: 0.1.0 } } async def _handle_list_tools(self, params: Dict) - Dict: 返回服务器支持的工具列表 from .file_handlers import list_directory_tool, read_file_tool return { tools: [ list_directory_tool.dict(), # 假设我们已经定义了Tool对象 read_file_tool.dict() ] } async def _handle_call_tool(self, params: Dict) - Dict: 调用具体的工具 tool_name params.get(name) arguments params.get(arguments, {}) if tool_name list_directory: return await self._execute_list_directory(arguments) elif tool_name read_file: return await self._execute_read_file(arguments) else: raise ValueError(fUnknown tool: {tool_name}) async def _execute_list_directory(self, arguments: Dict) - Dict: # 具体实现见下一章 pass async def _execute_read_file(self, arguments: Dict) - Dict: # 具体实现见下一章 pass async def _handle_list_resources(self, params: Dict) - Dict: 列出可用的资源文件 # 可以将允许根目录下的文件映射为Resource对象返回 pass async def _handle_read_resource(self, params: Dict) - Dict: 读取指定URI的资源 # 根据resource.uri读取文件内容 pass async def process_request(self, request_data: str) - Optional[str]: 处理一个原始的JSON-RPC请求字符串 try: request_dict json.loads(request_data) request JSONRPCRequest(**request_dict) handler self.method_handlers.get(request.method) if not handler: # 返回方法未找到错误 error_response JSONRPCResponse( idrequest.id, error{code: -32601, message: fMethod not found: {request.method}} ).json() return error_response # 执行处理函数 result await handler(request.params or {}) response JSONRPCResponse(idrequest.id, resultresult).json() return response except json.JSONDecodeError: # 返回解析错误 return JSONRPCResponse( idNone, error{code: -32700, message: Parse error} ).json() except Exception as e: # 返回内部错误 return JSONRPCResponse( idgetattr(request, id, None), error{code: -32603, message: fInternal error: {str(e)}} ).json() async def run(self): 主循环从stdin读取处理向stdout写入 loop asyncio.get_event_loop() reader asyncio.StreamReader() protocol asyncio.StreamReaderProtocol(reader) await loop.connect_read_pipe(lambda: protocol, sys.stdin) # 简化处理实际中需要更健壮地处理行读取和消息边界 while True: line await reader.readline() if not line: break line line.decode().strip() if line: response await self.process_request(line) if response: sys.stdout.write(response \n) sys.stdout.flush()这个框架搭建起了服务器的通信骨架。它定义了如何接收请求、路由到对应的方法处理器并返回格式正确的响应。run方法中的主循环是服务器的核心它持续监听标准输入。这里使用了asyncio来处理潜在的I/O等待让服务器更高效。实操心得在实现协议层时最容易出错的地方是JSON-RPC响应格式。务必确保result和error字段是互斥的并且id必须与请求中的id严格对应。我建议在开发初期用一个简单的测试脚本模拟客户端发送请求来验证服务器的响应格式是否正确。5. 实现文件系统操作与工具逻辑协议层搭建好后我们来填充最核心的业务逻辑安全地浏览和读取文件。5.1 定义工具在file_handlers.py中首先我们定义要暴露给客户端的工具。from mcp_protocol import Tool from pydantic import BaseModel, Field from typing import Optional # 定义工具的输入参数模型 class ListDirectoryArgs(BaseModel): path: str Field(, description目录路径相对于服务器配置的根目录。默认为根目录。) show_hidden: Optional[bool] Field(False, description是否显示隐藏文件) class ReadFileArgs(BaseModel): file_path: str Field(..., description文件的相对路径) # 创建Tool对象 list_directory_tool Tool( namelist_directory, description列出指定目录下的文件和子目录。, inputSchemaListDirectoryArgs.schema() # Pydantic自动生成JSON Schema ) read_file_tool Tool( nameread_file, description读取指定文本文件的内容。支持.txt, .md, .json, .pdf, .docx等格式。, inputSchemaReadFileArgs.schema() )5.2 实现安全的目录列表功能在server.py的MCPFileServer类中实现_execute_list_directory方法。import os from pathlib import Path from config import ServerConfig class MCPFileServer: # ... 之前的代码 ... async def _execute_list_directory(self, arguments: Dict) - Dict: 执行list_directory工具 args ListDirectoryArgs(**arguments) request_path args.path.strip() # 1. 路径安全检查 if not ServerConfig.is_path_safe(request_path): return { content: [{ type: text, text: f错误路径 {request_path} 不在允许的访问范围内。 }] } # 2. 构建绝对路径 safe_root ServerConfig.ALLOWED_ROOT.resolve() target_dir (safe_root / request_path.lstrip(/)).resolve() # 3. 检查路径是否存在且为目录 if not target_dir.exists(): return {content: [{type: text, text: f错误目录 {request_path} 不存在。}]} if not target_dir.is_dir(): return {content: [{type: text, text: f错误{request_path} 不是一个目录。}]} # 4. 遍历目录 items [] try: for item in target_dir.iterdir(): # 过滤隐藏文件根据配置 if not ServerConfig.SHOW_HIDDEN_FILES and item.name.startswith(.): continue item_info { name: item.name, type: directory if item.is_dir() else file, size: item.stat().st_size if item.is_file() else 0, } # 如果是文件添加扩展名信息 if item.is_file(): item_info[extension] item.suffix.lower() items.append(item_info) except PermissionError: return {content: [{type: text, text: f错误没有权限读取目录 {request_path}。}]} # 5. 格式化输出 # MCP工具调用通常返回一个content数组其中包含文本或图像等内容。 dirs [f[DIR] {i[name]} for i in items if i[type] directory] files [f{i[name]} ({i[size]} bytes) for i in items if i[type] file] output_text f目录: {request_path or /}\n output_text ---\n if dirs: output_text 子目录:\n \n.join(dirs) \n---\n if files: output_text 文件:\n \n.join(files) return { content: [{ type: text, text: output_text }] }这个方法展示了完整的处理链条参数验证 - 安全校验 - 文件系统操作 - 结果格式化。返回的格式遵循了MCP工具调用的通用结构将结果放在content字段的文本块中。5.3 实现多格式文件读取功能这是服务器的核心价值所在。我们需要根据文件扩展名分派给不同的处理器。class MCPFileServer: # ... 之前的代码 ... async def _execute_read_file(self, arguments: Dict) - Dict: 执行read_file工具 args ReadFileArgs(**arguments) file_path args.file_path.strip() # 1. 安全校验 if not ServerConfig.is_path_safe(file_path): return { content: [{ type: text, text: f错误文件路径 {file_path} 访问被拒绝。 }] } safe_root ServerConfig.ALLOWED_ROOT.resolve() target_file (safe_root / file_path.lstrip(/)).resolve() # 2. 存在性及类型检查 if not target_file.exists(): return {content: [{type: text, text: f错误文件 {file_path} 不存在。}]} if not target_file.is_file(): return {content: [{type: text, text: f错误{file_path} 不是一个文件。}]} # 3. 根据扩展名选择处理器 ext target_file.suffix.lower() try: if ext in [.txt, .md, .json, .csv, .py, .js, .html]: # 文本文件直接读取 content self._read_text_file(target_file) elif ext .pdf: content self._read_pdf_file(target_file) elif ext in [.docx, .doc]: content self._read_docx_file(target_file) else: # 不支持的文件类型 return { content: [{ type: text, text: f错误不支持读取 {ext} 格式的文件。当前支持: {, .join(ServerConfig.SUPPORTED_EXTENSIONS.keys())} }] } except Exception as e: return { content: [{ type: text, text: f读取文件时发生错误: {str(e)} }] } # 4. 返回结果 # 注意MCP协议中readResource要求返回特定的结构但工具调用返回相对自由。 # 这里我们返回一个清晰的文本块。 return { content: [{ type: text, text: f文件内容 ({target_file.name}):\n---\n{content}\n---\n[文件大小: {target_file.stat().st_size} 字节] }] } def _read_text_file(self, file_path: Path) - str: 读取纯文本文件尝试多种编码 encodings [utf-8, gbk, latin-1] for encoding in encodings: try: return file_path.read_text(encodingencoding) except UnicodeDecodeError: continue # 如果所有编码都失败尝试以二进制读取并忽略错误 return file_path.read_bytes().decode(utf-8, errorsignore) def _read_pdf_file(self, file_path: Path) - str: 使用pdfplumber提取PDF文本 import pdfplumber full_text [] with pdfplumber.open(file_path) as pdf: for page in pdf.pages: text page.extract_text() if text: full_text.append(text) return \n.join(full_text) def _read_docx_file(self, file_path: Path) - str: 使用python-docx读取Word文档 from docx import Document doc Document(file_path) full_text [] for para in doc.paragraphs: full_text.append(para.text) return \n.join(full_text)注意事项文件编码是文本读取的一大坑。我们采用了常见的编码列表进行尝试最后有一个兜底策略。对于生产环境你可能需要更复杂的编码检测库如chardet。另外PDF和Word解析库可能对文件格式有要求复杂的排版或加密文件可能解析失败务必在返回结果中做好错误处理给用户明确的提示。6. 实现资源Resources列表与读取除了通过工具动态交互MCP还允许服务器静态地公布一批资源。这适用于那些固定的、已知重要的文件。6.1 实现listResources方法在_handle_list_resources方法中我们可以遍历根目录将特定类型的文件发布为资源。async def _handle_list_resources(self, params: Dict) - Dict: 列出所有支持的、可公开访问的文件资源 from mcp_protocol import Resource resources [] safe_root ServerConfig.ALLOWED_ROOT.resolve() # 递归遍历安全根目录寻找支持的文件 # 注意对于大型目录树这里可能需要优化或分页。 for ext, mime_type in ServerConfig.SUPPORTED_EXTENSIONS.items(): for file_path in safe_root.rglob(f*{ext}): if file_path.is_file(): # 再次进行安全校验虽然理论上都在根目录下 rel_path file_path.relative_to(safe_root) uri ffile://{file_path} resources.append( Resource( uriuri, namefile_path.name, mimeTypemime_type, descriptionf位于 {rel_path} ) ) return {resources: [r.dict() for r in resources]}6.2 实现readResource方法当客户端通过资源URI请求内容时我们需要解析URI并返回内容。async def _handle_read_resource(self, params: Dict) - Dict: 读取指定URI的资源内容 uri params.get(uri, ) if not uri.startswith(file://): return { contents: [{ type: text, text: f错误不支持的URI协议。仅支持 file:// }] } # 从 file:// 路径中提取本地文件路径 # 注意这里需要移除 file://并处理可能的URL编码 import urllib.parse file_path_str urllib.parse.unquote(uri[7:]) # 去掉file:// file_path Path(file_path_str) # 关键必须验证该路径是否在我们的安全根目录下 if not ServerConfig.is_path_safe(str(file_path.relative_to(ServerConfig.ALLOWED_ROOT) if file_path.is_relative_to(ServerConfig.ALLOWED_ROOT) else )): return { contents: [{ type: text, text: 错误无权访问该资源。 }] } # 使用之前实现的文件读取逻辑 # 这里可以复用 _execute_read_file 中的核心读取代码 try: ext file_path.suffix.lower() if ext in [.txt, .md, .json]: content self._read_text_file(file_path) mime_type text/plain elif ext .pdf: content self._read_pdf_file(file_path) mime_type application/pdf elif ext in [.docx, .doc]: content self._read_docx_file(file_path) mime_type application/vnd.openxmlformats-officedocument.wordprocessingml.document else: content fUnsupported file type: {ext} mime_type text/plain return { contents: [{ type: text, text: content }], mimeType: mime_type } except Exception as e: return { contents: [{ type: text, text: f读取资源失败: {str(e)} }] }注意readResource的返回格式与工具调用略有不同它要求返回contents和mimeType字段。同时资源读取的安全校验同样至关重要必须确保请求的URI对应的文件在允许的根目录之下。7. 服务器集成、测试与问题排查7.1 编写主入口并集成创建一个main.py或完善server.py的__main__部分将一切串联起来。# 在 server.py 末尾添加 if __name__ __main__: import asyncio server MCPFileServer() # 检查根目录是否存在 if not ServerConfig.ALLOWED_ROOT.exists(): print(f错误配置的根目录 {ServerConfig.ALLOWED_ROOT} 不存在。, filesys.stderr) sys.exit(1) print(fMCP文件读取服务器启动根目录: {ServerConfig.ALLOWED_ROOT}, filesys.stderr) try: asyncio.run(server.run()) except KeyboardInterrupt: print(\n服务器已停止。, filesys.stderr)服务器设计为通过标准输入输出通信这意味着它通常由AI助手客户端作为子进程启动。7.2 使用标准输入输出进行手动测试在开发过程中我们可以手动模拟客户端进行测试。创建一个测试脚本test_client.pyimport subprocess import json import time # 启动服务器进程 proc subprocess.Popen( [python, server.py], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue ) def send_request(method, paramsNone, req_id1): request { jsonrpc: 2.0, id: req_id, method: method, params: params or {} } proc.stdin.write(json.dumps(request) \n) proc.stdin.flush() # 读取响应 line proc.stdout.readline() return json.loads(line.strip()) # 1. 初始化 init_resp send_request(initialize) print(初始化响应:, init_resp) # 2. 列出工具 tools_resp send_request(tools/list) print(工具列表:, json.dumps(tools_resp, indent2)) # 3. 调用 list_directory 工具 list_resp send_request(tools/call, { name: list_directory, arguments: {path: } }, req_id3) print(列出根目录结果:, list_resp.get(result, {}).get(content, [{}])[0].get(text, )[:200]) # 截取部分 # 4. 调用 read_file 工具 read_resp send_request(tools/call, { name: read_file, arguments: {file_path: README.md} # 假设根目录下有这个文件 }, req_id4) result_content read_resp.get(result, {}).get(content, [{}]) if result_content: print(读取文件结果预览:, result_content[0].get(text, )[:300]) proc.terminate()这个脚本能帮你验证服务器的基础功能是否正常。7.3 常见问题与排查技巧实录在实际搭建和运行中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案服务器启动后立即退出无错误信息。1. 根目录配置错误或不存在。2. 依赖库未正确安装。1. 检查config.py中的ALLOWED_ROOT路径确保存在且有读取权限。2. 运行pip list确认pydantic,pdfplumber等已安装。在服务器启动代码开头添加print语句或使用logging模块输出日志到stderr。客户端连接后调用工具无响应或返回“Method not found”。1. 工具名称在method_handlers字典中注册有误。2. JSON-RPC请求的method字段格式不对。MCP工具调用对应tools/call。1. 检查_register_handlers方法中的键名是否与客户端发送的method完全一致注意大小写。2. 打印收到的原始请求print(request_data, filesys.stderr)确认method是tools/call而不是read_file。工具名在params.name里。读取中文文本文件出现乱码。文件编码不是UTF-8。1. 在_read_text_file方法中增加更多编码尝试如gb2312, big5。2. 使用chardet库动态检测编码import chardet; raw file_path.read_bytes(); encoding chardet.detect(raw)[encoding]。读取PDF返回空内容。1. PDF是扫描件图片无嵌入式文本。2. PDF使用了特殊字体或加密。1. 对于扫描件需要考虑集成OCR功能如pytesseract但这会大幅增加复杂度。2. 使用pdfplumber的extract_text(x_tolerance2)调整参数或尝试pdfminer库。对于加密PDF目前我们的服务器不支持应返回友好错误。路径安全校验误判合法请求被拒绝。is_path_safe函数中的路径解析逻辑有缺陷例如处理符号链接symlink时。1. 使用Path.resolve()解析所有符号链接为绝对路径后再进行比较。2. 在安全校验前后打印路径进行调试print(fRequested: {user_path}, Resolved: {requested_path}, Root: {cls.ALLOWED_ROOT.resolve()})。服务器进程卡住不响应。1. 主循环readline()阻塞。2. 某个文件操作如读取超大文件耗时过长阻塞了事件循环。1. 确保使用asyncio异步处理I/O对于可能耗时的文件读取使用asyncio.to_thread将其放到线程池中执行避免阻塞主循环。2. 为工具调用设置超时机制。7.4 与AI助手如Claude Desktop集成最终我们的服务器需要被AI客户端调用。以Claude Desktop为例通常需要在其配置文件中添加我们的服务器信息。创建一个配置文件claude_desktop_config.json路径因系统而异{ mcpServers: { my-file-server: { command: python, args: [/absolute/path/to/your/mcp-file-server/server.py], env: { MCP_FILE_ROOT: /absolute/path/to/your/safe/documents } } } }重启Claude Desktop后你应该能在助手的工具列表中看到list_directory和read_file并可以与之交互了。8. 性能优化与扩展方向一个基础的服务器完成后我们可以从以下几个方向让它变得更强大、更可靠8.1 性能优化资源列表缓存listResources遍历整个目录树可能很慢。可以为资源列表添加缓存并监听目录变化使用watchdog库来使缓存失效。大文件分块读取对于巨大的文本文件一次性读入内存可能导致问题。可以实现流式读取或分块返回在readResource或read_file工具中支持offset和limit参数。异步文件I/O使用aiofiles库替代同步的file.read()操作让服务器在等待磁盘I/O时能处理其他请求。8.2 功能扩展更多文件格式集成openpyxl处理ExcelPIL或opencv处理图像并提取文字OCRemail库处理.eml文件等。搜索工具添加一个search_in_files工具允许客户端在指定目录下的文件中搜索关键词这能极大提升AI助手的资料检索能力。写操作谨慎在严格的安全管控下可以添加write_file或create_note工具让AI助手能够创建或修改文件。这需要极其严格的权限控制和操作确认机制。资源变更通知实现MCP的resources/listChanged能力当监控目录下的文件被增删改时主动通知客户端保持上下文新鲜。8.3 安全加固配置化黑白名单除了根目录限制还可以通过配置文件指定允许或禁止访问的特定子目录、文件模式如*.tmp。请求频率限制防止客户端恶意频繁调用工具消耗服务器资源。更精细的权限模型为不同的文件或目录设置只读、可列表等不同权限级别。实现一个MCP文件读取服务器的过程本质上是在定义AI与真实世界数据之间安全、可控的交互边界。从协议理解到安全校验从工具定义到错误处理每一步都需要仔细考量。这个项目不仅让你获得了一个实用的工具更重要的是它为你打开了构建更复杂MCP服务器如数据库查询服务器、API网关服务器的大门。当你看到AI助手能流畅地浏览、总结你本地文档库里的内容时那种亲手搭建桥梁的成就感就是对这个项目最好的回报。