Code Understanding MCP Server

⚠️ プラットフォームサポートに関するお知らせ

この MCP サーバーは macOS と Linux でテスト済みです。Windows のサポートは現在未確認です（まだテストされていません）。

Windows で試して問題が発生した場合は、クロスプラットフォームサポートの改善に役立てるため、issue を作成してください。

コード理解 MCP サーバー

コードベースを理解し、AI コーディングアシスタントにインテリジェントなコンテキストを提供するために設計された MCP（Model Context Protocol）サーバーです。このサーバーはローカルおよびリモートの GitHub リポジトリに対応し、標準的な MCP 準拠の操作をサポートします。

🤖 AI アシスタントによるインストール

AI コーディングアシスタントに、このサーバーのインストールを手伝ってもらいましょう！ セットアップアシスタントプロンプトの内容をコピーして AI アシスタント（Claude、ChatGPT、Cursor など）に貼り付けると、インストール手順全体を案内してくれます。

機能

• GitHub リポジトリまたはローカルのコードベースをクローンして分析
• リポジトリの構造とファイル構成を取得
• 複雑さの指標とコード構造に基づいて重要なファイルを特定
• 以下を示す詳細なリポジトリマップを生成：
  • 関数のシグネチャと関係
  • クラス定義と階層
  • コード構造と依存関係
• リポジトリのドキュメントを取得して分析
• 特定のファイルまたはディレクトリを対象に分析
• 更新によってリポジトリの変更を反映し、分析を最新の状態に維持

クイックスタート：MCP クライアントの設定

前提条件

必須：uv のインストール

このサーバーには、最新の Python パッケージマネージャーである uv が必要です。まだ uv をインストールしていない場合：

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

その他のインストール方法については、公式の uv インストールガイド astral.sh/uv をご覧ください。

インストール方法

方法 1：uvx で直接実行（推奨）

# Run directly without installing a global binary
uvx code-understanding-mcp-server

これは、UV が管理する分離環境で、実行するたびにサーバーを起動します。

方法 2：仮想環境へのインストール（任意）

専用の仮想環境内にバイナリを常設する場合：

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package into the venv
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

インストールの確認

選択した方法に応じて：

# Method 1 (uvx): runs via uvx; no persistent binary is installed
uvx --version

# Method 2 (venv install): verify the binary inside your venv
which code-understanding-mcp-server
# Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

MCP クライアントの設定

MCP クライアントには、以下のいずれかの設定を使用してください：

{
  "mcpServers": {
    "code-understanding": {
      "command": "uvx",
      "args": [
        "code-understanding-mcp-server"
      ]
    }
  }
}

または、仮想環境にインストールした場合は、その環境内のバイナリを直接指定します：

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server",
      "args": []
    }
  }
}

この MCP サーバーを使う理由

MCP コード理解サーバー

提供価値

MCP コード理解サーバーは、AI アシスタントに包括的なコード理解機能を提供し、ソフトウェア開発タスクに対して、より正確で、文脈に即した実用的な支援を可能にします。リポジトリと AI システムを結ぶセマンティックブリッジを構築することで、コードの探索、分析、実装に関するガイダンスに伴う時間と手間を大幅に削減します。

一般的な使用例

参照リポジトリの分析

• 外部リポジトリ（ライブラリ、依存関係など）を調査し、現在の開発に役立てる
• オープンソースプロジェクトから実装パターンや例を見つける
• ドキュメントだけでは不十分な場合に、特定のライブラリの内部動作を理解する
• 類似プロジェクト間で実装方法を比較する
• 高品質なコードベースからベストプラクティスを特定する

ナレッジの抽出とドキュメント作成

• ドキュメントが不十分なコードベース向けに、包括的なドキュメントを生成する
• アーキテクチャの概要とコンポーネントの関係図を作成する
• 開発者のオンボーディング向けに、段階的な学習パスを作成する
• コードに埋め込まれたビジネスロジックとドメイン知識を抽出する
• システムの統合ポイントと依存関係を特定して文書化する

コードベースの評価と改善

• 技術的負債を分析し、リファクタリングの取り組みに優先順位を付ける
• セキュリティの脆弱性とコンプライアンス上の問題を特定する
• テストカバレッジと品質を評価する
• デッドコード、重複したロジック、最適化の機会を検出する
• デザインパターンとアーキテクチャ原則に照らして実装を評価する

レガシーシステムの理解

• ドキュメントが最小限のシステムから知識を復元します
• システムの境界を把握し、移行計画を支援します
• 変更を加える前に、複雑な依存関係を分析します
• 複数のコンポーネントにまたがる機能の実装を追跡します
• 過去の設計上の判断とその根拠を理解します

プロジェクト間の知識移転

• あるプロジェクトのパターンを別のプロジェクトに適用します
• 関連システムを扱うチーム間の知識のギャップを埋めます
• 複数のプロジェクトで再利用できるコンポーネントを特定します
• チーム間の実装アプローチの違いを理解します
• 分散開発環境での知識共有を促進します

MCP Code Understanding Server を実際のシナリオで使用する詳しい例については、シナリオ例をご覧ください。以下の手順を追った解説が含まれています。

• 複雑なコードベースへの開発者のオンボーディングを迅速化する
• API の移行を計画して実施する
• セキュリティ脆弱性の評価を実施する

動作の仕組み

MCP Code Understanding Server は、一連の分析手順を通じてリポジトリを処理します。

1. リポジトリのクローン作成：サーバーは対象のリポジトリをキャッシュにクローンします
2. 構造分析：ディレクトリ、ファイル、およびそれらの構成を分析します
3. 重要ファイルの特定：構造上重要なコンポーネントを特定します
4. ドキュメントの取得：すべてのドキュメントファイルを収集します
5. セマンティックマッピング：コンポーネント間の関係を示す詳細なマップを作成します
6. コンテンツ分析：より深く理解するため、必要に応じて特定のファイルを調査します

AI アシスタントは、分析の各段階で対象を絞ったリクエストを送信してサーバーと連携し、特定のユーザーの質問やニーズへの対応に活用できる、コードベースの包括的な理解を構築します。

AI アシスタントに推奨するワークフロー

リポジトリを扱う際、最適な結果を得るには、AI アシスタントは次のワークフローに従ってください。

1. まずキャッシュを確認する：list_cached_repository_branches を使って、リポジトリがすでにキャッシュされているか確認します

   • キャッシュされている場合：手順 3（更新）に進みます
   • キャッシュされていない場合：手順 2 に進みます

2. ブランチ名を確認する：多くのリポジトリでは、「main」ではなく「master」、「develop」などの名前が使われています

   • list_remote_branches を使って、利用可能なブランチを確認します
   • クローンする前に、正しいデフォルトブランチを特定します

3. 分析前に更新する：キャッシュされたリポジトリは時間の経過とともに古くなります

   • 分析の前に refresh_repo を使って最新の変更を取得します
   • これにより、古いキャッシュではなく最新のコードに基づいて分析できます

4. 分析を実行する：リポジトリが最新の状態になったら、分析ツールを使います

   • コード構造には get_source_repo_map
   • 主要なコンポーネントの特定には get_repo_critical_files
   • ドキュメントの確認には get_repo_documentation

このワークフローにより、誤ったブランチ名によるクローンの失敗、不要なクローンの試行、古いキャッシュデータに基づく分析といったよくある問題を防げます。

大規模なコードベースにおける設計上の考慮事項

このサーバーでは、エンタープライズ規模のリポジトリでもパフォーマンスと使いやすさを維持するため、いくつかの戦略を採用しています。

• 非同期処理：リポジトリのクローンと分析はバックグラウンドスレッドで実行され、詳細な分析が続く間もすぐにフィードバックを得られます
• 段階的な分析：まず迅速な初期分析を行うため、すぐに操作を開始でき、時間の経過とともにより詳細な理解が構築されます
• 分析範囲の制御：max_tokens、files、directories の各パラメーターを使って、関心のある特定の領域に絞った分析ができます
• しきい値の管理：リポジトリのサイズを自動的に検出し、適切な分析戦略を案内します
• 階層的な理解：まずリポジトリの構造を分析することで、重要なコンポーネントを優先し、より深い意味分析を行います

これらの設計上の工夫により、開発者は大規模なコードベースですぐに作業を開始でき、システムはバックグラウンドで段階的に理解を深めていきます。分析の深さと応答性の最適なバランスを実現します。

GitHub 認証（任意）

プライベートリポジトリへのアクセスが必要な場合、または GitHub API のレート制限を避けたい場合は、GitHub トークンを設定に追加してください。

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

高度な設定オプション

上級ユーザー向けに、サーバーでは次の設定オプションをサポートしています。

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [
        "--cache-dir", "~/custom-cache-dir",     // Override repository cache location
        "--max-cached-repos", "20",              // Override maximum number of cached repos
        "--transport", "stdio",                  // Transport type (stdio or sse)
        "--port", "3001"                         // Port for SSE transport (only used with sse)
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

利用可能なオプション：

• --cache-dir：リポジトリのキャッシュディレクトリの場所を変更します（デフォルト：~/.cache/mcp-code-understanding）
• --max-cached-repos：キャッシュするリポジトリの最大数を設定します（デフォルト：10）
• --transport：トランスポートの種類を選択します（stdio または sse、デフォルト：stdio）
• --port：SSE トランスポートのポートを設定します（デフォルト：3001、sse トランスポート使用時のみ）

プラットフォーム固有の注意事項

macOS

• uvx を使用する場合、永続的なバイナリはインストールされないため、PATH の変更は不要です
• 仮想環境を使用する場合は、有効化するか、venv バイナリへのフルパスを指定してください

Linux

• uvx を使用する場合、永続的なバイナリはインストールされないため、PATH の変更は不要です
• 仮想環境を使用する場合は、ヘルパーエイリアスを追加するか、使用前に venv を有効化すると便利です

Windows

• 現在サポートされていません — Windows のサポートは今後のリリースで予定されています
• Windows との互換性を実現するための開発が進行中です

トラブルシューティング

依存関係の競合

uvx の使用時に依存関係の競合が発生した場合は、分離された環境を作成し、そこでパッケージをインストールしてください。

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

バイナリが見つからない

インストール済みのバイナリが見つからない場合：

1. インストール先を確認します。

   # macOS/Linux
   find ~/.local -name "code-understanding-mcp-server" 2>/dev/null
   

2. 必要に応じて PATH に追加します。

   # Add to ~/.bashrc, ~/.zshrc, or appropriate shell config
   export PATH="$HOME/.local/bin:$PATH"
   

3. venv を有効化しない場合は、MCP の設定で venv バイナリの絶対パスを使用します。

サーバーの設定

サーバーでは、基本設定に config.yaml ファイルを使用します。このファイルは、サーバーの初回起動時に標準の設定ディレクトリ（~/.config/mcp-code-understanding/config.yaml）に自動作成されます。現在のディレクトリに config.yaml ファイルを配置して、デフォルト設定を上書きすることもできます。

デフォルトの設定構造は次のとおりです。

name: "Code Understanding Server"
log_level: "debug"

repository:
  cache_dir: "~/.cache/mcp-code-understanding"
  max_cached_repos: 10

documentation:
  include_tags:
    - markdown
    - rst
    - adoc
  include_extensions:
    - .md
    - .markdown
    - .rst
    - .txt
    - .adoc
    - .ipynb
  format_mapping:
    tag:markdown: markdown
    tag:rst: restructuredtext
    tag:adoc: asciidoc
    ext:.md: markdown
    ext:.markdown: markdown
    ext:.rst: restructuredtext
    ext:.txt: plaintext
    ext:.adoc: asciidoc
    ext:.ipynb: jupyter
  category_patterns:
    readme: 
      - readme
    api: 
      - api
    documentation:
      - docs
      - documentation
    examples:
      - examples
      - sample

開発者向け

前提条件

• Python 3.11 または 3.12：開発と使用の両方に必要です

  # Verify your Python version
  python --version
  # or
  python3 --version
  

• UV パッケージマネージャー：最新の Python パッケージインストーラーです

  # Install UV
  curl -sSf https://astral.sh/uv/install.sh | sh
  

開発環境のセットアップ

このプロジェクトへの貢献またはローカルでの実行を行うには、次の手順に従ってください。

# 1. Clone the repository
git clone https://github.com/yourusername/mcp-code-understanding.git
cd mcp-code-understanding

# 2. Create virtual environment
uv venv

# 3. Activate the virtual environment
#    Choose the command appropriate for your operating system and shell:

#    Linux/macOS (bash/zsh):
source .venv/bin/activate

#    Windows (Command Prompt - cmd.exe):
.venv\\Scripts\\activate.bat

#    Windows (PowerShell):
#    Note: You might need to adjust your execution policy first.
#    Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.venv\\Scripts\\Activate.ps1

# 4. Install dependencies (editable mode with dev extras)
#    (Ensure your virtual environment is activated first!)
uv pip install -e ".[dev]"

# 5. Set up pre-commit hooks
pre-commit install

# 6. Run tests
uv run pytest

# 7. Test the server using MCP inspector
# Without GitHub authentication:
uv run mcp dev src/code_understanding/mcp/server/app.py

# With GitHub authentication (for testing private repos):
GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here uv run mcp dev src/code_understanding/mcp/server/app.py

対話型コンソールが起動し、すべての MCP サーバーエンドポイントを直接テストできます。

開発ツール

開発用追加パッケージ（.[dev]）をインストールすると、次の開発ツールを使用できます。

カバレッジ付きでテストを実行します。

uv run pytest

コードをフォーマットします（black と isort を使用）。

# Format with black
uv run black .

# Sort imports
uv run isort .

mypy で型チェックを実行します。

uv run mypy .

すべてのツールは、このプロジェクトに最適化された設定で pyproject.toml を介して構成されています。

PyPI への公開

PyPI に新しいバージョンを公開する準備ができたら、次の手順に従ってください。

1. pyproject.toml のバージョン番号を更新します：

   # Edit pyproject.toml and change the version field
   # For example: version = "0.1.1"
   

2. 以前のビルド成果物を削除します：

   # Remove previous distribution packages and build directories
   rm -rf dist/ 2>/dev/null || true
   rm -rf build/ 2>/dev/null || true
   rm -rf src/*.egg-info/ 2>/dev/null || true
   

3. 配布パッケージをビルドします：

   uv run python -m build
   

4. ビルドしたパッケージを確認します：

   ls dist/
   

5. PyPI にアップロードします（不安な場合は、まず TestPyPI を使用してください）：

   # Install twine if you haven't already
   uv pip install twine
   
   # For PyPI release:
   uv run python -m twine upload dist/*
   

PyPI の認証情報を設定しておく必要があります。設定されていない場合は、アップロード時に入力を求められます。

バージョン履歴

v0.1.6（最新）

• 依存関係の修正：PyPI で削除されたバージョンが原因で発生するインストールの問題を解決するため、configargparse==1.7 を明示的に固定しました
• 依存関係の解決に失敗しないようにすることで、uvx やその他のパッケージマネージャーで確実にインストールできます
• サーバーの機能に変更はありません

ライセンス

MIT