KARP Inspector
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
KARP Inspector
The Complete Development Intelligence Server for Claude Desktop
Version: 0.5.0
Author: SoulDriver (Adelaide, Australia)
Licence: MIT — free and open source, every tool included
Formerly KARP Inspector Premium. Up to v0.4.0 it was a paid extension with a licence key. From v0.5.0 all 52 tools are free for everyone.
What Is This?
KARP Inspector is a single MCP server that gives Claude everything it needs to understand, navigate, modify, and reason about your codebase — plus a persistent knowledge graph that remembers decisions, tracks changes, and connects code to context.
52 tools. One server. One database. Zero external services.
Everything runs locally. Your code never leaves your machine.
Related MCP server: Axme-code
Inspector vs Inspector Lite
Inspector Lite is the lightweight, search-only sibling. Inspector is the full toolkit.
Capability | Inspector Lite | Inspector |
Semantic code search | ✅ | ✅ |
Grep / file outline / diff | ✅ | ✅ |
Read files | ❌ | ✅ |
Write / patch files | ❌ | ✅ (atomic, corruption-safe) |
Move / copy / delete | ❌ | ✅ (soft delete with trash) |
Find files (glob + filters) | ❌ | ✅ |
Search & replace (cross-file) | ❌ | ✅ (with dry-run preview) |
Knowledge graph | ❌ | ✅ (remember, recall, connect) |
Custom node types | ❌ | ✅ (propose any schema) |
Semantic graph search | ❌ | ✅ (ONNX embeddings) |
Repo map (compressed overview) | ❌ | ✅ |
Dependency graph | ❌ | ✅ (with circular dep detection) |
Impact analysis | ❌ | ✅ (blast radius + symbol tracking) |
Dead code detection | ❌ | ✅ |
TODO / FIXME scanner | ❌ | ✅ |
Security audit | ❌ | ✅ (secrets, keys, high-entropy) |
Git checkpoint | ❌ | ✅ (or SQLite fallback) |
Undo / rollback | ❌ | ✅ (snapshot-based revert) |
Run terminal commands | ❌ | ✅ (pre-approved patterns only) |
Disk usage analysis | ❌ | ✅ |
File checksums | ❌ | ✅ (SHA256) |
Unified database | ❌ | ✅ (single SQLite file) |
Version history | File snapshots | SQLite snapshots (searchable) |
Index observability | ❌ | ✅ (list, status, forget, export/import) |
Server diagnostics | ❌ | ✅ ( |
Total tools | 9 | 52 |
Installation
Extension Install (Recommended)
Download
karp-inspector.mcpbfrom the latest release.In Claude Desktop, open Settings (on Windows: File → Settings), click Desktop app in the left panel, scroll to the bottom and choose Extensions → Manage → Advanced settings → Install extension, then select the downloaded file.
Choose a Data Folder (where the database lives) and one or more Project Folders (the code Claude can read and edit).
Click Enable, then Configure, and choose Allow all on the permissions screen.
Then ask Claude to run server_status: it should report version 0.5.0 and 52 tools.
The server runs directly via stdio (no proxy, no background process) — same pattern as every other KARP MCP server.
Upgrading from Inspector Premium
The new extension installs under a different name, so it sits alongside the old one. Disable or remove KARP Inspector Premium first so the two never write to the same database at once, then install KARP Inspector and choose the same Data Folder you used before. Your knowledge graph, code index and snapshots carry straight over: the database file names (premium.db, premium-*.db) are unchanged for exactly this reason. There are no licence fields any more, so there's nothing to enter.
Manual Config (Development)
git clone https://github.com/souldriver007/karp-inspector.gitInside the folder, run
npm install, thennpm run download-model(the embedding model isn't committed to git; about 33MB)Add to your
claude_desktop_config.json:
{
"mcpServers": {
"karp-inspector": {
"command": "node",
"args": ["C:\\path\\to\\karp-inspector\\server\\index.js"],
"env": {
"ALLOWED_DIRS": "C:\\Users\\You\\Projects;D:\\Code",
"DATA_PATH": "C:\\path\\to\\your\\chosen\\data\\folder",
"ALLOWED_COMMANDS": "node --check"
}
}
}
}
ALLOWED_COMMANDSabove is the safe default. Addingnpm test,npm run buildorpytestlets the project you point at execute its own code — only do that for repositories you trust.
Restart Claude Desktop
Say: "Set project to C:\path\to\my\project and index it"
Build the extension yourself
npm install
npm run download-model
npm run buildThe extension is written to dist/karp-inspector.mcpb.
Linux (x64): run installs as
ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install(ornpm ci). Otherwise onnxruntime-node's install script tries to download optional GPU binaries, and that download currently fails. Inspector only needs the CPU binaries, which are already in the package.
Testing
npm run smokeSpawns the server and drives it over stdio with a real JSON-RPC client — no Claude Desktop, no GUI, no SDK dependency. 32 assertions, a few seconds.
Every assertion corresponds to something that actually broke during development, so this is a regression net rather than a formality:
Assertion | The bug it guards against |
| The directory sandbox once covered only one module in four, making |
Two roots sharing a | Chunk ids were |
A one-line | Two chunks with the same start line produced duplicate ids |
| File hashes committed before chunks; an interrupted run left the index claiming N files with zero chunks, unrecoverable |
| Proves the vectors are meaningful, not merely present |
Hybrid finds a file semantic search misses |
|
Export records | An index recording only the model name imports cleanly into a server on the other precision and returns plausible nonsense |
Deleting a file yields | Deleted files' chunks previously survived forever |
Ambiguous relative path errors |
|
| Before v0.5.0 these were licence-gated, so CI only reached them when licence secrets were set, and |
The fixture is created under the OS temp directory, which on macOS is a
symlink into /private/var/... — so the run also exercises the realpath
handling in assertAllowed.
CI runs the same suite on macOS, Windows and Linux on every push, covering
every tool, including run_check's non-Windows which branch. See
.github/workflows/smoke-test.yml.
How search works
search_code runs two rankers over the same chunks and fuses the results.
Semantic compares the query's embedding against each chunk's. Good at concepts — "validate a token before the request runs" finds the middleware even though it never uses those words.
Literal scores term frequency over each chunk's text and name, with
identifiers split on camelCase and snake_case so totalLines matches "total
lines". Good at the thing semantic search is worst at: you half-remember an
identifier, a config key, or an error string.
Fusion uses Reciprocal Rank Fusion — Σ 1/(60 + rank) across both lists.
RRF works on ranks rather than raw scores, which matters because cosine
similarity and term frequency aren't on comparable scales. Every result reports
semantic_score, lexical_score and the fused rrf value, so a ranking can be
explained rather than taken on trust.
Why both: on a real codebase, a query for "count the number of lines of code"
returned countFiles, countRows and getRecordCounts from semantic search
alone — and missed a file named count-lines.js containing totalLines. Literal
matching finds it instantly. Neither ranker is sufficient by itself.
Pass mode: "semantic" or mode: "literal" to force one.
A note on queries. Search quality depends more on vocabulary than on any
setting. Search the way the code is written, not the way you'd describe it to a
colleague — "service worker cache" rather than "works offline". The embedding
model matches vocabulary in context; it does not reliably infer that
caches.match() means offline support.
Indexed file types
Text and source files up to 1MB:
.py .js .jsx .ts .tsx .html .css .md .txt
.sql .sh .ps1 .bat
.go .rs .java .cs .rb .php .vue .svelte .kt .swift
.c .h .cpp .hpp .scala .ex .exsConfig and data formats (.json, .yaml, .toml, .ini) are deliberately
not indexed: generated files like package-lock.json crowd out real code in
search results. grep_code reads straight from disk, so literal lookups in
those files still work.
Three of these get structural parsing rather than fixed-size windows:
Python — functions and classes become individual chunks
JavaScript / TypeScript — parsed with
acornHTML — inline
<script>is parsed as JavaScript with correct absolute line numbers, inline<style>is skipped, and remaining markup is chunked as prose only when it reads like prose rather than a navigation menu
Everything else is chunked into overlapping windows, which works acceptably for uniform content.
.gitignore is respected, along with a default skip list (node_modules,
.git, dist, build, __pycache__ and similar). If a root contains nothing
indexable, index_project says so and lists what it looks for, rather than
reporting a successful index of nothing.
Configuration Reference
Environment Variable | Required | Description | Example |
| Required (manual config) | Semicolon-separated list of directories the server may access. There is no unrestricted mode — if this is empty and no |
|
| Required via | Where the unified SQLite database is stored, including automatic snapshots ( |
|
| Optional | Semicolon-separated command prefixes for |
|
| Optional | Where soft-deleted files go. Defaults to |
|
MCPB Extension Config (as actually shipped)
Users configure these two fields via Claude Desktop's built-in settings UI when installing the .mcpb. data_path is a single folder picker; project_dirs is a multi-select folder picker ("multiple": true) — click it again to add more folders, and it expands to as many directories as you pick:
{
"user_config": {
"data_path": {
"type": "directory",
"title": "Data Folder",
"description": "Choose where to store your knowledge graph and code index. Pick any folder — your data stays on your machine and survives extension updates.",
"required": true
},
"project_dirs": {
"type": "directory",
"title": "Project Folders",
"description": "Choose one or more top-level folders Claude can read, write, and search within (subfolders included). This is the file boundary for all filesystem tools — Claude can't touch anything outside these. Click again to add more.",
"multiple": true,
"required": true
}
}
}Under the hood, multi-select directory fields expand into separate command-line arguments (per the MCPB spec — arrays aren't passed through env as a single string), so project_dirs is wired into args rather than env. server/index.js reads both process.argv (for the .mcpb path) and the ALLOWED_DIRS env var (for manual config), merges and dedupes them.
All 52 Tools
Filesystem (20 tools)
Tool | Description |
| Show which directories the server can access |
| Read a text file with optional head/tail line limits |
| Read multiple files in a single call |
| Atomic write (temp file + rename) with parent dir creation |
| Edit a file by replacing one exact text match |
| List files and dirs with type, size, modification date |
| Recursive tree view respecting .gitignore |
| Detailed metadata: size, dates, permissions, MIME type |
| Move or rename files and directories |
| Copy files or directories (recursive) |
| Create directories (and parents) |
| Soft delete to trash (or permanent) |
| Glob pattern search with date/size filters |
| Cross-file find and replace with dry-run preview |
| Biggest files, directory sizes, breakdown by extension |
| SHA256 hash of one or more files |
| Execute pre-approved terminal commands (syntax check, tests, linter) |
| Show which commands are approved for run_check |
| Safety checkpoint: git commit or SQLite snapshot fallback |
| Revert file changes using saved snapshots |
Knowledge Graph (11 tools)
Tool | Description |
| Store a memory, decision, todo, insight, changelog, or custom type |
| Semantic search across the knowledge graph by meaning |
| Delete a node permanently |
| Create a named relationship between two nodes |
| Edit a node in place — preserves its id, created_at and edges, re-embeds only if the text changed |
| Keyword search across node summaries and details |
| Browse nodes by type, tags, or date |
| Create a custom node type with icon and description |
| Health check: node counts, DB size, embedding coverage |
| Backup the entire database |
| Rebuild all vector embeddings |
Code Intelligence (14 tools)
Tool | Description |
| Hybrid code search — fuses semantic similarity with literal term matching. |
| Exact string or regex search with context lines |
| Structural overview: classes, functions, signatures, line numbers. Takes an absolute path or one relative to a root |
| Build or rebuild the semantic search index across every configured root |
| Re-index a single file after editing. Takes an absolute path or one relative to a root |
| List saved snapshots of a file |
| Diff between snapshots or against the live file. Refuses rather than guess when the same path exists under several roots |
| Index statistics: files, chunks, extensions |
| Set one root, or several at once for a monorepo — all search, grep and index tools then span every root |
| Every indexed root with chunk/file counts, last indexed date, and whether it still exists on disk |
| What's new, changed or deleted since the last index — tells you whether indexing is needed at all |
| Delete one root's index and reclaim the space. Dry run by default |
| Export a root's chunks and embeddings to a portable file |
| Import an exported index, optionally remapping the root path |
Server (1 tool)
Tool | Description |
| Version, uptime, directory boundary, allowed commands, database size, index totals, snapshot health |
Developer Intelligence (6 tools)
Tool | Description |
| Compressed structural map — function signatures and class names across a directory, without implementation code. 10,000 lines → 500 tokens. |
| Import/require mapping across the project. Finds circular dependencies. |
| "If I change this file, what breaks?" Blast radius + symbol reference tracking. |
| Find exported symbols that nothing imports |
| Extract TODO, FIXME, HACK, XXX, NOTE comments across the codebase |
| Scan for API keys, tokens, private keys, high-entropy strings, hardcoded credentials |
Architecture
┌─────────────────────────────────────────────┐
│ KARP Inspector v0.5.0 │
│ 52 tools • 1 server • 1 database │
├─────────────────────────────────────────────┤
│ │
│ server/index.js ─ MCP Protocol (hand-rolled) │
│ │ runs directly via stdio │
│ │ (Desktop's entry_point) │
│ ├── filesystem.js (20 tools) │
│ ├── graph.js (11 tools) │
│ ├── inspector.js (14 tools) │
│ └── intelligence.js ( 6 tools) │
│ │
│ database.js ── Unified SQLite (WAL mode) │
│ ├── nodes (knowledge graph) │
│ ├── edges (relationships) │
│ ├── type_definitions │
│ ├── chunks (code index) │
│ ├── file_hashes (change detection) │
│ └── snapshots (version history — │
│ auto + manual) │
│ │
│ utils.js ── Shared helpers + dir boundary │
│ │
├─────────────────────────────────────────────┤
│ Stack: Node.js • SQLite • ONNX • Acorn │
│ Protocol: Hand-rolled MCP (no SDK dep) │
│ Embeddings: bge-small-en-v1.5 (local) │
│ External services: None │
└─────────────────────────────────────────────┘What makes this different
Unified database — Code index, knowledge graph, and version history in one SQLite file. A file write, an index update, and a changelog entry happen in the same transaction.
Multi-root projects —
set_projecttakes one directory or several. A monorepo'sfrontend/andapi/, or a project plus its shared library, are searched and indexed together instead of switching back and forth. Chunk ids are namespaced by root, so two roots holding the sameREADME.mdorsrc/index.jscoexist cleanly.The index is visible and reversible —
index_statussays whether indexing is even needed,list_projectsshows what's stored, andforget_projectremoves a root you indexed by mistake. Most tools in this space let you build an index and never look inside it again.No SDK dependency — Hand-rolled MCP protocol over stdio. Fewer dependencies, fewer failure modes.
No external services — No Docker, no Qdrant, no PostgreSQL, no API keys. Everything runs in-process.
Knowledge + code in one tool — Ask "why did we change the auth flow?" and get both the reasoning (graph) AND the code diff (inspector).
Performance
Scenario | Time |
First index — 12 files, 117 chunks, model load included | ~17s |
Re-index — 12 files, 117 chunks, model cached | ~13s |
Incremental index — 1 changed file | 0.1s (11 skipped via SHA256) |
No-op index — nothing changed | 0.02s |
Semantic search | <1s |
Grep search | Instant |
Repo map | Instant |
Dependency graph (first call / cached) | Instant / cached 60s |
Project switching (cached) | Instant |
Git checkpoint (SQLite fallback, 19 files) | <1s |
Embedding runs at roughly 9 chunks/sec on CPU with the full-precision
bge-small model. That is the dominant cost of a first index and it scales
linearly — 1,800 chunks is about 200 seconds. The fastest index is the one
you don't run, which is what index_status and the pre-flight guard on
index_project are for. Measured on Windows, Node 24, no GPU acceleration
(onnxruntime-node ships CPU-only binaries by default).
Supported Languages
Full AST parsing: JavaScript, TypeScript, JSX, TSX (via Acorn)
Regex parsing: Python (classes, functions, decorators, multi-line signatures)
Section-based chunking: HTML, CSS, Markdown, plain text
Dependency analysis: JavaScript/TypeScript (import/require), Python (import/from)
Requirements
Claude Desktop (Windows or macOS)
Node.js 18+ (ships with Claude Desktop)
Windows — developed and tested here
macOS / Linux — core functionality verified by CI on every commit; the
.mcpbinstall flow in Claude Desktop has not yet been walked through by hand on a Mac~33MB disk for the bundled embedding model (quantized bge-small, ships inside the extension — no download, works offline)
No Python, Docker, API keys, or external services
How Is This Different?
Tool | Filesystem | Knowledge Graph | Code Intelligence | Terminal |
Anthropic Filesystem Extension | ✅ | ❌ | ❌ | ❌ |
KARP Inspector Lite | ❌ | ❌ | ✅ (9 tools) | ❌ |
KARP Graph Lite | ❌ | ✅ (11 tools) | ❌ | ❌ |
Cline | ✅ | ❌ | Partial | ✅ |
Aider | ✅ | ❌ | Partial | ✅ |
KARP Inspector | ✅ (20 tools) | ✅ (11 tools) | ✅ (20 tools) | ✅ (pre-approved commands) |
Key differentiators:
Filesystem, knowledge graph and code intelligence in one server
Unified SQLite database — code changes and decisions in the same store
Terminal execution limited to the command prefixes you pre-approve
Impact analysis with blast radius — knows what breaks before you break it
Repo map — 10,000 lines compressed to 500 tokens
Security audit built in — catches secrets before they ship
Free and MIT licensed — read the code, fork it, change it
Privacy Policy
KARP Inspector is fully local. No data is collected, transmitted, or shared.
No telemetry, analytics, or tracking
No network requests after initial model download
No API keys or external services
Your code never leaves your machine
Database stored locally in your configured DATA_PATH
Restoring from a Snapshot
If the database gets corrupted, wiped, or bloated, here's how to actually restore from a snapshot:
Fully quit Claude Desktop first. Toggling the extension off/on in Desktop's UI is not sufficient — the underlying
node.exeprocess can stay running with the old (bad) database already loaded in memory, and any write from that stale process will silently overwrite whatever file you restore. On Windows, if Desktop doesn't close cleanly, end it via Task Manager. Confirmed this the hard way: a toggle leftkg_statusstill reporting the pre-restore state; only a full close did.With Desktop closed, copy the snapshot you want over the live database:
<DATA_PATH>\snapshots\auto-<timestamp>.db(orpremium-<timestamp>.dbfor a manualgraph_snapshot) →<DATA_PATH>\premium.db, overwriting it.Start Claude Desktop back up.
server/index.jsreadspremium.dbfresh on process start — this is the point where your restored snapshot actually takes effect.Verify with
kg_status— checktotal_nodes/total_chunksanddb_sizematch what you expect from the snapshot you restored, not the state you were trying to get away from.
Licence
MIT. See LICENSE. Use it, fork it, ship it.
Up to v0.4.0 this project was sold as KARP Inspector Premium, with 25 of its 52 tools behind an offline licence key. From v0.5.0 the licence check is gone and every tool is free.
Third-party components
Component | Licence |
bge-small-en-v1.5 embedding model (BAAI), bundled in the | MIT |
Apache-2.0 | |
acorn and acorn-walk | MIT |
MIT |
Contributing
Issues and pull requests are welcome. Please run npm run smoke before opening a pull request; CI runs the same suite on Windows, macOS and Linux.
Support
Bugs and questions: GitHub Issues
Website: souldriver.com.au/karp-tools.html
Built in Adelaide, Australia by SoulDriver
Part of the KARP ecosystem — Knowledge Acquisition Research Protocol
Democratising access to intelligent tools.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides semantic code intelligence to help users search, navigate, and analyze entire codebases using plain English. It enables Claude to perform architectural overviews, bug detection, and refactor suggestions through local semantic search and keyword indexing.MIT
- AlicenseNot gradedqualityCmaintenancePersistent project memory + architectural decisions + pre-execution safety hooks for Claude Code. Local-only storage, multi-repo workspace, automatic knowledge extraction via background auditor.6 npm14MIT
- AlicenseNot gradedqualityDmaintenanceProvides Claude Code with local semantic search and indexing of your codebase using AST-aware chunking and hybrid search, enabling deep code understanding without sending data to the cloud.53 PyPIMIT
- AlicenseAqualityCmaintenanceLocal knowledge engine for codebases with hybrid search, knowledge graph, and interaction tracking, enabling Claude Code to search and interact with project knowledge locally.72MIT