MCP File Reader Server

MCP 文件读取器服务

本项目提供了一个简单的 MCP（Model-Control-Protocol）文件读取服务，可通过两种模式运行：

1. Stdio 模式（file-reader）： 由 Cursor 通过全局配置管理。
2. SSE 模式（file-reader-sse）： 通过手动启动独立运行。

设置说明

1. 前置条件

• Python 3.8 或更高版本
• 已安装 Cursor 应用
• pip 包管理器

2. 安装

1. 克隆或下载此仓库
2. 创建虚拟环境：

   python3 -m venv venv
   

3. 激活虚拟环境：

   source venv/bin/activate  # On macOS/Linux
   venv\Scripts\activate  # On Windows
   

4. 安装所需的软件包：

   pip install mcp
   # Uvicorn & Starlette are needed for running the SSE server
   # httpx is needed for the SSE client
   pip install "uvicorn[standard]" starlette httpx
   

3. 配置

选项 1：为 Stdio 模式（file-reader）配置 Cursor

要让 Cursor 管理 stdio 服务：

1. 编辑全局 MCP 配置文件：
   • macOS：~/Library/Application Support/Cursor/cursor_mcp_config.json
   • Windows：%APPDATA%\Cursor\cursor_mcp_config.json
   • Linux：~/.config/Cursor/cursor_mcp_config.json
2. 确保存在 file-reader 条目，并指向正确的 venv Python 和主脚本 file_reader_server.py：

   {
     "mcpServers": {
       "file-reader": {
         // Server name for stdio mode
         "command": "/FULL/PATH/TO/YOUR/PROJECT/venv/bin/python",
         "args": [
           "/FULL/PATH/TO/YOUR/PROJECT/mcp-file-reader-example/file_reader_server.py"
         ],
         "enabled": true,
         "env": {}
       }
       // ... other servers ...
     }
   }
   

3. (请参阅此仓库中的 cursor_mcp_config.json 模板)

选项 2：配置项目以发现 SSE 服务（file-reader-sse）

项目本地的 .mcp.json 文件已配置为描述运行在 http://127.0.0.1:8080 的 SSE 服务（file-reader-sse）。请注意，客户端可能需要连接到 /sse 子路径（http://127.0.0.1:8080/sse）。

数据目录

• stdio 服务（file-reader）默认使用 ~/mcp_data（位于你的主目录中）。
• SSE 服务（file-reader-sse）默认使用 ./project_mcp_data_sse（位于此项目目录中）。

运行相应服务之前，请确保这些目录存在。若 ./project_mcp_data_sse 不存在，./start_sse.sh 脚本会创建该目录。

4. 运行服务

选择一种方式：

方法 A：Stdio 模式（通过 Cursor 运行 file-reader）

1. 完成全局配置（上方的选项 1）。
2. 重启 Cursor。
3. 前往 Cursor 设置 -> MCP。
4. 找到 file-reader 并将其切换为开启状态。

方法 B：SSE 模式（手动运行 file-reader-sse）

使用提供的启动脚本。在终端中运行：

./start_sse.sh

此脚本会确保依赖项（包括 uvicorn、starlette）已安装，并运行 Uvicorn ASGI 服务，加载 file_reader_server_sse.py 中定义的 Starlette app。Starlette 应用会将 MCP 服务的 SSE 处理器（mcp.sse_app()）挂载到根路径。

服务将开始监听 http://127.0.0.1:8080。

5. 在 Cursor 中使用服务

• 如果使用 Stdio 模式（方法 A）： 从 ~/mcp_data 读取：

  read test.txt using the file-reader server
  

• 如果使用 SSE 模式（方法 B）： 假设 Cursor 通过 .mcp.json 发现该服务。从 ./project_mcp_data_sse 读取：

  read sse_test.txt using the file-reader-sse server
  

  (注意：请使用指定的服务名称 file-reader-sse，以及 ./project_mcp_data_sse 中预期存在的文件名)

6. 使用 SSE 客户端脚本（手动测试）

本项目包含一个 Python 客户端脚本（file_reader_sse_client.py）和一个包装 shell 脚本（run_sse_client.sh），用于通过 mcp 库的 SSE 客户端功能独立测试 SSE 服务。

1. 确保 SSE 服务正在运行（使用 ./start_sse.sh）。

2. 在终端中运行客户端包装脚本：

   # 连接、初始化、列出工具，并为 sse_test.txt 调用 read_file
   ./run_sse_client.sh
   
   # 尝试读取其他文件（例如 another_sse.txt）
   ./run_sse_client.sh another_sse.txt
   

   （包装脚本会确保已安装 httpx 等依赖项，并使用正确的 Python。）

3. 客户端将连接到 http://127.0.0.1:8080/sse，初始化 MCP 会话，按名称调用 read_file 工具，并打印响应或任何错误。

故障排除

• Stdio： 检查 Cursor Settings -> MCP 中的状态（绿色圆点），确认全局配置路径；如果启动失败，请检查 Cursor 日志中的 stderr。
• SSE： 确保手动启动服务（使用 ./start_sse.sh），检查其终端输出（stderr）中的错误，并确认客户端可以访问 http://127.0.0.1:8080/sse。
• 修改配置后重启 Cursor。

高级用法

• stdio 服务使用 file_reader_server.py。
• sse 服务使用 file_reader_server_sse.py。
• 两者的日志均输出到 stderr。
• 项目提供了 SSE 服务的基础客户端 file_reader_sse_client.py。
• 项目提供了 SSE 服务的启动脚本：start_sse.sh。
• SSE 服务使用 Starlette 挂载 MCP SSE 应用（mcp.sse_app()），然后由 Uvicorn 通过 start_sse.sh 运行。
• 项目提供了 SSE 客户端的包装脚本：run_sse_client.sh。
• SSE 客户端脚本使用 mcp.client.sse.sse_client 和 mcp.ClientSession 与服务交互。

许可证

MIT

服务详情

• file-reader（Stdio）：
  • 脚本：file_reader_server.py
  • 传输方式：Stdio
  • 管理方式：通过 Cursor 全局配置（~/.cursor/mcp.json）和 Settings 开关。
  • 规则：00-MCP-Server-Rules.txt、00-MCP-Client-Rules.txt
  • 数据目录：~/mcp_data
• file-reader-sse（SSE）：
  • 脚本：file_reader_server_sse.py（定义 FastMCP 实例和 Starlette 应用）
  • 传输方式：通过 Starlette/Uvicorn 使用 SSE（监听 http://127.0.0.1:8080，客户端连接到 /sse 路径）
  • 管理方式：通过 start_sse.sh 手动启动/停止（运行 uvicorn ...:app）。
  • 发现方式：通过项目 .mcp.json。
  • 规则：00-MCP-SSE-Server-Rule.txt、00-MCP-SSE-Client-Rule.txt
  • 数据目录：./project_mcp_data_sse（相对于项目根目录）