1. 项目概述为什么我们需要一个能读本地文件的MCP服务最近在折腾AI应用开发特别是想把手头的本地数据喂给大模型时遇到了一个挺普遍的问题很多AI助手或应用框架比如基于Claude的它们默认的“活动范围”被限制在云端或沙箱里没法直接访问我电脑上的文档、代码库或者数据库。这就好比请了一个知识渊博的管家却把他锁在书房门外不让他进去查阅资料。为了解决这个“最后一公里”的数据接入问题我决定动手写一个极简的MCPModel Context Protocol服务。MCP你可以把它理解为一套标准化的“插件协议”。它定义了大模型或AI应用与外部工具、数据源之间如何安全、规范地通信。通过实现一个MCP服务就相当于为AI打造了一个专属的、可控的“手”和“眼”让它能按指令去读取我指定的本地文件内容并将结果结构化地返回。这个项目不追求功能大而全核心目标就一个用最少的代码跑通一个能安全读取本地文本文件的MCP服务端并成功集成到像Claude Desktop这样的客户端中。对于任何想将本地数据与AI能力结合的开发者来说这都是一个非常实用且必要的起点。2. MCP核心概念与项目设计思路在撸起袖子写代码之前我们得先搞清楚MCP到底是怎么一回事以及我们这个“文件阅读器”服务在整个体系里扮演什么角色。2.1 MCP协议的三层架构与核心组件MCP协议的设计很清晰主要包含三个角色客户端Client通常是最终用户交互的界面比如Claude Desktop、Cursor IDE或者你自己写的AI应用。它负责向服务器发起请求。服务器Server就是我们这次要构建的东西。它提供具体的“能力”比如读文件、查数据库、调用API。服务器向客户端宣告自己有哪些工具Tools可用。传输层Transport负责在客户端和服务器之间传递消息。常见的有stdio标准输入输出用于本地进程和SSEServer-Sent Events用于网络。我们这次用最简单的stdio。协议的核心是围绕“工具Tools”和“资源Resources”展开的。工具代表可执行的操作如read_file资源代表可访问的数据实体如file:///path/to/doc.txt。我们的服务主要实现工具。2.2 极简文件阅读器的设计蓝图基于“极简”和“实战”的目标我的设计思路如下功能聚焦只实现一个核心工具——read_file。输入是文件路径输出是文件内容。其他如列出目录、写入文件等功能一概不做保持核心路径最短。安全第一绝对不能允许服务随意读取整个磁盘。必须通过明确的配置限定服务可以访问的目录范围即“根目录”。任何试图访问此范围外的文件的请求都应被立即拒绝。协议兼容严格遵循MCP协议定义的消息格式JSON-RPC进行通信。确保我们的服务能与标准的MCP客户端如Claude Desktop无缝对接。语言选择选用Python。原因很简单生态好有现成的MCP SDK开发快适合快速原型验证。当然你用Node.js、Go甚至Rust来实现协议本身都是通用的。开发流程先实现一个能跑通的独立服务再配置Claude Desktop进行集成测试最后总结调试技巧和避坑指南。这个设计确保了项目目标明确、边界清晰我们能集中火力攻克从零到一的关键环节。3. 环境准备与核心依赖解析工欲善其事必先利其器。我们不需要复杂的框架几个核心库就足够了。3.1 创建项目与虚拟环境首先避免污染全局Python环境使用虚拟环境是最佳实践。# 创建项目目录 mkdir mcp-file-reader cd mcp-file-reader # 创建虚拟环境这里使用venv你也可以用conda python -m venv .venv # 激活虚拟环境 # Windows: .venv\Scripts\activate # Linux/Mac: source .venv/bin/activate激活后命令行提示符前通常会显示(.venv)表示你已经在虚拟环境中了。3.2 安装MCP SDK与其他依赖MCP协议的核心是JSON-RPC消息的收发和处理。虽然我们可以完全手搓这些JSON但使用官方或社区维护的SDK能极大提升开发效率避免低级错误。这里我们使用mcp这个Python库它提供了构建MCP服务器和客户端的底层支持。同时我们也会用到pydantic来做数据验证和序列化让代码更健壮。pip install mcp pydantic为什么是这几个库mcp这是构建MCP服务的核心。它封装了协议细节让我们可以专注于工具和资源的逻辑实现而不是JSON解析和状态管理。pydantic在定义工具输入参数时它能提供强大的类型检查和数据验证。比如确保传入的路径是字符串并且我们可以自定义验证逻辑来检查路径是否在允许的范围内。这比手动写一堆if语句要优雅和可靠得多。安装完成后可以创建一个requirements.txt文件来固化依赖pip freeze requirements.txt。4. 极简MCP服务端代码实现现在进入核心环节我们将一步步构建出服务端。我会把代码拆解成块并解释每一部分的意图和关键点。4.1 定义工具输入参数模型首先我们需要定义read_file工具接受的参数。使用Pydantic模型能确保传入的数据符合预期格式。# server.py from typing import Any from pydantic import BaseModel, Field, field_validator from pathlib import Path import os class ReadFileArgs(BaseModel): 读取文件的参数模型 path: str Field(description要读取的文件的路径相对于配置的根目录。) field_validator(path) classmethod def validate_path(cls, v: str) - str: # 基础校验路径不能为空且不能是绝对路径我们期望相对路径 if not v: raise ValueError(文件路径不能为空) # 防止目录遍历攻击检查路径中是否包含.. if .. in v: raise ValueError(路径中不允许包含父目录引用..) # 这里可以添加更多清洗逻辑比如去除开头的斜杠 v v.lstrip(/) return v关键点解析我们定义了一个ReadFileArgs类它只有一个字段path描述为文件路径。field_validator(path)装饰器用于自定义验证逻辑。这里我们做了两件事检查路径是否为空。安全检查禁止路径中包含..。这是防止目录遍历攻击Path Traversal的关键一步攻击者可能通过../../../etc/passwd这样的路径试图访问系统文件。虽然我们后续还有根目录限制但在这里加一道防线是很好的习惯。v v.lstrip(/)是为了处理可能以/开头的路径将其统一为相对路径格式。4.2 实现服务器类与工具函数接下来我们创建MCP服务器类并实现read_file工具函数。# server.py (续) from mcp.server import Server from mcp.server.models import Tool import mcp.server.stdio import mcp.types as types class FileReaderServer: def __init__(self, root_dir: str): # 初始化MCP服务器实例 self.server Server(local-file-reader) # 将允许访问的根目录转换为Path对象并解析为绝对路径 self.root_dir Path(root_dir).expanduser().resolve() # 确保根目录存在且是一个目录 if not self.root_dir.exists(): raise ValueError(f配置的根目录不存在: {self.root_dir}) if not self.root_dir.is_dir(): raise ValueError(f配置的根目录不是一个目录: {self.root_dir}) # 向服务器注册我们提供的工具 self.server.list_tools().add_handler(self.list_tools) self.server.call_tool().add_handler(self.call_tool) async def list_tools(self) - list[types.Tool]: 返回服务器提供的工具列表 return [ Tool( nameread_file, description读取指定文本文件的内容。, inputSchema{ type: object, properties: { path: {type: string, description: 相对于根目录的文件路径。} }, required: [path] } ) ] async def call_tool(self, name: str, arguments: dict[str, Any]) - list[types.TextContent]: 处理工具调用请求 if name ! read_file: # 理论上list_tools里只有read_file但这里还是做一下防御性检查 raise ValueError(f未知工具: {name}) # 1. 验证和解析参数 args ReadFileArgs(**arguments) # 2. 构建绝对路径并确保其在根目录内 requested_path (self.root_dir / args.path).resolve() # 关键安全校验请求的路径是否在允许的根目录之下 try: # 使用commonpath检查比字符串前缀比较更可靠 requested_path.relative_to(self.root_dir) except ValueError: # 如果抛出ValueError说明requested_path不是self.root_dir的子路径 raise PermissionError(f拒绝访问路径 {args.path} 超出了允许的根目录范围。) # 3. 检查文件是否存在且是普通文件 if not requested_path.exists(): raise FileNotFoundError(f文件不存在: {requested_path}) if not requested_path.is_file(): raise ValueError(f路径不是一个文件: {requested_path}) # 4. 读取文件内容 # 这里先假设是文本文件用UTF-8编码。实际项目中可能需要处理编码探测或二进制文件。 try: content requested_path.read_text(encodingutf-8) except UnicodeDecodeError: # 如果UTF-8解码失败可以尝试其他编码或返回错误 raise ValueError(f文件无法以UTF-8编码读取可能不是文本文件: {requested_path}) # 5. 按照MCP协议返回结果 return [types.TextContent(typetext, textcontent)] async def run(self): 启动服务器使用stdio传输 async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await self.server.run(read_stream, write_stream, self.server.create_initialization_options())代码逐段解读与避坑指南初始化与根目录设置(__init__)self.root_dir Path(root_dir).expanduser().resolve()这一行做了三件事。expanduser()将~展开为用户家目录resolve()获取绝对路径并消除任何符号链接。这是必须的它确保了后续路径比较的准确性。如果不做resolve()符号链接可能会导致安全校验绕过。紧接着检查根目录是否存在且为目录。这是对配置的预先验证避免服务器启动后才发现路径错误。工具列表声明(list_tools)返回一个Tool对象列表。这里我们只声明一个工具。inputSchema严格按照JSON Schema格式定义这决定了客户端如Claude如何生成调用界面。required字段指明path是必填参数。工具调用处理(call_tool)这是核心逻辑。参数验证args ReadFileArgs(**arguments)这行代码利用Pydantic自动完成了类型转换和我们在模型中定义的验证如检查..。安全校验重中之重requested_path (self.root_dir / args.path).resolve() requested_path.relative_to(self.root_dir)第一行将相对路径与根目录拼接并再次resolve()。注意args.path是已经过清洗去除了..和开头的/的相对路径。第二行Path.relative_to()方法会检查requested_path是否以self.root_dir为起始路径。如果不是则抛出ValueError。这种方法比检查字符串前缀str.startswith更安全可靠因为它处理了路径解析和大小写在区分大小写的系统上等问题。文件状态检查在读取前确认文件存在且是普通文件避免对目录或特殊文件进行误操作。文件读取使用read_text(encodingutf-8)。这里是一个简化处理。在实际应用中你可能会遇到不同编码的文件如GBK。更健壮的做法可以尝试多种编码或者通过chardet库探测编码但对于极简版明确约定为UTF-8并处理解码错误是可以接受的。返回结果MCP协议要求工具调用返回一个Content列表。这里我们返回TextContent类型为text。运行入口(run)使用mcp.server.stdio.stdio_server()创建标准输入输出流然后交给server的run方法。这是MCP SDK提供的标准启动方式。4.3 主程序入口与配置最后我们需要一个主函数来启动这一切并处理根目录的配置。# server.py (续) import asyncio import sys async def main(): # 从命令行参数或环境变量获取根目录。这里简单处理优先取命令行参数。 if len(sys.argv) 1: root_dir sys.argv[1] else: # 如果没有提供参数默认使用当前用户的家目录下的一个特定文件夹降低风险。 # 例如创建一个 ~/mcp_shared 目录来存放允许被读取的文件。 default_dir Path.home() / mcp_shared default_dir.mkdir(exist_okTrue) # 如果目录不存在则创建 root_dir str(default_dir) print(f未指定根目录使用默认目录: {root_dir}, filesys.stderr) try: server FileReaderServer(root_dir) print(fMCP 文件阅读器服务已启动根目录: {root_dir}, filesys.stderr) print(服务正在运行... (按 CtrlC 停止), filesys.stderr) await server.run() except Exception as e: print(f启动服务器失败: {e}, filesys.stderr) sys.exit(1) if __name__ __main__: asyncio.run(main())配置策略说明根目录通过命令行参数传入提供了灵活性。例如python server.py /path/to/your/data。如果没有提供参数我们没有默认使用当前目录(.)或根目录(/)而是指向用户家目录下的一个特定子目录~/mcp_shared。这是一个重要的安全实践最小权限原则。默认情况下服务只能访问一个明确创建的、意图用于共享的空白目录最大程度减少了误配置导致的安全风险。我们甚至主动创建这个目录mkdir(exist_okTrue)。错误信息输出到stderr因为MCP协议通信使用stdout避免日志污染了协议消息。至此一个功能完整、具备基础安全防护的MCP文件阅读器服务端就完成了。你可以通过python server.py /your/allowed/path来运行它。运行后它会等待来自stdin的MCP协议消息。5. 配置Claude Desktop进行集成测试服务端跑起来只是成功了一半我们需要一个客户端来真正使用它。Claude Desktop是Anthropic官方提供的客户端它内置了MCP客户端功能非常适合做集成测试。5.1 定位Claude Desktop配置文件Claude Desktop的配置通常位于用户配置目录下。macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在可以手动创建。5.2 编写MCP服务器配置我们需要编辑上述配置文件告诉Claude Desktop如何启动我们的服务。配置内容是一个JSON对象。{ mcpServers: { local-file-reader: { command: python, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-reader/server.py, /ABSOLUTE/PATH/TO/YOUR/ALLOWED/DIRECTORY ], env: { PYTHONPATH: /ABSOLUTE/PATH/TO/YOUR/mcp-file-reader } } } }配置详解与避坑指南command: 这里是python。这意味着Claude Desktop会尝试在系统环境变量中寻找python命令。强烈建议你使用虚拟环境中的Python解释器的绝对路径来避免依赖问题。例如如果你的虚拟环境在项目目录.venv下那么在macOS/Linux上可能是/ABSOLUTE/PATH/TO/mcp-file-reader/.venv/bin/python在Windows上是C:\\ABSOLUTE\\PATH\\TO\\mcp-file-reader\\.venv\\Scripts\\python.exe。这是集成测试中最常见的坑之一。args: 第一个参数是我们的脚本绝对路径第二个是允许读取的根目录绝对路径。所有路径都必须是绝对路径因为Claude Desktop启动子进程时工作目录可能是不确定的。env(可选但推荐): 设置PYTHONPATH环境变量确保我们的脚本能找到mcp等依赖库如果它们没有安装在虚拟环境的默认搜索路径中但通常安装在虚拟环境site-packages里就够了。更稳妥的做法是确保command指向的Python解释器来自已经安装了所有依赖的虚拟环境。一个更健壮的配置示例macOS/Linux{ mcpServers: { local-file-reader: { command: /Users/yourname/projects/mcp-file-reader/.venv/bin/python, args: [ /Users/yourname/projects/mcp-file-reader/server.py, /Users/yourname/Documents/ai_data ] } } }5.3 测试与验证保存配置编辑好claude_desktop_config.json后保存。重启Claude Desktop完全退出并重新启动Claude Desktop应用以确保它加载新的配置。观察日志启动Claude Desktop时你可以打开它的开发者工具通常Help菜单里有查看日志。如果配置正确你会看到它尝试启动local-file-reader服务器的日志。如果启动失败日志里会有详细的错误信息这是排查问题的第一现场。在对话中测试新建一个对话尝试让Claude读取文件。例如你可以说“请使用read_file工具读取一下my_note.txt的内容。” 如果一切正常Claude会识别到这个工具并调用它。你可以在它生成的思考过程中看到工具调用的请求和返回的文件内容。注意首次配置时Claude Desktop可能会提示你“允许外部服务器运行”需要你点击确认授权。这是其安全机制的一部分。6. 开发调试与常见问题全记录在实际操作中你几乎一定会遇到各种问题。下面是我在开发和测试过程中踩过的坑和总结的排查方法。6.1 独立测试服务器脱离客户端的快速验证在集成到Claude Desktop之前最好先能独立验证服务器的基本功能。我们可以写一个极简的客户端脚本或者使用ncnetcat进行手动测试。但更简单的方法是直接运行服务器然后通过标准输入手动发送MCP协议消息。不过手动构造JSON-RPC消息很麻烦。推荐使用MCP SDK自带的测试工具或编写一个测试客户端。这里提供一个非常简单的测试脚本它模拟客户端初始化并调用一次工具# test_client.py import asyncio import json import sys import subprocess from pathlib import Path async def test_server(): # 启动服务器子进程 server_script Path(__file__).parent / server.py root_dir Path.home() / mcp_shared # 在测试目录下放一个测试文件 test_file root_dir / test.txt test_file.write_text(Hello, MCP! This is a test file.\n第二行内容。) proc await asyncio.create_subprocess_exec( sys.executable, str(server_script), str(root_dir), stdinasyncio.subprocess.PIPE, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, ) # 发送初始化请求 init_request { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 0.1.0, capabilities: {}, clientInfo: {name: test-client, version: 1.0} } } proc.stdin.write((json.dumps(init_request) \n).encode()) await proc.stdin.drain() # 读取初始化响应略过实际需要解析 # ... # 发送工具调用请求 tool_request { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: read_file, arguments: {path: test.txt} } } proc.stdin.write((json.dumps(tool_request) \n).encode()) await proc.stdin.drain() # 读取并打印响应 while True: line await proc.stdout.readline() if not line: break response json.loads(line.decode().strip()) if response.get(id) 2: result response.get(result, {}) content result.get(content, [{}])[0] print(读取到的内容:, content.get(text, No text found)) break # 清理 proc.terminate() await proc.wait() if __name__ __main__: asyncio.run(test_server())这个脚本能帮你确认服务器逻辑是否正确而不需要依赖完整的客户端环境。6.2 Claude Desktop集成问题排查清单当Claude Desktop无法正常使用你的工具时可以按照以下清单逐步排查问题现象可能原因排查步骤与解决方案Claude完全“不知道”有工具1. 配置文件路径错误。2. 配置文件格式错误JSON语法。3. Claude Desktop未重启。1. 确认配置文件在正确的操作系统路径下。2. 使用JSON验证工具如jq或在线校验器检查配置文件。3. 彻底退出并重启Claude Desktop。Claude识别到工具但调用失败日志显示“Server exited”或启动错误1.command路径错误。2. Python依赖未安装。3. 服务器脚本本身有语法错误或启动时抛出异常。1.检查command确保指向的Python解释器路径绝对正确且可执行。这是最高频的错误点。使用虚拟环境Python的绝对路径。2.检查依赖在虚拟环境中运行pip list确认mcp和pydantic已安装。3.独立运行服务器在终端用配置中的命令手动执行一次看是否有错误输出。例如/path/to/python /path/to/server.py /data/dir。工具调用后返回“权限错误”或“文件未找到”1. 配置的根目录(args中的第二个参数)路径错误或不存在。2. 请求的文件路径相对于根目录不正确。3. 服务器安全校验阻止。1. 确认根目录存在且服务器有读取权限。2. 在服务器日志中查看它接收到的具体path参数和解析后的绝对路径。3. 检查服务器代码中的安全校验逻辑relative_to部分是否过于严格。工具调用超时或无响应1. 服务器进程卡死或崩溃。2. 读取的文件非常大。3. 协议消息格式错误导致通信中断。1. 查看Claude Desktop日志或系统进程管理器确认服务器进程是否在运行。2. 在服务器代码中为文件读取添加超时或分块读取逻辑对于极简版先确保能处理小文件。3. 使用上面的test_client.py或打印调试信息检查服务器发出的JSON-RPC响应格式是否正确。中文字符显示乱码文件编码非UTF-8而服务器固定用UTF-8读取。1. 确保待读取的文件是UTF-8编码。2. 或者修改服务器代码尝试通用编码如utf-8-sig或使用chardet探测编码。content requested_path.read_text(encodingutf-8-sig)可以处理带BOM的UTF-8。一个关键的调试技巧查看Claude Desktop日志。在macOS上你可以通过运行Console.app在左侧选择你的设备然后在右上角搜索“Claude”来查看系统日志。更直接的方式是在Claude Desktop应用内通过菜单栏的“Help” - “Toggle Developer Tools”打开开发者工具在“Console”标签页里会看到详细的MCP服务器启动和通信日志任何错误信息都会在这里显示这是定位问题的金钥匙。6.3 安全性强化考量我们当前的实现已经包含了基础的安全措施根目录限制、路径遍历防护。对于生产环境或更敏感的数据还可以考虑更细粒度的访问控制除了目录还可以通过配置文件定义允许读取的文件扩展名如只允许.txt,.md,.json。请求频率限制防止被恶意频繁调用耗尽资源。内容过滤在返回内容前可以检查是否包含某些敏感模式如密钥、令牌并进行脱敏处理。但这需要权衡可能会影响性能和数据完整性。使用SSE传输并添加认证对于网络部署stdio传输不合适。可以改用SSEServer-Sent Events传输并在服务器端实现简单的API密钥认证。对于个人开发环境我们目前的安全设计已经足够。核心原则始终是最小权限默认拒绝。7. 项目总结与扩展方向通过这个项目我们完整地走通了一个MCP服务从设计、编码、配置到调试的全流程。这个“极简”服务虽然只做了一个read_file功能但它像一把钥匙打开了将本地私有数据与AI能力安全连接的大门。我个人在实操中最深的体会是配置与调试环节往往比编码更耗时。尤其是确保Claude Desktop能正确启动子进程路径和依赖问题必须反复确认。养成先独立测试服务器逻辑再集成到客户端的好习惯能节省大量时间。这个服务可以作为一个坚实的起点向多个方向扩展支持更多文件操作实现write_file写入、list_directory列出目录、search_files搜索等工具构建一个简单的文件管理套件。支持二进制文件或特定格式例如读取图片并返回base64编码或者解析PDF、Word文档提取文本。连接数据库实现query_database工具让AI能直接查询你的SQLite、MySQL或PostgreSQL数据库务必注意SQL注入防护。封装外部API将一些需要认证的第三方API如GitHub、Jira、Slack封装成MCP工具让AI在对话中帮你查询信息或执行操作。部署为网络服务将当前的stdio服务器改造成一个HTTP/SSE服务器这样任何支持MCP协议的客户端不限于Claude Desktop都可以通过网络连接使用它实现跨设备的数据共享。最后一个小技巧在开发过程中善用Python的logging模块替代print可以更方便地控制日志级别和输出目的地将调试信息输出到stderr而将协议信息保留给stdout这样在排查问题时日志会更清晰。 基于MCP协议构建本地文件读取服务：打通AI与私有数据的安全桥梁
1. 项目概述为什么我们需要一个能读本地文件的MCP服务最近在折腾AI应用开发特别是想把手头的本地数据喂给大模型时遇到了一个挺普遍的问题很多AI助手或应用框架比如基于Claude的它们默认的“活动范围”被限制在云端或沙箱里没法直接访问我电脑上的文档、代码库或者数据库。这就好比请了一个知识渊博的管家却把他锁在书房门外不让他进去查阅资料。为了解决这个“最后一公里”的数据接入问题我决定动手写一个极简的MCPModel Context Protocol服务。MCP你可以把它理解为一套标准化的“插件协议”。它定义了大模型或AI应用与外部工具、数据源之间如何安全、规范地通信。通过实现一个MCP服务就相当于为AI打造了一个专属的、可控的“手”和“眼”让它能按指令去读取我指定的本地文件内容并将结果结构化地返回。这个项目不追求功能大而全核心目标就一个用最少的代码跑通一个能安全读取本地文本文件的MCP服务端并成功集成到像Claude Desktop这样的客户端中。对于任何想将本地数据与AI能力结合的开发者来说这都是一个非常实用且必要的起点。2. MCP核心概念与项目设计思路在撸起袖子写代码之前我们得先搞清楚MCP到底是怎么一回事以及我们这个“文件阅读器”服务在整个体系里扮演什么角色。2.1 MCP协议的三层架构与核心组件MCP协议的设计很清晰主要包含三个角色客户端Client通常是最终用户交互的界面比如Claude Desktop、Cursor IDE或者你自己写的AI应用。它负责向服务器发起请求。服务器Server就是我们这次要构建的东西。它提供具体的“能力”比如读文件、查数据库、调用API。服务器向客户端宣告自己有哪些工具Tools可用。传输层Transport负责在客户端和服务器之间传递消息。常见的有stdio标准输入输出用于本地进程和SSEServer-Sent Events用于网络。我们这次用最简单的stdio。协议的核心是围绕“工具Tools”和“资源Resources”展开的。工具代表可执行的操作如read_file资源代表可访问的数据实体如file:///path/to/doc.txt。我们的服务主要实现工具。2.2 极简文件阅读器的设计蓝图基于“极简”和“实战”的目标我的设计思路如下功能聚焦只实现一个核心工具——read_file。输入是文件路径输出是文件内容。其他如列出目录、写入文件等功能一概不做保持核心路径最短。安全第一绝对不能允许服务随意读取整个磁盘。必须通过明确的配置限定服务可以访问的目录范围即“根目录”。任何试图访问此范围外的文件的请求都应被立即拒绝。协议兼容严格遵循MCP协议定义的消息格式JSON-RPC进行通信。确保我们的服务能与标准的MCP客户端如Claude Desktop无缝对接。语言选择选用Python。原因很简单生态好有现成的MCP SDK开发快适合快速原型验证。当然你用Node.js、Go甚至Rust来实现协议本身都是通用的。开发流程先实现一个能跑通的独立服务再配置Claude Desktop进行集成测试最后总结调试技巧和避坑指南。这个设计确保了项目目标明确、边界清晰我们能集中火力攻克从零到一的关键环节。3. 环境准备与核心依赖解析工欲善其事必先利其器。我们不需要复杂的框架几个核心库就足够了。3.1 创建项目与虚拟环境首先避免污染全局Python环境使用虚拟环境是最佳实践。# 创建项目目录 mkdir mcp-file-reader cd mcp-file-reader # 创建虚拟环境这里使用venv你也可以用conda python -m venv .venv # 激活虚拟环境 # Windows: .venv\Scripts\activate # Linux/Mac: source .venv/bin/activate激活后命令行提示符前通常会显示(.venv)表示你已经在虚拟环境中了。3.2 安装MCP SDK与其他依赖MCP协议的核心是JSON-RPC消息的收发和处理。虽然我们可以完全手搓这些JSON但使用官方或社区维护的SDK能极大提升开发效率避免低级错误。这里我们使用mcp这个Python库它提供了构建MCP服务器和客户端的底层支持。同时我们也会用到pydantic来做数据验证和序列化让代码更健壮。pip install mcp pydantic为什么是这几个库mcp这是构建MCP服务的核心。它封装了协议细节让我们可以专注于工具和资源的逻辑实现而不是JSON解析和状态管理。pydantic在定义工具输入参数时它能提供强大的类型检查和数据验证。比如确保传入的路径是字符串并且我们可以自定义验证逻辑来检查路径是否在允许的范围内。这比手动写一堆if语句要优雅和可靠得多。安装完成后可以创建一个requirements.txt文件来固化依赖pip freeze requirements.txt。4. 极简MCP服务端代码实现现在进入核心环节我们将一步步构建出服务端。我会把代码拆解成块并解释每一部分的意图和关键点。4.1 定义工具输入参数模型首先我们需要定义read_file工具接受的参数。使用Pydantic模型能确保传入的数据符合预期格式。# server.py from typing import Any from pydantic import BaseModel, Field, field_validator from pathlib import Path import os class ReadFileArgs(BaseModel): 读取文件的参数模型 path: str Field(description要读取的文件的路径相对于配置的根目录。) field_validator(path) classmethod def validate_path(cls, v: str) - str: # 基础校验路径不能为空且不能是绝对路径我们期望相对路径 if not v: raise ValueError(文件路径不能为空) # 防止目录遍历攻击检查路径中是否包含.. if .. in v: raise ValueError(路径中不允许包含父目录引用..) # 这里可以添加更多清洗逻辑比如去除开头的斜杠 v v.lstrip(/) return v关键点解析我们定义了一个ReadFileArgs类它只有一个字段path描述为文件路径。field_validator(path)装饰器用于自定义验证逻辑。这里我们做了两件事检查路径是否为空。安全检查禁止路径中包含..。这是防止目录遍历攻击Path Traversal的关键一步攻击者可能通过../../../etc/passwd这样的路径试图访问系统文件。虽然我们后续还有根目录限制但在这里加一道防线是很好的习惯。v v.lstrip(/)是为了处理可能以/开头的路径将其统一为相对路径格式。4.2 实现服务器类与工具函数接下来我们创建MCP服务器类并实现read_file工具函数。# server.py (续) from mcp.server import Server from mcp.server.models import Tool import mcp.server.stdio import mcp.types as types class FileReaderServer: def __init__(self, root_dir: str): # 初始化MCP服务器实例 self.server Server(local-file-reader) # 将允许访问的根目录转换为Path对象并解析为绝对路径 self.root_dir Path(root_dir).expanduser().resolve() # 确保根目录存在且是一个目录 if not self.root_dir.exists(): raise ValueError(f配置的根目录不存在: {self.root_dir}) if not self.root_dir.is_dir(): raise ValueError(f配置的根目录不是一个目录: {self.root_dir}) # 向服务器注册我们提供的工具 self.server.list_tools().add_handler(self.list_tools) self.server.call_tool().add_handler(self.call_tool) async def list_tools(self) - list[types.Tool]: 返回服务器提供的工具列表 return [ Tool( nameread_file, description读取指定文本文件的内容。, inputSchema{ type: object, properties: { path: {type: string, description: 相对于根目录的文件路径。} }, required: [path] } ) ] async def call_tool(self, name: str, arguments: dict[str, Any]) - list[types.TextContent]: 处理工具调用请求 if name ! read_file: # 理论上list_tools里只有read_file但这里还是做一下防御性检查 raise ValueError(f未知工具: {name}) # 1. 验证和解析参数 args ReadFileArgs(**arguments) # 2. 构建绝对路径并确保其在根目录内 requested_path (self.root_dir / args.path).resolve() # 关键安全校验请求的路径是否在允许的根目录之下 try: # 使用commonpath检查比字符串前缀比较更可靠 requested_path.relative_to(self.root_dir) except ValueError: # 如果抛出ValueError说明requested_path不是self.root_dir的子路径 raise PermissionError(f拒绝访问路径 {args.path} 超出了允许的根目录范围。) # 3. 检查文件是否存在且是普通文件 if not requested_path.exists(): raise FileNotFoundError(f文件不存在: {requested_path}) if not requested_path.is_file(): raise ValueError(f路径不是一个文件: {requested_path}) # 4. 读取文件内容 # 这里先假设是文本文件用UTF-8编码。实际项目中可能需要处理编码探测或二进制文件。 try: content requested_path.read_text(encodingutf-8) except UnicodeDecodeError: # 如果UTF-8解码失败可以尝试其他编码或返回错误 raise ValueError(f文件无法以UTF-8编码读取可能不是文本文件: {requested_path}) # 5. 按照MCP协议返回结果 return [types.TextContent(typetext, textcontent)] async def run(self): 启动服务器使用stdio传输 async with mcp.server.stdio.stdio_server() as (read_stream, write_stream): await self.server.run(read_stream, write_stream, self.server.create_initialization_options())代码逐段解读与避坑指南初始化与根目录设置(__init__)self.root_dir Path(root_dir).expanduser().resolve()这一行做了三件事。expanduser()将~展开为用户家目录resolve()获取绝对路径并消除任何符号链接。这是必须的它确保了后续路径比较的准确性。如果不做resolve()符号链接可能会导致安全校验绕过。紧接着检查根目录是否存在且为目录。这是对配置的预先验证避免服务器启动后才发现路径错误。工具列表声明(list_tools)返回一个Tool对象列表。这里我们只声明一个工具。inputSchema严格按照JSON Schema格式定义这决定了客户端如Claude如何生成调用界面。required字段指明path是必填参数。工具调用处理(call_tool)这是核心逻辑。参数验证args ReadFileArgs(**arguments)这行代码利用Pydantic自动完成了类型转换和我们在模型中定义的验证如检查..。安全校验重中之重requested_path (self.root_dir / args.path).resolve() requested_path.relative_to(self.root_dir)第一行将相对路径与根目录拼接并再次resolve()。注意args.path是已经过清洗去除了..和开头的/的相对路径。第二行Path.relative_to()方法会检查requested_path是否以self.root_dir为起始路径。如果不是则抛出ValueError。这种方法比检查字符串前缀str.startswith更安全可靠因为它处理了路径解析和大小写在区分大小写的系统上等问题。文件状态检查在读取前确认文件存在且是普通文件避免对目录或特殊文件进行误操作。文件读取使用read_text(encodingutf-8)。这里是一个简化处理。在实际应用中你可能会遇到不同编码的文件如GBK。更健壮的做法可以尝试多种编码或者通过chardet库探测编码但对于极简版明确约定为UTF-8并处理解码错误是可以接受的。返回结果MCP协议要求工具调用返回一个Content列表。这里我们返回TextContent类型为text。运行入口(run)使用mcp.server.stdio.stdio_server()创建标准输入输出流然后交给server的run方法。这是MCP SDK提供的标准启动方式。4.3 主程序入口与配置最后我们需要一个主函数来启动这一切并处理根目录的配置。# server.py (续) import asyncio import sys async def main(): # 从命令行参数或环境变量获取根目录。这里简单处理优先取命令行参数。 if len(sys.argv) 1: root_dir sys.argv[1] else: # 如果没有提供参数默认使用当前用户的家目录下的一个特定文件夹降低风险。 # 例如创建一个 ~/mcp_shared 目录来存放允许被读取的文件。 default_dir Path.home() / mcp_shared default_dir.mkdir(exist_okTrue) # 如果目录不存在则创建 root_dir str(default_dir) print(f未指定根目录使用默认目录: {root_dir}, filesys.stderr) try: server FileReaderServer(root_dir) print(fMCP 文件阅读器服务已启动根目录: {root_dir}, filesys.stderr) print(服务正在运行... (按 CtrlC 停止), filesys.stderr) await server.run() except Exception as e: print(f启动服务器失败: {e}, filesys.stderr) sys.exit(1) if __name__ __main__: asyncio.run(main())配置策略说明根目录通过命令行参数传入提供了灵活性。例如python server.py /path/to/your/data。如果没有提供参数我们没有默认使用当前目录(.)或根目录(/)而是指向用户家目录下的一个特定子目录~/mcp_shared。这是一个重要的安全实践最小权限原则。默认情况下服务只能访问一个明确创建的、意图用于共享的空白目录最大程度减少了误配置导致的安全风险。我们甚至主动创建这个目录mkdir(exist_okTrue)。错误信息输出到stderr因为MCP协议通信使用stdout避免日志污染了协议消息。至此一个功能完整、具备基础安全防护的MCP文件阅读器服务端就完成了。你可以通过python server.py /your/allowed/path来运行它。运行后它会等待来自stdin的MCP协议消息。5. 配置Claude Desktop进行集成测试服务端跑起来只是成功了一半我们需要一个客户端来真正使用它。Claude Desktop是Anthropic官方提供的客户端它内置了MCP客户端功能非常适合做集成测试。5.1 定位Claude Desktop配置文件Claude Desktop的配置通常位于用户配置目录下。macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在可以手动创建。5.2 编写MCP服务器配置我们需要编辑上述配置文件告诉Claude Desktop如何启动我们的服务。配置内容是一个JSON对象。{ mcpServers: { local-file-reader: { command: python, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-file-reader/server.py, /ABSOLUTE/PATH/TO/YOUR/ALLOWED/DIRECTORY ], env: { PYTHONPATH: /ABSOLUTE/PATH/TO/YOUR/mcp-file-reader } } } }配置详解与避坑指南command: 这里是python。这意味着Claude Desktop会尝试在系统环境变量中寻找python命令。强烈建议你使用虚拟环境中的Python解释器的绝对路径来避免依赖问题。例如如果你的虚拟环境在项目目录.venv下那么在macOS/Linux上可能是/ABSOLUTE/PATH/TO/mcp-file-reader/.venv/bin/python在Windows上是C:\\ABSOLUTE\\PATH\\TO\\mcp-file-reader\\.venv\\Scripts\\python.exe。这是集成测试中最常见的坑之一。args: 第一个参数是我们的脚本绝对路径第二个是允许读取的根目录绝对路径。所有路径都必须是绝对路径因为Claude Desktop启动子进程时工作目录可能是不确定的。env(可选但推荐): 设置PYTHONPATH环境变量确保我们的脚本能找到mcp等依赖库如果它们没有安装在虚拟环境的默认搜索路径中但通常安装在虚拟环境site-packages里就够了。更稳妥的做法是确保command指向的Python解释器来自已经安装了所有依赖的虚拟环境。一个更健壮的配置示例macOS/Linux{ mcpServers: { local-file-reader: { command: /Users/yourname/projects/mcp-file-reader/.venv/bin/python, args: [ /Users/yourname/projects/mcp-file-reader/server.py, /Users/yourname/Documents/ai_data ] } } }5.3 测试与验证保存配置编辑好claude_desktop_config.json后保存。重启Claude Desktop完全退出并重新启动Claude Desktop应用以确保它加载新的配置。观察日志启动Claude Desktop时你可以打开它的开发者工具通常Help菜单里有查看日志。如果配置正确你会看到它尝试启动local-file-reader服务器的日志。如果启动失败日志里会有详细的错误信息这是排查问题的第一现场。在对话中测试新建一个对话尝试让Claude读取文件。例如你可以说“请使用read_file工具读取一下my_note.txt的内容。” 如果一切正常Claude会识别到这个工具并调用它。你可以在它生成的思考过程中看到工具调用的请求和返回的文件内容。注意首次配置时Claude Desktop可能会提示你“允许外部服务器运行”需要你点击确认授权。这是其安全机制的一部分。6. 开发调试与常见问题全记录在实际操作中你几乎一定会遇到各种问题。下面是我在开发和测试过程中踩过的坑和总结的排查方法。6.1 独立测试服务器脱离客户端的快速验证在集成到Claude Desktop之前最好先能独立验证服务器的基本功能。我们可以写一个极简的客户端脚本或者使用ncnetcat进行手动测试。但更简单的方法是直接运行服务器然后通过标准输入手动发送MCP协议消息。不过手动构造JSON-RPC消息很麻烦。推荐使用MCP SDK自带的测试工具或编写一个测试客户端。这里提供一个非常简单的测试脚本它模拟客户端初始化并调用一次工具# test_client.py import asyncio import json import sys import subprocess from pathlib import Path async def test_server(): # 启动服务器子进程 server_script Path(__file__).parent / server.py root_dir Path.home() / mcp_shared # 在测试目录下放一个测试文件 test_file root_dir / test.txt test_file.write_text(Hello, MCP! This is a test file.\n第二行内容。) proc await asyncio.create_subprocess_exec( sys.executable, str(server_script), str(root_dir), stdinasyncio.subprocess.PIPE, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, ) # 发送初始化请求 init_request { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 0.1.0, capabilities: {}, clientInfo: {name: test-client, version: 1.0} } } proc.stdin.write((json.dumps(init_request) \n).encode()) await proc.stdin.drain() # 读取初始化响应略过实际需要解析 # ... # 发送工具调用请求 tool_request { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: read_file, arguments: {path: test.txt} } } proc.stdin.write((json.dumps(tool_request) \n).encode()) await proc.stdin.drain() # 读取并打印响应 while True: line await proc.stdout.readline() if not line: break response json.loads(line.decode().strip()) if response.get(id) 2: result response.get(result, {}) content result.get(content, [{}])[0] print(读取到的内容:, content.get(text, No text found)) break # 清理 proc.terminate() await proc.wait() if __name__ __main__: asyncio.run(test_server())这个脚本能帮你确认服务器逻辑是否正确而不需要依赖完整的客户端环境。6.2 Claude Desktop集成问题排查清单当Claude Desktop无法正常使用你的工具时可以按照以下清单逐步排查问题现象可能原因排查步骤与解决方案Claude完全“不知道”有工具1. 配置文件路径错误。2. 配置文件格式错误JSON语法。3. Claude Desktop未重启。1. 确认配置文件在正确的操作系统路径下。2. 使用JSON验证工具如jq或在线校验器检查配置文件。3. 彻底退出并重启Claude Desktop。Claude识别到工具但调用失败日志显示“Server exited”或启动错误1.command路径错误。2. Python依赖未安装。3. 服务器脚本本身有语法错误或启动时抛出异常。1.检查command确保指向的Python解释器路径绝对正确且可执行。这是最高频的错误点。使用虚拟环境Python的绝对路径。2.检查依赖在虚拟环境中运行pip list确认mcp和pydantic已安装。3.独立运行服务器在终端用配置中的命令手动执行一次看是否有错误输出。例如/path/to/python /path/to/server.py /data/dir。工具调用后返回“权限错误”或“文件未找到”1. 配置的根目录(args中的第二个参数)路径错误或不存在。2. 请求的文件路径相对于根目录不正确。3. 服务器安全校验阻止。1. 确认根目录存在且服务器有读取权限。2. 在服务器日志中查看它接收到的具体path参数和解析后的绝对路径。3. 检查服务器代码中的安全校验逻辑relative_to部分是否过于严格。工具调用超时或无响应1. 服务器进程卡死或崩溃。2. 读取的文件非常大。3. 协议消息格式错误导致通信中断。1. 查看Claude Desktop日志或系统进程管理器确认服务器进程是否在运行。2. 在服务器代码中为文件读取添加超时或分块读取逻辑对于极简版先确保能处理小文件。3. 使用上面的test_client.py或打印调试信息检查服务器发出的JSON-RPC响应格式是否正确。中文字符显示乱码文件编码非UTF-8而服务器固定用UTF-8读取。1. 确保待读取的文件是UTF-8编码。2. 或者修改服务器代码尝试通用编码如utf-8-sig或使用chardet探测编码。content requested_path.read_text(encodingutf-8-sig)可以处理带BOM的UTF-8。一个关键的调试技巧查看Claude Desktop日志。在macOS上你可以通过运行Console.app在左侧选择你的设备然后在右上角搜索“Claude”来查看系统日志。更直接的方式是在Claude Desktop应用内通过菜单栏的“Help” - “Toggle Developer Tools”打开开发者工具在“Console”标签页里会看到详细的MCP服务器启动和通信日志任何错误信息都会在这里显示这是定位问题的金钥匙。6.3 安全性强化考量我们当前的实现已经包含了基础的安全措施根目录限制、路径遍历防护。对于生产环境或更敏感的数据还可以考虑更细粒度的访问控制除了目录还可以通过配置文件定义允许读取的文件扩展名如只允许.txt,.md,.json。请求频率限制防止被恶意频繁调用耗尽资源。内容过滤在返回内容前可以检查是否包含某些敏感模式如密钥、令牌并进行脱敏处理。但这需要权衡可能会影响性能和数据完整性。使用SSE传输并添加认证对于网络部署stdio传输不合适。可以改用SSEServer-Sent Events传输并在服务器端实现简单的API密钥认证。对于个人开发环境我们目前的安全设计已经足够。核心原则始终是最小权限默认拒绝。7. 项目总结与扩展方向通过这个项目我们完整地走通了一个MCP服务从设计、编码、配置到调试的全流程。这个“极简”服务虽然只做了一个read_file功能但它像一把钥匙打开了将本地私有数据与AI能力安全连接的大门。我个人在实操中最深的体会是配置与调试环节往往比编码更耗时。尤其是确保Claude Desktop能正确启动子进程路径和依赖问题必须反复确认。养成先独立测试服务器逻辑再集成到客户端的好习惯能节省大量时间。这个服务可以作为一个坚实的起点向多个方向扩展支持更多文件操作实现write_file写入、list_directory列出目录、search_files搜索等工具构建一个简单的文件管理套件。支持二进制文件或特定格式例如读取图片并返回base64编码或者解析PDF、Word文档提取文本。连接数据库实现query_database工具让AI能直接查询你的SQLite、MySQL或PostgreSQL数据库务必注意SQL注入防护。封装外部API将一些需要认证的第三方API如GitHub、Jira、Slack封装成MCP工具让AI在对话中帮你查询信息或执行操作。部署为网络服务将当前的stdio服务器改造成一个HTTP/SSE服务器这样任何支持MCP协议的客户端不限于Claude Desktop都可以通过网络连接使用它实现跨设备的数据共享。最后一个小技巧在开发过程中善用Python的logging模块替代print可以更方便地控制日志级别和输出目的地将调试信息输出到stderr而将协议信息保留给stdout这样在排查问题时日志会更清晰。