@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:

1. Installs @codeweave/mcp globally
2. Installs Ollama if needed
3. Downloads the embedding model
4. Configures your MCP client (Claude Code, VS Code)
5. 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.

Tools

8 tools organized around the code understanding workflow:

Discover

Read

Analyze

Maintain

How It Works

Source Code
    │
    ▼
tree-sitter AST  ───>  Function Index (in-memory)
                              │
                   ┌──────────┼──────────┐
                   ▼          ▼          ▼
              Call Graph  Type Graph  Embeddings
              (JSON)      (JSON)     (LanceDB)
                   │          │          │
                   └──────────┼──────────┘
                              ▼
                       8 MCP Tools  ───>  AI Agent

1. Parse — tree-sitter extracts every function, class, method, and interface across 7 languages
2. Embed — Qwen3-Embedding-0.6B generates vector embeddings for semantic search
3. Index — LanceDB stores vectors with BM25 full-text index alongside
4. Graph — Call graph tracks who-calls-whom with type-aware resolution; type graph tracks inheritance and implementations
5. Watch — File watcher detects changes and incrementally reindexes affected files
6. Serve — 8 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:

1. Exact name match — Fast path for known function names (score 0.95+)
2. Vector search — Embed the query, find semantically similar functions (over-fetches 3x for reranking headroom)
3. Full-text search — BM25 keyword matching catches what embeddings miss
4. RRF merge — Reciprocal Rank Fusion combines both result lists without needing score calibration
5. Exact match boost — Functions whose name matches the query get priority
6. Density reranking — Structural signals determine information density, pushing trivial code down

Density Scoring uses 7 language-agnostic structural signals:

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. AST-based tools (dependencies, impact analysis, module summary) work without any embedding infrastructure.

Why These Technologies

Every technology choice serves the core goal: local, fast, zero-config code understanding.

Supported Languages

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:
  - .                                  # Root workspace
  - clients/web                        # Web client
  - clients/mobile                     # Mobile client

embedding:
  model: "qwen3-embedding:0.6b"     # Embedding model name
  ollamaUrl: "http://localhost:11434" # Ollama API endpoint
  dimensions: 1024                    # Vector dimensions
  batchSize: 50                       # Embedding batch size

parser:
  sourceRoot: "src"                   # Strip this prefix from module paths
  ignore:
    - "**/*.generated.*"              # Additional ignore patterns
    - "**/vendor/**"

search:
  rrfK: 60                           # RRF smoothing constant
  expandCamelCase: true               # Expand camelCase in search chunks
  density:
    enabled: true                     # Density-based reranking
    accessorPenalty: 0.6              # Penalty for getters/setters
    constructorPenalty: 0.7           # Penalty for constructors
    testFilePenalty: 0.5              # Penalty for test files

watcher:
  debounceMs: 500                     # File change debounce
  minIntervalMs: 2000                 # Minimum reindex interval

indexing:
  maxFileSizeKb: 500                  # Skip files larger than this

CLI Tools

# Full project initialization (AST + embeddings + graphs)
codeweave-init [path] [--force] [--no-embed]

# Incremental reindex (only changed files)
codeweave-reindex [--all] [--files=path1,path2] [--stdin]

# Docstring coverage report
codeweave-check-docstrings [--strict] [files...]

Manual Setup

If you prefer step-by-step instead of npx @codeweave/mcp:

# 1. Install globally
npm install -g @codeweave/mcp

# 2. Install Ollama and pull the embedding model
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh

ollama pull qwen3-embedding:0.6b

# 3. Index your project
cd your-project
codeweave-init

4. Configure your MCP client

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. AST-based tools work without Ollama.

Status

CodeWeave is under active development. The core indexing pipeline and all 8 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