Fossil Mcp

Fossil MCP

氛围编程时代的代码质量工具包。

静态分析，发现氛围编程留下的混乱——死代码、重复逻辑、脚手架残留和孤立函数——覆盖 16 种语言。

fossil-mcp.com

问题

AI 辅助编码没问题——你审查代码，你理解架构，你保持掌控。氛围编程则不同。 你描述想要什么，AI 写出来，你不逐行阅读就发布。像 Claude Code、Cursor、GitHub Copilot 和 Windsurf 这样的工具让这种工作流快速且高效。但日复一日、周复一周，氛围编程的项目会累积一类传统 linter 无法捕捉的特定问题：

死代码迅速堆积。 当 AI 重构一个函数时，它会写新版本，但往往忘记删除旧版本。你不会注意到，因为你没有逐行阅读 diff。经过多次会话，未使用的函数、不可达的分支和孤立的工具函数不断堆积——代码库在增长，但没有任何东西被修剪。一项 METR 研究 发现，开发者在检查和调试 AI 输出上花费了大量时间。死代码让这件事变得指数级更难。

重复悄无声息地蔓延。 每个 AI 会话的上下文窗口都有限。它会生成一个别处已经存在的工具函数，或者在三个文件之外用略有不同的实现解决同一个问题。你要了一个功能，它能用，于是你继续前进。传统的重复检测专注于复制粘贴——氛围编程的重复是结构性的：相似的逻辑，不同的名字，分散在各个模块中。

// Phase 1、// TODO、// Step 2——到处都是。 AI Agent 分阶段工作。它们留下本应是临时的脚手架标记：// Phase 1: Setup、// TODO: implement error handling、用 pass 或 todo!() 占位的函数体，以及像 process_data_v2 这样的分阶段命名。在氛围编程中，没有人会回头清理这些。它们成了永久的固定装置。

存在没有任何东西调用的函数。 这是氛围编程的标志性特征。AI 写了一个辅助函数，使用了它，然后在之后的会话中重写调用方改用另一种方式——但辅助函数留下了。没有调用图，你和 AI 都无法分辨哪些函数实际上与代码库的其余部分相连。当前的 AI 编码工具通过文本搜索来导航代码，而不是通过理解函数之间如何相互调用。

临时文件在仓库中累积。 AI 会话会创建 temp_、backup_、old_、phase_1_ 文件和目录。在氛围编程中，你不会在每次会话后审计文件树。这些残留物会跨提交持续存在。

解决方案

Fossil MCP 是一个专为氛围编程项目打造的静态分析工具包。它能检测当 AI 编写大部分代码时累积的残留物——它既可作为面向开发者的 CLI 工具，也可作为 MCP 服务，为 AI Agent 提供代码图，而不仅仅是文本搜索。

  ███████╗ ██████╗ ███████╗███████╗██╗██╗           ()    ()
  ██╔════╝██╔═══██╗██╔════╝██╔════╝██║██║            \    /
  █████╗  ██║   ██║███████╗███████╗██║██║             |  |
  ██╔══╝  ██║   ██║╚════██║╚════██║██║██║             |  |
  ██║     ╚██████╔╝███████║███████║██║███████╗       /    \
  ╚═╝      ╚═════╝ ╚══════╝╚══════╝╚═╝╚══════╝      ()    ()
  Dig up dead code. Unearth clones. Expose scaffolding.

Fossil 能检测什么

Fossil 有何不同

• 专为 vibe coding 打造。 不是通用 linter——专门针对 AI 编写大部分代码、人类审查较少时积累的混乱。
• 用图，而不是 grep。 AI 编码工具通过搜索文本导航代码。Fossil 构建调用图，让 Agent 追踪函数如何连接，在重构前发现爆炸半径，发现死胡同——无需阅读每个文件。
• MCP 原生。 作为 MCP 服务运行，因此 AI Agent 可以在开发过程中自检其输出。
• 节省 token，节省金钱。 Agent 不必反复扫描文件来发现问题，Fossil 一次就能识别死代码、克隆和脚手架——减少大模型推理轮次，降低成本。
• 用 Rust 构建。 单一二进制文件，无运行时依赖。几秒钟扫描数千个文件。设计上内存安全。
• 跨文件分析。 解析导入、barrel 重导出和类层次结构，跨模块边界发现死代码。
• 框架感知。 自动检测 React、Next.js、Django、Spring、Axum 等——不会将生命周期方法误报为死代码。
• 零配置。 开箱即用。配置文件可选。
• 16 种语言。 一个工具应对多语言代码库。

安装

快速安装（推荐）

macOS / Linux：

curl -fsSL fossil-mcp.com/install.sh | sh

Windows (PowerShell)：

irm fossil-mcp.com/install.ps1 | iex

自动检测你的操作系统和架构，下载最新二进制文件，并将其添加到 PATH。

手动下载

从 GitHub Releases 下载适合你平台的最新二进制文件：

# macOS (Apple Silicon)
curl -L https://github.com/yfedoseev/fossil-mcp/releases/latest/download/fossil-mcp-macos-aarch64.tar.gz | tar xz
mv fossil-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/yfedoseev/fossil-mcp/releases/latest/download/fossil-mcp-macos-x86_64.tar.gz | tar xz
mv fossil-mcp /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/yfedoseev/fossil-mcp/releases/latest/download/fossil-mcp-linux-x86_64-musl.tar.gz | tar xz
mv fossil-mcp ~/.local/bin/

cargo-binstall

如果你有 cargo-binstall，它会下载预构建的二进制文件，而不是从源码编译：

cargo binstall fossil-mcp

来自 crates.io

cargo install fossil-mcp

这会从 crates.io 下载源码并在本地编译。需要 Rust 工具链。

来自源码

git clone https://github.com/yfedoseev/fossil-mcp.git
cd fossil-mcp
cargo build --release

二进制文件位于 ./target/release/fossil-mcp。

更新

fossil-mcp update

MCP 服务设置

Fossil 默认作为 MCP 服务运行 —— 只需不带参数运行 fossil-mcp。将它连接到你的 AI 编码工具：

claude mcp add fossil fossil-mcp

{
  "mcpServers": {
    "fossil": {
      "command": "fossil-mcp"
    }
  }
}

{
  "mcpServers": {
    "fossil": {
      "command": "fossil-mcp"
    }
  }
}

{
  "mcp": {
    "servers": {
      "fossil": {
        "command": "fossil-mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "fossil": {
      "command": "fossil-mcp"
    }
  }
}

{
  "mcpServers": {
    "fossil": {
      "command": "fossil-mcp"
    }
  }
}

MCP 工具

连接后，你的 AI Agent 即可使用以下工具：

命令行用法

模式

Fossil 有四种运行模式：

交互式模式

不带参数运行 fossil-mcp（或 fossil-mcp scan .）会扫描当前目录中的死代码、克隆和脚手架，显示仪表板，然后进入交互式 REPL：

  FOSSIL Scanning .
  ────────────────────────────────────────────────
   ✓  1200 nodes analyzed, 42 unreachable
   ✓  380 files analyzed, 8 clone groups
   ✓  3 scaffolding artifacts

  ══════════════════════════════════════════════════
  RESULTS  53  findings across 28 files
  ══════════════════════════════════════════════════

  ▐ Dead Code     42   ██████████████░░
  ▐ Clones         8   ██░░░░░░░░░░░░░░    120 duplicated lines
  ▐ Scaffolding    3   █░░░░░░░░░░░░░░░

  fossil>

REPL 命令

所有探索命令都支持可选的计数和语言过滤器：command [N] [lang]

fossil> dead 10                  # Top 10 dead code findings
fossil> dead 20 typescript       # Top 20 dead code in TypeScript
fossil> clones 5 rust            # Top 5 clone groups in Rust
fossil> scaffolding              # All scaffolding findings
fossil> scaffolding 10 python    # Top 10 scaffolding in Python
fossil> hotspots                 # Files with most findings
fossil> hotspots 10 go           # Top 10 hotspot files in Go
fossil> file auth.ts             # All findings in a specific file
fossil> langs                    # Language breakdown
fossil> export sarif             # Export full SARIF report
fossil> summary                  # Re-show dashboard
fossil> q                        # Quit

命令

fossil-mcp scan [path]

运行所有分析（死代码 + 克隆 + 脚手架）并显示交互式仪表板。

fossil-mcp scan .
fossil-mcp scan /path/to/project --format sarif -o results.sarif
fossil-mcp scan /path/to/project --format json

fossil-mcp dead-code [path]

仅进行死代码检测。

fossil-mcp dead-code .
fossil-mcp dead-code . --min-confidence high
fossil-mcp dead-code . --min-lines 10
fossil-mcp dead-code . --language rust,python
fossil-mcp dead-code . --diff main                  # Only changed files
fossil-mcp dead-code . --stats                      # Show graph statistics
fossil-mcp dead-code . --cache-dir .fossil-cache     # Persistent cache
fossil-mcp dead-code . --cache-stats                 # Cache hit rate

fossil-mcp clones [path]

仅检测克隆（重复代码）。

fossil-mcp clones .
fossil-mcp clones . --min-lines 10
fossil-mcp clones . --similarity 0.9
fossil-mcp clones . --language typescript
fossil-mcp clones . --types type1,type2

fossil-mcp scaffolding [path]

检测 AI 生成的脚手架痕迹。

fossil-mcp scaffolding .
fossil-mcp scaffolding . --language rust
fossil-mcp scaffolding . --include-todos
fossil-mcp scaffolding . --format json

检测：占位符主体（pass、todo!()、unimplemented!()）、分阶段注释（Phase 1、Step 2）、脚手架标识符（scaffold_*、boilerplate_*）、调试打印，以及临时文件（temp_*、backup_*、old_*）。

fossil-mcp check [path]

CI/CD 模式 — 当超过阈值时使构建失败。完整详情见 CI/CD 集成。

fossil-mcp check
fossil-mcp check --max-dead-code 10 --max-clones 5
fossil-mcp check --diff origin/main
fossil-mcp check --diff origin/main --format sarif
fossil-mcp check --fail-on-scaffolding

fossil-mcp weekly

显示开源项目中每周的 AI 垃圾内容排名。

fossil-mcp weekly
fossil-mcp weekly --detailed

fossil-mcp update

将 fossil-mcp 更新到最新版本。

fossil-mcp update
fossil-mcp update --check    # Check without installing

fossil-mcp mcp

显式启动 MCP 服务（通常通过管道 stdin 自动检测）。

全局标志

这些标志适用于所有命令：

支持的语言

配置（可选）

Fossil 可零配置工作。所有设置都有合理的默认值。如果需要自定义行为，请在项目根目录创建 fossil.toml：

[dead_code]
min_confidence = "high"       # low, medium, high, certain
include_tests = false
exclude_patterns = ["generated/**", "vendor/**"]

[clones]
min_lines = 6
similarity_threshold = 0.8

[entry_points]
# Mark additional functions as entry points (won't be flagged as dead)
functions = ["custom_handler", "my_entry"]
# Additional entry point attributes/decorators
attributes = ["MyFramework::route"]
# Framework presets (auto-detected by default)
presets = ["axum", "react"]
auto_detect_presets = true

配置会从以下文件名自动发现：fossil.toml、.fossil.toml、fossil.yml、fossil.yaml、fossil.json。

环境变量会覆盖配置文件中的值：

框架预设

预设会从项目依赖中自动检测。它们会告诉 Fossil 哪些函数是框架入口点（生命周期钩子、路由处理器等），从而不会被标记为死代码：

CI/CD 集成

Fossil 包含一个用于 CI/CD 流水线的 check 命令。当代码质量阈值被超出时，它会使构建失败，帮助团队强制执行代码标准并防止技术债务累积。

基本用法

# Check against configured thresholds
fossil-mcp check

# Override thresholds via CLI
fossil-mcp check --max-dead-code 10 --max-clones 5

# Diff-aware mode (only analyze changed files in PR)
fossil-mcp check --diff origin/main

# Generate SARIF for GitHub code scanning
fossil-mcp check --diff origin/main --format sarif

# Quiet mode (no diagnostic output)
fossil-mcp check --quiet

配置

在 fossil.toml 中添加 [ci] 配置段：

[ci]
max_dead_code = 10           # Maximum dead code findings (0 = fail on any)
max_clones = 5               # Maximum clone findings
max_scaffolding = 3          # Maximum scaffolding findings
min_confidence = "medium"    # Minimum confidence (low|medium|high|certain)
fail_on_scaffolding = false  # Fail if any scaffolding found

GitHub Actions 集成

创建 .github/workflows/fossil-check.yml：

name: Fossil CI Check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  fossil:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Fossil
        run: curl -fsSL fossil-mcp.com/install.sh | sh

      - name: Run Fossil check
        run: |
          fossil-mcp check \
            --diff origin/${{ github.base_ref || 'main' }} \
            --format sarif \
            > fossil-results.sarif

      - name: Upload to GitHub Security
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: fossil-results.sarif

工作原理

1. 使用与 scan 相同的分析引擎 扫描 项目
2. 可选地筛选 仅变更文件（通过 --diff branch）
3. 根据配置的阈值进行 评估
4. 将结果 报告 为文本、JSON 或 SARIF
5. 如果超出阈值则 退出 并返回代码 1（使 CI 构建失败）

退出代码

完整示例请参见 examples/fossil.toml 和 examples/fossil-check.yml。

工作原理

1. 扫描 — 遍历项目文件，遵循 .gitignore，跳过供应商/生成的代码
2. 解析 — 为每个源文件构建 tree-sitter AST（16 种语言）
3. 提取 — 从 AST 中提取函数、调用、导入、属性和类层次结构
4. 构建图 — 构建带有导入解析和 barrel 重导出支持的跨文件 CodeGraph
5. 分析 — 检测入口点（通过启发式 + 框架预设），运行可达性分析，识别死代码和克隆
6. 报告 — 将结果输出为文本仪表盘、JSON 或 SARIF

贡献

我们欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

• 行为准则
• 安全策略

许可

根据您的选择，在 Apache License, Version 2.0 或 MIT License 下授权。