@codeweave/mcp
Give your AI agent structured code understanding — not just file dumps.
CodeWeave is an MCP server that gives AI agents cheap, precise code intelligence. Instead of dumping entire files into context, your agent queries local indexes — AST, call graph, type graph, hybrid semantic search — and gets back only what it needs.
Less tokens. More relevant context. Better decisions.
The semantic search pipeline is the heart of the system: a 6-stage hybrid engine combining vector embeddings, full-text search, and structural density scoring. Tested extensively across large production codebases — Java monoliths, TypeScript monorepos, Python ML pipelines, Go microservices — with consistently strong retrieval accuracy.
Actively developed. New tools and improvements ship regularly. Contributions and feedback are welcome.
Quick Start
cd your-project
npx @codeweave/mcp
That's it. The setup wizard handles everything:
- Installs
@codeweave/mcp globally
- Installs Ollama if needed
- Downloads the embedding model
- Configures your MCP client (Claude Code, VS Code)
- Indexes your project
Note: The first run requires a one-time download of Ollama and the embedding model. This takes a few minutes but only happens once.
Open your project in Claude Code or VS Code and start asking questions.
3 tools organized around the code understanding workflow:
| Tool | Purpose |
|---|
semantic_search | Search by meaning — finds functions even when you don't know exact names. Hybrid vector + keyword search with density-based reranking. |
reindex | Manually trigger index update. Usually unnecessary — file watcher auto-reindexes on changes. |
get_index_status | Index health dashboard: file/function counts, embedding status, call graph stats, language breakdown. |
How It Works
Source Code
│
▼
tree-sitter AST ───> Function Index (in-memory)
│
┌──────────┼──────────┐
▼ ▼ ▼
Call Graph Type Graph Embeddings
(JSON) (JSON) (LanceDB)
│ │ │
└──────────┼──────────┘
▼
3 MCP Tools ───> AI Agent
- Parse — tree-sitter extracts every function, class, method, and interface across 7 languages
- Embed — Qwen3-Embedding-0.6B generates vector embeddings for semantic search
- Index — LanceDB stores vectors with BM25 full-text index alongside
- Graph — Call graph tracks who-calls-whom with type-aware resolution; type graph tracks inheritance and implementations (powers ranking and index-status reporting)
- Watch — File watcher detects changes and incrementally reindexes affected files
- Serve — 3 tools exposed over MCP protocol (stdio), ready before indexing completes
Semantic Search
The search pipeline is where CodeWeave really shines. It's not just vector similarity — it's a multi-stage system designed to surface the most relevant and important code:
6-Stage Pipeline:
- Exact name match — Fast path for known function names (score 0.95+)
- Vector search — Embed the query, find semantically similar functions (over-fetches 3x for reranking headroom)
- Full-text search — BM25 keyword matching catches what embeddings miss
- RRF merge — Reciprocal Rank Fusion combines both result lists without needing score calibration
- Exact match boost — Functions whose name matches the query get priority
- Density reranking — Structural signals determine information density, pushing trivial code down
Density Scoring uses 7 language-agnostic structural signals:
| Signal | What it measures |
|---|
| Body size | Larger functions carry more behavior (log-scaled) |
| Docstring presence | Documented code is more likely to be important |
| Docstring richness | Tags, deps, side effects indicate well-maintained code |
| Parameter count | More params = more complex behavior |
| Call graph centrality | Functions called by many others are architectural anchors |
| Visibility | Public > protected > private |
| Kind | Classes > methods/functions > interfaces |
Penalties prevent noise from dominating results:
- Accessors (getters/setters) — pure data access, no behavior
- Constructors — many params inflate scores, but they're just assignments
- Test files — large bodies don't mean important behavior (unless you're searching for tests)
Graceful degradation: If Ollama is unavailable, search falls back to full-text only.
Why These Technologies
Every technology choice serves the core goal: local, fast, zero-config code understanding.
| Technology | Why |
|---|
| tree-sitter | One parsing framework for all 7 languages. Mature, fast, battle-tested. Gives us full AST access without writing 7 different parsers from scratch. |
| LanceDB | Embedded vector database — no external server, no Docker, no configuration. Just a directory on disk. Supports both vector search and BM25 full-text search in a single engine. |
| Qwen3-Embedding-0.6B | The secret weapon. Just 0.6B parameters but delivers embedding quality that rivals models 10x its size for code understanding. Tested across large production codebases — Java enterprise monoliths, TypeScript monorepos, Python data pipelines — with consistently excellent retrieval accuracy. Runs locally via Ollama, fast enough for real-time reindexing, lightweight enough for any developer machine. |
| RRF (Reciprocal Rank Fusion) | Proven technique from information retrieval research. Merges ranked lists from different scoring systems (vector similarity vs. BM25 relevance) without needing score calibration. Simple, robust, effective. |
| MCP Protocol | Standard interface for AI tool integration. One server works with Claude Code, VS Code, Cursor, and any MCP-compatible client. |
Supported Languages
| Language | Functions | Calls | Imports | Types | Test Detection |
|---|
| Python | functions, methods, classes | call sites | import/from-import | class inheritance, type hints | pytest, unittest |
| TypeScript | functions, arrows, methods, classes, interfaces | call sites | named/default/namespace imports | implements, extends, member types | jest, vitest, playwright |
| JavaScript | (same as TypeScript) | (same as TypeScript) | (same as TypeScript) | (same as TypeScript) | jest, vitest, mocha |
| Go | functions, methods (receiver), structs | call sites | import specs | implicit interfaces, structs | testing, testify |
| Rust | functions, methods (impl), structs, enums | call sites | use declarations | impl Trait for Type | #[test], #[cfg(test)] |
| Java | methods, constructors, classes, interfaces | method invocations | import declarations | extends, implements | JUnit, Mockito, AssertJ |
| C# | methods, constructors, classes, structs, interfaces, records | invocations | using directives | base types, interface impl | NUnit, xUnit, Moq |
Every language parser also provides:
- Noise filtering — built-in lists of standard library calls (e.g.,
console.log, fmt.Println, System.out.println) that get filtered from dependency analysis
- Structural hints — AST-confirmed classifications (constructor, abstract, getter/setter, test) that feed into density scoring
Configuration
CodeWeave works zero-config out of the box. For customization, create .code-context/config.yaml:
workspaces:
- .
- clients/web
- clients/mobile
embedding:
model: "qwen3-embedding:0.6b"
ollamaUrl: "http://localhost:11434"
dimensions: 1024
batchSize: 50
parser:
sourceRoot: "src"
ignore:
- "**/*.generated.*"
- "**/vendor/**"
search:
rrfK: 60
expandCamelCase: true
density:
enabled: true
accessorPenalty: 0.6
constructorPenalty: 0.7
testFilePenalty: 0.5
watcher:
debounceMs: 500
minIntervalMs: 2000
indexing:
maxFileSizeKb: 500
codeweave-init [path] [--force] [--no-embed]
codeweave-reindex [--all] [--files=path1,path2] [--stdin]
Manual Setup
If you prefer step-by-step instead of npx @codeweave/mcp:
npm install -g @codeweave/mcp
brew install ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3-embedding:0.6b
cd your-project
codeweave-init
Claude Code — add .mcp.json to your project root:
{
"mcpServers": {
"codeweave": {
"command": "codeweave-server"
}
}
}
VS Code — add .vscode/mcp.json:
{
"servers": {
"codeweave": {
"command": "codeweave-server"
}
}
}
Monorepo Support
CodeWeave auto-detects workspaces in monorepos by scanning for manifest files (package.json, build.gradle, pom.xml, go.mod, Cargo.toml, pyproject.toml, etc.):
my-project/
├── backend/build.gradle → workspace "backend"
├── mobile/package.json → workspace "mobile"
└── shared/package.json → workspace "shared"
Each workspace gets its own isolated index, call graph, type graph, and vector store. Tools accept an optional workspace parameter — omit it to search across all workspaces.
Git Worktree Support
CodeWeave automatically detects git worktrees (including Claude Code's /worktree). On first start in a worktree, it copies the main repo's cache for a fast warm start (~2s instead of 30s+). After that, each worktree maintains its own fully isolated index.
- Automatic — no configuration needed
- Isolated — worktree changes don't affect the main repo's cache
- Incremental — only files that differ from the main branch are re-parsed and re-embedded
Requirements
- Node.js 20+
- Ollama — for semantic search embeddings. Install via the setup wizard or manually from ollama.com. Without Ollama, semantic search falls back to full-text only.
Status
CodeWeave is under active development. The core indexing pipeline and all 3 tools are stable and tested across production codebases in all 7 supported languages.
Feedback, bug reports, and contributions are welcome — open an issue at github.com/semihkayan/codeweave-mcp.
License
Apache 2.0