File Reader Server Example

MCP文件读取器服务器

该项目提供了一个用于读取文件的简单MCP（模型控制协议）服务器，可在两种模式下运行：

1. 标准模式(file-reader): 由Cursor通过全局配置进行管理。
2. SSE模式(file-reader-sse): 通过手动启动独立运行。

安装说明

1.先决条件

• Python 3.8或更高版本
• 已安装光标应用程序
• pip包管理器

2.安装

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

   python3 -m venv venv

1. 激活虚拟环境：

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

1. 安装所需的软件包：

   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：为标准模式配置光标(file-reader)

让Cursor管理 stdio 服务器：

1. 编辑全局MCP配置文件：

- macOS: ~/Library/Application Support/Cursor/cursor_mcp_config.json - 视窗: %APPDATA%\Cursor\cursor_mcp_config.json - Linux: ~/.config/Cursor/cursor_mcp_config.json

1. 确保存在以下条目 file-reader，指向正确的venv Python和main 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 ...
     }
   }

1. _（参见 cursor_mcp_config.json 在此模板仓库中）_

选项2：为SSE发现配置项目(file-reader-sse)

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

数据目录

• 这 标准输入输出 服务器(file-reader)用途 ~/mcp_data 默认情况下（在您的主目录中）。
• 这 SSE 服务器(file-reader-sse)用途 ./project_mcp_data_sse 默认情况下（在此项目目录中）。

在运行相应的服务器之前，请确保这些目录存在。这 ./start_sse.sh 脚本将创建 ./project_mcp_data_sse 如果它不见了。

4.运行服务器

选择 一 方法：

方法A：标准模式(file-reader 通过光标）

1. 完成全局配置（上述选项1）。
2. 重新启动游标。
3. 转到光标设置->MCP。
4. 找到 file-reader 并将其打开。

方法B:SSE模式(file-reader-sse 手动）

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

./start_sse.sh

此脚本确保依赖关系（包括 uvicorn, starlette)安装并运行Uvicorn ASGI服务器，加载Starlette app 定义于 file_reader_server_sse.pyStarlette应用程序安装MCP服务器的SSE处理程序(mcp.sse_app())根路径。

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

5.在游标中使用服务器

• 如果使用标准模式（方法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客户端功能。

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

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

   # Connects, initializes, lists tools, and calls read_file for sse_test.txt
   ./run_sse_client.sh

   # Tries to read a different file (e.g., another_sse.txt)
   ./run_sse_client.sh another_sse.txt

_（包装器脚本确保依赖关系，如 httpx 安装并使用正确的Python。)_

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

故障排除

• 标准： 检查光标设置->MCP的状态（绿点），验证全局配置路径，检查 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 与服务器交互。

许可证

麻省理工学院

服务器详细信息

• file-reader （标准）：

- 脚本： file_reader_server.py - 运输：Stdio - 管理：通过游标全局配置(~/.cursor/mcp.json)&设置切换。 - 规则： 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（收听 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 （相对于项目根）