Knowerage
Local MCP server that tracks AI analysis coverage against your codebase
Ask AI about Knowerage
Powered by Claude Β· Grounded in docs
I know everything about Knowerage. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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).
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
- AI agent creates analysis
.mdfiles with YAML frontmatter declaring source file and covered line ranges - Registry (
knowerage/registry.json) tracks analysis records with SHA-256 hashes for freshness - MCP 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 --> 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
- User Onboarding β Setup, config, typical usage
- INSTRUCTIONS.md β MCP agent instructions
- Rust Practices
- JS Practices
- Contracts β Schemas and API contracts (registry + frontmatter)
- Example registry JSON β Sample
registry.jsoncontents
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.
