MCP File Reader Server

MCP File Reader Server

このプロジェクトは、ファイルを読み取るためのシンプルな MCP（Model-Control-Protocol）サーバーを、次の 2 つのモードで実行できるように提供します。

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 のエントリが存在し、適切な仮想環境の 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 を使用します。

各サーバーを実行する前に、これらのディレクトリが存在することを確認してください。./start_sse.sh スクリプトは、./project_mcp_data_sse が存在しない場合に作成します。

4. サーバーの実行

次のいずれか 1 つ の方法を選択します。

方法 A：Stdio モード（Cursor 経由の file-reader）

1. グローバル設定（上記オプション 1）を完了します。
2. Cursor を再起動します。
3. Cursor Settings -> MCP に移動します。
4. file-reader を見つけて ON に切り替えます。

方法 B：SSE モード（手動で file-reader-sse を実行）

付属の起動スクリプトを使用します。ターミナルで次を実行します。

./start_sse.sh

このスクリプトは、依存関係（uvicorn、starlette を含む）がインストールされていることを確認し、file_reader_server_sse.py で定義された Starlette app を読み込んで Uvicorn ASGI サーバーを実行します。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 クライアントスクリプトの使用（手動テスト）

このプロジェクトには、mcp ライブラリの SSE クライアント機能を使って SSE サーバーを単独でテストするための Python クライアントスクリプト（file_reader_sse_client.py）とラッパーシェルスクリプト（run_sse_client.sh）が含まれています。

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()）をマウントし、その後 start_sse.sh 経由で Uvicorn によって実行します。
• 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（プロジェクトルートからの相対パス）