Skip to main content
Glama

KARP Inspector

The Complete Development Intelligence Server for Claude Desktop

Smoke Test

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

❌

✅ (server_status)

Total tools

9

52


Installation

  1. Download karp-inspector.mcpb from the latest release.

  2. 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.

  3. Choose a Data Folder (where the database lives) and one or more Project Folders (the code Claude can read and edit).

  4. 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)

  1. git clone https://github.com/souldriver007/karp-inspector.git

  2. Inside the folder, run npm install, then npm run download-model (the embedding model isn't committed to git; about 33MB)

  3. 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_COMMANDS above is the safe default. Adding npm test, npm run build or pytest lets the project you point at execute its own code — only do that for repositories you trust.

  1. Restart Claude Desktop

  2. Say: "Set project to C:\path\to\my\project and index it"

Build the extension yourself

npm install
npm run download-model
npm run build

The extension is written to dist/karp-inspector.mcpb.

Linux (x64): run installs as ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install (or npm 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 smoke

Spawns 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

set_project outside the boundary is denied

The directory sandbox once covered only one module in four, making grep_code an arbitrary-file reader

Two roots sharing a README.md both index

Chunk ids were filepath:line, so any two projects sharing a relative path collided on the primary key

A one-line const a = () => {}, b = () => {} indexes

Two chunks with the same start line produced duplicate ids

index_project returns chunks > 0

File hashes committed before chunks; an interrupted run left the index claiming N files with zero chunks, unrecoverable

search_code ranks the right file first

Proves the vectors are meaningful, not merely present

Hybrid finds a file semantic search misses

count-lines.js contains totalLines; semantic search returned countFiles and countRows instead

Export records embedding_dtype

An index recording only the model name imports cleanly into a server on the other precision and returns plausible nonsense

Deleting a file yields pruned: 1

Deleted files' chunks previously survived forever

Ambiguous relative path errors

resolveInRoots used to return the first match and call it an answer

security_audit, git_checkpoint, run_check and export → import all run

Before v0.5.0 these were licence-gated, so CI only reached them when licence secrets were set, and import_index shipped broken because nothing exercised it

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 .exs

Config 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 acorn

  • HTML — 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

ALLOWED_DIRS

Required (manual config)

Semicolon-separated list of directories the server may access. There is no unrestricted mode — if this is empty and no project_dirs are passed, every filesystem, search and analysis tool refuses to run. The .mcpb extension config uses project_dirs (a folder picker, see below) instead of this env var — both feed the same boundary.

C:\Users\Me\Desktop;D:\Projects

DATA_PATH

Required via .mcpb config screen (Data Folder); optional in manual config

Where the unified SQLite database is stored, including automatic snapshots (DATA_PATH/snapshots/). Manual-config default is ~/.karp-premium (the name dates from the Premium release and is kept so existing data still loads).

C:\path\to\data

ALLOWED_COMMANDS

Optional

Semicolon-separated command prefixes for run_check. Defaults to node --check only. Leave empty to disable terminal execution entirely. Adding test or build runners lets a project execute its own code — npm test/npm run build run scripts from that project's package.json, and pytest runs its conftest.py. Only add them for repositories you trust.

node --check;npm test;pytest

TRASH_DIR

Optional

Where soft-deleted files go. Defaults to DATA_PATH/trash.

C:\path\to\trash

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

list_allowed_directories

Show which directories the server can access

read_file

Read a text file with optional head/tail line limits

read_files

Read multiple files in a single call

write_file

Atomic write (temp file + rename) with parent dir creation

patch_file

Edit a file by replacing one exact text match

list_directory

List files and dirs with type, size, modification date

directory_tree

Recursive tree view respecting .gitignore

file_info

Detailed metadata: size, dates, permissions, MIME type

move_file

Move or rename files and directories

copy_file

Copy files or directories (recursive)

create_directory

Create directories (and parents)

delete_file

Soft delete to trash (or permanent)

find_files

Glob pattern search with date/size filters

search_replace

Cross-file find and replace with dry-run preview

disk_usage

Biggest files, directory sizes, breakdown by extension

checksum

SHA256 hash of one or more files

run_check

Execute pre-approved terminal commands (syntax check, tests, linter)

list_allowed_commands

Show which commands are approved for run_check

git_checkpoint

Safety checkpoint: git commit or SQLite snapshot fallback

karp_undo

Revert file changes using saved snapshots

Knowledge Graph (11 tools)

Tool

Description

remember

Store a memory, decision, todo, insight, changelog, or custom type

recall

Semantic search across the knowledge graph by meaning

forget

Delete a node permanently

connect

Create a named relationship between two nodes

update

Edit a node in place — preserves its id, created_at and edges, re-embeds only if the text changed

graph_search

Keyword search across node summaries and details

graph_list

Browse nodes by type, tags, or date

propose_node_type

Create a custom node type with icon and description

kg_status

Health check: node counts, DB size, embedding coverage

graph_snapshot

Backup the entire database

re_embed

Rebuild all vector embeddings

Code Intelligence (14 tools)

Tool

Description

search_code

Hybrid code search — fuses semantic similarity with literal term matching. mode accepts hybrid (default), semantic, or literal

grep_code

Exact string or regex search with context lines

file_outline

Structural overview: classes, functions, signatures, line numbers. Takes an absolute path or one relative to a root

index_project

Build or rebuild the semantic search index across every configured root

reindex_file

Re-index a single file after editing. Takes an absolute path or one relative to a root

file_history

List saved snapshots of a file

file_diff

Diff between snapshots or against the live file. Refuses rather than guess when the same path exists under several roots

project_stats

Index statistics: files, chunks, extensions

set_project

Set one root, or several at once for a monorepo — all search, grep and index tools then span every root

list_projects

Every indexed root with chunk/file counts, last indexed date, and whether it still exists on disk

index_status

What's new, changed or deleted since the last index — tells you whether indexing is needed at all

forget_project

Delete one root's index and reclaim the space. Dry run by default

export_index

Export a root's chunks and embeddings to a portable file

import_index

Import an exported index, optionally remapping the root path

Server (1 tool)

Tool

Description

server_status

Version, uptime, directory boundary, allowed commands, database size, index totals, snapshot health

Developer Intelligence (6 tools)

Tool

Description

repo_map

Compressed structural map — function signatures and class names across a directory, without implementation code. 10,000 lines → 500 tokens.

dependency_graph

Import/require mapping across the project. Finds circular dependencies.

impact_analysis

"If I change this file, what breaks?" Blast radius + symbol reference tracking.

dead_code

Find exported symbols that nothing imports

todo_scan

Extract TODO, FIXME, HACK, XXX, NOTE comments across the codebase

security_audit

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_project takes one directory or several. A monorepo's frontend/ and api/, 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 same README.md or src/index.js coexist cleanly.

  • The index is visible and reversible — index_status says whether indexing is even needed, list_projects shows what's stored, and forget_project removes 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 .mcpb install 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:

  1. Fully quit Claude Desktop first. Toggling the extension off/on in Desktop's UI is not sufficient — the underlying node.exe process 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 left kg_status still reporting the pre-restore state; only a full close did.

  2. With Desktop closed, copy the snapshot you want over the live database: <DATA_PATH>\snapshots\auto-<timestamp>.db (or premium-<timestamp>.db for a manual graph_snapshot) → <DATA_PATH>\premium.db, overwriting it.

  3. Start Claude Desktop back up. server/index.js reads premium.db fresh on process start — this is the point where your restored snapshot actually takes effect.

  4. Verify with kg_status — check total_nodes/total_chunks and db_size match 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 .mcpb

MIT

@huggingface/transformers

Apache-2.0

acorn and acorn-walk

MIT

sql.js

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


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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent project memory + architectural decisions + pre-execution safety hooks for Claude Code. Local-only storage, multi-repo workspace, automatic knowledge extraction via background auditor.
      6 npm
      14
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 PyPI
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local knowledge engine for codebases with hybrid search, knowledge graph, and interaction tracking, enabling Claude Code to search and interact with project knowledge locally.
      7
      2
      MIT