Pecorino

Pecorino MCP 服务

用于深入分析 Git 历史统计数据、跟踪仓库健康状况以及分析面向对象设计（OOD）指标的模型上下文协议（MCP）服务。

Pecorino 可让大语言模型（LLM）和开发工具（如 Claude Desktop 或 Cursor）检查代码库、分析代码结构、计算复杂度和可维护性指数，并检测风险热点。

---

功能

• 模型上下文协议（MCP）：向 AI 助手提供 5 个统一工具（browse、search、update_index、set_workspace、metrics）。
• 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

将 Pecorino 添加到你的 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"
      }
    }
  }
}

（将 /path/to/pecorino 替换为实际的绝对路径）。

---

提供的 MCP 工具

连接后，你的 AI 助手可以使用以下工具：

1. browse

浏览代码库结构（树、依赖项、类、函数、PageRank、摘要），或通过 view="code" 获取指定代码行。用于查看结构和获取代码。

2. search

支持多种模式的统一搜索与分析工具：

• hybrid（默认）——结合向量相似度和 SQLite3 FTS，并使用 RRF 和 LTR 评分。
• fts ——在整个代码库中进行全文关键词搜索。
• callers / callees ——调用图分析：谁调用了 X？X 调用了什么？
• impact ——从文件或目录开始深入追踪依赖关系。
• usages ——在一次调用中结合搜索与调用方查询（查找定义及所有调用方）。
• 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 索引并返回结构摘要。克隆仓库或进行重大更改后调用一次。

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）：原生 SQLite3 C 扩展，使用 Linux io_uring 实现快速异步 BM25F 全文搜索。
4. AI 重排与学习排序（src/mcp_server/cross_encoder.py 和 ltr_ranker.py）：
   • 交叉编码器重排：使用成对交叉编码器，对排名靠前的候选结果进行 ONNX 重排。
   • LTR 模型：融合 20 多种信号（PageRank、中介中心性、OOD 指标、Git 变更频率/作者熵）。
   • 命名分析：使用备用本地 LLM 进行启发式解析。
5. Git 分析引擎（src/git/、src/core/）：解析 reflog 和提交历史，构建时间耦合图并跟踪代码变更频率。
6. MCP 传输层（src/transports/）：通过标准 Model Context Protocol（stdio、SSE）向 AI Agent 提供索引、向量和图数据库。

提示

所用模型一览

• 嵌入模型：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/ — Git 子模块，包括 gorgonzola、py-tree-sitter 和 pecorino-utils。
• docs/ — 架构文档（搜索、索引、可观测性与安全、Agent 技能、演进时间线）。
• 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 通用公共许可证 v3（AGPL-3.0）授权，详情请参阅 LICENSE 文件。欢迎贡献、报告错误和提出改进建议！请提交问题，或提交包含小幅、专注更改的拉取请求。