Pecorino

Pecorino MCP Server

A Model Context Protocol (MCP) server for deep Git history statistics, repository health tracking, and Object-Oriented Design (OOD) metrics analysis.

Pecorino allows Large Language Models (LLMs) and dev tools (such as Claude Desktop or Cursor) to inspect codebases, analyze code structures, compute complexity/maintainability indexes, and detect risk hotspots.

---

Features

• Model Context Protocol (MCP): Exposes 5 unified tools (browse, search, update_index, set_workspace, metrics) to your AI assistant.
• Git History Analytics: Commits, LOC growth, author contributions, activity patterns, and team performance tracking.
• Object-Oriented Design Metrics: Afferent/efferent coupling (Ca/Ce), instability (I), abstractness (A), and Distance-from-Main-Sequence (D) analysis.
• Risk Hotspot Detection: Combines code churn (revision frequency) and complexity to pinpoint high-risk source files.
• Fast SQLite3 Indexing: Leverages SQLite3 + c-fts-uring for robust metadata storage, hybrid vector search (HNSW), and BM25F full-text search, alongside Gorgonzola for property graph traversal.
• Flexible CLI & HTTP SSE: Run as a standard CLI tool, start a local stdio MCP server, or deploy as a network-accessible SSE server.

---

Quick Start

1. System Prerequisites

Before setting up the environment, ensure you have the required build tools installed (needed to compile the native gorgonzola database module):

• 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. Installation

Clone the repository recursively (to fetch the MCP SDK submodule) and set up the environment:

# 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. Configure Claude Desktop

Add Pecorino to your claude_desktop_config.json:

• 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"
      }
    }
  }
}

(Replace /path/to/pecorino with your actual absolute path).

---

Exposed MCP Tools

Once connected, your AI assistant can use the following tools:

1. browse

Browse codebase structure (tree, deps, classes, functions, pagerank, summary) or retrieve specific lines of code with view="code". Use this for structural viewing and code retrieval.

2. search

Unified search and analysis tool with multiple modes:

• hybrid (default) — Blended vector similarity + SQLite3 FTS with RRF and LTR scoring.
• fts — Full-text keyword search across the codebase.
• callers / callees — Call graph analysis. Who calls X? What does X call?
• impact — Deep dependency trace from a file or directory.
• usages — Combined search + callers in one call (find definition and all callers).
• intent — Preset AST queries: all_classes, all_functions, entry_points, dead_code, files_by_language.
• community — Semantic neighborhood and cluster discovery via Leiden community detection.
• explain — Ranking explanation surfacing why a symbol scored highly.
• snippet / trace — Contextual code snippet retrieval and deep path tracing.
• cypher — Embedded Cypher query execution within search.
• auto — Automatic natural language query intent routing.
• dsl — Custom JSON DSL query against the codebase AST and graph.
• functional-analysis — Functional purity analysis.

3. query_graph

Execute openCypher queries directly against the Kùzu/Gorgonzola knowledge graph for deep structural and similarity analysis.

4. update_index

Update the AST index for the codebase and return a structural summary. Call this once after cloning or after significant changes.

5. set_workspace

Change the server's workspace root directory at runtime.

6. metrics (Admin only)

Calculate OOP metrics, cyclomatic complexity, or hotspot risk analysis. Use what: ['hotspots'] for repo-level risk triage.

7. detect_changes

Detect modified files and git reflog changes to track incremental updates.

8. manage_adr

Create, list, and query Architecture Decision Records (ADRs) within the codebase.

9. manage_snapshot

Take structural snapshots of the codebase graph and index for historical comparison and diffing.

---

Architecture

Pecorino relies on a multi-stage Dual Index & Graph Architecture to extract, index, and analyze codebase structure:

1. AST Parsing (src/parsers/): Uses py-tree-sitter to parse source files across multiple languages, extracting definitions for modules, classes, interfaces, functions, and imports.
2. Graph Knowledge Base (src/mcp_server/gorgonzola_graph.py): Stores code structures, call graphs, dependencies, and caller/callee relationships as an openCypher property graph powered by the gorgonzola / Kùzu engine.
3. Dual Search Engine (Relational, Vector & c-fts-uring) (src/mcp_server/index_db.py):
   • Bi-Encoder Embeddings (embedding.py): Dense vector representations stored in SQLite3 using HNSW vector extension for fast cosine similarity.
   • c-fts-uring FTS (index_db.py): Native SQLite3 C extension using Linux io_uring for fast asynchronous BM25F full-text search.
4. AI Reranking & Learning-to-Rank (src/mcp_server/cross_encoder.py & ltr_ranker.py):
   • Cross-Encoder Reranking: Pairwise ONNX cross-encoder reranking the top candidate results.
   • LTR Model: Blends 20+ signals (PageRank, Betweenness Centrality, OOD metrics, Git churn/authorship entropy).
   • Naming Analysis: Uses a fallback local LLM for heuristic resolution.
5. Git Analytics Engine (src/git/, src/core/): Parses reflogs and commit histories to build temporal coupling graphs and track code churn.
6. MCP Transport Layer (src/transports/): Exposes index, vector, and graph databases over standard Model Context Protocol (stdio, SSE) to AI agents.

Tip

Models Used Highlight

• Embedding Model: Xenova/all-MiniLM-L12-v2 (384-dim local embeddings)
• Cross-Encoder Model: cross-encoder/ms-marco-MiniLM-L-12-v2
• Fallback LLM: ollama/llama3 (for naming analyzer)

Core Functions (Python API)

Beyond the CLI and MCP Server, Pecorino can be used directly as a Python library. Key modules and functions exported via src/__init__.py include:

• Metrics & Complexity:
  • calculate_maintainability_index(), calculate_mccabe_complexity(), calculate_halstead_metrics()
  • OOPMetricsAnalyzer (computes Ca, Ce, I, A, D)
• Git Analytics:
  • GitDataCollector (harvests commit history and LOC metrics)
  • HotspotDetector, analyze_hotspots() (identifies churn vs. complexity risks)
• AST Manipulation:
  • TreeSitterGrammarManager (manages language grammars)
  • ASTNode, ClassDef, FunctionDef, walk(), iter_child_nodes()
• Export & Utilities:
  • MetricsExporter, export_to_json(), export_to_yaml()

Repository Layout

• src/cli/ — Command-line interface and entry points.
• src/core/ — Core data collectors and configuration.
• src/git/ — Git history and commit log parsers.
• src/mcp_server/ — MCP server endpoints and core logic.
  • src/mcp_server/index_pipeline.py — Unified AST extraction and indexing pipeline.
  • src/mcp_server/index_db.py — SQLite3 and c-fts-uring Full-Text Search (FTS) codebase index.
  • src/mcp_server/gorgonzola_graph.py — Gorgonzola graph database adapter.
  • src/mcp_server/ramdisk.py — /dev/shm RAM-disk staging for bulk indexing.
• src/metrics/ — Maintainability, complexity, and OOP metrics analyzers.
• src/parsers/ — AST parsing (using Tree-sitter).
• src/transports/ — MCP Adapters (stdio, fastAPI).
• src/utils/ — Export formats and helper utilities.
• modules/ — Git submodules including gorgonzola, py-tree-sitter, and pecorino-utils.
• docs/ — Architectural documentation (Search, Indexing, Observability & Security, Agent Skills, Evolution Timeline).
• tests/ — Automated test suites.

---

Command Line Interface (CLI)

You can also run Pecorino directly via the terminal:

# 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

For comprehensive CLI flags, transport details, and configuration options, see the Local Server Deployment Guide.

---

License & Contributing

This project is licensed under the GNU Affero General Public License v3 (AGPL-3.0) - see the LICENSE file for details. Contributions, bug reports, and improvements are welcome! Open an issue or submit a pull request with small, focused changes.