Knowerage — Verwaltung der KI-Analyseabdeckung

Ein Local-First MCP-Server, der die Abdeckung und Aktualität von Legacy-Code-Analysen verfolgt.

Quelle: github.com/MTimma/knowerage

Schnellstart

Voraussetzungen: Node.js 18 oder neuer — npx muss in Ihrem PATH vorhanden sein (es wird mit npm geliefert, das in Node enthalten ist).

Related MCP server: Atlas

MCP-Server-Konfiguration

Registrieren Sie Knowerage dort, wo Ihr MCP-Host Serverdefinitionen erwartet (einige Clients verwenden beispielsweise .cursor/mcp.json oder .vscode/mcp.json; andere nutzen Umgebungsvariablen oder eine Benutzeroberfläche – folgen Sie der Dokumentation Ihres Hosts). Verwenden Sie das gleiche Format für den Servereintrag:

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

Ersetzen Sie ${workspaceFolder} durch Ihr Projektstammverzeichnis, falls Ihr Host diese Variable nicht auflöst.

KNOWERAGE_AUTO_FULL_RECONCILE ist optional: Wenn es nicht gesetzt, leer oder kein wahrheitsgemäßer Wert ist, ist der Datei-Watcher standardmäßig aus. Setzen Sie es auf 1, true, yes oder on (getrimmt, unabhängig von Groß-/Kleinschreibung), um es zu aktivieren. Wenn es an ist, überwacht der Server knowerage/ und führt nach einer kurzen Entprellung bei Dateisystemänderungen knowerage_reconcile_all aus. Das ist nicht dasselbe wie ein vollständiger Abgleich nach jedem MCP-Tool-Aufruf – es reagiert nur auf Dateiänderungen unter knowerage/. Schreibvorgänge der Registrierung in registry.json werden vom Watcher ignoriert, damit Speichervorgänge keine Endlosschleifen verursachen.

Verwendung von Knowerage

Nachdem der MCP-Server konfiguriert ist, sprechen Sie in normalen Sätzen mit Ihrem Assistenten. Sie müssen sich keine Tool-Namen merken.

Code analysieren oder dokumentieren

Verweisen Sie auf Dateien, Klassen oder Verhalten, die Sie interessieren. Zum Beispiel:

• Analysiere mit Knowerage den logischen Algorithmus-Workflow in main.java.

• Analysiere die Logik zur Datenentitätsabgleichung und Versionierung im ETL-Service.

Der Assistent erstellt oder aktualisiert Markdown-Dateien unter knowerage/analysis/ und protokolliert die Abdeckung in knowerage/registry.json (siehe Funktionsweise unten).

Abdeckung und Lücken (gleiches Projekt, späterer Chat oder anderer Agent)

Wenn Sie bereits Analysen im Baum haben, können Sie fragen:

• Wie viel Prozent des Codes ist durch unsere Analyse abgedeckt?

• Welcher Teil dieser Codebasis ist noch nicht analysiert?

Knowerage beantwortet dies basierend auf der Registrierung und den Abdeckungs-Hilfsprogrammen (z. B. Übersicht, Status pro Datei und Listen veralteter Einträge) – nicht durch vage Vermutungen über das Repository.

Alternative Ansätze

Installation via npm

npx @mtimma/knowerage

Oder aus dem Quellcode bauen

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

Funktionsweise

1. Der KI-Agent erstellt Analyse-.md-Dateien mit YAML-Frontmatter, das die Quelldatei und die abgedeckten Zeilenbereiche deklariert.

2. Die Registrierung (knowerage/registry.json) verfolgt Analyse-Datensätze mit SHA-256-Hashes für die Aktualität.

3. MCP-Tools stellen Operationen zum Erstellen, Abgleichen, Abfragen und Exportieren bereit.

4. Der Agent sagt "analysiere X" → der vollständige Workflow läuft automatisch ab (erstellen → abgleichen → protokollieren).

Format der Registrierungsdatei (knowerage/registry.json)

Das Format auf der Festplatte ist ein JSON-Objekt, dessen Schlüssel Analysepfade (Strings) sind. Jeder Wert ist ein Datensatz (siehe contracts/contracts.md). Ein vollständiges Beispiel mit zwei Datensätzen finden Sie unter 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

Das Frontmatter für Analyse-.md-Dateien wird separat im Contracts-Dokument (Metadaten-Schema) spezifiziert, nicht innerhalb der registry.json.

MCP-Tools

Projektstruktur

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

Dokumentation

• Benutzer-Onboarding — Einrichtung, Konfiguration, typische Verwendung

• INSTRUCTIONS.md — Anweisungen für den MCP-Agenten

• Rust-Praktiken

• JS-Praktiken

• Verträge — Schemata und API-Verträge (Registrierung + Frontmatter)

• Beispiel-Registrierungs-JSON — Inhalt der Beispiel-registry.json

Sicherheit

• Alle Pfade werden gegen das Arbeitsverzeichnis validiert

• Pfad-Traversal (..) wird abgelehnt

• Atomare Schreibvorgänge für die Registrierung (absturzsicher)

• Keine Geheimnisse in Analysedateien oder Berichten

• SHA-256-Hash-basierte Aktualitätsprüfung (übersteht git pull)

Lizenz

MIT — Copyright Martins Timma.

Teile dieses Projekts wurden mit generativen KI-Coding-Assistenten geschrieben oder verfeinert. Menschliche Überprüfung gilt für Design, sicherheitsrelevantes Verhalten und Releases.