Knowerage

Knowerage — Gerenciamento de Cobertura de Análise com IA

Links: GitHub · Listagem MCP do Glama · npm @mtimma/knowerage

Início Rápido

Requisitos: Node.js 18 ou mais recente — npx deve estar no seu PATH (ele vem com o npm, que está incluído no Node).

Configuração do servidor MCP

Registre o Knowerage onde seu host MCP espera definições de servidor (por exemplo, alguns clientes usam .cursor/mcp.json ou .vscode/mcp.json; outros usam variáveis de ambiente ou uma interface—siga a documentação do seu host). Use o mesmo formato de entrada de servidor:

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

Substitua ${workspaceFolder} pela raiz do seu projeto se o seu host não expandir essa variável.

KNOWERAGE_AUTO_FULL_RECONCILE é opcional: quando não definido, vazio ou não for um valor verdadeiro, o observador de arquivos fica desativado por padrão. Defina como 1, true, yes ou on (sem espaços, sem diferenciar maiúsculas/minúsculas) para ativar. Quando ativado, o servidor observa knowerage/ e, após um pequeno debounce, executa knowerage_reconcile_all em alterações do sistema de arquivos. Isso não é o mesmo que executar uma reconciliação completa após cada chamada de ferramenta MCP—ele apenas reage a alterações de arquivos em knowerage/. Gravações do registro em registry.json são ignoradas pelo observador para que salvamentos não entrem em loop.

Como usar o Knowerage

Após configurar o servidor MCP, você conversa com seu assistente em frases normais. Você não precisa memorizar nomes de ferramentas.

Analisar ou documentar código

Aponte para arquivos, classes ou comportamentos que você considera importantes. Por exemplo:

• Usando o Knowerage, analise o fluxo do algoritmo lógico em main.java.
• Analise a lógica de reconciliação e versionamento de entidades de dados no serviço ETL.

O assistente cria ou atualiza markdown em knowerage/analysis/ e registra a cobertura em knowerage/registry.json (veja Como Funciona abaixo).

Cobertura e lacunas (mesmo projeto, chat posterior ou outro agente)

Quando você já tem análises na árvore, pode perguntar:

• Em porcentagem, quanto do código nossa análise já cobriu?
• Qual parte deste código ainda não foi analisada?

O Knowerage responde a essas perguntas a partir do registro e dos auxiliares de cobertura (por exemplo, visão geral, status por arquivo e listas de desatualizados)—não por suposições sobre o repositório.

Abordagens alternativas

Instalar via npm

npx @mtimma/knowerage

Ou compilar a partir do código-fonte

cargo build --release
./target/release/knowerage-mcp

Como Funciona

1. O agente de IA cria arquivos de análise .md com frontmatter YAML declarando o arquivo de origem e os intervalos de linhas cobertos
2. O registro (knowerage/registry.json) rastreia registros de análise com hashes SHA-256 para verificar atualização
3. As ferramentas MCP expõem operações de criação, reconciliação, consulta e exportação
4. O agente diz "analise X" → o fluxo completo é executado automaticamente (criar → reconciliar → registrar)

Formato do arquivo de registro (knowerage/registry.json)

O formato em disco é um objeto JSON cujas chaves são caminhos de análise (strings). Cada valor é um registro (veja contracts/contracts.md). Um exemplo completo com dois registros está em examples/registry.sample.json.

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

O frontmatter para arquivos de análise .md é especificado separadamente no documento de contratos (esquema de metadados), não dentro de registry.json.

Ferramentas MCP

Ferramenta	Finalidade
knowerage_create_or_update_doc	Criar/atualizar documento de análise
knowerage_parse_doc_metadata	Analisar e validar frontmatter
knowerage_reconcile_record	Reconciliar um registro de análise
knowerage_reconcile_all	Reescaneamento/reconstrução completa
knowerage_get_file_status	Intervalos analisados vs. ausentes
knowerage_list_stale	Listar registros desatualizados/problemáticos
knowerage_list_registry	Snapshot completo do registro (mesma forma que registry.json, chaves ordenadas)
knowerage_get_tree	Cobertura em árvore/agrupada
registry_export_report	Exportar snapshot (JSON/YAML/TXT/HTML)
knowerage_generate_bundle	Exportação em partes de análises selecionadas (toc*.md, combined*.md, manifest.json)

Estrutura do Projeto

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

Documentação

• Onboarding do Usuário — Instalação, configuração, uso típico
• INSTRUCTIONS.md — Instruções do agente MCP
• Práticas Rust
• Práticas JS
• Contratos — Esquemas e contratos de API (registro + frontmatter)
• Exemplo de registro JSON — Exemplo de conteúdo de registry.json

Segurança

• Todos os caminhos validados contra a raiz do workspace
• Travessia de caminho (..) rejeitada
• Gravações atômicas para o registro (à prova de falhas)
• Sem segredos em arquivos de análise ou relatórios
• Atualização baseada em hash SHA-256 (sobrevive a git pull)

Licença

MIT — direitos autorais de Martins Timma.

Partes deste projeto foram escritas ou refinadas com assistentes de codificação com IA generativa. A revisão humana se aplica ao design, ao comportamento sensível à segurança e aos lançamentos.