MCP Docs Tools

MCP ドキュメントツール

Python プロジェクト向けに、ドキュメント生成に特化した 3 つのツールを提供する Node.js ベースの MCP（Model Context Protocol）ツールサーバーです。Git リポジトリから直接インストールできる npm パッケージとして構築されています。

機能

🔧 強力な 3 つのツール

1. create_class_diagram - Python ファイルを解析し、PlantUML 形式で UML クラス図を生成します
2. create_tree_structure - スマートな除外機能を備えた、見やすいディレクトリツリー構造のドキュメントを作成します
3. create_module_functions - モジュールレベルの関数を、シグネチャ、デコレーター、型ヒントとともにドキュメント化します

🚀 主なメリット

• 設定不要：妥当なデフォルト設定で、すぐに利用できます
• スマートな除外機能：キャッシュ、ビルド、IDE のファイルを自動的に除外します
• 充実したドキュメント：型ヒント、デコレーター、docstring、継承関係を記録します
• MCP 連携：Model Context Protocol を介して AI アシスタントとシームレスに連携します
• ハイブリッドアーキテクチャ：Node.js によるオーケストレーションと、信頼性の高い Python AST 解析を組み合わせています

インストール

Git リポジトリからのインストール（推奨）

# Clone the repository
git clone https://github.com/your-username/mcp-docs-tools.git
cd mcp-docs-tools

# Install dependencies
npm install

# Install globally (optional)
npm install -g .

# Or run directly
npm start

Git から直接インストール

# Install directly from GitHub
npm install -g git+https://github.com/your-username/mcp-docs-tools.git

# Then run
mcp-docs-tools

ローカル開発

git clone https://github.com/your-username/mcp-docs-tools.git
cd mcp-docs-tools
npm install
npm start

要件

• Node.js ≥18.0.0
• Python 3.x（AST 解析用）
• Git（リポジトリのクローン用）

Python インタープリターの検出と Windows のサポート

サーバーは実行時に、利用可能な Python 3 インタープリターを自動的に検出します。Windows では、py -3 が利用可能な場合は優先して使用し、Python 3 として解決される python または python3 にフォールバックします。macOS/Linux では、python3 を優先し、Python 3 として解決される場合は python にフォールバックします。

Python 3 インタープリターが見つからない場合は、対処方法を示すエラーが表示されます。

「Python 3 interpreter not found. Install Python 3 or set MCP_PYTHON (and optional MCP_PYTHON_ARGS). Tried: ...」

環境変数による上書き（任意）

インタープリターと引数を明示的に指定できます。

• MCP_PYTHON：コマンドまたは絶対パス（例：py、python3、C:\\Python312\\python.exe）
• MCP_PYTHON_ARGS：スペース区切りの引数（例：-3）

例：

# Windows PowerShell
$env:MCP_PYTHON = "python"
$env:MCP_PYTHON_ARGS = "-3"
npm start

# macOS/Linux bash
export MCP_PYTHON=py
export MCP_PYTHON_ARGS=-3
npm start

使い方

MCP サーバーとして

サーバーを起動して、Model Context Protocol 経由でツールを公開します。

# If installed globally
mcp-docs-tools

# Or from the project directory
npm start

# Or run directly with node
node bin/server.js

サーバーは stdin/stdout で待ち受け、MCP クライアントから呼び出せる 3 つのツールを公開します。

ツールの仕様

1. create_class_diagram

目的：Python コードから UML クラス図を生成します

パラメーター：

• project_path（string、必須）：解析する Python プロジェクトのルートパス

出力：

• ファイル：docs/uml.txt
• 形式：PlantUML 構文
• 内容：クラス、public/private メソッド、属性、継承関係

例：

@startuml
class MyClass {
  +public_attr: str
  -_private_attr: int
  --
  +__init__(self, name: str)
  +public_method(self, arg: int): bool
  -{static} _private_method(): None
}
@enduml

2. create_tree_structure

目的：プロジェクトのディレクトリツリー構造を生成します

パラメーター：

• project_path（string、必須）：解析するプロジェクトのルートパス

出力：

• ファイル：docs/tree-structure.txt
• 形式：Unicode の罫線文字によるツリー
• 内容：スマートな除外機能を備えた、完全なファイル／ディレクトリ構造

例：

my-project
├── src/
│   ├── main.py
│   └── utils/
│       └── helpers.py
├── tests/
│   └── test_main.py
└── README.md

3. create_module_functions

目的：モジュールレベルの関数とシグネチャをドキュメント化します

パラメーター：

• project_path（string、必須）：解析する Python プロジェクトのルートパス

出力：

• ファイル：docs/module-functions.txt
• 形式：階層構造の Markdown ドキュメント
• 内容：モジュールごとに整理された関数と、完全なシグネチャ、デコレーター、docstring

例：

## Module: src.utils.helpers

### `async def process_data(data: List[str], timeout: int = 30) -> Dict[str, Any]`

**Decorators:**
- `@retry(max_attempts=3)`

**Description:**
Process a list of data items with optional timeout.

**Line:** 42

アーキテクチャ

Node.js と Python のハイブリッド方式

このツールは、両方の利点を組み合わせたハイブリッドアーキテクチャを採用しています。

• Node.js サーバー：MCP プロトコル、ツール登録、プロセスのオーケストレーションを処理します
• Python スクリプト：堅牢な AST 解析とドキュメント生成を行います
• 明確な分離：プロトコル処理と解析ロジックを分離しています

プロジェクト構成

mcp-docs-tools/
├── package.json              # npm package configuration
├── bin/
│   └── server.js             # Main MCP server entry point
├── src/
│   ├── server.js             # MCP server implementation
│   ├── tools/                # Tool implementations
│   │   ├── class-diagram.js  # UML generation wrapper
│   │   ├── tree-structure.js # Tree generation wrapper
│   │   └── module-functions.js # Function docs wrapper
│   └── config/
│       └── exclusions.js     # Default exclusion patterns
├── python/
│   ├── generate_uml.py       # Python AST parsing for classes
│   ├── generate_tree.py      # Directory tree generation
│   ├── generate_functions.py # Function parsing and documentation
│   └── requirements.txt      # Python dependencies (none needed)
└── README.md

スマートな除外機能

ツールは、ドキュメント化に適さない一般的なファイルやディレクトリを自動的に除外します。

Python

• __pycache__、*.pyc、*.pyo、*.pyd
• build、dist、eggs、*.egg-info
• 仮想環境：venv、.venv、env、virtualenv

開発ツール

• バージョン管理：.git、.svn、.hg
• IDE：.idea、.vscode、.cursor
• テスト：.pytest_cache、.coverage、.tox

ビルドとパッケージマネージャー

• node_modules、target、out、bin
• package-lock.json、yarn.lock、Pipfile.lock

OS と一時ファイル

• .DS_Store、Thumbs.db、*.tmp、*.log

AI アシスタントとの統合

Cursor IDE

設定は、ツールのインストール方法によって異なります。

オプション A：リポジトリをクローンした場合（推奨）

プロジェクト内に .cursorrules ファイルを作成し、Cursor MCP の設定に以下を追加します。

{
  "mcpServers": {
    "docs-tools": {
      "command": "node",
      "args": ["/path/to/mcp-docs-tools/bin/server.js"],
      "cwd": "/path/to/mcp-docs-tools"
    }
  }
}

/path/to/mcp-docs-tools を、リポジトリをクローンした実際のパスに置き換えてください。

例：

• macOS/Linux："/Users/yourname/projects/mcp-docs-tools"
• Windows："C:\\Users\\yourname\\projects\\mcp-docs-tools"

オプション B：npm install -g でグローバルにインストールした場合

{
  "mcpServers": {
    "docs-tools": {
      "command": "mcp-docs-tools"
    }
  }
}

.cursorrules ファイルの内容（すべてのインストール方法向け）

Python プロジェクト内に、この .cursorrules ファイルを作成します。

# Documentation Tools Integration

## Available MCP Tools
- `create_class_diagram` - Generate UML class diagrams  
- `create_tree_structure` - Generate directory tree
- `create_module_functions` - Document module functions

## Usage
Run these tools at session start to generate documentation in `docs/` directory.
Reference the generated files to understand codebase structure.

## Generated Files
- `docs/uml.txt` - PlantUML class diagrams
- `docs/tree-structure.txt` - Directory structure  
- `docs/module-functions.txt` - Function documentation

Claude Desktop

オプション A：リポジトリをクローンした場合（推奨）

Claude Desktop MCP の設定に以下を追加します。

{
  "mcpServers": {
    "docs-tools": {
      "command": "node",
      "args": ["/path/to/mcp-docs-tools/bin/server.js"],
      "cwd": "/path/to/mcp-docs-tools"
    }
  }
}

/path/to/mcp-docs-tools を、リポジトリをクローンした実際のパスに置き換えてください。

オプション B：npm install -g でグローバルにインストールした場合

{
  "mcpServers": {
    "docs-tools": {
      "command": "mcp-docs-tools"
    }
  }
}

クイックセットアップガイド

1. クローンしてインストールする（推奨）：

   git clone https://github.com/your-username/mcp-docs-tools.git
   cd mcp-docs-tools
   npm install
   

2. インストール先のパスを確認する：

   pwd
   # Copy this path for your MCP configuration
   

3. 手順 2 で確認したパスで MCP の設定を更新する

4. Python プロジェクトでツールをテストする！

エラー処理

ツールには、包括的なエラー処理が含まれています。

• Python プロセスの失敗：stdout/stderr を含む詳細なエラーメッセージ
• 依存関係の不足：Python のインストールに関する明確な手順
• ファイル権限の問題：わかりやすいメッセージを表示し、適切に処理
• 無効なプロジェクトパス：処理前にパスを検証

パフォーマンス

• 軽量：短時間で終了する Python プロセスにより、メモリ使用量を最小限に抑えます
• 高速：スマートなファイルフィルタリングを備えた効率的な AST 解析
• スケーラブル：数千のファイルを含む大規模なコードベースにも対応
• 並行実行：複数のツールを同時に実行できます

コントリビューション

1. リポジトリをフォークする
2. フィーチャーブランチを作成する
3. 変更を加える
4. 該当する場合はテストを追加する
5. プルリクエストを送信する

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

サポート

• 問題：GitHub でバグや機能リクエストを報告してください
• ドキュメント：リポジトリで完全な API ドキュメントを確認できます
• 例：examples ディレクトリにサンプルプロジェクトと使用例があります

---

Python 開発コミュニティのために ❤️ を込めて作成