Roo Code Index Bridge MCP

A client-neutral, local-first semantic code indexing and search MCP. Version 0.3.0 owns the whole indexing pipeline — file discovery, structural chunking, embeddings, Qdrant storage, incremental sync, and watching — so Roo Code is not required. It works from Codex, ZCode, OpenCode, Claude Code, VS Code, Vibe Code, and any other MCP-compatible client.

Legacy Roo Code ws-* indexes remain searchable read-only for backward compatibility.

Architecture in One Page

MCP client (Codex/ZCode/Claude Code/VS Code/...)
        │  stdio
        ▼
FastMCP server (server.py — registration only)
        ▼
IndexBridgeService (service.py — policy + orchestration)
        │
        ├─ FileDiscovery  → git ls-files / safe walk, .gitignore + .rooignore, size/binary/symlink guards
        ├─ Chunker        → tree-sitter structural chunks, markdown headings, line fallback
        ├─ EmbeddingClient→ Ollama /api/embed batches (also OpenAI-compatible, Gemini, Mistral)
        ├─ QdrantStore    → rci-* collections, batched upserts, ownership checks, alias swaps
        ├─ StateDB        → SQLite at %LOCALAPPDATA%\roo-code-index-bridge\state.sqlite3
        └─ WatchManager   → debounced watchfiles → one incremental sync

Details: docs/architecture.md · Tools: docs/mcp-tools.md · Configuration: docs/configuration.md · Problems: docs/troubleshooting.md

Requirements

• Python 3.11+ and uv
• Ollama at http://127.0.0.1:11434 with an embedding model, e.g. ollama pull qwen3-embedding:0.6b (1024 dimensions)
• Qdrant at http://127.0.0.1:6333 (e.g. docker run -p 6333:6333 qdrant/qdrant)

No Roo Code extension, no cloud services, no accounts.

Quick Start (Roo-independent)

# 1. Get the code and dependencies
cd D:\Github\roo-code-index-bridge-mcp
uv sync

# 2. Point at your services (this file is optional; defaults match Ollama+Qdrant)
copy config.example.json config.json
$env:ROO_INDEX_BRIDGE_CONFIG_PATH = "D:\Github\roo-code-index-bridge-mcp\config.json"

# 3. Check the stack
uv run roo-code-index-bridge-mcp doctor

# 4. Index and search any repository
uv run roo-code-index-bridge-mcp index D:\some\repo
uv run roo-code-index-bridge-mcp search D:\some\repo "configuration loading and secret resolution"

Browser UI (new in 0.3.0)

roo-code-index-bridge-mcp ui --open

Serves a localhost-only browser interface (default http://127.0.0.1:8765) for inspecting index health, browsing bridge-managed indexes, running semantic searches, and exploring a bounded semantic-similarity graph. Read-only: the browser exposes no delete or rebuild operations, no telemetry, and no external assets. See docs/ui.md and docs/adr/0001-browser-ui.md.

MCP Registrations (copy-paste)

All examples use stdio; adjust paths. Set ROO_INDEX_BRIDGE_CONFIG_PATH if you use a config file (recommended). Full installation methods (uv tool install, pipx, uvx), secrets handling, and additional clients (Codex, Claude Desktop, generic JSON) are documented in docs/installation.md.

ZCode / VS Code (mcp.json)

{
  "servers": {
    "roo-code-index-bridge": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run", "--directory",
        "D:\\Github\\roo-code-index-bridge-mcp",
        "roo-code-index-bridge-mcp"
      ],
      "env": {
        "ROO_INDEX_BRIDGE_CONFIG_PATH": "D:\\AI\\Config\\roo-code-index-bridge\\config.json"
      }
    }
  }
}

Claude Code / Codex / OpenCode

claude mcp add roo-code-index-bridge -- uv run --directory "D:\Github\roo-code-index-bridge-mcp" roo-code-index-bridge-mcp

[mcp_servers.roo-code-index-bridge]
command = "uv"
args = ["run", "--directory", "D:\\Github\\roo-code-index-bridge-mcp", "roo-code-index-bridge-mcp"]

The default (no subcommand) invocation starts the stdio server — identical to 0.1.0.

CLI

All commands print JSON. Exit code 0 = success.

Index Lifecycle

1. build — discovers files, chunks structurally, embeds in batches, writes a staging collection rci-<hash>-vN, then swaps the rci-<hash> alias atomically. A failed build deletes staging and leaves the previous index searchable. Without --force, a healthy index is updated incrementally instead of rebuilt.
2. sync — hashes files; only changed/added files are re-chunked and re-embedded; deleted files' points are removed. An unchanged sync performs zero embedding calls.
3. watch — debounced bursts coalesce into one sync. Watchers live only while the MCP process runs.
4. delete — requires the confirmation to equal the normalized workspace path and verifies owner/workspace_id payload metadata before removing anything.

Collections: alias rci-<hash16> (stable per workspace) over physical rci-<hash16>-v1, -v2, … See docs/configuration.md for the hash rules.

Rebuilding after embedding-model changes

The embedder fingerprint (provider|model|dimension) is stored per workspace. If it changes, code-index-sync returns status: "needs-rebuild" and the next code-index-build (or build --force) re-embeds everything through a fresh staging collection.

Watch-mode limitations

• Watchers are in-process: stopping the MCP server stops watching (state is kept; re-run code-index-sync after restart).
• Network shares and virtualized filesystems may not deliver reliable events; poll with code-index-sync instead.
• A watcher that fails three times stops in an error state rather than restarting forever.

Ignore-File Behavior

• Git repositories: git ls-files --cached --others --exclude-standard (respects .gitignore), plus a root .rooignore on top.
• Non-Git directories: safe walk honoring nested .gitignore and root .rooignore.
• Always excluded: node_modules, dist, build, .venv, __pycache__, lockfiles, binaries (NUL-byte sniff), files > 1 MB (configurable), and anything symlinked outside the workspace.

Security and Privacy

• Local-first: everything stays on your machine — Ollama, Qdrant, SQLite. No telemetry.
• Secrets are resolved by environment-variable name (qdrant_api_key_env, api_key_env) and are never printed; health/status output is passed through a redaction guard.
• Destructive operations are namespace-restricted (rci-* only) and ownership-verified from point payload metadata. ca_* and legacy ws-* collections are never created, updated, listed as owned, or deleted.
• Your code is sent only to the embedding provider you configure (Ollama = fully local).

Legacy Roo Compatibility

roo-code-index-search, roo-code-index-resolve-collection, and roo-code-index-health keep their 0.1.0 behavior. Search prefers a standalone rci-* index when present and otherwise resolves the Roo ws-* collection (multiple path-string hash candidates) with the Roo local-cache lexical fallback as a last resort. Every result reports index_family (standalone or legacy-roo).

Migration Notes from 0.1.0

• Entry point and default stdio invocation are unchanged; --transport still works.
• Configuration is additive — existing 0.1.0 config files work as-is. New settings have defaults (see docs/configuration.md).
• A SQLite state database is created automatically at %LOCALAPPDATA%\roo-code-index-bridge\state.sqlite3 (override state_db_path).
• New tools appear alongside the legacy ones; nothing was removed.
• The package version is 0.3.0; run uv sync after pulling.

Local Validation

uv sync
uv run ruff check .
uv run pytest -q
uv run roo-code-index-bridge-mcp --help

License

MIT — see LICENSE. Third-party grammars are consumed via tree-sitter-language-pack; no Roo Code extension code is included. Behavior-compatible protocol details were implemented from public documentation.