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

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

Performance

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

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.

Layer 2: Intelligence Tools (10 tools)

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

Layer 3: Context Engine (2 tools)

Token-aware context building for agents.

Layer 4: Live Intelligence (3 tools)

Post-edit verification.

find_code query classes

find_code supports five query classes, routed automatically:

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