MCP Document Server

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

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

🎯 目的

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

📋 機能

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

1. get_document - 指定されたドキュメントを取得
2. list_documents - 利用可能なドキュメントのリストを表示
3. 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通信では print() は使用禁止です！

# ❌ これは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ツールを使用してドキュメントを取得し、内容を説明)

🤝 コントリビューション

プルリクエスト歓迎！

📄 ライセンス

[ライセンスを記載してください]

🔗 参考リンク

• Model Context Protocol
• MCP Python SDK
• Claude Desktop