contextplus-rs

High-performance MCP server for semantic code analysis, written in Rust. Drop-in replacement for the original Context+ TypeScript implementation with 5-20x faster warm queries.

Why Rust?

Cold Start Benchmark (fresh process per call)

Measured against the workspace (~2800 source files), each call spawns a fresh process:

* Grep is fast but returns raw matches — see token comparison below.

Token Efficiency (MCP vs Grep)

MCP tools return ranked, structured results. Grep returns raw lines.

20-Search Session Cost

Internal Bottleneck Comparison

Rust eliminates all overhead via:

• Zero-copy cache with rkyv + memmap2 (no deserialization)
• SIMD cosine similarity via simsimd (AVX-512/AVX2 auto-dispatch)
• Native tree-sitter (compiled in, no WASM VM) — 15 languages + regex fallback
• Binary serialization (rkyv replaces JSON for memory graph)
• Disk-persistent embedding cache with content-hash staleness detection
• Adaptive embedding retry with exponential backoff and cancellation tokens
• Automatic chunking for oversized embedding inputs (chunk → embed → merge)
• Process lifecycle management — idle timeout, parent PID orphan detection, SIGTERM/SIGHUP handling
• Memory graph disk persistence with debounced flush on mutation

Install

Build from source

git clone https://github.com/mrsufgi/contextplus-rs.git
cd contextplus-rs
cargo build --release

The binary is at target/release/contextplus-rs.

Prerequisites

• Ollama running locally with an embedding model:

ollama pull snowflake-arctic-embed2   # embeddings
ollama pull qwen3.5:9b                # chat (for cluster labeling)

Configuration

Ollama / embedding

Search / indexing

Warmup

Tracker (file-watcher)

Process lifecycle

Usage

As an MCP server (stdio)

contextplus-rs --root-dir /path/to/project

Claude Code integration

Add to your MCP config (~/.claude/mcp.json or project .mcp.json):

{
  "mcpServers": {
    "contextplus": {
      "command": "/path/to/contextplus-rs",
      "args": ["--root-dir", "/path/to/project"],
      "env": {
        "OLLAMA_EMBED_MODEL": "snowflake-arctic-embed2",
        "OLLAMA_CHAT_MODEL": "qwen3.5:9b",
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "CONTEXTPLUS_EMBED_BATCH_SIZE": "256",
        "CONTEXTPLUS_EMBED_TRACKER": "eager"
      }
    }
  }
}

Note: think: false is sent automatically to the chat model to avoid slow thinking-mode responses. Models like qwen3.5:9b produce cluster labels in <1s with thinking disabled vs 45s+ with thinking enabled.

CLI subcommands

# Generate MCP config for your editor (claude, cursor, vscode, windsurf, opencode)
contextplus-rs init claude
contextplus-rs init cursor

# Print file skeleton
contextplus-rs skeleton src/main.rs

# Print context tree
contextplus-rs tree --max-tokens 5000

MCP Resources

Tools (17)

Code Analysis

Semantic Search

File Management

Memory Graph

Navigation

Architecture

See ARCHITECTURE.md for detailed internals (data flow, caching strategy, memory layout, performance architecture, and how to add new tools).

src/
  main.rs                    # CLI + MCP server entry point
  server_adapters.rs         # rmcp ServerHandler impl + tool dispatch
  server_definitions.rs      # Tool definitions (names, descriptions, JSON schemas)
  server_helpers.rs          # Shared handler utilities
  config.rs                  # Environment variable configuration
  error.rs                   # ContextPlusError enum (thiserror)
  core/
    embeddings.rs            # OllamaClient + adaptive retry + chunking + cancellation
    tree_sitter.rs           # Native multi-lang parser (15 languages)
    parser.rs                # Code symbol extraction + regex fallback for unsupported langs
    walker.rs                # gitignore-aware file walker (ignore crate)
    embedding_tracker.rs     # File watcher with lazy/eager/off modes
    clustering.rs            # Spectral clustering (nalgebra)
    memory_graph.rs          # petgraph + rkyv disk persistence with debounced flush
    hub.rs                   # Wikilink parser
    process_lifecycle.rs     # Idle timeout + parent PID orphan detection
    safe_path.rs             # Path traversal prevention
    utils.rs                 # Shared utilities
  tools/                     # One file per tool (context_tree supports depth_limit filtering)
  git/shadow.rs              # Restore points (file-based backup)
  cache/rkyv_store.rs        # Zero-copy rkyv+mmap VectorStore

Supported Languages (tree-sitter)

TypeScript, TSX, JavaScript, Python, Rust, Go, Java, C, C++, Bash, Ruby, PHP, C#, Kotlin, HTML, CSS

Unsupported file types fall back to regex-based symbol extraction.

Key Crates

Benchmarks (cargo bench)

Nine Criterion benchmark suites cover the critical hot paths — no Ollama dependency, fully reproducible.

Cache Load (rkyv + mmap)

How fast the embedding cache loads from disk. This was the #1 bottleneck in TS (1,109ms raw, 115ms with VectorStore optimization).

At 5K vectors (typical project size), total load is ~4ms. At 30K vectors, mmap beats read by 43%.

Cosine Similarity (simsimd SIMD vs scalar)

30K-vector scan in 4.1ms — well under the 20ms target.

Tree-sitter Parse (native, 15 languages)

All 15 languages parsed in ~2.1ms total — vs 50-200ms for WASM in TS.

Warm Search Pipeline

End-to-end: disk load → VectorStore build → find_nearest(top_5) → format results.

Warm search on 30K files: 4.3ms. Hash-check (no-op refresh): <1ms.

Development

cargo test                  # 1050+ tests
cargo bench                 # 9 Criterion benchmark suites
cargo clippy --all-targets  # Lint
cargo fmt --check           # Format check

Credits

This is a Rust rewrite of Context+ (TypeScript), originally created by the Context+ community. The Rust port was built from the fix/merge-cache-on-save branch which includes performance optimizations (hash-based cache invalidation, VectorStore extraction, parallel call-site ranking, tree-sitter dedup).

License

MIT