kontext MCP server
Commit Nov 15, 2026Provides freshness-aware context management for AI agents by verifying markdown documentation against git history to prevent stale information.
Also known as patkusch/kontext
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is kontext MCP?
kontext provides freshness-aware context management for AI agents by verifying markdown documentation against git history to prevent stale information.
Summary generated from the project's README
About kontext MCP server
Developers working with large codebases can use kontext to ensure AI agents receive accurate, up-to-date documentation instead of stale markdown files. By linking documentation to git history through a describes field in the file frontmatter, the server verifies if the code described by a document has changed since the document was last updated. This prevents agents from following outdated runbooks or refactored logic that no longer exists in the source code.
To use this server with an MCP client like Claude Desktop, you must provide the absolute path to the server file and set the KONTEXT_ROOT environment variable to your repository path. The server provides specialized tools such as kontext_pack for creating budgeted context bundles, kontext_freshness for checking document reliability, and kontext_handoff tools for passing state between different AI sessions. It distinguishes between fresh, drifting, stale, and orphaned documents by comparing git logs against the globs defined in your documentation.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
KONTEXT_ROOT
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepatkusch/kontext is public and reachablegithub.com/patkusch/kontext ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/patkusch/kontext ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThe problem
Your project has a hundred markdown files. Some are load-bearing truth. Some describe a system you refactored away eleven months ago.
They look identical. Same folder, same font, same confident tone.
You cope by ignoring the docs and reading the code. Your agent can't. Hand Claude a
stale runbook and it will follow the stale runbook, because it has no way to smell that
src/auth/ was rewritten in March. So every team lands on one of two losing strategies:
- Load everything → burn the context window on documents that are mostly wrong
- Load nothing → rediscover the codebase from scratch, every single session
Neither is context management. They're surrender in two directions.
The root cause isn't volume. It's that a markdown file is born and then immortal. Code has tests. Dependencies have versions. Infrastructure has health checks. Documentation alone never has to prove it still works.
The idea
A context document isn't a file. It's a claim about code — and claims can be checked.
Let a document declare what it describes. Git already knows every change to that subject, timestamped and attributed. So git can answer the question the document can't answer about itself:
Has the thing this document describes changed since the document last did?
That has an objective answer. Two git log calls and a comparison. No LLM, no
embeddings, no vibes.
---
kontext: 1
id: auth-session-flow
kind: guide
describes:
- src/auth/**
- src/middleware/session.ts
verify: npm run test:auth
---
That describes field is the whole trick. It turns an unfalsifiable assertion into a
checkable claim.
Quickstart
kontext is not on npm yet, so install it from source. You need Node 20 or newer and git.
git clone https://github.com/patkusch/kontext.git && cd kontext && npm install && npm run build && npm link
npm link puts the kontext command on your PATH. If you would rather not link it,
run node /path/to/kontext/dist/cli.js wherever the docs below say kontext.
Then, in any repo you want to look at:
kontext doctor
Works on any repo right now, with zero setup and zero frontmatter. It'll tell you how bad things actually are.
kontext check
kontext check · 5 docs · ~42 tokens · ~/demo
── orphaned (1) ────────────────────────────────────────────────────────────────
⊘ docs/legacy-queue.md 7 1 dead glob
· orphaned: `describes` glob workers/queue/** matches zero tracked files
— the code this doc describes was deleted, renamed, or moved
── stale (2) ───────────────────────────────────────────────────────────────────
○ docs/auth.md 10 12 commits · 181d behind · 1 file
· stale: 12 commits touched src/auth/** since this doc was last updated
(latest: eeefbd7 'auth change 11', 19 days ago); the described code is
181 days ahead of the doc (doc: 808f909 'initial: code and docs
together', 200 days ago) — past the 45-day stale threshold
· files that moved: src/auth/session.ts
── unverified (1) ──────────────────────────────────────────────────────────────
· docs/philosophy.md 50
· unverified: no `describes` field, so this doc makes no falsifiable
claim about source files — staleness can be neither proven nor ruled
out. Add `describes: [<globs>]` to make it checkable.
── fresh (1) ───────────────────────────────────────────────────────────────────
● docs/api.md 100 1 file
1 fresh · 1 unverified · 2 stale · 1 orphaned
● fresh ◐ drifting ○ stale ⊗ expired ⊘ orphaned ⇥ superseded · unverified
check failed: 3 docs in fail set [stale, expired, orphaned]
(Real output, not a mockup — that's kontext check run against a demo repo.)
Every verdict cites its evidence. You can check the reasoning and overrule it — a tool that says "trust me, it's stale" deserves the same fate as the docs it's judging.
Adopt it gradually
kontext init --dry-run # propose frontmatter for existing docs, write nothing
kontext init --yes # prepend it, preserving every body byte-for-byte
init infers an id from the filename, guesses kind from structure, and proposes
describes globs from the code paths your doc actually mentions. These are guesses,
and it marks them as guesses. Narrow them by hand — that's the part that matters.
Gate it in CI
- run: kontext check --fail-on stale,orphaned # needs fetch-depth: 0
That fetch-depth: 0 matters: kontext proves staleness from git history, and a shallow
clone makes every doc look freshly committed.
Now a PR that changes src/auth/ and not its docs fails the build. Documentation joins
the set of things that must keep working.
How it works
your docs ──┐
├──► scan ──► assess ──► rank ──► pack
git history ┘ │ │
│ └──► budgeted bundle
└──► evidence: for one task
commits, dates,
drift days
Freshness verdicts:
| Verdict | Meaning | |
|---|---|---|
| ● | fresh |
Described code hasn't moved since the doc did |
| ◐ | drifting |
Code moved, within the warning threshold |
| ○ | stale |
Code moved materially after the doc — don't trust it blind |
| ⏱ | expired |
Past its expires / ttlDays |
| ↪ | superseded |
Another doc declares it replaced |
| ⊘ | orphaned |
describes matches no files — the subject is gone or moved |
| · | unverified |
No describes — no claim to check |
unverified isn't a failure. Most docs in most repos start there. It marks absence of
evidence, and the honest thing to do with that is say so.
When a folder moves. Say a doc describes src/auth/** and the team moves that folder
to src/identity/**. The glob now matches nothing, so the doc reads as orphaned. kontext
asks git where the files went, and says so:
⊘ docs/auth.md 10 1 dead glob
· `src/auth/**` matches nothing now, but it used to match 4 files (the last
of them left in 65fa565 'move auth to identity', 79 days ago). 4 of 4 now
appear at `src/identity/**` (git matched them by content; the weakest
match is 98% identical). Update `describes` to `src/identity/**` if that
is where this doc's subject lives.
That is a suggestion. kontext never edits your doc, and the doc stays orphaned until you do.
It only suggests a new glob when more than half of the files moved to one place (3 of 4,
not 2 of 4). Git decides what counts as the same file, at 50% alike or more. If files were
moved and heavily rewritten in one commit, kontext says it cannot tell instead of guessing.
Move first and edit in a second commit, and git can follow it.
Age is not staleness. A 2019 ADR explaining why you rejected microservices is still
true — its subject is a historical decision, and history doesn't drift. A runbook from
last month with the wrong port is actively harmful. kontext ranks decision and
runbook docs differently for exactly this reason.
Packing context for a task
kontext pack "refactor session expiry" --budget 8000
Ranks by relevance weighted by freshness, fills the token budget, truncates on heading boundaries, stamps provenance on everything.
And the rule that matters most:
A pack never silently omits anything.
Everything excluded gets reported — stale docs under excludedForStaleness, budget
casualties under omitted, each with a reason. An agent that doesn't know something was
withheld will reason confidently from a hole in its context and never signal doubt.
Silent truncation is indistinguishable, from the inside, from complete knowledge. That's
a worse failure than the stale docs this tool exists to fix, because it's invisible.
Context switching & handoffs
The moment context reliably dies: you close the session. What you'd ruled out, what surprised you, what you were mid-way through — all of it lived in a conversation that just ended.
kontext handoff --task "session expiry refactor" \
--message "ruled out Redis TTL; see open question on clock skew"
Captures branch, recent commits, working-tree changes, freshness of the docs touching
those files, open questions, next steps → .kontext/handoff.md, with ttlDays: 7
because working state rots faster than anything else you write.
The acceptance test: a fresh agent with no prior context can read it and resume the work. If it needs the original conversation to make sense, it's a note, not a handoff.
For AI agents (MCP)
This is where it stops being a linter and starts being infrastructure.
Instead of an agent slurping every markdown file, it gets a freshness-aware context API — ranked, budgeted, and tagged with how much each source can be trusted.
claude mcp add kontext -- node /absolute/path/to/kontext/dist/mcp/server.js
Claude Desktop's working directory isn't your repo, so KONTEXT_ROOT is required there:
{
"mcpServers": {
"kontext": {
"command": "node",
"args": ["/absolute/path/to/kontext/dist/mcp/server.js"],
"env": { "KONTEXT_ROOT": "/absolute/path/to/your/repo" }
}
}
}
Tools exposed:
| Tool | What it's for |
|---|---|
kontext_pack |
Ranked, budgeted context bundle for a task |
kontext_freshness |
"Can I trust this doc?" — verdict + evidence |
kontext_search |
Cheap discovery without pulling full bodies |
kontext_read |
A doc, with its trust verdict attached |
kontext_handoff_write |
Hand working state to the next agent |
kontext_handoff_read |
Pick up where the last one left off |
kontext_conflicts |
"Do my sources disagree?" |
kontext_read never returns a document without telling the agent whether it's
trustworthy. That's the entire thesis in one API decision.
Conflict detection
Two docs, two different answers, and an agent picks one at random:
kontext doctor
⚠ contradiction docs/setup.md ↔ README.md
└ dev server port: "localhost:3000" vs "localhost:8080"
⚠ duplicate docs/onboarding.md ↔ docs/getting-started.md
└ 87% similar — one probably supersedes the other
Deliberately conservative. A false contradiction is worse than a missed one, because it costs you trust in the tool.
Design principles
- Evidence over opinion. Every claim traces to a commit.
- Absence of evidence is reported as such.
unverifiedis a real answer. - Never omit silently. What got dropped, and why, is part of the output.
- Degrade, don't crash. No frontmatter, no commits, broken YAML, globs matching nothing — all normal, none fatal.
- No lock-in. Frontmatter is inert YAML. Delete kontext tomorrow and you've lost nothing but the tool.
- No LLM in the staleness path. Determinism is the feature. Same commit, same answer, every time — which is the only reason CI can gate on it.
What kontext deliberately doesn't do
- Judge whether a doc is good — only whether it's current. Different problems.
- Auto-update your docs. A tool that rewrites docs to match the code produces text describing the code, which the code already does better. The why is what documentation is for, and only you know it.
- Use an LLM to detect staleness. See principle 6.
Commands
kontext doctor |
Diagnose the repo. Start here. |
kontext check |
Freshness verdicts + evidence. CI gate. |
kontext map |
Full corpus inventory and freshness heatmap. |
kontext pack <task> |
Budgeted context bundle. |
kontext init |
Propose frontmatter for existing docs. |
kontext handoff |
Capture working state for the next session. |
kontext mcp |
Run the MCP server (stdio). |
All commands support --json.
Docs
- The Context Lifecycle Spec — the full model, the reasoning, and the open questions. Start here if you want to argue with the design.
Status
Early. v0.1. The core mechanism — git-provable drift — is the part I'm confident in. The ranking heuristics and conflict detection are where feedback would help most.
The open questions are genuinely open: monorepo scoping, section-level staleness, cross-repo context. Rename tracking is closed: a folder that moves is found and suggested, and the reasoning is written down.
License
MIT © patkusch
kontext MCP questions
How does kontext determine if a document is stale?
It compares the git history of the files described in the document's 'describes' field against the last time the document itself was updated.
Can I use kontext with Claude Desktop?
Yes, you can add it as an MCP server, but you must set the KONTEXT_ROOT environment variable because Claude Desktop's working directory is not your repository.
What happens if a document doesn't have a 'describes' field?
The document is marked as 'unverified', meaning its staleness cannot be proven or ruled out because it makes no falsifiable claim about source files.
Does kontext automatically edit my markdown files?
No, the tool only suggests changes or proposes frontmatter; it never edits your documents directly.