Knowerage
Knowerage is a local-first MCP server for tracking AI-generated analysis coverage and freshness for legacy codebases, enabling AI agents to create, manage, query, and export code analysis documentation.
Create or update analysis documents (
knowerage_create_or_update_doc): Write structured markdown files with YAML frontmatter specifying source file paths and covered line ranges.Parse document metadata (
knowerage_parse_doc_metadata): Extract and validate YAML frontmatter from existing analysis files.Reconcile individual records (
knowerage_reconcile_record): Sync a single analysis file intoregistry.json, computing SHA-256 hashes and updating coverage/freshness status.Reconcile all records (
knowerage_reconcile_all): Rescan all analysis files and rebuild the entire registry — useful after bulk edits or agit pull. (Can also be automated viaKNOWERAGE_AUTO_FULL_RECONCILE.)Get per-file coverage status (
knowerage_get_file_status): See which line ranges of a source file have been analyzed vs. are missing.List stale records (
knowerage_list_stale): Identify records that are stale, have missing sources, or are dangling (no matching source).List the full registry (
knowerage_list_registry): Retrieve a complete snapshot of all coverage records including paths, line ranges, hashes, and freshness status.Get a tree view (
knowerage_get_tree): Browse analysis records grouped by directory for a structured overview.Coverage overview (
knowerage_coverage_overview): Get project-wide and per-source coverage percentages, analyzed vs. missing ranges, and stale record counts.Export reports (
registry_export_report): Export the registry as JSON, YAML, plain text, or HTML.Generate bundles (
knowerage_generate_bundle): Package selected analysis files into NotebookLM-style chunked bundles (table of contents, combined content, manifest) for external use or sharing.
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/knowerageOr build from source
cargo build --release
./target/release/knowerage-mcpHow It Works
AI agent creates analysis
.mdfiles with YAML frontmatter declaring source file and covered line rangesRegistry (
knowerage/registry.json) tracks analysis records with SHA-256 hashes for freshnessMCP tools expose create, reconcile, query, and export operations
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 --> recFrontmatter for analysis .md files is specified separately in the contracts doc (metadata schema), not inside registry.json.
MCP Tools
Tool | Purpose |
| Create/update analysis document |
| Parse and validate frontmatter |
| Reconcile one analysis record |
| Full rescan/rebuild |
| Analyzed vs missing ranges |
| List stale/problematic records |
| Full registry snapshot (same shape as |
| Tree/grouped coverage |
| Export snapshot (JSON/YAML/TXT/HTML) |
| Chunked export of selected analyses ( |
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.rsDocumentation
User Onboarding — Setup, config, typical usage
INSTRUCTIONS.md — MCP agent instructions
Contracts — Schemas and API contracts (registry + frontmatter)
Example registry JSON — Sample
registry.jsoncontents
Security
All paths validated against workspace root
Path traversal (
..) rejectedAtomic 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 toolsknowerage_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
MCP Server for an Agent Task Marketplace
MCP server for querying Forkast documentation
Repository knowledge graph MCP server for codebase understanding and debugging.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceMCP server for collecting code from files and directories into a single markdown document.28MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for querying multi-repo engineering documentation artifacts from a SQLite corpus.5 npmAGPL 3.0
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server that provides project context, verification gates, and structured tools for coding agents to discover knowledge, run diagnostics, and execute allowlisted commands within a repository.40 npmMIT
- FlicenseNot gradedqualityDmaintenanceLocal 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-