Fossil MCP

Fossil MCP

O kit de ferramentas de qualidade de código para a era do vibe coding.

Análise estática que encontra a bagunça que o vibe coding deixa para trás — código morto, lógica duplicada, artefatos de scaffolding e funções desconectadas — em 16 linguagens.

fossil-mcp.com

O Problema

Codificação assistida por IA é aceitável — você revisa o código, entende a arquitetura e mantém o controle. Vibe coding é diferente. Você descreve o que quer, a IA escreve e você envia sem ler cada linha. Ferramentas como Claude Code, Cursor, GitHub Copilot e Windsurf tornam esse fluxo de trabalho rápido e produtivo. Mas, ao longo de dias e semanas, projetos feitos com vibe coding acumulam uma classe específica de problemas que os linters tradicionais não detectam:

Código morto se acumula rápido. Quando a IA refatora uma função, ela escreve a nova versão, mas muitas vezes esquece de remover a antiga. Você não percebe porque não leu o diff linha por linha. Em várias sessões, funções não utilizadas, ramificações inalcançáveis e utilitários órfãos se acumulam — a base de código cresce, mas nada é podado. Um estudo da METR descobriu que desenvolvedores gastam tempo significativo verificando e depurando a saída da IA. Código morto torna isso exponencialmente mais difícil.

Duplicação se espalha silenciosamente. Cada sessão de IA tem uma janela de contexto limitada. Ela gera uma função utilitária que já existe em outro lugar, ou resolve o mesmo problema com uma implementação ligeiramente diferente três arquivos adiante. Você pediu um recurso, ele funciona, então você segue em frente. A detecção tradicional de duplicação foca em copiar e colar — a duplicação do vibe coding é estrutural: lógica semelhante, nomes diferentes, espalhada entre módulos.

// Phase 1, // TODO, // Step 2 — em todo lugar. Agentes de IA trabalham em fases. Eles deixam marcadores de scaffolding que deveriam ser temporários: // Phase 1: Setup, // TODO: implement error handling, corpos de função placeholder com pass ou todo!(), e nomenclatura em fases como process_data_v2. No vibe coding, ninguém volta para limpar isso. Eles se tornam elementos permanentes.

Existem funções que nada chama. Esta é a assinatura do vibe coding. A IA escreve uma função auxiliar, usa-a e, em uma sessão posterior, reescreve o chamador para usar uma abordagem diferente — mas a função auxiliar permanece. Sem um grafo de chamadas, nem você nem a IA conseguem dizer quais funções estão realmente conectadas ao restante da base de código. As ferramentas atuais de codificação com IA navegam pelo código por busca de texto, não por entender como as funções se chamam.

Arquivos temporários se acumulam no repositório. Sessões de IA criam arquivos e diretórios temp_, backup_, old_, phase_1_. No vibe coding, você não audita sua árvore de arquivos após cada sessão. Esses artefatos persistem entre commits.

A Solução

Fossil MCP é um kit de ferramentas de análise estática criado especificamente para projetos de vibe coding. Ele detecta os artefatos que se acumulam quando a IA escreve a maior parte do código — e funciona tanto como uma ferramenta CLI para desenvolvedores quanto como um servidor MCP que dá aos agentes de IA um grafo de código em vez de apenas busca de texto.

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

O que o Fossil Detecta

O Que Torna o Fossil Diferente

• Feito sob medida para vibe coding. Não é um linter genérico — visa especificamente a bagunça que se acumula quando a IA escreve a maior parte do código e os humanos revisam menos.
• Grafo, não grep. Ferramentas de codificação com IA navegam pelo código buscando texto. O Fossil constrói um grafo de chamadas e permite que agentes rastreiem como as funções se conectam, encontrem o raio de impacto antes de refatorar e descubram becos sem saída — sem ler cada arquivo.
• Nativo para MCP. Funciona como um servidor MCP para que agentes de IA possam verificar sua própria saída durante o desenvolvimento.
• Economiza tokens, economiza dinheiro. Em vez de um agente escanear arquivos repetidamente para encontrar problemas, o Fossil identifica código morto, clones e scaffolding em uma única passada — menos rodadas de inferência de LLM, menor custo.
• Construído em Rust. Binário único, sem dependências de runtime. Escaneia milhares de arquivos em segundos. Seguro por design em relação à memória.
• Análise entre arquivos. Resolve imports, re-exports de barris e hierarquias de classes para encontrar código morto através de limites de módulos.
• Ciente de frameworks. Detecta automaticamente React, Next.js, Django, Spring, Axum e mais — não sinalizará métodos de ciclo de vida como código morto.
• Zero configuração. Funciona imediatamente. O arquivo de configuração é opcional.
• 16 linguagens. Uma ferramenta para bases de código poliglotas.

Instalação

Instalação rápida (recomendada)

macOS / Linux:

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

Windows (PowerShell):

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

Detecta automaticamente seu sistema operacional e arquitetura, baixa o binário mais recente e o adiciona ao seu PATH.

Download manual

Baixe o binário mais recente para sua plataforma em 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

Se você tem cargo-binstall, ele baixa binários pré-compilados em vez de compilar a partir do código-fonte:

cargo binstall fossil-mcp

Do crates.io

cargo install fossil-mcp

Isso baixa o código-fonte do crates.io e o compila localmente. Requer um toolchain Rust.

Do código-fonte

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

O binário está em ./target/release/fossil-mcp.

Atualização

fossil-mcp update

Configuração do Servidor MCP

O Fossil funciona como um servidor MCP por padrão — basta executar fossil-mcp sem argumentos. Conecte-o à sua ferramenta de codificação com IA:

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

Ferramentas MCP

Uma vez conectado, seu agente de IA tem acesso a estas ferramentas:

Uso da CLI

Modos

O Fossil tem quatro modos de operação:

Modo Interativo

Executar fossil-mcp sem argumentos (ou fossil-mcp scan .) escaneia o diretório atual em busca de código morto, clones e scaffolding, mostra um painel e, em seguida, entra em um REPL interativo:

  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>

Comandos do REPL

Todos os comandos de exploração suportam filtro opcional de contagem e linguagem: 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

Comandos

fossil-mcp scan [path]

Executa todas as análises (código morto + clones + scaffolding) com painel interativo.

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]

Apenas detecção de código morto.

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]

Apenas detecção de clones (código duplicado).

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]

Detecta artefatos de scaffolding gerados por IA.

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

Detecta: corpos placeholder (pass, todo!(), unimplemented!()), comentários em fases (Phase 1, Step 2), identificadores de scaffolding (scaffold_*, boilerplate_*), prints de depuração e arquivos temporários (temp_*, backup_*, old_*).

fossil-mcp check [path]

Modo CI/CD — falha em builds quando limites são excedidos. Veja Integração CI/CD para detalhes completos.

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

Mostre as classificações semanais de "AI slop" em projetos de código aberto.

fossil-mcp weekly
fossil-mcp weekly --detailed

fossil-mcp update

Atualize o fossil-mcp para a versão mais recente.

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

fossil-mcp mcp

Inicie o servidor MCP explicitamente (normalmente detectado automaticamente via stdin canalizado).

Flags Globais

Estas flags funcionam com todos os comandos:

Linguagens Suportadas

Configuração (Opcional)

O Fossil funciona com zero configuração. Todas as configurações têm padrões sensatos. Se você precisar personalizar o comportamento, crie um fossil.toml na raiz do seu projeto:

[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

A configuração é descoberta automaticamente a partir destes nomes de arquivo: fossil.toml, .fossil.toml, fossil.yml, fossil.yaml, fossil.json.

Variáveis de ambiente sobrescrevem os valores do arquivo de configuração:

Presets de Framework

Os presets são detectados automaticamente a partir das dependências do projeto. Eles informam ao Fossil quais funções são pontos de entrada do framework (hooks de ciclo de vida, manipuladores de rota, etc.) para que não sejam sinalizados como código morto:

Integração CI/CD

O Fossil inclui um comando check para pipelines de CI/CD. Ele falha as builds quando os limites de qualidade de código são excedidos, ajudando as equipes a aplicar padrões de código e evitar o acúmulo de dívida técnica.

Uso Básico

# 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

Configuração

Adicione uma seção [ci] ao fossil.toml:

[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

Integração com GitHub Actions

Crie .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

Como Funciona

1. Escaneia o projeto usando o mesmo mecanismo de análise do scan
2. Opcionalmente filtra para apenas arquivos alterados (via --diff branch)
3. Avalia em relação aos limites configurados
4. Relata achados como texto, JSON ou SARIF
5. Sai com código 1 se os limites forem excedidos (falha a build de CI)

Códigos de Saída

Para exemplos completos, veja examples/fossil.toml e examples/fossil-check.yml.

Como Funciona

1. Escaneia — percorre os arquivos do projeto, respeita .gitignore, ignora código vendido/gerado
2. Analisa sintaticamente — constrói ASTs tree-sitter para cada arquivo de código-fonte (16 linguagens)
3. Extrai — obtém funções, chamadas, importações, atributos e hierarquia de classes dos ASTs
4. Grafo — constrói um CodeGraph entre arquivos com resolução de importações e suporte a re-exportação de barris
5. Analisa — detecta pontos de entrada (via heurísticas + presets de framework), executa análise de alcançabilidade, identifica código morto e clones
6. Relata — gera saída de achados como painel de texto, JSON ou SARIF

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para obter diretrizes.

• Código de Conduta
• Política de Segurança

Licença

Licenciado sob Apache License, Version 2.0 ou MIT License, à sua escolha.