Skip to main content
Glama

Knowerage — AI Analysis Coverage Management

Links: GitHub · Glama MCP listing · npm @mtimma/knowerage

Quick Start

Requirements: Node.js 18 or newer — npx must be on your PATH (it comes with npm, which is included with Node).

Related MCP server: Atlas

MCP server configuration

Register Knowerage wherever your MCP host expects server definitions (for example some clients use .cursor/mcp.json or .vscode/mcp.json; others use environment variables or a UI—follow your host’s documentation). Use the same server entry shape:

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

Replace ${workspaceFolder} with your project root if your host does not expand that variable.

KNOWERAGE_AUTO_FULL_RECONCILE is optional: when unset, empty, or not a truthy value, the file watcher defaults to off. Set to 1, true, yes, or on (trimmed, case-insensitive) to enable. When on, the server watches knowerage/ and, after a short debounce, runs knowerage_reconcile_all on filesystem changes. That is not the same as running a full reconcile after every MCP tool call—it only reacts to file changes under knowerage/. Registry writes to registry.json are ignored by the watcher so saves do not loop.

How to use Knowerage

After the MCP server is configured, you talk to your assistant in normal sentences. You do not need to memorize tool names.

Analyse or document code

Point at files, classes, or behaviour you care about. For example:

  • Using Knowerage, analyse the logical algorithm workflow in main.java.

  • Analyze the data entity reconciliation and versioning logic in the ETL service.

The assistant creates or updates markdown under knowerage/analysis/ and records coverage in knowerage/registry.json (see How It Works below).

Coverage and gaps (same project, later chat or another agent)

When you already have analyses in the tree, you can ask:

  • In percentage, how much of the code has our analysis covered?

  • What part of this codebase is not yet analysed?

Knowerage answers these from the registry and coverage helpers (for example overview, per-file status, and stale lists)—not from hand-waving over the repo.

Alternative approaches

Install via npm

npx @mtimma/knowerage

Or build from source

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

How It Works

  1. AI agent creates analysis .md files with YAML frontmatter declaring source file and covered line ranges

  2. Registry (knowerage/registry.json) tracks analysis records with SHA-256 hashes for freshness

  3. MCP tools expose create, reconcile, query, and export operations

  4. Agent says "analyze X" → full workflow runs automatically (create → reconcile → record)

Registry file shape (knowerage/registry.json)

The on-disk format is a JSON object whose keys are analysis paths (strings). Each value is one record (see contracts/contracts.md). A full sample with two records lives at 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

Frontmatter for analysis .md files is specified separately in the contracts doc (metadata schema), not inside registry.json.

MCP Tools

Tool

Purpose

knowerage_create_or_update_doc

Create/update analysis document

knowerage_parse_doc_metadata

Parse and validate frontmatter

knowerage_reconcile_record

Reconcile one analysis record

knowerage_reconcile_all

Full rescan/rebuild

knowerage_get_file_status

Analyzed vs missing ranges

knowerage_list_stale

List stale/problematic records

knowerage_list_registry

Full registry snapshot (same shape as registry.json, sorted keys)

knowerage_get_tree

Tree/grouped coverage

registry_export_report

Export snapshot (JSON/YAML/TXT/HTML)

knowerage_generate_bundle

Chunked export of selected analyses (toc*.md, combined*.md, manifest.json)

Project Structure

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

Documentation

Security

  • All paths validated against workspace root

  • Path traversal (..) rejected

  • Atomic writes for registry (crash-safe)

  • No secrets in analysis files or reports

  • SHA-256 hash-based freshness (survives git pull)

License

MIT — copyright Martins Timma.

Parts of this project were written or refined with generative AI coding assistants. Human review applies to design, security-sensitive behavior, and releases.

Available Tools

11 tools
knowerage_coverage_overviewA

Batch coverage overview for all source files. Returns per-source coverage percentage, analyzed/missing ranges, range attribution, stale records, and project-wide file/line totals. Uses fresh records only for coverage calculation. Optional extensions filter applies to sources, stale list, and project scan.

Inputs: extensions.

knowerage_create_or_update_docA

PRIMARY tool for persisting legacy/source code analysis: create or update an analysis markdown file under knowerage/analysis/ with YAML frontmatter (source path, covered line ranges, dates). Use this whenever the user asks to analyze, document, or explain a source file and Knowerage is in the tool list—do not use generic file-write tools alone for knowerage analysis paths, or the registry will not stay consistent. Follow with knowerage_reconcile_record on the same analysis_path.

Inputs: analysis_path (required), content (required), covered_lines (required), source_path (required).

knowerage_generate_bundleA

Export selected analysis markdown files into chunked NotebookLM-style bundles under output_dir: writes toc.md + combined.md for part 1, toc_N.md + combined_N.md for further parts when size limits require splitting, plus manifest.json (files, errors, part metadata). Every analysis_paths entry is validated under the workspace (no traversal). Per-file and per-part size limits apply (see contracts).

Inputs: analysis_paths (required), output_dir (required).

knowerage_get_file_statusA

Per-source coverage: total lines, analyzed vs missing ranges, and which analysis paths claim them. Prefer this over guessing from open files when answering 'what is documented for this source?' while Knowerage is enabled.

Inputs: source_path (required).

knowerage_get_treeC

Get a tree view of analysis records grouped by directory

Inputs: group_by, root.

knowerage_list_registryA

Return the full analysis coverage registry in one structured JSON response. USE THIS when you need an inventory of which source files are documented, where the analysis markdown lives, which line ranges are claimed, and freshness (fresh/stale_doc/stale_src/missing_src/dangling_doc). The records object is the same shape as the entire knowerage/registry.json file (sorted keys for stable reading). Call early when planning documentation work, finding gaps, or mapping analysis paths to sources—instead of opening registry.json by hand. Optional filters: analysis_path_prefix narrows by analysis key; statuses limits to given status values (same strings as in each record). After reconcile_record/reconcile_all, call again if you need the latest snapshot.

Inputs: analysis_path_prefix, statuses.

knowerage_list_staleB

List registry records filtered by staleness status

Inputs: statuses.

knowerage_parse_doc_metadataB

Parse YAML frontmatter from an analysis markdown file

Inputs: analysis_path (required).

knowerage_reconcile_allA

Rescan all analysis markdown files matching the glob and rebuild registry entries. Use after git pull, bulk edits, or when the registry may be empty or out of date; prefer reconcile_record when only one file changed.

Inputs: analysis_glob.

knowerage_reconcile_recordA

MANDATORY after every create_or_update_doc (or manual edit) to one analysis file: reconciles that analysis into knowerage/registry.json (hashes, covered_ranges, freshness). Call immediately after writing analysis content so coverage is recorded; skipping this leaves the registry wrong or stale.

Inputs: analysis_path (required).

registry_export_reportB

Export the registry as a report file in json, yaml, txt, or html format

Inputs: format (required), output_path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: coverage overview per batch, per-source status, registry listing with filters, doc creation/update, reconciliation, bundle generation, tree view, metadata parsing, stale listing, and export. Even overlapping tools like list_registry and list_stale are clearly differentiated by filters and purpose.

    Naming Consistency3/5

    All tools use the 'knowerage_' prefix except for 'registry_export_report', which breaks the pattern. Within the prefixed group, naming follows a consistent verb_noun style (e.g., get_file_status, create_or_update_doc, reconcile_record). The one outlier lowers the score.

    Tool Count5/5

    With 11 tools, the server covers the core operations of a documentation coverage system (CRUD-like, reconciliation, reporting, exploration) without being excessive. Each tool serves a clear purpose and none feel redundant.

    Completeness4/5

    The tool surface covers creation/update, reconciliation (single and bulk), listing, coverage overview, bundle generation, metadata parsing, and export. Missing a direct delete tool for docs, but the create_or_update tool may handle updates. Overall, agents can perform most tasks without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Local MCP server that indexes documentation from URLs/files into a vector database, enabling coding agents to search and use up-to-date library and API documentation.
      1
      -