MCP File Reader Server

This project provides a simple MCP (Model-Control-Protocol) server for reading files, runnable in two modes:

1. Stdio Mode (file-reader): Managed by Cursor via global config.
2. SSE Mode (file-reader-sse): Runs independently via manual start.

Setup Instructions

1. Prerequisites

- Python 3.8 or higher
- Cursor app installed
- pip package manager

2. Installation

1. Clone or download this repository
2. Create a virtual environment:

   python3 -m venv venv

   

   source venv/bin/activate  # On macOS/Linux

   venv\Scripts\activate  # On Windows

   

   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. Configuration

Option 1: Configure Cursor for Stdio Mode (file-reader)

To let Cursor manage the stdio server:

1. Edit your global MCP config file:
- macOS: ~/Library/Application Support/Cursor/cursor_mcp_config.json
- Windows: %APPDATA%\Cursor\cursor_mcp_config.json
- Linux: ~/.config/Cursor/cursor_mcp_config.json
2. Ensure an entry exists for file-reader, pointing to the correct venv Python and the main file_reader_server.py script:

    {

      "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 ...

      }

    }

    

Option 2: Configure Project for SSE Discovery (file-reader-sse)

The project-local .mcp.json file is already configured to describe the SSE server (file-reader-sse) running at http://127.0.0.1:8080. Note that the client will likely need to connect to the /sse subpath (http://127.0.0.1:8080/sse).

Data Directory

- The stdio server (file-reader) uses ~/mcp_data by default (in your home directory).
- The SSE server (file-reader-sse) uses ./project_mcp_data_sse by default (within this project directory).

Make sure these directories exist before running the respective servers. The ./start_sse.sh script will create ./project_mcp_data_sse if it's missing.

4. Running the Server

Choose one method:

Method A: Stdio Mode (file-reader via Cursor)

1. Complete the global configuration (Option 1 above).
2. Restart Cursor.
3. Go to Cursor Settings -> MCP.
4. Find file-reader and toggle it ON.

Method B: SSE Mode (file-reader-sse Manually)

Use the provided start script. In your terminal:

./start_sse.sh

This script ensures dependencies (including uvicorn, starlette) are installed and runs the Uvicorn ASGI server, loading the Starlette app defined in file_reader_server_sse.py. The Starlette app mounts the MCP server's SSE handler (mcp.sse_app()) at the root path.

The server will start listening on http://127.0.0.1:8080.

5. Using the Server in Cursor

- If using Stdio Mode (Method A):
Reads from ~/mcp_data:

  read test.txt using the file-reader server

  

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

  

6. Using the SSE Client Script (Manual Testing)

This project includes a Python client script (file_reader_sse_client.py) and a wrapper shell script (run_sse_client.sh) to test the SSE server independently using the mcp library's SSE client capabilities.

1. Ensure the SSE server is running (use ./start_sse.sh).
2. Run the client wrapper script in your terminal:

    # 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

    

_(The wrapper script ensures dependencies like httpx are installed and uses the correct Python.)_

3. The client will connect to http://127.0.0.1:8080/sse, initialize the MCP session, call the read_file tool by name, and print the response or any errors.

Troubleshooting

- Stdio: Check Cursor Settings -> MCP for status (green dot), verify global config paths, check stderr via Cursor logs if startup fails.
- SSE: Ensure the server is running manually (use ./start_sse.sh), check its terminal output (stderr) for errors, verify the client can reach http://127.0.0.1:8080/sse.
- Restart Cursor after config changes.

Advanced Usage

- The stdio server uses file_reader_server.py.
- The sse server uses file_reader_server_sse.py.
- Logging is to stderr for both.
- A basic client for the SSE server is provided in file_reader_sse_client.py.
- A startup script for the SSE server is provided: start_sse.sh.
- The SSE server uses Starlette to mount the MCP SSE application (mcp.sse_app()) which is then run by Uvicorn via start_sse.sh.
- A wrapper script for the SSE client is provided: run_sse_client.sh.
- The SSE client script uses mcp.client.sse.sse_client and mcp.ClientSession to interact with the server.

License

MIT

Server Details

- file-reader (Stdio):
- Script: file_reader_server.py
- Transport: Stdio
- Management: Via Cursor global config (~/.cursor/mcp.json) & Settings toggle.
- Rules: 00-MCP-Server-Rules.txt, 00-MCP-Client-Rules.txt
- Data Dir: ~/mcp_data
- file-reader-sse (SSE):
- Script: file_reader_server_sse.py (defines FastMCP instance and Starlette app)
- Transport: SSE via Starlette/Uvicorn (listens on http://127.0.0.1:8080, client connects to /sse path)
- Management: Manual start/stop via start_sse.sh (runs uvicorn ...:app).
- Discovery: Via project .mcp.json.
- Rules: 00-MCP-SSE-Server-Rule.txt, 00-MCP-SSE-Client-Rule.txt
- Data Dir: ./project_mcp_data_sse (relative to project root)