inspect-mcp

An MCP server that gives AI coding agents instant, structured understanding of any codebase.

One tool call. Full project context. No more fumbling.

The problem

AI coding agents (Claude Code, Cursor, Aider, Cline, Windsurf) waste significant time and tokens orienting themselves every session:

Agent: Let me look at package.json...          # tool call 1
Agent: Now let me see the directory structure... # tool call 2
Agent: Let me check tsconfig.json...            # tool call 3
Agent: What's in the src/ folder?               # tool call 4
Agent: How is the auth module structured?       # tool call 5

That's 5 tool calls, ~30 seconds, and hundreds of tokens burned before any real work begins. Multiply that across every task, every session, every day.

The solution

Agent: inspect scan /path/to/project   # 1 tool call, <3 seconds

Returns everything the agent needs in structured JSON:

| What | Why it matters | |------|---------------| | Project identity | Language, framework, package manager, runtime — no guessing | | Smart file tree | Full structure with noise collapsed (node_modules, dist, .git) | | Symbol index | Every exported function, class, type with signatures and line numbers | | Dependency map | Who imports what — bidirectional, internal files only | | Health baseline | Existing linter/type errors so the agent knows what it inherited vs introduced |

Three commands

scan — understand the project

First call does a full scan. Subsequent calls are incremental (only re-processes what git says changed). Cached and fast.

{
  "command": "scan",
  "path": "/path/to/project",
  "include_health": false
}

changed — what moved since last scan?

After a git pull, branch switch, or teammate's push. Returns deltas, blast radius, and new/removed/modified symbols.

{
  "command": "changed",
  "path": "/path/to/project"
}

impact — before I edit this, what depends on it?

Point it at a file or symbol. Get direct dependents, transitive dependents, usage sites with line numbers, and test coverage status.

{
  "command": "impact",
  "path": "/path/to/project",
  "target": "src/lib/auth.ts:getUserById"
}

Why this matters

For developers using AI agents

• Fewer wasted tool calls — 1 call replaces 3-5 exploratory ones
• Fewer broken edits — the agent knows the dependency graph before touching anything
• Faster sessions — orientation in seconds, not minutes
• Better context — agents make smarter decisions with structured project knowledge

For agent framework builders

• Drop-in MCP tool — standard protocol, works with any MCP client
• Structured JSON — consistent, machine-parseable output with stable keys
• Incremental by design — stays useful throughout a session, not just the first call

For teams with large codebases

• Scales to thousands of files — tree-sitter parsing with smart collapsing
• Git-native — handles pulls, rebases, branch switches correctly
• Zero config — works out of the box for TypeScript, JavaScript, Python, Rust, Go, Java, Ruby
• Fully local — no network calls, no cloud, no telemetry

Installation

Claude Code

claude mcp add inspect-mcp -- npx inspect-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "inspect-mcp": {
      "command": "npx",
      "args": ["inspect-mcp"]
    }
  }
}

Cursor

Add to MCP settings:

{
  "mcpServers": {
    "inspect-mcp": {
      "command": "npx",
      "args": ["inspect-mcp"]
    }
  }
}

Global install

npm install -g inspect-mcp

Build from source

git clone https://github.com/ykushch/inspecta.git
cd inspecta
pnpm install
pnpm build
node dist/index.js

When using a source build with MCP clients, replace npx inspect-mcp with node /absolute/path/to/inspecta/dist/index.js.

Agent instructions

Add to your CLAUDE.md or agent system prompt:

## Codebase awareness

- At the start of any coding task, call `inspect scan` to understand the project
- Before editing a function used elsewhere, call `inspect impact` to see dependents
- After `git pull` or branch switch, call `inspect changed` to see what moved

## Token efficiency

Pair with [RTK](https://github.com/rtk-ai/rtk) to reduce token usage by 60-90% on
CLI operations (git, test runners, linters). inspect-mcp gives structured codebase
context in a single tool call; RTK compresses everything else.

Install: `brew install rtk && rtk init --global`

How it works

• Project detection — reads config files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) to identify language, framework, package manager, and available tools
• File tree — recursive walk with smart collapsing (node_modules → { _collapsed: true, file_count: 48210 })
• Symbols — tree-sitter WASM parses source files to extract functions, classes, types with full signatures
• Dependencies — tree-sitter extracts imports, resolves paths, builds a bidirectional adjacency map
• Health — runs the project's own configured linters/type-checkers and structures the output
• Cache — results cached in .inspect/ anchored to git HEAD; incremental updates on subsequent calls

Performance targets

| Operation | Target | |-----------|--------| | Initial scan (500 files) | < 3 seconds | | Impact query | < 500ms | | Incremental update | < 1 second |

Monorepo & workspace support

inspecta automatically detects and handles multi-project layouts:

• Monorepos — when the root has no config file, sub-projects are detected in child directories
• Workspace directories — recurses into packages/, libs/, apps/, modules/, services/, etc.
• Python — builds a package index from all __init__.py files, resolving absolute imports (from mylib.config import settings) regardless of nesting depth
• Java — builds a fully-qualified class index from all .java files, resolving cross-module imports
• TypeScript/JS — resolves relative imports and path aliases from tsconfig.json

Works with any directory structure — no configuration needed.

Supported languages

| Language | Project detection | Symbols | Dependencies | |----------|-------------------|---------|-------------| | TypeScript | Yes | Yes | Yes | | JavaScript | Yes | Yes | Yes | | Python | Yes | Yes | Yes | | Java | Yes | Yes | Yes | | Rust | Yes | No | No | | Go | Yes | No | No | | Ruby | Yes | No | No | | Kotlin | Build detection only | No | No |

Design principles

1. Speed over completeness — fast partial answers beat slow perfect ones
2. Structured JSON only — every response is machine-parseable, no prose
3. Local and private — no network calls, no cloud, no telemetry
4. Git-native — anchored to commits, not filesystem watchers
5. Incremental by default — only re-process what changed
6. Zero config — works out of the box, optional config for customization

Configuration

Optional inspect.config.json in your project root:

{
  "collapse_dirs": ["node_modules", "dist", "build", ".next", "target"],
  "ignore_patterns": ["*.min.js", "*.generated.*", "*.d.ts"],
  "max_file_size_kb": 100,
  "tree_depth": 6,
  "health_timeout_ms": 15000
}

Maintainer release flow

1. Update version in package.json.
2. Merge the release commit and confirm CI is green.
3. Create and push a matching tag such as v0.1.1.
4. GitHub Actions verifies the tag, runs pnpm lint, pnpm test, pnpm build, packs the tarball, creates a GitHub Release, and publishes to npm.

Setup:

1. On npm: go to Settings → "Trusted Publishing" → link the ykushch/inspecta repository.
2. On GitHub: add your npm automation token as the NPM_TOKEN secret in Settings → Secrets → Actions.

License

MIT