# Contextception > Deterministic context intelligence for code - **Type:** MCP server - **Install:** `agentstack add mcp-kehoej-contextception` - **Verified:** Pending review - **Seller:** [kehoej](https://agentstack.voostack.com/s/kehoej) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kehoej](https://github.com/kehoej) - **Source:** https://github.com/kehoej/contextception ## Install ```sh agentstack add mcp-kehoej-contextception ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Contextception [](https://github.com/kehoej/contextception/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/kehoej/contextception) [](https://goreportcard.com/report/github.com/kehoej/contextception) [](LICENSE) [](https://github.com/kehoej/contextception/releases) [](go.mod) **Deterministic context intelligence for code.** Answers: *"What must be understood before making a safe change?"* Contextception builds a dependency graph of your repository and returns ranked, explainable lists of files you need to read before safely modifying a given file. Static analysis only, no AI generation, no tokens wasted. --- 97% Precision (independent ground truth)  ·  Tested across 16 repos  ·  Sub-second Analysis  ·  6 Languages  ·  Free & Open Source --- ## Install **Go install:** ```bash go install github.com/kehoej/contextception/cmd/contextception@latest ``` > **Note:** `go install` works out of the box on all platforms. On systems with a C compiler available, TypeScript/JavaScript extraction uses tree-sitter (AST-based) for higher accuracy. Without a C compiler (`CGO_ENABLED=0`), it falls back to regex-based extraction which handles the vast majority of import patterns correctly. **Homebrew:** ```bash brew install kehoej/tap/contextception ``` **Shell script (Linux/macOS):** ```bash curl -fsSL https://raw.githubusercontent.com/kehoej/contextception/main/install.sh | sh ``` **Build from source:** ```bash git clone https://github.com/kehoej/contextception.git cd contextception && make build # Binary at ./bin/contextception ``` **Windows:** Download the `.zip` from [GitHub Releases](https://github.com/kehoej/contextception/releases) and add to your PATH. --- ## How It Works ### 1. Index your repo ```bash $ contextception index Indexed 2,638 files, 10,087 edges in 0.9s ``` Scans your codebase, extracts imports across 6 languages, resolves dependencies, computes git history signals. **Incremental:** only changed files reprocessed. ### 2. Analyze any file ```bash $ contextception analyze src/auth/login.py ``` ```json { "schema_version": "3.2", "subject": "src/auth/login.py", "confidence": 0.92, "must_read": [ { "file": "src/auth/session.py", "symbols": ["createSession"], "direction": "imports", "role": "foundation" }, { "file": "src/auth/types.py", "symbols": ["User", "AuthConfig"], "direction": "imports", "role": "utility" } ], "likely_modify": { "high": [{ "file": "src/auth/session.py", "signals": ["direct_import"] }] }, "tests": { "direct": ["tests/auth/test_login.py"], "indirect": ["tests/auth/test_session.py"] }, "blast_radius": { "level": "medium", "detail": "8 files in dependency subgraph, 3 direct importers", "fragility": 0.45 } } ``` Returns ranked context: what to read, what might change, which tests cover it, and the blast radius, with **every recommendation explained**. Analyze multiple files at once to get merged context across a feature: ```bash $ contextception analyze src/auth/login.py src/auth/session.py src/auth/types.py ``` ### 3. Act on the context Feed the output to your AI agent via MCP, gate PRs with blast radius in CI, or use it to understand unfamiliar code: ```yaml # CI: fail PR if blast radius is high contextception analyze-change --ci --fail-on high ``` --- ## Blast Radius Analysis Every change has a ripple effect. Contextception maps it: - **Critical zone:** files that will definitely break - **Warning zone:** files needing review - **Fragility score:** how unstable the affected subgraph is (0.0–1.0) --- ## Hotspot Detection High churn + high fan-in = architectural risk. Contextception finds these automatically: Files that change frequently AND are imported by many others are the most dangerous files in your codebase. These are the ones that need the most care, and the most tests. --- ## Git History Intelligence Static analysis shows what *can* affect a file. Git history shows what *actually changes together*. Contextception combines both. During indexing, Contextception analyzes your last 90 days of git history to extract three signals: - **Co-change frequency:** files that are frequently modified in the same commits get boosted in rankings, even if they're several hops apart in the dependency graph - **Hidden coupling:** files that co-change 3+ times but have *no import relationship* are surfaced in `related` with a `hidden_coupling:N` signal. These represent behavioral coupling invisible to static analysis: shared data formats, API contracts, coordinated changes - **Churn tracking:** high-churn files are flagged so you know which dependencies are volatile vs. stable These signals feed directly into the scoring engine. A file that co-changes frequently with your target is ranked higher than one that merely imports it. A file flagged `stable` (high fan-in, low churn) tells you it's safe to rely on without deep review. --- ## PR & Change Analysis Analyze an entire PR or commit range to understand its impact before merging: ```bash $ contextception analyze-change origin/main ``` Returns a PR-level impact report with: - **Per-file risk scoring:** every changed file gets a risk score (0–100) and tier (SAFE/REVIEW/TEST/CRITICAL) - **Risk triage:** files grouped by tier with human-readable risk narratives explaining why each file is flagged - **Test gaps:** changed files with no test coverage, flagged before merge - **Test suggestions:** auto-generated recommendations for high-risk untested files (which test file to create, what to test) - **Coupling detection:** pairs of changed files that depend on each other - **Hidden coupling:** co-change partners *not in your diff* that may need updating - **Aggregate risk:** overall PR risk score with percentile ranking against historical baselines (after 10+ analyses) - **Aggregated must_read:** merged context across all changed files ### Risk Tiers | Tier | Score | Meaning | |------|-------|---------| | **SAFE** | 0–20 | New files, well-tested utilities, low coupling | | **REVIEW** | 21–50 | Moderate risk, standard code review sufficient | | **TEST** | 51–75 | High risk, targeted testing recommended | | **CRITICAL** | 76–100 | Maximum risk, regressions likely without careful review | Risk scores combine change status, structural factors (importer count, co-change frequency, fragility, mutual dependencies), and test coverage adjustments. ### Token-optimized output Use `--compact` for a text summary optimized for LLM consumption (~60–75% fewer tokens than JSON): ```bash $ contextception analyze-change --compact ``` ### CI integration Use `--ci --fail-on` to gate PRs automatically. A risk badge is printed to stderr: ```bash # Fail on high blast radius contextception analyze-change --ci --fail-on high # Fail only if risk triage has CRITICAL files contextception analyze-change --ci --fail-on critical ``` Results are stored in a local history database, enabling trend tracking with `contextception history`: ```bash $ contextception history hotspots # Files that repeatedly appear as hotspots $ contextception history trend # Blast radius trend over recent analyses ``` --- ## Confidence Scoring Every analysis includes a confidence score (0.0–1.0) based on import resolution completeness: If imports can't be resolved (dynamic imports, missing packages), the confidence score tells you how much to trust the results. --- ## Performance | Repository | Files | Index Time | Analysis Time | |-----------|-------|-----------|---------------| | Excalidraw | 602 | 0.3s | Per-repo recall breakdown | Repository | Files | Contextception | Aider @8192t | Aider @4096t | |-----------|-------|---------------|-------------|-------------| | httpx (Python) | 60 | 97% | 90% | 83% | | Excalidraw (TS) | 602 | 100%\* | 25.3% | 20.0% | | Tokio (Rust) | 1,021 | 100%\* | 1.4% | 1.4% | | Terraform (Go) | 1,885 | 100%\* | 7.9% | 6.3% | | Zulip (Python) | 2,638 | 100%\* | 27.4% | 24.2% | | Spring Boot (Java) | 7,978 | 100%\* | 0% | 0% | \* Measured against CC's own validated output (Grade A, 3.76–3.97). See [benchmarks/](benchmarks/) for full methodology and reproducible results. --- ## MCP Setup (30 seconds) Make your AI agent smarter. The `setup` command auto-detects every installed editor and configures all of them: ```bash # Auto-detect: Claude Code, Cursor, Windsurf, opencode, VSCode (Copilot Chat), Warp contextception setup # Or target one explicitly contextception setup --editor cursor contextception setup --editor opencode contextception setup --editor vscode contextception setup --editor warp # prints manual UI steps (Warp's MCP is UI-configured) # Also drop the agent instruction snippet into the current project cd /path/to/your/project contextception setup --instructions # upserts CLAUDE.md / AGENTS.md / .cursor/rules/ / .github/copilot-instructions.md ``` Use `--dry-run` to preview changes, or `--uninstall` to reverse. `--instructions` uses begin/end markers so existing user content in those files is preserved on re-runs and on `--uninstall --instructions`. Or configure manually — add to your `~/.claude.json` (Claude Code) or equivalent MCP config: ```json { "mcpServers": { "contextception": { "command": "contextception", "args": ["mcp"] } } } ``` This exposes nine tools to the AI agent: | Tool | Description | |------|-------------| | `get_context` | Analyze a file's context dependencies (auto-indexes if needed) | | `index` | Build or update the repository index | | `status` | Return index diagnostics | | `search` | Search the index for files by path pattern or symbol name | | `get_entrypoints` | Return entrypoint and foundation files for project orientation | | `get_structure` | Return directory structure with file counts and language distribution | | `get_archetypes` | Detect representative files across architectural layers | | `analyze_change` | Analyze the impact of a git diff / PR (risk scoring, triage, test gaps, coupling) | | `rate_context` | Rate how useful a previous `get_context` result was (feedback for accuracy tracking) | Works with **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible tool. ### Slash Commands Two built-in slash commands for AI-assisted PR review (installed automatically by `contextception setup`): | Command | Description | |---------|-------------| | `/pr-risk` | Run risk analysis on the current branch and present an actionable, human-friendly review | | `/pr-fix` | Analyze risk, then build an ordered plan to fix every issue found (test gaps, coupling, fragility) | These work by combining contextception's deterministic risk analysis with the LLM's ability to explain and translate — contextception computes the scores, the LLM presents them in plain language. See [`integrations/`](integrations/) for setup details. --- ## Language Support | Language | Extractor | Resolver | File Types | |----------|-----------|----------|------------| | **Python** | Regex | Package hierarchy, pyproject.toml, `__init__.py` | `.py` | | **TypeScript/JS** | Tree-sitter (CGO) / Regex fallback | tsconfig paths + extends chains, workspace monorepos, barrel files | `.ts` `.tsx` `.js` `.jsx` | | **Go** | Regex | go.mod + go.work, same-package resolution | `.go` | | **Java** | Regex | Package-to-directory, mirror-directory test discovery | `.java` | | **Rust** | Regex | Cargo workspaces, mod.rs, crate/super/self paths, inline test detection | `.rs` | | **C#** | Regex | .csproj project detection, namespace-to-file resolution, filename search fallback | `.cs` | --- ## CLI Reference ``` contextception index Build or update the index contextception analyze Analyze context dependencies for a file contextception analyze-change [base] Analyze the impact of a PR or commit range contextception search Search the index for files by path or symbol contextception archetypes Detect archetype files from the index contextception history View historical analysis (trend, hotspots, distribution, file) contextception reindex Delete and rebuild the index from scratch contextception extensions List supported file extensions contextception status Show index status and diagnostics contextception mcp Start the MCP server (stdio transport) contextception update Check for and install the latest version contextception setup Configure contextception for your AI editor contextception gain Show usage analytics dashboard contextception accuracy Show recommendation accuracy from LLM feedback contextception discover Find files edited without get_context being called contextception session Show contextception adoption across Claude Code sessions ``` ### Key Flags | Flag | Description | |------|-------------| | `--mode plan\|implement\|review` | Shape output for AI workflow stage | | `--token-budget N` | Cap output to fit token limits | | `--compact` | Token-optimized text summary (~60-75% fewer tokens than JSON) | | `--ci --fail-on high\|medium\|critical` | Exit codes for CI pipelines | | `--cap N` | Limit must_read entries (overflow to related) | | `--no-external` | Exclude external dependencies | | `--no-update-check` | Disable automatic update version check | ### Updating Contextception checks for new versions automatically (once per day, cached) and prints a notification to stderr when an update is available. To update: ```bash contextception update ``` The update command detects your install method and acts accordingly: - **Direct download:** downloads and replaces the binary with checksum verification - **Homebrew:** suggests `brew upgrade contextception` - **go install:** suggests `go install ...@latest` Disable the automatic check with `--no-update-check`, `CONTEXTCEPTION_NO_UPDATE_CHECK=1`, or set `update.check: false` in the global config at `/contextception/config.yaml` (where `` is `~/Library/Application Support` on macOS, `~/.config` on Linux, `%AppData%` on Windows). --- ## Analytics & Feedback Contextception tracks its own usage and recommendation quality: ```bash contextception gain # Usage dashboard: analysis counts, top files, trends contextception accuracy # Recommendation quality: precision, recall from LLM feedback contextception discover # Find files edited without context being checked contextception session # Adoption rates per Claude Code session ``` The `rate_context` MCP tool lets AI agents submit structured feedback after using `get_context` — which files were useful, unnecessary, or missing. This creates a closed feedback loop for measuring and improving recommendation quality over time. All analytics are deterministic and stored locally in `.contextception/history.sqlite`. Export with `--format json` or `--format csv` for dashboards. --- ## What You Get The output provides structured, ranked context across eight categories: - **`confidence`:** 0.0–1.0 reliability score for the analysis - **`must_read`:** files required to safely understand the change, with symbols, direction, and role - **`likely_modify`:** files likely needing modification, grouped by confidence (high/medium/low) - **`tests`:** test files covering the subject (direct and indirect tiers) - **`related`:** nearby context worth reviewing (2-hop dependencies, hidden coupling) - **`blast_radius`:** overall risk profile (high/medium/low with fragility metric) - **`hotspots`:** high-churn files that are also structural bottlenecks - **`circular_deps`:** import cycles involving the subject file --- ## Configuration Optional. Create `.contextception/config.yaml` in your repo ro … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [kehoej](https://github.com/kehoej) - **Source:** [kehoej/contextception](https://github.com/kehoej/contextception) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-kehoej-contextception - Seller: https://agentstack.voostack.com/s/kehoej - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.