1. 项目概述为什么是MCP服务器如果你最近在折腾大模型应用开发特别是用上了Cursor、Claude Code这类AI编程工具那你大概率已经接触过“MCP”这个词了。MCP全称是Model Context Protocol你可以把它理解成大模型和外部工具、数据源之间的一座“标准桥梁”。简单来说它定义了一套规则让AI助手比如Claude能够安全、可控地调用你本地的脚本、查询数据库或者访问特定的API而不仅仅是基于它训练截止日期前的知识库来回答问题。那么开发一个MCP服务器有什么用呢想象一下你公司内部有一套独特的项目管理系统API或者你个人写了一个自动化处理本地文件的脚本库。通过将这些能力封装成一个MCP服务器你的AI编程伙伴就能直接“学会”使用它们。你可以在编辑器里直接对AI说“帮我把当前打开文件的内容提交到内部系统并创建一个Jira任务”AI就能通过你写的MCP服务器去执行这一系列操作。这极大地扩展了AI编程的边界让它从“代码建议者”变成了“工作流执行者”。今天这个实战项目目标就是带你用Python在15分钟内从一个空文件夹开始构建一个具备基础功能的MCP服务器并完成从本地调试到生产级容器化部署的全过程。我们会聚焦于一个最经典、也最实用的场景一个文件系统操作服务器。它能让AI帮你安全地读取、列出、甚至写入指定目录下的文件。别被“生产级”吓到我们会用Docker把环境、依赖全部打包确保它能在任何地方稳定运行。2. 核心设计协议、工具与安全边界在动手写代码之前我们必须先吃透MCP协议的核心思想这决定了我们服务器的骨架设计。MCP协议基于JSON-RPC 2.0通信方式通常是stdio标准输入输出或SSE服务器发送事件。对于我们这种轻量级、高性能的本地工具服务器stdio模式是最简单直接的选择——你的AI客户端如Cursor启动我们的服务器进程然后通过管道stdin/stdout进行JSON消息的交换。2.1 工具Tools的定义与设计MCP服务器的核心能力是通过“工具”来暴露的。每个工具都有明确的输入参数和输出格式。对于我们的文件系统服务器我设计了三个基础但足够强大的工具list_directory(列出目录)接收一个path参数返回该路径下的文件和文件夹列表。这是AI探索你项目结构的“眼睛”。read_file(读取文件)接收一个path参数返回文件的内容。这是AI获取代码、文档等具体信息的“手”。write_file(写入文件)接收path和content两个参数将内容写入指定路径。这是AI进行代码生成和修改的“笔”。这里有一个关键的安全设计我们绝不能允许AI任意访问整个文件系统。因此我们需要引入“根目录”的概念。服务器启动时我们会设定一个允许访问的根目录例如/workspace或./project所有工具的参数path都必须是这个根目录下的相对路径或经过校验的绝对路径。在实现时我们会使用os.path.abspath和os.path.commonpath等方法确保任何请求的路径都不会逃逸出我们设定的安全沙箱。2.2 生产级考量配置化与可观测性一个玩具脚本和一个生产级服务的区别往往在于对配置、错误处理和可观测性的重视程度。配置化服务器的行为如允许的根目录、日志级别不应硬编码在代码里。我们将使用环境变量如MCP_SERVER_ROOT_DIR或配置文件来管理这为后续的容器化部署铺平了道路。结构化日志简单的print语句在调试时还行但在生产环境远远不够。我们将集成structlog或Python原生的logging模块输出带有时间戳、日志级别、请求ID的JSON格式日志。这样无论是通过Docker查看日志还是将日志收集到ELK等系统都非常方便。健壮的错误处理文件不存在、权限不足、路径非法……各种异常情况都必须被捕获并转化为符合MCP协议规范的错误响应返回给客户端而不是让整个服务器进程崩溃。3. 从零开始用Python快速实现MCP服务器理论清晰了现在打开你的编辑器我们开始实战。我将使用官方推荐的mcpSDK它封装了协议通信的底层细节让我们能专注于工具逻辑。3.1 初始化项目与环境首先创建一个新的项目目录并建立虚拟环境这是保证依赖隔离的好习惯。mkdir mcp-file-server cd mcp-file-server python -m venv .venv # 激活虚拟环境 # Linux/Mac: source .venv/bin/activate # Windows: # .venv\Scripts\activate接着创建requirements.txt文件写入我们的核心依赖mcp0.3.0 structlog23.0.0 click8.0.0 # 用于创建命令行接口然后安装它们pip install -r requirements.txt3.2 构建服务器核心server.py现在创建主文件server.py。我们将逐步构建它。第一步导入与基础设置import os import sys from pathlib import Path from typing import Any, List import logging import structlog from mcp import ClientSession, StdioServerParameters from mcp.server import Server from mcp.server.models import InitializationOptions import click # 配置结构化日志 structlog.configure( processors[ structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.TimeStamper(fmtiso), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.JSONRenderer() ], context_classdict, logger_factorystructlog.stdlib.LoggerFactory(), cache_logger_on_first_useTrue, ) logger structlog.get_logger()第二步创建服务器实例与工具函数# 创建MCP服务器实例 app Server(file-system-server) # 定义安全的根目录默认为当前目录 ROOT_DIR Path(os.getenv(MCP_SERVER_ROOT_DIR, .)).resolve() def _validate_path(user_path: str) - Path: 将用户提供的路径解析为绝对路径并确保其在ROOT_DIR内 requested_path (ROOT_DIR / user_path).resolve() # 关键安全校验确保请求路径在根目录之下 try: requested_path.relative_to(ROOT_DIR) except ValueError: logger.warning(Path traversal attempt detected, requesteduser_path, rootstr(ROOT_DIR)) raise ValueError(fAccess to path {user_path} is not allowed.) return requested_path app.list_tool() async def list_directory(path: str .) - List[str]: 列出指定目录下的内容 safe_path _validate_path(path) if not safe_path.is_dir(): return [fError: {path} is not a directory or does not exist.] items [] for item in safe_path.iterdir(): items.append(f{[DIR] if item.is_dir() else [FILE]} {item.name}) logger.info(Listed directory, pathstr(safe_path), item_countlen(items)) return items app.list_tool() async def read_file(path: str) - str: 读取指定文件的内容 safe_path _validate_path(path) if not safe_path.is_file(): return fError: File {path} does not exist or is not a file. try: content safe_path.read_text(encodingutf-8) logger.info(File read, pathstr(safe_path), sizelen(content)) return content except UnicodeDecodeError: return fError: Cannot read file {path} as text (binary file?). app.list_tool() async def write_file(path: str, content: str) - str: 将内容写入指定文件不存在则创建存在则覆盖 safe_path _validate_path(path) # 可选检查路径是否为文件防止写到目录名上 if safe_path.exists() and not safe_path.is_file(): return fError: {path} exists but is not a file. safe_path.parent.mkdir(parentsTrue, exist_okTrue) # 确保父目录存在 safe_path.write_text(content, encodingutf-8) logger.info(File written, pathstr(safe_path), sizelen(content)) return fSuccessfully wrote to {path}.第三步创建命令行入口与主循环click.command() click.option(--root-dir, default., helpRoot directory for file operations. Can also be set via MCP_SERVER_ROOT_DIR env var.) def main(root_dir: str): 启动MCP文件服务器 global ROOT_DIR env_root os.getenv(MCP_SERVER_ROOT_DIR) final_root Path(env_root if env_root else root_dir).resolve() if not final_root.exists(): logger.error(Root directory does not exist, pathstr(final_root)) sys.exit(1) ROOT_DIR final_root logger.info(Starting MCP File Server, root_dirstr(ROOT_DIR), pidos.getpid()) # 使用stdio传输模式 server_params StdioServerParameters( commandsys.executable, # 当前Python解释器 args[__file__], # 运行自身当被客户端调用时 envNone ) # 注意在实际被客户端调用时我们不会执行到下面的run()。 # 下面这段代码主要用于本地独立测试我们的工具函数。 # 真正的服务器模式由MCP SDK内部处理。 async def run_test(): async with app.run_stdio_server(server_params) as (read_stream, write_stream): # 这里通常由SDK接管通信我们只是保持运行 await asyncio.Future() # 永远等待 # 如果是直接运行脚本打印提示信息 if __name__ __main__: print(fMCP File Server initialized. Root directory is: {ROOT_DIR}, filesys.stderr) print(This server is intended to be launched by an MCP client (e.g., Cursor)., filesys.stderr) # 为了保持进程运行以便stdio通信 try: import asyncio asyncio.run(run_test()) except KeyboardInterrupt: logger.info(Server shutdown by user) except Exception as e: logger.error(Server crashed, errorstr(e)) sys.exit(1) if __name__ __main__: main()关键安全提示_validate_path函数中的relative_to检查是防止目录遍历攻击的核心。它确保了用户请求的路径无论使用..还是符号链接最终都不会超出我们设定的ROOT_DIR。这是生产环境中必须有的安全锁。3.3 本地测试与调试在交付给AI客户端之前我们必须先验证服务器是否能正确响应协议。我们可以写一个简单的测试脚本test_server.py来模拟客户端# test_server.py import asyncio import json import subprocess from pathlib import Path async def test_tool(server_process, tool_name, arguments): 模拟发送一个执行工具的请求 request { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: tool_name, arguments: arguments } } server_process.stdin.write(json.dumps(request) \n) server_process.stdin.flush() # 简化读取一行响应实际协议更复杂涉及初始化等步骤 # 这里仅为演示概念 async def main(): # 启动我们的服务器进程 proc await asyncio.create_subprocess_exec( python, server.py, stdinasyncio.subprocess.PIPE, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, ) # 在实际中你需要按照MCP协议顺序发送初始化请求等。 # 此处省略详细握手过程。 print(Server started. Testing basic functions...) # 创建一个测试文件 test_file Path(./test_hello.txt) test_file.write_text(Hello from MCP test!) # 这里你应该通过stdin发送正式的MCP请求。 # 作为快速验证我们可以直接运行脚本看它是否启动成功。 await proc.wait() print(fServer exited with code: {proc.returncode}) if __name__ __main__: asyncio.run(main())更实用的方法是直接使用MCP SDK提供的测试工具或者查阅官方示例。不过对于我们的目标——与Cursor/Claude Code集成——最直接的测试就是实际集成。4. 集成AI客户端以Cursor为例服务器跑起来了现在要让它被AI“看见”。这里以目前非常流行的Cursor编辑器为例。4.1 配置Cursor的MCP设置Cursor支持通过配置文件添加自定义MCP服务器。你需要找到Cursor的配置位置macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json如果mcp.json文件不存在就创建一个。然后添加我们的服务器配置{ mcpServers: { file-system-server: { command: /path/to/your/.venv/bin/python, args: [/absolute/path/to/your/mcp-file-server/server.py], env: { MCP_SERVER_ROOT_DIR: /path/to/your/safe/project/root } } } }配置解析command: 这里必须指向你虚拟环境中的Python解释器绝对路径以确保能加载所有依赖。使用which python或where python在激活的虚拟环境中来获取。args: 指向我们刚写的server.py的绝对路径。env: 设置环境变量MCP_SERVER_ROOT_DIR这是我们的安全沙箱根目录。务必将其设置为你希望AI访问的项目目录比如你的代码仓库根目录。4.2 验证与使用保存mcp.json。完全重启Cursor。这是关键一步配置只在启动时加载。重启后打开Cursor的Chat面板通常是Cmd/Ctrl K。你可以尝试输入“你能用什么工具”或者“列出当前目录的文件”。如果配置成功Claude会回复它已连接到一个文件服务器并可以调用list_directory等工具。进一步测试“请读取server.py文件的内容”或“在根目录创建一个名为test_from_ai.md的文件内容为‘# Hello AI’”。当你看到AI不仅能回答还能实际执行文件操作时恭喜你最核心的一步已经完成了5. 生产级部署Docker化与持续集成本地能跑离在任何地方都能稳定运行还差一个“集装箱”——Docker。容器化能解决“在我机器上好好的”这类环境依赖问题。5.1 编写Dockerfile在项目根目录创建Dockerfile# 使用官方Python精简版镜像 FROM python:3.11-slim as builder WORKDIR /app # 安装系统依赖如有需要例如用于编译某些Python包 RUN apt-get update apt-get install -y --no-install-recommends \ gcc \ rm -rf /var/lib/apt/lists/* # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir --user -r requirements.txt # 第二阶段运行阶段使用更小的基础镜像 FROM python:3.11-slim WORKDIR /app # 从构建阶段复制已安装的Python包 COPY --frombuilder /root/.local /root/.local # 确保脚本可找到已安装的包 ENV PATH/root/.local/bin:$PATH # 复制应用代码 COPY server.py . # 创建一个非root用户运行应用增强安全性 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser # 设置默认的环境变量可在运行时覆盖 ENV MCP_SERVER_ROOT_DIR/workspace ENV PYTHONUNBUFFERED1 # 声明容器以stdio模式运行 ENTRYPOINT [python, server.py]这个Dockerfile采用了两阶段构建最终镜像更小。它设置了非root用户是一个重要的安全实践。5.2 构建与运行容器在Dockerfile同级目录下执行构建docker build -t mcp-file-server:latest .构建完成后可以运行测试# 将当前目录挂载到容器的 /workspace作为根目录 docker run -it --rm \ -v $(pwd):/workspace \ -e MCP_SERVER_ROOT_DIR/workspace \ mcp-file-server:latest你应该看到服务器启动的日志信息。现在我们需要修改Cursor的配置让它调用这个容器内的服务器。5.3 配置Cursor调用Docker容器这需要一点技巧因为Cursor需要启动一个命令而这个命令需要启动Docker容器并与之进行stdio通信。我们可以写一个简单的包装脚本。创建一个脚本文件run_server.shLinux/Mac或run_server.batWindowsLinux/Mac (run_server.sh):#!/bin/bash # 确保传递所有参数给docker run docker run -i --rm \ -v /absolute/path/to/your/project:/workspace \ -e MCP_SERVER_ROOT_DIR/workspace \ mcp-file-server:latest记得给脚本执行权限chmod x run_server.shWindows (run_server.bat):echo off docker run -i --rm ^ -v C:\path\to\your\project:/workspace ^ -e MCP_SERVER_ROOT_DIR/workspace ^ mcp-file-server:latest然后更新Cursor的mcp.json配置将command指向这个包装脚本{ mcpServers: { file-system-server-docker: { command: /absolute/path/to/your/mcp-file-server/run_server.sh, args: [], env: {} } } }这样Cursor启动时就会执行这个脚本脚本负责启动Docker容器并将stdio管道连接起来。这种方式实现了完全容器化的部署服务器环境纯净且一致。5.4 进阶结合持续集成/部署CI/CD对于团队协作或需要频繁更新的场景可以将Docker镜像推送到镜像仓库如Docker Hub、GitHub Container Registry并在CI/CD流水线中自动构建。一个简单的GitHub Actions工作流示例.github/workflows/build.ymlname: Build and Push Docker Image on: push: branches: [ main ] tags: [ v* ] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Log in to Docker Hub uses: docker/login-actionv3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_TOKEN }} - name: Build and push Docker image uses: docker/build-push-actionv5 with: context: . push: true tags: | yourdockerhubusername/mcp-file-server:latest yourdockerhubusername/mcp-file-server:${{ github.sha }}这样每次推送到主分支都会自动构建并推送最新的Docker镜像。团队其他成员只需拉取最新镜像即可无需关心本地Python环境。6. 常见问题与深度排查指南在实际开发和集成过程中你几乎一定会遇到一些问题。下面是我踩过坑后总结的排查清单。6.1 服务器启动失败症状Cursor聊天框提示无法连接服务器或直接报错。排查步骤检查命令路径mcp.json中的command和args必须是绝对路径。使用which python确认虚拟环境Python路径。手动测试命令在终端中完整运行你在mcp.json中配置的命令行包括command和args看是否能正常启动并打印出初始化信息如我们代码中print的提示。如果报错“ModuleNotFoundError: No module named mcp”说明Python环境不对依赖没安装。检查文件权限确保脚本文件有可执行权限仅Linux/Mac并且当前用户有权访问。查看Cursor日志Cursor通常有开发者控制台或日志文件。在设置中开启详细日志查看是否有关于MCP服务器启动失败的更具体错误信息。6.2 工具调用无响应或报错症状AI说连接了服务器但调用工具时没反应或返回权限错误、路径错误。排查步骤验证根目录权限确保MCP_SERVER_ROOT_DIR指向的目录存在且运行服务器的用户在Docker中是appuser对该目录有读写权限。在Docker中特别注意挂载卷的权限问题主机用户ID可能与容器内用户ID1000不匹配导致“Permission denied”。可以在Docker run时加上-u $(id -u):$(id -g)来使用主机用户ID。检查路径安全校验故意在AI请求中使用../../../etc/passwd这样的路径看服务器是返回了拒绝访问的错误还是真的返回了内容。如果返回了内容说明你的_validate_path函数有安全漏洞。启用调试日志在服务器代码中将日志级别调到DEBUG或者增加更多logger.debug语句输出收到的请求参数、处理后的安全路径等。这能帮你看清数据流动。6.3 Docker容器内路径问题症状在Docker模式下AI工具返回“路径不存在”或“没有权限”但本地模式正常。排查步骤确认挂载卷docker run -v参数是否正确将主机项目目录挂载到了容器内的/workspace或你设定的目录进入容器检查使用docker run -it --rm --entrypoint/bin/bash your-image进入容器内部手动执行ls -la /workspace看看文件是否存在。环境变量传递确保MCP_SERVER_ROOT_DIR环境变量在Docker run命令中正确设置并且与Dockerfile或脚本中预期的目录一致。6.4 性能与资源优化当工具被频繁调用时你可能需要考虑性能。连接池与持久化目前的实现是每次调用都进行路径解析和文件IO。对于read_file这种操作如果频繁读取大文件可以考虑增加简单的基于LRU的内存缓存但要注意缓存一致性问题文件被外部修改。异步处理我们的工具函数使用了async def但文件IO本身是阻塞的。对于高性能场景可以考虑使用asyncio.to_thread将文件操作放到线程池中执行避免阻塞事件循环。不过对于轻量级操作当前方式通常足够。资源限制在Docker部署时可以通过--memory、--cpus等参数为容器设置资源上限防止单个MCP服务器占用过多主机资源。7. 扩展思路从文件服务器到万能助手一个基本的文件操作服务器只是起点。MCP协议的强大之处在于你可以将任何能力封装成工具。以下是一些扩展方向可以让你的AI助手能力倍增数据库查询服务器封装SQL查询工具让AI能直接查询项目数据库需严格限制为只读或特定安全操作获取实时数据来辅助决策。内部API网关将公司内部的项目管理、CI/CD、监控系统等API封装成工具。AI可以帮你创建工单、触发部署、查看服务状态。代码库分析器结合libcst或tree-sitter提供“查找函数引用”、“分析类结构”等高级代码理解工具让AI的代码重构建议更有上下文。自定义搜索集成Elasticsearch或Meilisearch为你的知识库或代码库提供专属的语义搜索工具。与OAuth集成为需要认证的外部服务如GitHub、Jira提供安全的OAuth流程。注意这需要仔细设计通常需要一个轻量的Web服务器来处理回调。MCP服务器本身stdio模式不适合直接处理HTTP回调但可以启动一个临时的本地HTTP服务或与已有的认证守护进程通信。核心原则是绝不将敏感令牌硬编码或明文传输。开发这些扩展时安全仍然是第一要务。始终遵循最小权限原则为每个工具设定清晰的、受限的操作边界并对所有输入进行严格的验证和清理。走到这一步你已经拥有了一个完全受控、可扩展、生产就绪的AI能力扩展底座。下次当AI说“我无法访问你的本地文件”时你可以自信地告诉它“不现在你可以了。” 15分钟构建生产级MCP服务器：扩展AI编程边界
1. 项目概述为什么是MCP服务器如果你最近在折腾大模型应用开发特别是用上了Cursor、Claude Code这类AI编程工具那你大概率已经接触过“MCP”这个词了。MCP全称是Model Context Protocol你可以把它理解成大模型和外部工具、数据源之间的一座“标准桥梁”。简单来说它定义了一套规则让AI助手比如Claude能够安全、可控地调用你本地的脚本、查询数据库或者访问特定的API而不仅仅是基于它训练截止日期前的知识库来回答问题。那么开发一个MCP服务器有什么用呢想象一下你公司内部有一套独特的项目管理系统API或者你个人写了一个自动化处理本地文件的脚本库。通过将这些能力封装成一个MCP服务器你的AI编程伙伴就能直接“学会”使用它们。你可以在编辑器里直接对AI说“帮我把当前打开文件的内容提交到内部系统并创建一个Jira任务”AI就能通过你写的MCP服务器去执行这一系列操作。这极大地扩展了AI编程的边界让它从“代码建议者”变成了“工作流执行者”。今天这个实战项目目标就是带你用Python在15分钟内从一个空文件夹开始构建一个具备基础功能的MCP服务器并完成从本地调试到生产级容器化部署的全过程。我们会聚焦于一个最经典、也最实用的场景一个文件系统操作服务器。它能让AI帮你安全地读取、列出、甚至写入指定目录下的文件。别被“生产级”吓到我们会用Docker把环境、依赖全部打包确保它能在任何地方稳定运行。2. 核心设计协议、工具与安全边界在动手写代码之前我们必须先吃透MCP协议的核心思想这决定了我们服务器的骨架设计。MCP协议基于JSON-RPC 2.0通信方式通常是stdio标准输入输出或SSE服务器发送事件。对于我们这种轻量级、高性能的本地工具服务器stdio模式是最简单直接的选择——你的AI客户端如Cursor启动我们的服务器进程然后通过管道stdin/stdout进行JSON消息的交换。2.1 工具Tools的定义与设计MCP服务器的核心能力是通过“工具”来暴露的。每个工具都有明确的输入参数和输出格式。对于我们的文件系统服务器我设计了三个基础但足够强大的工具list_directory(列出目录)接收一个path参数返回该路径下的文件和文件夹列表。这是AI探索你项目结构的“眼睛”。read_file(读取文件)接收一个path参数返回文件的内容。这是AI获取代码、文档等具体信息的“手”。write_file(写入文件)接收path和content两个参数将内容写入指定路径。这是AI进行代码生成和修改的“笔”。这里有一个关键的安全设计我们绝不能允许AI任意访问整个文件系统。因此我们需要引入“根目录”的概念。服务器启动时我们会设定一个允许访问的根目录例如/workspace或./project所有工具的参数path都必须是这个根目录下的相对路径或经过校验的绝对路径。在实现时我们会使用os.path.abspath和os.path.commonpath等方法确保任何请求的路径都不会逃逸出我们设定的安全沙箱。2.2 生产级考量配置化与可观测性一个玩具脚本和一个生产级服务的区别往往在于对配置、错误处理和可观测性的重视程度。配置化服务器的行为如允许的根目录、日志级别不应硬编码在代码里。我们将使用环境变量如MCP_SERVER_ROOT_DIR或配置文件来管理这为后续的容器化部署铺平了道路。结构化日志简单的print语句在调试时还行但在生产环境远远不够。我们将集成structlog或Python原生的logging模块输出带有时间戳、日志级别、请求ID的JSON格式日志。这样无论是通过Docker查看日志还是将日志收集到ELK等系统都非常方便。健壮的错误处理文件不存在、权限不足、路径非法……各种异常情况都必须被捕获并转化为符合MCP协议规范的错误响应返回给客户端而不是让整个服务器进程崩溃。3. 从零开始用Python快速实现MCP服务器理论清晰了现在打开你的编辑器我们开始实战。我将使用官方推荐的mcpSDK它封装了协议通信的底层细节让我们能专注于工具逻辑。3.1 初始化项目与环境首先创建一个新的项目目录并建立虚拟环境这是保证依赖隔离的好习惯。mkdir mcp-file-server cd mcp-file-server python -m venv .venv # 激活虚拟环境 # Linux/Mac: source .venv/bin/activate # Windows: # .venv\Scripts\activate接着创建requirements.txt文件写入我们的核心依赖mcp0.3.0 structlog23.0.0 click8.0.0 # 用于创建命令行接口然后安装它们pip install -r requirements.txt3.2 构建服务器核心server.py现在创建主文件server.py。我们将逐步构建它。第一步导入与基础设置import os import sys from pathlib import Path from typing import Any, List import logging import structlog from mcp import ClientSession, StdioServerParameters from mcp.server import Server from mcp.server.models import InitializationOptions import click # 配置结构化日志 structlog.configure( processors[ structlog.stdlib.filter_by_level, structlog.stdlib.add_logger_name, structlog.stdlib.add_log_level, structlog.stdlib.PositionalArgumentsFormatter(), structlog.processors.TimeStamper(fmtiso), structlog.processors.StackInfoRenderer(), structlog.processors.format_exc_info, structlog.processors.JSONRenderer() ], context_classdict, logger_factorystructlog.stdlib.LoggerFactory(), cache_logger_on_first_useTrue, ) logger structlog.get_logger()第二步创建服务器实例与工具函数# 创建MCP服务器实例 app Server(file-system-server) # 定义安全的根目录默认为当前目录 ROOT_DIR Path(os.getenv(MCP_SERVER_ROOT_DIR, .)).resolve() def _validate_path(user_path: str) - Path: 将用户提供的路径解析为绝对路径并确保其在ROOT_DIR内 requested_path (ROOT_DIR / user_path).resolve() # 关键安全校验确保请求路径在根目录之下 try: requested_path.relative_to(ROOT_DIR) except ValueError: logger.warning(Path traversal attempt detected, requesteduser_path, rootstr(ROOT_DIR)) raise ValueError(fAccess to path {user_path} is not allowed.) return requested_path app.list_tool() async def list_directory(path: str .) - List[str]: 列出指定目录下的内容 safe_path _validate_path(path) if not safe_path.is_dir(): return [fError: {path} is not a directory or does not exist.] items [] for item in safe_path.iterdir(): items.append(f{[DIR] if item.is_dir() else [FILE]} {item.name}) logger.info(Listed directory, pathstr(safe_path), item_countlen(items)) return items app.list_tool() async def read_file(path: str) - str: 读取指定文件的内容 safe_path _validate_path(path) if not safe_path.is_file(): return fError: File {path} does not exist or is not a file. try: content safe_path.read_text(encodingutf-8) logger.info(File read, pathstr(safe_path), sizelen(content)) return content except UnicodeDecodeError: return fError: Cannot read file {path} as text (binary file?). app.list_tool() async def write_file(path: str, content: str) - str: 将内容写入指定文件不存在则创建存在则覆盖 safe_path _validate_path(path) # 可选检查路径是否为文件防止写到目录名上 if safe_path.exists() and not safe_path.is_file(): return fError: {path} exists but is not a file. safe_path.parent.mkdir(parentsTrue, exist_okTrue) # 确保父目录存在 safe_path.write_text(content, encodingutf-8) logger.info(File written, pathstr(safe_path), sizelen(content)) return fSuccessfully wrote to {path}.第三步创建命令行入口与主循环click.command() click.option(--root-dir, default., helpRoot directory for file operations. Can also be set via MCP_SERVER_ROOT_DIR env var.) def main(root_dir: str): 启动MCP文件服务器 global ROOT_DIR env_root os.getenv(MCP_SERVER_ROOT_DIR) final_root Path(env_root if env_root else root_dir).resolve() if not final_root.exists(): logger.error(Root directory does not exist, pathstr(final_root)) sys.exit(1) ROOT_DIR final_root logger.info(Starting MCP File Server, root_dirstr(ROOT_DIR), pidos.getpid()) # 使用stdio传输模式 server_params StdioServerParameters( commandsys.executable, # 当前Python解释器 args[__file__], # 运行自身当被客户端调用时 envNone ) # 注意在实际被客户端调用时我们不会执行到下面的run()。 # 下面这段代码主要用于本地独立测试我们的工具函数。 # 真正的服务器模式由MCP SDK内部处理。 async def run_test(): async with app.run_stdio_server(server_params) as (read_stream, write_stream): # 这里通常由SDK接管通信我们只是保持运行 await asyncio.Future() # 永远等待 # 如果是直接运行脚本打印提示信息 if __name__ __main__: print(fMCP File Server initialized. Root directory is: {ROOT_DIR}, filesys.stderr) print(This server is intended to be launched by an MCP client (e.g., Cursor)., filesys.stderr) # 为了保持进程运行以便stdio通信 try: import asyncio asyncio.run(run_test()) except KeyboardInterrupt: logger.info(Server shutdown by user) except Exception as e: logger.error(Server crashed, errorstr(e)) sys.exit(1) if __name__ __main__: main()关键安全提示_validate_path函数中的relative_to检查是防止目录遍历攻击的核心。它确保了用户请求的路径无论使用..还是符号链接最终都不会超出我们设定的ROOT_DIR。这是生产环境中必须有的安全锁。3.3 本地测试与调试在交付给AI客户端之前我们必须先验证服务器是否能正确响应协议。我们可以写一个简单的测试脚本test_server.py来模拟客户端# test_server.py import asyncio import json import subprocess from pathlib import Path async def test_tool(server_process, tool_name, arguments): 模拟发送一个执行工具的请求 request { jsonrpc: 2.0, id: 1, method: tools/call, params: { name: tool_name, arguments: arguments } } server_process.stdin.write(json.dumps(request) \n) server_process.stdin.flush() # 简化读取一行响应实际协议更复杂涉及初始化等步骤 # 这里仅为演示概念 async def main(): # 启动我们的服务器进程 proc await asyncio.create_subprocess_exec( python, server.py, stdinasyncio.subprocess.PIPE, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, ) # 在实际中你需要按照MCP协议顺序发送初始化请求等。 # 此处省略详细握手过程。 print(Server started. Testing basic functions...) # 创建一个测试文件 test_file Path(./test_hello.txt) test_file.write_text(Hello from MCP test!) # 这里你应该通过stdin发送正式的MCP请求。 # 作为快速验证我们可以直接运行脚本看它是否启动成功。 await proc.wait() print(fServer exited with code: {proc.returncode}) if __name__ __main__: asyncio.run(main())更实用的方法是直接使用MCP SDK提供的测试工具或者查阅官方示例。不过对于我们的目标——与Cursor/Claude Code集成——最直接的测试就是实际集成。4. 集成AI客户端以Cursor为例服务器跑起来了现在要让它被AI“看见”。这里以目前非常流行的Cursor编辑器为例。4.1 配置Cursor的MCP设置Cursor支持通过配置文件添加自定义MCP服务器。你需要找到Cursor的配置位置macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json如果mcp.json文件不存在就创建一个。然后添加我们的服务器配置{ mcpServers: { file-system-server: { command: /path/to/your/.venv/bin/python, args: [/absolute/path/to/your/mcp-file-server/server.py], env: { MCP_SERVER_ROOT_DIR: /path/to/your/safe/project/root } } } }配置解析command: 这里必须指向你虚拟环境中的Python解释器绝对路径以确保能加载所有依赖。使用which python或where python在激活的虚拟环境中来获取。args: 指向我们刚写的server.py的绝对路径。env: 设置环境变量MCP_SERVER_ROOT_DIR这是我们的安全沙箱根目录。务必将其设置为你希望AI访问的项目目录比如你的代码仓库根目录。4.2 验证与使用保存mcp.json。完全重启Cursor。这是关键一步配置只在启动时加载。重启后打开Cursor的Chat面板通常是Cmd/Ctrl K。你可以尝试输入“你能用什么工具”或者“列出当前目录的文件”。如果配置成功Claude会回复它已连接到一个文件服务器并可以调用list_directory等工具。进一步测试“请读取server.py文件的内容”或“在根目录创建一个名为test_from_ai.md的文件内容为‘# Hello AI’”。当你看到AI不仅能回答还能实际执行文件操作时恭喜你最核心的一步已经完成了5. 生产级部署Docker化与持续集成本地能跑离在任何地方都能稳定运行还差一个“集装箱”——Docker。容器化能解决“在我机器上好好的”这类环境依赖问题。5.1 编写Dockerfile在项目根目录创建Dockerfile# 使用官方Python精简版镜像 FROM python:3.11-slim as builder WORKDIR /app # 安装系统依赖如有需要例如用于编译某些Python包 RUN apt-get update apt-get install -y --no-install-recommends \ gcc \ rm -rf /var/lib/apt/lists/* # 复制依赖文件并安装 COPY requirements.txt . RUN pip install --no-cache-dir --user -r requirements.txt # 第二阶段运行阶段使用更小的基础镜像 FROM python:3.11-slim WORKDIR /app # 从构建阶段复制已安装的Python包 COPY --frombuilder /root/.local /root/.local # 确保脚本可找到已安装的包 ENV PATH/root/.local/bin:$PATH # 复制应用代码 COPY server.py . # 创建一个非root用户运行应用增强安全性 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser # 设置默认的环境变量可在运行时覆盖 ENV MCP_SERVER_ROOT_DIR/workspace ENV PYTHONUNBUFFERED1 # 声明容器以stdio模式运行 ENTRYPOINT [python, server.py]这个Dockerfile采用了两阶段构建最终镜像更小。它设置了非root用户是一个重要的安全实践。5.2 构建与运行容器在Dockerfile同级目录下执行构建docker build -t mcp-file-server:latest .构建完成后可以运行测试# 将当前目录挂载到容器的 /workspace作为根目录 docker run -it --rm \ -v $(pwd):/workspace \ -e MCP_SERVER_ROOT_DIR/workspace \ mcp-file-server:latest你应该看到服务器启动的日志信息。现在我们需要修改Cursor的配置让它调用这个容器内的服务器。5.3 配置Cursor调用Docker容器这需要一点技巧因为Cursor需要启动一个命令而这个命令需要启动Docker容器并与之进行stdio通信。我们可以写一个简单的包装脚本。创建一个脚本文件run_server.shLinux/Mac或run_server.batWindowsLinux/Mac (run_server.sh):#!/bin/bash # 确保传递所有参数给docker run docker run -i --rm \ -v /absolute/path/to/your/project:/workspace \ -e MCP_SERVER_ROOT_DIR/workspace \ mcp-file-server:latest记得给脚本执行权限chmod x run_server.shWindows (run_server.bat):echo off docker run -i --rm ^ -v C:\path\to\your\project:/workspace ^ -e MCP_SERVER_ROOT_DIR/workspace ^ mcp-file-server:latest然后更新Cursor的mcp.json配置将command指向这个包装脚本{ mcpServers: { file-system-server-docker: { command: /absolute/path/to/your/mcp-file-server/run_server.sh, args: [], env: {} } } }这样Cursor启动时就会执行这个脚本脚本负责启动Docker容器并将stdio管道连接起来。这种方式实现了完全容器化的部署服务器环境纯净且一致。5.4 进阶结合持续集成/部署CI/CD对于团队协作或需要频繁更新的场景可以将Docker镜像推送到镜像仓库如Docker Hub、GitHub Container Registry并在CI/CD流水线中自动构建。一个简单的GitHub Actions工作流示例.github/workflows/build.ymlname: Build and Push Docker Image on: push: branches: [ main ] tags: [ v* ] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Log in to Docker Hub uses: docker/login-actionv3 with: username: ${{ secrets.DOCKER_USERNAME }} password: ${{ secrets.DOCKER_TOKEN }} - name: Build and push Docker image uses: docker/build-push-actionv5 with: context: . push: true tags: | yourdockerhubusername/mcp-file-server:latest yourdockerhubusername/mcp-file-server:${{ github.sha }}这样每次推送到主分支都会自动构建并推送最新的Docker镜像。团队其他成员只需拉取最新镜像即可无需关心本地Python环境。6. 常见问题与深度排查指南在实际开发和集成过程中你几乎一定会遇到一些问题。下面是我踩过坑后总结的排查清单。6.1 服务器启动失败症状Cursor聊天框提示无法连接服务器或直接报错。排查步骤检查命令路径mcp.json中的command和args必须是绝对路径。使用which python确认虚拟环境Python路径。手动测试命令在终端中完整运行你在mcp.json中配置的命令行包括command和args看是否能正常启动并打印出初始化信息如我们代码中print的提示。如果报错“ModuleNotFoundError: No module named mcp”说明Python环境不对依赖没安装。检查文件权限确保脚本文件有可执行权限仅Linux/Mac并且当前用户有权访问。查看Cursor日志Cursor通常有开发者控制台或日志文件。在设置中开启详细日志查看是否有关于MCP服务器启动失败的更具体错误信息。6.2 工具调用无响应或报错症状AI说连接了服务器但调用工具时没反应或返回权限错误、路径错误。排查步骤验证根目录权限确保MCP_SERVER_ROOT_DIR指向的目录存在且运行服务器的用户在Docker中是appuser对该目录有读写权限。在Docker中特别注意挂载卷的权限问题主机用户ID可能与容器内用户ID1000不匹配导致“Permission denied”。可以在Docker run时加上-u $(id -u):$(id -g)来使用主机用户ID。检查路径安全校验故意在AI请求中使用../../../etc/passwd这样的路径看服务器是返回了拒绝访问的错误还是真的返回了内容。如果返回了内容说明你的_validate_path函数有安全漏洞。启用调试日志在服务器代码中将日志级别调到DEBUG或者增加更多logger.debug语句输出收到的请求参数、处理后的安全路径等。这能帮你看清数据流动。6.3 Docker容器内路径问题症状在Docker模式下AI工具返回“路径不存在”或“没有权限”但本地模式正常。排查步骤确认挂载卷docker run -v参数是否正确将主机项目目录挂载到了容器内的/workspace或你设定的目录进入容器检查使用docker run -it --rm --entrypoint/bin/bash your-image进入容器内部手动执行ls -la /workspace看看文件是否存在。环境变量传递确保MCP_SERVER_ROOT_DIR环境变量在Docker run命令中正确设置并且与Dockerfile或脚本中预期的目录一致。6.4 性能与资源优化当工具被频繁调用时你可能需要考虑性能。连接池与持久化目前的实现是每次调用都进行路径解析和文件IO。对于read_file这种操作如果频繁读取大文件可以考虑增加简单的基于LRU的内存缓存但要注意缓存一致性问题文件被外部修改。异步处理我们的工具函数使用了async def但文件IO本身是阻塞的。对于高性能场景可以考虑使用asyncio.to_thread将文件操作放到线程池中执行避免阻塞事件循环。不过对于轻量级操作当前方式通常足够。资源限制在Docker部署时可以通过--memory、--cpus等参数为容器设置资源上限防止单个MCP服务器占用过多主机资源。7. 扩展思路从文件服务器到万能助手一个基本的文件操作服务器只是起点。MCP协议的强大之处在于你可以将任何能力封装成工具。以下是一些扩展方向可以让你的AI助手能力倍增数据库查询服务器封装SQL查询工具让AI能直接查询项目数据库需严格限制为只读或特定安全操作获取实时数据来辅助决策。内部API网关将公司内部的项目管理、CI/CD、监控系统等API封装成工具。AI可以帮你创建工单、触发部署、查看服务状态。代码库分析器结合libcst或tree-sitter提供“查找函数引用”、“分析类结构”等高级代码理解工具让AI的代码重构建议更有上下文。自定义搜索集成Elasticsearch或Meilisearch为你的知识库或代码库提供专属的语义搜索工具。与OAuth集成为需要认证的外部服务如GitHub、Jira提供安全的OAuth流程。注意这需要仔细设计通常需要一个轻量的Web服务器来处理回调。MCP服务器本身stdio模式不适合直接处理HTTP回调但可以启动一个临时的本地HTTP服务或与已有的认证守护进程通信。核心原则是绝不将敏感令牌硬编码或明文传输。开发这些扩展时安全仍然是第一要务。始终遵循最小权限原则为每个工具设定清晰的、受限的操作边界并对所有输入进行严格的验证和清理。走到这一步你已经拥有了一个完全受控、可扩展、生产就绪的AI能力扩展底座。下次当AI说“我无法访问你的本地文件”时你可以自信地告诉它“不现在你可以了。”