Roo Code Index Bridge MCP

A client-neutral, local-first semantic code indexing and search MCP. Version 0.6.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 any MCP-compatible client. One-click setup targets: Codex, Claude Code, ZCode, VS Code, VS Code (workspace), and OpenCode. ChatGPT desktop can use the bridge through a local Codex host that shares Codex's MCP configuration — see docs/installation.md. ChatGPT web / remote MCP endpoints are not local-stdio targets and are out of scope.

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 (platform data dir, see docs/configuration.md)
        └─ WatchManager   → debounced watchfiles → one incremental sync

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

Requirements

• The launcher installs uv and managed Python 3.11+ as needed.
• Healthy configured Ollama and Qdrant services are reused.
• To provision missing default local services, install and start Docker Desktop, then rerun the launcher.

No Roo Code extension, no cloud services, no accounts. Remote providers are supported (see Privacy) but everything defaults to loopback.

Quick Start

Download and run setup

After downloading and extracting this repository, double-click SETUP.cmd on Windows. On macOS/Linux run sh setup.sh from the extracted folder. The launcher installs uv for the current user if needed, obtains Python through uv, and persistently installs the published bridge CLI. Its first-run command reuses healthy configured services, provisions missing default local backends through Docker, obtains the configured Ollama model when missing, and verifies a real embedding request. It configures detected Codex, Claude Code, ZCode, OpenCode and VS Code installations, installs supported agent skills, backs up changes, and reports verification and restart instructions.

Preview without changing client files: SETUP.cmd --dry-run or sh setup.sh --dry-run. Dry runs install nothing and do not download packages or models. Missing client apps receive installation links. Missing Docker returns NEEDS_ACTION with prerequisite instructions; rerunning the same command resumes setup. Pass --config "/absolute/path/config.json" to preserve a particular configuration, or --no-provision to require already running backends. Semantic indexing/search requires healthy Qdrant and an embedding backend. ChatGPT desktop support is through its local Codex agent, not ordinary hosted ChatGPT chats. See the complete one-click guide.

Automatically installed agent skills

Setup includes roo-code-search, roo-code-setup, and roo-code-troubleshoot for semantic orientation, installation, and recovery. There is no separate skill installation step. Setup renders the packaged skill with your version, embedding provider and freshness policy, then installs it for the current user. See skill locations and verification.

Previous release verification: v0.5.0 completion and recheck (2026-09-29). See v0.5.1 fixes.

Terminal setup

The recommended setup uses the published package — never a source checkout, never repo-coupled --directory invocations. The canonical command is the version-pinned published package — exactly what setup writes into client registrations:

uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp

A pin is only usable when that version is actually published — setup refuses to write any registration pinned to a version that fails the cold-cache publication proof (see docs/installation.md).

(If your uv build rejects --system-certs, drop that flag; setup detects this and adapts.)

# 0. Pull a model and start Qdrant (defaults assume loopback)
ollama pull nomic-embed-text-v2-moe:latest
docker run -p 6333:6333 qdrant/qdrant

# 1. Run the published package (no install step required)
uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp --help

# 2. Check the stack (Qdrant, embedder, SQLite, parsers, registrations)
uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp doctor

# 3. Preview what setup would change — writes NOTHING
uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp setup --dry-run

# 4. Configure every detected client + install agent skills + verify (add --json for machine output)
uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp setup --all

# 5. RESTART your MCP clients — they only re-read registrations at startup

# 6. Live verification after restart
uv --system-certs tool run --from roo-code-index-bridge-mcp==0.6.0 roo-code-index-bridge-mcp doctor --registrations

setup refuses to write anything unless the pinned version can be installed from a genuinely cold cache, so step 4 fails safely (exit 1, target-version-unavailable, zero writes) if the version is not actually published. Exit 0 with verification: ok means every required target was verified. Full details: docs/installation.md.

Tip: uv tool install roo-code-index-bridge-mcp puts roo-code-index-bridge-mcp on PATH, shortening every command above. The uv tool run --from ...==<version> form is what setup writes into client registrations, so both are shown.

What setup writes (and how to undo it)

Per client (Codex, Claude Code, ZCode, VS Code, OpenCode), setup writes a pinned registration that resolves from the package index — no repo paths, no --offline, no venv coupling:

# ~/.codex/config.toml (Codex)
[mcp_servers.roo_code_index_bridge]
command = "uv"
args = ["--system-certs", "tool", "run", "--from", "roo-code-index-bridge-mcp==0.6.0", "roo-code-index-bridge-mcp"]
startup_timeout_sec = 60.0

The pin is the version of the package that is running setup (0.6.0 above); it is written only after that version passes the cold-cache publication proof, so a setup-written registration never points at an unpublished version.

Every write is backed up, recorded in a setup manifest (SHA-256 before/after), validated before an atomic replace, and rolled back hash-guarded if a later write fails. setup --remove restores pre-setup bytes from the manifest. Rollback, manifest, and uninstall semantics: docs/installation.md.

Indexing from the CLI

uv --system-certs tool run roo-code-index-bridge-mcp index D:/some/repo
uv --system-certs tool run roo-code-index-bridge-mcp search D:/some/repo "configuration loading and secret resolution"

Browser UI

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 (what setup configures)

Running setup (above) is the recommended way to register clients — it detects, repairs, backs up, and verifies. The entries it writes, per client:

All of them run the same canonical command: uv --system-certs tool run --from roo-code-index-bridge-mcp==<version> roo-code-index-bridge-mcp, plus a single ROO_INDEX_BRIDGE_CONFIG_PATH env entry when a bridge config file actually exists (a dead config path is never registered; with no config the server uses built-in loopback defaults).

Prefer manual editing? Point the client at the canonical command exactly as written above — pinned, from the package index. Full copy-paste blocks per client and per platform are in docs/installation.md.

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

CLI

All commands print JSON. Exit code 0 = success (doctor/setup also exit nonzero on drift or refusals — that is the verification working, not a crash).

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 / auto-sync — debounced bursts coalesce into one sync. Watchers live only while the MCP process runs. Additionally, a search against an index older than auto_sync_stale_after_seconds triggers one lock-safe sync first (scope-aware default and privacy rules: docs/installation.md).
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 by default: 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.
• Autonomous sync is scope-aware. With a loopback (local) embedder the default policy auto-syncs stale indexes at 900 s. With a remote/cloud embedder (OpenAI, Gemini, Mistral, OpenRouter, Vercel, Bedrock, or any non-loopback base URL) autonomous sync stays disabled until you explicitly set auto_sync_stale_after_seconds — because a sync sends source code chunks to that provider. Setup prints this classification and the egress answer for your configuration on every run (source code may leave this machine: YES/NO), never rewrites your config to enable syncing, and renders the installed roo-code-search skill with the matching consent policy. See docs/installation.md.
• Your code is sent only to the embedding provider you configure (Ollama = fully local) and stored only in the Qdrant you configure (remote Qdrant also counts as egress).

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).

Upgrading from 0.4.0

• Registrations that still point at a repo checkout (repo-coupled --directory commands) or carry --offline / --project / UV_PROJECT_ENVIRONMENT are reported as legacy-command drift by doctor and structurally repaired by setup to the pinned published command.
• Existing indexes, collections, and config files are untouched; configuration remains additive.
• The new scope-aware auto-sync default applies only when your config does not set the key: local embedder → on at 900 s, remote embedder → off until you opt in. Explicit values, including 0, are always preserved.
• Accidentally pinned clients to an unpublished 0.5.1? See docs/installation.md.

Development (source checkout)

Everything above uses the published package. To hack on the bridge itself:

git clone https://github.com/prakashgarg91/roo-code-index-bridge-mcp.git
cd roo-code-index-bridge-mcp
uv sync
uv run roo-code-index-bridge-mcp --help      # run from the checkout (development only)
uv run ruff check . && uv run pytest -q      # lint + tests

Source-checkout registrations (uv run --directory <checkout> roo-code-index-bridge-mcp) are development-only — they couple clients to a directory on your disk. To test unreleased code in real clients, build a wheel and use the development-only setup mode: uv run roo-code-index-bridge-mcp setup --from-wheel <absolute-wheel-path> (registrations are labelled temporary-by-path). See docs/installation.md and RELEASING.md.

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.