Code AST MCP Server (code-ast-mcp)

code-ast-mcp は、Python 標準の抽象構文木 (ast) パーサーで構築されたアーキテクチャ用 Model Context Protocol (MCP) サーバーです。Claude Desktop、Cursor、Antigravity、またはカスタム MCP クライアント内の AI モデルが、ローカルの Python コードベース構造の分析、シンボル定義の検索、依存関係グラフの構築、docstring カバレッジの監査、コードのリファクタリングを、生のソースファイル全体を LLM コンテキストウィンドウに読み込むことなく実行できるようにします。

🔗 ライブリポジトリ: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Smithery レジストリ: https://smithery.ai/servers/sameerbalouch758/code-ast-mcp

⚡ 機能と特徴

🛠️ ツール

1. analyze_file_ast(file_path: str)

   • .py ファイルをクリーンな AST アウトラインに解析します。

   • モジュールの docstring、行数、インポート、トップレベル関数、クラス、メソッド、変数を抽出します。

2. find_class_methods(file_path: str, class_name: str)

   • 特定のクラスを特定し、メソッドシグネチャ、型アノテーション、行範囲、docstring を返します。

3. find_symbol(target_dir: str, symbol_name: str)

   • ディレクトリを再帰的に検索し、symbol_name に一致するクラス、関数、メソッド、または変数代入を探します。

4. get_imports_graph(target_dir: str)

   • Python ファイルをスキャンして依存関係のインポートマップを構築し、Mermaid ダイアグラム文字列を出力します。

5. find_missing_docstrings(target_dir: str, include_private: bool = False)

   • コードベースの docstring を監査し、全体的な docstring カバレッジ率を計算します。

📝 プロンプト

• refactor_code_summary(file_path: str)

  • LLM にファイルの AST アウトラインをレビューさせ、リファクタリング、デザインパターンの改善、ドキュメント修正を提案させる構造化プロンプトを生成します。

📊 リソース

• codeast://stats

  • ワークスペースの統計情報（スキャンされたファイル総数、docstring カバレッジ率、欠落項目数）を提供するライブ JSON リソース。

Related MCP server: codeweave-mcp

🚀 クイックスタートとインストール

オプション 1: Smithery CLI でインストール

smithery mcp add sameerbalouch758/code-ast-mcp

オプション 2: ソースからのローカルインストール

リポジトリをクローンし、依存関係を編集可能モードでインストールします：

git clone https://github.com/m-sameerkhan/code-ast-mcp.git
cd code-ast-mcp

# Create & activate virtual environment (or Conda)
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install project and dependencies
pip install -r requirements.txt
pip install -e .

オプション 3: MCP バンドル (.mcpb) としてパッケージ化

MCP バンドルをサポートするデスクトップクライアント（Claude Desktop など）向け：

# Install MCPB toolchain
npm install -g @anthropic-ai/mcpb

# Build bundle
mcpb pack . code-ast-mcp.mcpb

🧪 ローカルでのテスト

ユニットテストの実行

pytest

MCP Inspector でのテスト

公式の MCP Inspector を使用して、ツールとリソースを対話的にテストします：

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

⚙️ クライアント設定

Claude Desktop / Cursor / Antigravity との統合

code-ast-mcp をクライアント設定ファイル（claude_desktop_config.json または mcp_config.json）に追加します：

{
  "mcpServers": {
    "code-ast-mcp": {
      "command": "python",
      "args": [
        "-m",
        "code_ast_mcp.server"
      ],
      "cwd": "/path/to/code-ast-mcp"
    }
  }
}

Windows ユーザーへの注意："command" を仮想環境または Conda の Python パス（例：C:/Users/<Username>/.conda/envs/code-ast-mcp/python.exe または D:/my_mcp/.venv/Scripts/python.exe）に指定できます。

📦 プロジェクト構造

code-ast-mcp/
├── code_ast_mcp/          # Core package
│   ├── __init__.py        # Package exports
│   ├── analyzer.py        # Python AST parsing & static analysis engine
│   └── server.py          # FastMCP server definition & tool handlers
├── tests/                 # Test suite
│   └── test_analyzer.py   # Unit tests with pytest
├── manifest.json          # MCPB extension manifest
├── smithery.yaml          # Smithery registry configuration
├── Dockerfile             # Container image definition
├── pyproject.toml         # Packaging & metadata
└── requirements.txt       # Dependencies

📄 ライセンス

MIT ライセンス。m-sameerkhan によって作成されました。