MCP Document Server

効率的なドキュメント配信のためのModel Context Protocol (MCP) サーバー

プロジェクトのドキュメントをAIエージェント（Claude等）に必要に応じて提供し、トークン使用量を最適化します。

🎯 目的

プロジェクトのドキュメントを効率的にAIエージェントに配信
必要な時だけコンテキストを読み込み、トークン使用量を削減
チーム内で簡単に共有できる構成

📋 機能

MCPツール（AIが使用可能な機能）

get_document - 指定されたドキュメントを取得
list_documents - 利用可能なドキュメントのリストを表示
search_in_document - ドキュメント内でキーワードを検索

セキュリティ機能

パストラバーサル攻撃対策
ファイルサイズ制限
入力バリデーション
安全なエンコーディング処理

🚀 クイックスタート

必要要件

Python 3.10以上
Poetry（推奨）または pip
Docker（オプション、チーム配布用）

インストール

1. Poetry を使用（推奨）

# リポジトリをクローン git clone <your-repo-url> cd mcp_python # 依存関係をインストール poetry install # 開発依存関係も含む poetry install

2. pipを使用

pip install -e .

サーバーの起動

ローカル実行

# ドキュメントディレクトリを指定 export MCP_DOCS_DIR=/path/to/your/documents # サーバー起動 poetry run python -m mcp_server.main # または Makefile を使用 make run

Docker で実行

# イメージをビルド docker build -t mcp-document-server:latest . # 実行（docsディレクトリをマウント） docker run -it --rm \ -v $(PWD)/docs:/app/docs:ro \ mcp-document-server:latest # または Makefile を使用 make docker-build make docker-run

Docker Compose で実行

docker-compose up -d

🔧 Claude Desktop との連携

設定ファイル

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

ローカル実行の場合

{ "mcpServers": { "document-server": { "command": "poetry", "args": ["run", "python", "-m", "mcp_server.main"], "env": { "MCP_DOCS_DIR": "/path/to/your/documents" } } } }

Docker実行の場合

{ "mcpServers": { "document-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/to/your/documents:/app/docs:ro", "mcp-document-server:latest" ] } } }

🧪 テスト

テストの実行

# すべてのテストを実行 poetry run pytest # カバレッジ付きで実行 poetry run pytest --cov=src/mcp_server --cov-report=html # または Makefile を使用 make test make test-cov

MCP Inspector でテスト

サーバーをインタラクティブにテストできます：

npx @modelcontextprotocol/inspector poetry run python -m mcp_server.main # または Makefile を使用 make inspect

📁 プロジェクト構造

mcp_python/ ├── src/ │ └── mcp_server/ │ ├── __init__.py │ ├── server.py # メインサーバー │ ├── main.py # エントリーポイント │ ├── tools/ │ │ └── document.py # ドキュメントツール │ ├── resources/ │ │ └── file_handler.py # 安全なファイル操作 │ └── utils/ │ └── logging.py # ロギング設定 ├── tests/ # テストファイル ├── docs/ # ドキュメントディレクトリ ├── Dockerfile # Docker設定 ├── docker-compose.yml # Docker Compose設定 ├── pyproject.toml # プロジェクト設定 ├── pytest.ini # Pytest設定 ├── Makefile # 便利コマンド └── README.md

🛠️ 開発

コードフォーマット

# リンター実行 poetry run ruff check src/ tests/ # 自動フォーマット poetry run ruff format src/ tests/ # または Makefile を使用 make lint make format

クリーンアップ

make clean

📦 チーム配布

Docker Hub へのプッシュ

# イメージをビルド docker build -t your-org/mcp-document-server:latest . # Docker Hub にログイン docker login # プッシュ docker push your-org/mcp-document-server:latest

チームメンバー側の設定

# イメージを取得 docker pull your-org/mcp-document-server:latest

Claude Desktop の設定：

{ "mcpServers": { "document-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/to/documents:/app/docs:ro", "your-org/mcp-document-server:latest" ] } } }

⚠️ 重要な注意事項

ロギング

STDIO通信では

# ❌ これはNG（JSON-RPCメッセージが壊れる） print("Debug message") # ✅ これはOK logger.info("Debug message") # stderr に出力

ファイルパス

ドキュメントは MCP_DOCS_DIR で指定したディレクトリ以下に配置
パストラバーサル攻撃を防ぐため、ディレクトリ外へのアクセスは拒否されます

📝 使用例

Claudeでの利用

ユーザー: プロジェクトのドキュメントにはどんなものがありますか？ Claude: (list_documentsツールを使用) 以下のドキュメントが利用可能です： - README.md - docs/api.md - docs/setup.md ユーザー: setup.mdの内容を教えてください Claude: (get_documentツールを使用してドキュメントを取得し、内容を説明)