Code Intelligence MCP Server

Give your AI coding agent a deep understanding of your codebase.

A local code indexing engine that gives LLM agents like Claude Code, Cursor, Trae, and OpenCode semantic search, call graphs, type hierarchies, and impact analysis across your codebase. Written in Rust with Metal GPU acceleration.

Zero config. Runs via npx. Indexes in the background.

Install

Claude Code

claude mcp add code-intelligence -- npx -y @iceinvein/code-intelligence-mcp

{
  "mcpServers": {
    "code-intelligence": {
      "command": "npx",
      "args": ["-y", "@iceinvein/code-intelligence-mcp"],
      "env": {}
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "code-intelligence": {
      "command": "npx",
      "args": ["-y", "@iceinvein/code-intelligence-mcp"]
    }
  }
}

OpenCode / Trae

Add to opencode.json:

{
  "mcp": {
    "code-intelligence": {
      "type": "local",
      "command": ["npx", "-y", "@iceinvein/code-intelligence-mcp"],
      "enabled": true
    }
  }
}

On first launch, the server downloads three models, ~3.2 GB total: the embedding model (Jina Code 1.5b, ~1.5 GB), the description LLM (Qwen2.5-Coder-1.5B, ~1.0 GB), and the cross-encoder reranker (bge-reranker-v2-m3, ~600 MB). Indexing then runs in the background. Models are cached in ~/.code-intelligence/models/.

What It Does

Unlike basic text search (grep/ripgrep), this server builds a local knowledge graph of your code and exposes it through 32 MCP tools.

Tools (32)

Upgrade note (3.0.0): search_code no longer assembles a context markdown bundle by default. Pass context: "snippets" for compact per-hit code, or context: "full" to restore the v2 behavior. See Migration below.

Search & Navigation

Analysis

Testing, Frameworks & Discovery

Cross-Repo (standalone mode)

Index Management & Learning

Supported Languages

Rust, TypeScript/TSX, JavaScript, Python, Go, Java, C, C++

Standalone Mode (Multi-Client)

By default each MCP client spawns its own server process. If you run multiple clients (e.g. 5 Claude Code sessions across 3 repos), standalone mode loads the models once and shares them:

npx @iceinvein/code-intelligence-mcp-standalone

Then point all clients to http://localhost:3333/mcp:

claude mcp add --transport http code-intelligence http://localhost:3333/mcp

{
  "mcpServers": {
    "code-intelligence": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

{
  "mcp": {
    "code-intelligence": {
      "type": "remote",
      "url": "http://localhost:3333/mcp",
      "enabled": true
    }
  }
}

The server auto-detects each client's workspace via the MCP roots capability. Separate indexes are maintained per repo, models are shared.

┌──────────┐  ┌──────────┐  ┌──────────┐
│ Claude A  │  │ Cursor B │  │  Trae C  │
└─────┬─────┘  └─────┬─────┘  └─────┬─────┘
      │              │              │
      └──────── POST /mcp ─────────┘
                     │
        ┌────────────┴────────────┐
        │   Standalone Server     │
        │  (shared models, once)  │
        ├─────────────────────────┤
        │ Repo A   Repo B  Repo C│
        │ indexes  indexes indexes│
        └─────────────────────────┘

Configuration

Works out of the box with no configuration. All settings are optional environment variables.

Core:

Embeddings:

Ranking:

Context:

Learning (off by default):

[server]
host = "127.0.0.1"
port = 3333

[embeddings]
backend = "llamacpp"
device = "metal"

[repos.defaults]
index_patterns = "**/*.ts,**/*.tsx,**/*.rs,**/*.py,**/*.go"
exclude_patterns = "**/node_modules/**,**/dist/**,**/.git/**"
watch_mode = true

[lifecycle]
warm_ttl_seconds = 300      # How long idle repos stay in memory

Priority: CLI flags > Environment variables > server.toml > Defaults

How Ranking Works

The search pipeline runs keyword search (BM25) and semantic vector search in parallel, merges them with Reciprocal Rank Fusion, then applies structural signals:

• Intent detection — "struct User" boosts definitions, "who calls login" triggers graph lookup, "User schema" boosts models 50-75x
• Query decomposition — "authentication and authorization" automatically splits into sub-queries; sub-query coverage ensures each term has at least one matching result
• LLM-enriched index — on-device Qwen2.5-Coder generates descriptions bridging vocabulary gaps between how you search and how code is named
• Cross-encoder reranker — bge-reranker-v2-m3 re-scores top candidates for precision (always-on by default, disable with RERANKER_ENABLED=false)
• PageRank — graph-based importance scoring identifies central, heavily-used symbols
• Morphological expansion — watch matches watcher, index matches reindex
• Framework-pattern injection — route, middleware, and handler patterns surface alongside symbol matches
• Multi-layer test detection — file paths, symbol names, and AST-level analysis (#[test], mod tests)
• Edge expansion — high-ranking symbols pull in structurally related code (callers, type members)
• Export boost — public API surface ranks above private helpers
• Score-gap detection — drops trailing results that fall off a relevance cliff
• Token-aware truncation — context assembly keeps query-relevant lines within token budgets

For the full deep dive, see System Architecture.

Data Storage

All data lives in ~/.code-intelligence/:

~/.code-intelligence/
├── models/                     # Shared across repos (~3.2 GB total)
│   ├── jina-code-embeddings-1.5b-gguf/   # ~1.5 GB, 1536-dim Matryoshka, Q8_0
│   ├── qwen2.5-coder-1.5b-gguf/          # ~1.0 GB, Q4_K_M, description LLM
│   └── bge-reranker-v2-m3-gguf/          # ~600 MB, Q8_0, cross-encoder reranker
├── repos/
│   ├── registry.json           # Tracks all known repos
│   └── <hash>/                 # Per-repo (SHA256 of repo path)
│       ├── code-intelligence.db   # SQLite (symbols, edges, metadata, descriptions)
│       ├── tantivy-index/         # BM25 full-text search
│       └── vectors/               # LanceDB vector embeddings
├── logs/
└── server.toml                 # Standalone config (optional)

Development

cargo build --release
cargo test                                        # Full test suite
EMBEDDINGS_BACKEND=hash cargo test                # Fast (no model download)
./scripts/start_mcp.sh                            # Start MCP server

src/
├── indexer/          # File scanning, Tree-Sitter parsing, symbol extraction, embeddings, LLM descriptions
├── storage/          # SQLite, Tantivy (BM25), LanceDB (vectors)
├── retrieval/        # Hybrid search, ranking signals, RRF, context assembly, reranker, HyDE
├── graph/            # PageRank, call hierarchy, type graphs, dependency graph
├── handlers/         # MCP tool implementations
├── server/           # MCP protocol routing (embedded + standalone)
├── tools/            # Tool definitions (32 MCP tools)
├── embeddings/       # jina-code-embeddings-1.5b (GGUF via llama.cpp + Metal)
├── llm/              # Qwen2.5-Coder-1.5B (GGUF via llama.cpp + Metal)
├── reranker/         # bge-reranker-v2-m3 cross-encoder (GGUF via llama.cpp + Metal)
└── path/             # UTF-8 path normalization (camino)

Migration: v2 → v3

search_code previously returned both ranked hits and a context markdown bundle (source code for top hits + auto-expanded "Examples" / "Related" symbols). The bundle was always assembled, even when callers only needed the ranked list, and could exceed 30 KB per call.

In v3.0.0, search_code is a discovery tool by default. It returns hits only. Source code is opt-in via the new context parameter:

To restore v2 behavior, pass context: "full" on every call.

For most agent workflows, "snippets" is the recommended setting: enough code to ground the next decision, without rendering an entire markdown bundle. Agents that need full source for selected hits should call hydrate_symbols(ids[]) after search_code.

The web UI and cross-repo aggregator continue to request context: "full" internally; only the public MCP search_code tool default has changed.

License

MIT