Pecorino

Pecorino MCP サーバー

Git 履歴の詳細な統計、リポジトリの健全性追跡、オブジェクト指向設計（OOD）メトリクス分析を行う Model Context Protocol（MCP）サーバーです。

Pecorino を使うと、LLM や開発ツール（Claude Desktop や Cursor など）からコードベースを調べ、コード構造を分析し、複雑度／保守性インデックスを算出して、リスクの高い箇所を検出できます。

---

機能

• Model Context Protocol（MCP）：5 つの統合ツール（browse、search、update_index、set_workspace、metrics）を AI アシスタントに公開します。
• Git 履歴分析：コミット、LOC の増加、作成者ごとの貢献、活動パターン、チームのパフォーマンスを追跡します。
• オブジェクト指向設計メトリクス：求心性／遠心性結合度（Ca/Ce）、不安定度（I）、抽象度（A）、主系列からの距離（D）を分析します。
• リスクの高い箇所の検出：コードの変更頻度（リビジョン頻度）と複雑度を組み合わせて、リスクの高いソースファイルを特定します。
• 高速な SQLite3 インデックス作成：SQLite3 と c-fts-uring を活用し、信頼性の高いメタデータ保存、ハイブリッドベクトル検索（HNSW）、BM25F 全文検索を実現します。また、Gorgonzola によるプロパティグラフ走査にも対応しています。
• 柔軟な CLI と HTTP SSE：標準の CLI ツールとして実行したり、ローカルの stdio MCP サーバーを起動したり、ネットワーク経由でアクセスできる SSE サーバーとしてデプロイしたりできます。

---

クイックスタート

1. システムの前提条件

環境を設定する前に、必要なビルドツールがインストールされていることを確認してください（ネイティブの gorgonzola データベースモジュールのコンパイルに必要です）。

• Fedora/RHEL：sudo dnf install cmake ninja-build gcc gcc-c++ ccache python3-devel
• Ubuntu/Debian：sudo apt install cmake ninja-build build-essential ccache python3-dev
• macOS：brew install cmake ninja ccache

2. インストール

リポジトリを再帰的にクローンして（MCP SDK サブモジュールを取得するため）、環境をセットアップします。

# Clone recursively
git clone --recursive https://github.com/pecorino-mcp/pecorino.git
cd pecorino

# Run the environment setup script
# This will initialize the .venv, install dependencies, and compile the gorgonzola module
./scripts/setup_env.sh

# Activate the virtual environment
source .venv/bin/activate

3. Claude Desktop の設定

claude_desktop_config.json に Pecorino を追加します。

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

{
  "mcpServers": {
    "pecorino": {
      "command": "/path/to/pecorino/.venv/bin/pecorino-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "PYTHONPATH": "/path/to/pecorino"
      }
    }
  }
}

（/path/to/pecorino を実際の絶対パスに置き換えてください）。

---

公開される MCP ツール

接続すると、AI アシスタントは次のツールを使用できます。

1. browse

コードベースの構造（ツリー、依存関係、クラス、関数、PageRank、概要）を参照するか、view="code" で指定したコード行を取得します。構造の表示やコードの取得に使用します。

2. search

複数のモードを備えた統合検索・分析ツールです。

• hybrid（デフォルト）— ベクトル類似度と SQLite3 FTS を組み合わせ、RRF と LTR のスコアリングを使用します。
• fts — コードベース全体を対象にした全文キーワード検索です。
• callers / callees — 呼び出しグラフ分析です。X を呼び出すのは何か、X が呼び出すのは何かを調べます。
• impact — ファイルまたはディレクトリから依存関係を詳細にたどります。
• usages — 検索と呼び出し元の調査を 1 回の呼び出しで行います（定義とすべての呼び出し元を検索します）。
• intent — AST クエリのプリセット：all_classes、all_functions、entry_points、dead_code、files_by_language。
• community — Leiden コミュニティ検出により、意味的な近傍とクラスターを見つけます。
• explain — シンボルのスコアが高くなった理由を示すランキングの説明です。
• snippet / trace — 文脈付きのコードスニペット取得と、パスの詳細な追跡を行います。
• cypher — 検索内で Cypher クエリを実行します。
• auto — 自然言語クエリの意図に応じて自動的に振り分けます。
• dsl — コードベースの AST とグラフに対して、カスタム JSON DSL クエリを実行します。
• functional-analysis — 関数型の純粋性を分析します。

3. query_graph

Kùzu/Gorgonzola ナレッジグラフに対して openCypher クエリを直接実行し、構造と類似性を詳細に分析します。

4. update_index

コードベースの AST インデックスを更新し、構造の概要を返します。クローン後、または大幅な変更を加えた後に 1 回実行してください。

5. set_workspace

実行時にサーバーのワークスペースのルートディレクトリを変更します。

6. metrics (管理者専用)

OOP メトリクス、サイクロマティック複雑度、またはホットスポットリスク分析を計算します。リポジトリレベルのリスクトリアージには、what: ['hotspots'] を使用します。

7. detect_changes

変更されたファイルと Git の reflog の変更を検出し、増分更新を追跡します。

8. manage_adr

コードベース内でアーキテクチャ決定記録（ADR）を作成、一覧表示、検索します。

9. manage_snapshot

コードベースのグラフとインデックスの構造スナップショットを取得し、過去との比較や差分確認に使用します。

---

アーキテクチャ

Pecorino は、コードベースの構造を抽出、インデックス化、分析するために、多段階のデュアルインデックス＆グラフアーキテクチャを採用しています。

1. AST 解析（src/parsers/）：py-tree-sitter を使用して複数の言語のソースファイルを解析し、モジュール、クラス、インターフェース、関数、インポートの定義を抽出します。
2. グラフナレッジベース（src/mcp_server/gorgonzola_graph.py）：gorgonzola / Kùzu エンジンを基盤とする openCypher プロパティグラフとして、コード構造、呼び出しグラフ、依存関係、呼び出し元と呼び出し先の関係を保存します。
3. デュアル検索エンジン（リレーショナル、ベクトル、c-fts-uring）（src/mcp_server/index_db.py）：
   • バイエンコーダー埋め込み（embedding.py）：高速なコサイン類似度検索のため、HNSW ベクトル拡張を使用して SQLite3 に保存する高密度ベクトル表現です。
   • c-fts-uring FTS（index_db.py）：高速な非同期 BM25F 全文検索を実現する、Linux io_uring を使用したネイティブ SQLite3 C 拡張です。
4. AI 再ランキング＆Learning-to-Rank（src/mcp_server/cross_encoder.py & ltr_ranker.py）：
   • クロスエンコーダー再ランキング：ペアワイズ ONNX クロスエンコーダーにより、上位候補の結果を再ランキングします。
   • LTR モデル：20 以上のシグナル（PageRank、Betweenness Centrality、OOD メトリクス、Git の変更頻度／著者エントロピー）を組み合わせます。
   • 命名分析：ヒューリスティックな解決には、フォールバックのローカル LLM を使用します。
5. Git 分析エンジン（src/git/, src/core/）：reflog とコミット履歴を解析し、時間的結合グラフを構築してコードの変更頻度を追跡します。
6. MCP トランスポート層（src/transports/）：標準の Model Context Protocol（stdio、SSE）を介して、インデックス、ベクトル、グラフデータベースを AI エージェントに公開します。

ヒント

使用モデルの概要

• 埋め込みモデル：Xenova/all-MiniLM-L12-v2（384 次元のローカル埋め込み）
• クロスエンコーダーモデル：cross-encoder/ms-marco-MiniLM-L-12-v2
• フォールバック LLM：ollama/llama3（命名アナライザー用）

主な機能（Python API）

CLI と MCP サーバーに加えて、Pecorino は Python ライブラリとして直接使用できます。src/__init__.py を介してエクスポートされる主なモジュールと関数は次のとおりです。

• メトリクス＆複雑度：
  • calculate_maintainability_index()、calculate_mccabe_complexity()、calculate_halstead_metrics()
  • OOPMetricsAnalyzer（Ca、Ce、I、A、D を計算）
• Git 分析：
  • GitDataCollector（コミット履歴と LOC メトリクスを収集）
  • HotspotDetector、analyze_hotspots()（変更頻度と複雑度に関するリスクを特定）
• AST 操作：
  • TreeSitterGrammarManager（言語文法を管理）
  • ASTNode、ClassDef、FunctionDef、walk()、iter_child_nodes()
• エクスポート＆ユーティリティ：
  • MetricsExporter、export_to_json()、export_to_yaml()

リポジトリの構成

• src/cli/ — コマンドラインインターフェースとエントリーポイント。
• src/core/ — コアデータコレクターと設定。
• src/git/ — Git の履歴とコミットログのパーサー。
• src/mcp_server/ — MCP サーバーのエンドポイントとコアロジック。
  • src/mcp_server/index_pipeline.py — AST 抽出とインデックス作成を統合したパイプライン。
  • src/mcp_server/index_db.py — SQLite3 と c-fts-uring を使用した、全文検索（FTS）対応のコードベースインデックス。
  • src/mcp_server/gorgonzola_graph.py — Gorgonzola グラフデータベースアダプター。
  • src/mcp_server/ramdisk.py — 一括インデックス作成用の /dev/shm RAM ディスクステージング。
• src/metrics/ — 保守性、複雑度、OOP メトリクスの分析ツール。
• src/parsers/ — AST 解析（Tree-sitter を使用）。
• src/transports/ — MCP アダプター（stdio、fastAPI）。
• src/utils/ — エクスポート形式とヘルパーユーティリティ。
• modules/ — gorgonzola、py-tree-sitter、pecorino-utils などの Git サブモジュール。
• docs/ — アーキテクチャに関するドキュメント（検索、インデックス作成、可観測性とセキュリティ、エージェントスキル、進化のタイムライン）。
• tests/ — 自動テストスイート。

---

コマンドラインインターフェース（CLI）

ターミナルから Pecorino を直接実行することもできます。

# Start the stdio MCP server manually
pecorino-mcp --transport stdio

# Start the SSE MCP server (requires Starlette & Uvicorn: pip install -e .[sse])
pecorino-mcp --transport sse --host 127.0.0.1 --port 8000

# Run a CLI analysis and save the report inside a directory
python pecorino.py /path/to/repo /path/to/output_dir

CLI のフラグ、トランスポートの詳細、設定オプションについては、ローカルサーバーのデプロイガイドをご覧ください。

---

ライセンスとコントリビューション

このプロジェクトは GNU Affero General Public License v3（AGPL-3.0）の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。コントリビューション、バグ報告、改善提案を歓迎します。問題を報告するか、小規模で焦点を絞った変更をプルリクエストとして送信してください。