AST MCP Server

AST MCP サーバー

抽象構文木（AST）と抽象意味グラフ（ASG）を通じて、コード構造と意味解析の機能を提供する MCP（Model Context Protocol）サーバーです。

機能

• コードを抽象構文木（AST）に解析します
• コードから抽象意味グラフ（ASG）を生成します
• コードの構造と複雑さを分析します
• 複数のプログラミング言語（Python、JavaScript、TypeScript、Go、Rust、C/C++、Java）をサポートします
• Claude Desktop やその他の MCP クライアントと互換性があります
• 大きなファイルをより高速に処理するための増分解析に対応しています
• スコープ処理を強化し、より包括的な意味解析を行います
• AST の差分を取得し、コードのバージョン間の変更を特定します
• パフォーマンスを向上させるためにリソースをキャッシュします

インストール

前提条件

• Python 3.9 以降
• パッケージマネージャーの uv（推奨）または pip

uv を使用する場合（推奨）

1. このリポジトリをクローンします。

git clone https://github.com/angrysky56/ast-mcp-server.git
cd ast-mcp-server

2. プロジェクトと依存関係をインストールします。

# Install the project in development mode with all dependencies
uv sync

# Or install with specific optional dependencies
uv sync --extra dev  # Development tools
uv sync --extra testing  # Testing dependencies
uv sync --extra docs  # Documentation tools

3. tree-sitter パーサーをビルドします。

uv run build-parsers

pip を使用する場合（代替方法）

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Build parsers
python build_parsers.py

Claude Desktop での使用方法

1. 設定ファイルを編集して、サーバーを使用するよう Claude Desktop を設定します。

設定ファイルの場所：

• macOS：~/Library/Application Support/claude-desktop/claude_desktop_config.json
• Linux：~/.config/claude-desktop/claude_desktop_config.json
• Windows：%APPDATA%\claude-desktop\claude_desktop_config.json

2. AST MCP サーバーの設定を追加します。

{
  "mcpServers": {
    "AstAnalyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/ty/Repositories/ai_workspace/ast-mcp-server/ast_mcp_server",
        "run",
        "server.py"
      ]
    }
  }
}

重要： /absolute/path/to/ast-mcp-server を、お使いのシステム上の実際の絶対パスに置き換えてください。

3. Claude Desktop を再起動して、新しい MCP サーバーを読み込みます。

4. Claude Desktop で、コードファイルを指定するか、コードスニペットを貼り付けると、AST ベースのコード解析ツールを使用できます。

開発

開発環境のセットアップ

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks (optional)
uv run pre-commit install

開発モードでの実行

MCP インスペクターを使用して、開発モードでサーバーを実行します。

# Using uv
uv run --extra dev -- -m mcp dev server.py

# Or using the development script
./dev_server.sh

テスト

# Run all tests
uv run --extra testing pytest

# Run tests with coverage
uv run --extra testing pytest --cov=ast_mcp_server --cov-report=html

# Run specific tests
uv run --extra testing pytest tests/test_specific.py

コード品質

# Format code
uv run black .
uv run isort .

# Lint code
uv run flake8 .

# Type checking
uv run mypy ast_mcp_server/

利用可能なツール

サーバーはコード解析用に以下のツールを提供します。

基本ツール

• parse_to_ast：コードを抽象構文木に解析します
• generate_asg：コードから抽象意味グラフを生成します
• analyze_code：コードの構造と複雑さを分析します
• supported_languages：サポート対象のプログラミング言語の一覧を取得します

キャッシュツール

• parse_and_cache：コードを AST に解析し、リソースからアクセスできるようにキャッシュします
• generate_and_cache_asg：ASG を生成し、リソースからアクセスできるようにキャッシュします
• analyze_and_cache：コードを分析し、結果をリソースからアクセスできるようにキャッシュします

拡張ツール

• parse_to_ast_incremental：増分解析に対応してコードを解析し、処理を高速化します
• generate_enhanced_asg：スコープ処理を改善した拡張 ASG を生成します
• diff_ast：2 つのコードバージョン間の差分を検出します
• find_node_at_position：指定した行と列にあるノードを特定します
• parse_and_cache_incremental：コードを増分解析し、結果をキャッシュします
• generate_and_cache_enhanced_asg：拡張 ASG を生成してキャッシュします
• ast_diff_and_cache：AST の差分を生成してキャッシュします

言語サポートの追加

追加のプログラミング言語をサポートするには：

1. 対応する tree-sitter 言語パッケージをインストールします。

uv add tree-sitter-<language>

2. build_parsers.py と ast_mcp_server/tools.py の LANGUAGE_MODULES 辞書を更新します。

3. パーサーをビルドします。

uv run build-parsers

現在サポートされている言語

• Python（tree-sitter-python）
• JavaScript（tree-sitter-javascript）
• TypeScript（tree-sitter-typescript）
• Go（tree-sitter-go）
• Rust（tree-sitter-rust）
• C（tree-sitter-c）
• C++（tree-sitter-cpp）
• Java（tree-sitter-java）

仕組み

AST MCP Server は、Model Context Protocol（MCP）を通じて Claude Desktop に接続します。

1. 初期化：Claude Desktop は、適切な作業ディレクトリで uv run を使用してサーバーを起動します
2. 言語の読み込み：サーバーは、さまざまなプログラミング言語を解析するための tree-sitter 言語モジュールを読み込みます
3. MCP への登録：MCP プロトコルにツールとリソースを登録します
4. 分析：Claude は、共有したコードやローカルファイルを分析するために、これらのツールにアクセスできます。ツールは堅牢に設計されており、提供されたコードがプレースホルダーの場合、ローカルの filename パスからインテリジェントに読み取ることができます。
5. キャッシュ：パフォーマンス向上のため、結果はローカルにキャッシュされます

すべてのツールの実行はお使いのマシン上でローカルに行われ、結果は解釈や支援のために Claude に返されます。

設定ファイル

• pyproject.toml：プロジェクトのメタデータ、依存関係、ツールの設定
• claude_desktop_config.json：Claude Desktop の設定例
• dev_server.sh：開発サーバーのスクリプト
• .gitignore：Git の無視ルール

ディレクトリ構成

ast-mcp-server/
├── ast_mcp_server/          # Main package
│   ├── __init__.py
│   ├── tools.py             # Core AST/ASG tools
│   ├── enhanced_tools.py    # Enhanced analysis features
│   ├── resources.py         # MCP resource handlers
│   └── parsers/             # Tree-sitter parser cache
├── examples/                # Usage examples
├── tests/                   # Test suite
├── server.py                # Main server entry point
├── build_parsers.py         # Parser setup script
├── pyproject.toml           # Project configuration
└── README.md               # This file

トラブルシューティング

パーサーの問題

パーサー関連のエラーが発生した場合：

# Rebuild parsers
uv run build-parsers

# Check for missing language packages
uv add tree-sitter-python tree-sitter-javascript

Claude Desktop の接続に関する問題

1. Claude Desktop の設定で絶対パスを確認します
2. uv がシステムの PATH に含まれていることを確認します
3. Claude Desktop のログでエラーメッセージを確認します
4. 設定を変更した後、Claude Desktop を再起動します

パフォーマンスの問題

• 大きなファイルにはインクリメンタル解析ツールを使用します
• 解析を繰り返す場合はキャッシュを有効にします
• より小さなコードセクションの分析を検討します

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature-name
3. 適切なテストを含めて変更を加えます
4. テストスイートを実行します：uv run pytest
5. プルリクエストを送信します

開発ガイドライン

• PEP 8 のスタイルガイドラインに従います（black と flake8 によって適用されます）
• すべての公開関数に型ヒントを追加します
• すべてのモジュール、クラス、関数に docstring を記述します
• 新しい機能のテストを作成します
• 必要に応じてドキュメントを更新します

ライセンス

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

変更履歴

v0.2.0

• pyproject.toml の設定を追加
• uv との互換性を向上
• キャッシュシステムを強化
• インクリメンタル解析のサポートを追加
• 言語のサポートを拡充
• エラー処理とロギングを改善

v0.1.0

• 初回リリース
• 基本的な AST/ASG 解析
• Claude Desktop との統合
• Python と JavaScript をサポート