lsp-intelligence

lsp-intelligence

Local code intelligence for real engineering workflows.

Find implementations, API usage, structural patterns, configs, and routes. Explain why something broke. Guard the API contract before merging.

29 MCP tools across 5 layers. Supports TypeScript and JavaScript (TS, TSX, JS, JSX, MJS, CJS). Local-only — no paid API, no external calls.

Why this exists

AI coding agents use grep to understand code. Grep finds text, not meaning. It can't follow types through aliases, can't distinguish imports from function calls, and returns false positives from comments and strings.

lsp-intelligence gives agents the same code understanding that VS Code has — type-aware references, call hierarchies, impact analysis — via the Model Context Protocol (MCP).

Quick start

After installation, try in Claude Code:

"What breaks if I rename the UserService class?"

Under the hood, the agent calls:

{ "tool": "impact_trace", "arguments": { "symbol": "UserService" } }

Or get a file overview without reading it:

{ "tool": "outline", "arguments": { "file_path": "/workspace/src/services/auth.ts" } }

All tools that accept file_path require absolute paths.

Installation

Requires Node.js 20+.

Plugin install (recommended)

/plugin marketplace add perilevy/lsp-intelligence
/plugin install lsp-intelligence
/reload-plugins

That's it. The plugin installs the MCP server, skills, hooks, and agent context in one step. No separate runtime install, no manual .mcp.json edits.

MCP server only (advanced)

For non-Claude Code agents or manual MCP configuration:

{
  "mcpServers": {
    "lsp-intelligence": {
      "command": "npx",
      "args": ["-y", "lsp-intelligence"],
      "env": { "LSP_WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

This gives you the raw MCP tools only — no skills or hooks.

Capabilities

LSP vs text search

| Query | Text search (grep) | lsp-intelligence | |-------|-------------------|-----------------| | Find all references to a function | Finds text matches | Semantic references — no false positives from comments or strings | | Find references to a type alias | ⚠️ Includes substring matches (e.g. UserServiceConfig matches UserService) | Exact symbol resolution — only true references | | Cross-package references in monorepo | ⚠️ Text matches only — includes false positives, can't distinguish import vs call vs type annotation | Type-aware semantic references across packages |

What agents can do with LSP that they can't with grep

| Capability | Description | |-----------|-------------| | Follow type aliases | Trace through ReturnType<typeof X>, re-exports, and barrel files | | Go to definition | Jump to the actual source, not just a text match | | Call hierarchy | "Who calls this function?" / "What does this function call?" | | Type signatures | Get the full type signature without reading the implementation | | Impact analysis | "What breaks if I change this?" — one call, full answer | | Semantic diff | Git changes → which symbols changed → blast radius per symbol | | Context building | Trace an impact graph, extract only relevant code, token-budget the output | | Rename preview | See every file that would change before committing a rename | | Dead code detection | Find exports that nothing imports | | Auto-import | Resolve the correct import path for any symbol |

Performance

Tested on a TypeScript monorepo (9 packages, ~200k LOC):

| Metric | Value | |--------|-------| | Engine ready | ~10s (scales with repo size) | | Queries after warmup | 100-300ms | | 21 queries end-to-end | ~16s total |

The engine initializes once per session and stays warm. Warmup includes spawning TypeScript Server and pre-opening all monorepo packages. Queries start as soon as the index is available — no fixed delay.

Tools

Layer 1: Primitives (13 tools)

Direct LSP wrappers. Every tool accepts symbol names — agents never need to guess line numbers.

| Tool | Description | |------|-------------| | find_references | Find every usage of a symbol across the codebase. Semantic, not text. | | goto_definition | Jump to where a symbol is defined. Follows imports and re-exports. | | goto_type_definition | Find the type that defines a variable. | | hover | Get full type signature and documentation. | | find_implementations | Find concrete implementations of an interface. | | document_symbols | List all symbols in a file. | | workspace_symbols | Search for symbols by name across the workspace. | | call_hierarchy | Trace incoming callers or outgoing callees. | | rename | Preview a semantic rename across the codebase (dry-run by default). | | diagnostics | Get type errors and warnings for a file. | | completions | Code completion suggestions. | | file_imports | List all imports of a file. | | file_exports | List a file's public API including re-exports. |

Layer 2: Intelligence Tools (10 tools)

Combine LSP, AST, and Git substrates into high-level operations.

| Tool | Description | |------|-------------| | api_guard | Detect public API contract changes — export diffs, structural classification, consumer impact, semver summary. | | root_cause_trace | Trace the root cause of a TypeScript error — find the originating declaration change, not just the symptom. | | find_code | Unified code search: behavior discovery, identifier/API usage, structural queries, config/route lookup, and implementation-root discovery. Routes automatically. | | find_pattern | AST structural search — find code by pattern (e.g. useEffect($$$), try { $$$ } catch ($E) { $$$ }). | | inspect_symbol | Hover + definition + references in one call. Full context about any symbol. | | batch_query | Look up multiple symbols at once. Saves round-trips when exploring. | | impact_trace | Follow a symbol through type aliases and re-exports to find ALL transitive usages. | | semantic_diff | Analyze git diff semantically: identify changed symbols and their blast radius. | | find_test_files | Find all test/spec/stories files that reference a symbol. | | explain_error | Turn a TypeScript error into actionable context: expected type, actual type, and fix suggestion. |

Layer 3: Context Engine (2 tools)

Token-aware context building for agents.

| Tool | Description | |------|-------------| | outline | File structure with type signatures — understand a file without reading it. | | gather_context | Trace impact graph from entry symbols, classify files as must-modify / verify-only / skip, return token-budgeted context. |

Layer 4: Live Intelligence (3 tools)

Post-edit verification.

| Tool | Description | |------|-------------| | live_diagnostics | Re-read a file after editing and check for new type errors. | | find_unused_exports | Find exported symbols with zero cross-package importers. | | auto_import | Resolve the correct import path for a symbol name. |

find_code query classes

find_code supports five query classes, routed automatically:

| Class | Example query | What happens | |-------|--------------|-------------| | Identifier / API usage | useEffect, Promise.all | Usage index → exact call/import sites with enclosing context | | Structural | useEffect that returns cleanup conditionally | Identifier + structural predicates → AST evaluation on located nodes | | Behavior / entrypoint | where do we validate permissions | Fielded BM25 over declarations + JSDoc/comments + family hints | | Config / route / flag | where is the feature flag configured | Config index → JSON/YAML/package.json + env usage in code | | Implementation root | where is this actually implemented | Graph expansion → wrapper detection → root promotion |

Architecture

┌─────────────────────────────────────────────────────────┐
│ Layer 4: Live Intelligence              [state-mutating] │
│   live_diagnostics, find_unused_exports, auto_import    │
├─────────────────────────────────────────────────────────┤
│ Layer 3: Context Engine                 [read-only]      │
│   gather_context, outline                               │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Intelligence Tools              [read-only]      │
│   find_code, find_pattern, root_cause_trace, api_guard, │
│   impact_trace, semantic_diff, inspect_symbol,          │
│   batch_query, find_test_files, explain_error           │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Primitives                     [read-only]      │
│   find_references, hover, definition, call_hierarchy,   │
│   rename, diagnostics, symbols, imports, exports        │
├─────────────────────────────────────────────────────────┤
│ Layer 0: Analysis Substrates            [infrastructure]  │
│   LSP Engine (TypeScript Server, symbol resolver)       │
│   TypeScript AST (declarations, usages, predicates)     │
│   Local text/regex search (recipe-compiled patterns)    │
│   Config/doc indexes (JSON, YAML, env, JSDoc, comments) │
│   Graph expansion (wrapper detection, root promotion)   │
│   Git integration (semantic diff, base comparison)      │
└─────────────────────────────────────────────────────────┘

Each layer only depends on layers below it.

Monorepo Support

Works with any monorepo structure out of the box:

• packages/, apps/, libs/, modules/, services/ directory conventions
• pnpm-workspace.yaml
• package.json workspaces (yarn, npm)

At startup, the engine discovers all workspace packages and pre-opens one file per package. This triggers TypeScript Server to build configured projects for every package, enabling cross-package reference finding — a common challenge with LSP tooling in monorepos.

Symbol-Name Resolution

Every tool accepts { symbol: "UserService" } instead of requiring { file_path, line, column }. The engine resolves names to positions via workspace/symbol with priority sorting. Agents never need to guess line numbers.

Installation

Requires Node.js 20+.

Option 1: Claude Code plugin (recommended)

Installs the MCP server, hooks, and skills (/find, /why, /api-check, /verify, /check, /impact, /context, /diff) as a single package.

claude plugin add perilevy/lsp-intelligence

The full experience — the agent gets code intelligence tools, guided workflows via skills, and automatic hooks.

Option 2: MCP server only

For other AI agents (Copilot, Cursor, etc.) or if you only want the raw tools without hooks and skills.

Add to your .mcp.json:

{
  "mcpServers": {
    "lsp": {
      "command": "npx",
      "args": ["-y", "lsp-intelligence"]
    }
  }
}

Option 3: From source

For contributors or debugging.

git clone https://github.com/perilevy/lsp-intelligence.git
cd lsp-intelligence
yarn install && yarn build

Then in .mcp.json:

{
  "mcpServers": {
    "lsp": {
      "command": "node",
      "args": ["/absolute/path/to/lsp-intelligence/dist/index.js"]
    }
  }
}

Development

git clone https://github.com/perilevy/lsp-intelligence.git
cd lsp-intelligence
yarn install
yarn build       # clean build (rm -rf dist && tsc)
yarn test        # vitest
yarn typecheck   # TypeScript strict mode — no emit
yarn bench       # search quality benchmarks

Testing

Tests verify cross-package reference resolution, symbol-name lookup, type alias tracing, impact trace traversal, search quality, context building, and output formatting — all against self-contained fixture repos at test-fixtures/. No external dependencies needed.

Benchmarks

benchmarks/ contains reproducible quality cases for find_code, root_cause_trace, and api_guard. Every serious real-world failure should become a benchmark case.

What this is not

• Not a universal semantic search engine. Strong on code structure, API usage, configs, and known patterns. Does not understand arbitrary business logic.
• Not a replacement for full-text search. Use grep for literal string matching. find_code uses text patterns internally but optimizes for code-aware ranking.
• Not an AI model. All intelligence is local: AST analysis, LSP queries, fielded text ranking, adapter recipes. No paid API calls, no external services.
• Does not index secret-bearing .env files. Env variable usage in code (process.env.X, import.meta.env.X) is indexed and searchable. Non-secret template/example files (.env.example, .env.template) are indexed. Real .env files are excluded by default.

Dependencies

All dependencies are installed automatically. Under the hood: typescript-language-server for LSP, @modelcontextprotocol/sdk for MCP, @ast-grep/napi for structural patterns. Uses your project's own TypeScript version.

License

MIT