Metadata-Version: 2.5
Name: roo-code-index-bridge-mcp
Version: 0.6.0
Summary: Client-neutral semantic code indexing and search MCP: standalone indexes plus read-only Roo Code compatibility.
Project-URL: Homepage, https://github.com/prakashgarg91/roo-code-index-bridge-mcp
Project-URL: Repository, https://github.com/prakashgarg91/roo-code-index-bridge-mcp
Project-URL: Issues, https://github.com/prakashgarg91/roo-code-index-bridge-mcp/issues
Project-URL: Changelog, https://github.com/prakashgarg91/roo-code-index-bridge-mcp/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/prakashgarg91/roo-code-index-bridge-mcp/tree/main/docs
Author: Prakash Gupta
License-Expression: MIT
License-File: LICENSE
Keywords: code-search,embeddings,indexing,mcp,model-context-protocol,ollama,qdrant,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: anyio>=4.14.2
Requires-Dist: cryptography>=50.0.0
Requires-Dist: fastmcp>=4.0.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: idna>=3.15
Requires-Dist: joserfc>=1.6.8
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: python-multipart>=0.0.31
Requires-Dist: starlette>=1.3.1
Requires-Dist: tree-sitter-language-pack>=0.7.0
Requires-Dist: watchfiles>=1.0.5
Description-Content-Type: text/markdown

# 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](docs/installation.md#chatgpt-desktop-via-a-local-codex-host).
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](docs/architecture.md) · Tools: [docs/mcp-tools.md](docs/mcp-tools.md) ·
Installation & setup: [docs/installation.md](docs/installation.md) ·
Configuration: [docs/configuration.md](docs/configuration.md) · Problems: [docs/troubleshooting.md](docs/troubleshooting.md)

## Requirements

- The launcher installs [uv](https://docs.astral.sh/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](https://docs.docker.com/get-started/get-docker/), then rerun the launcher.

No Roo Code extension, no cloud services, no accounts. Remote providers are supported
(see [Privacy](#security-and-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](docs/installation.md#one-click-from-a-repository-download).

### 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](src/roo_code_index_bridge_mcp/skills/roo-code-search/SKILL.md)
with your version, embedding provider and freshness policy, then installs it for
the current user. See [skill locations and verification](docs/automatic-skill.md).

Previous release verification: [v0.5.0 completion and recheck (2026-09-29)](docs/completion-20260929.md).
See [v0.5.1 fixes](CHANGELOG.md#051---2026-09-30).

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

```bash
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](docs/installation.md#cold-cache-behavior-the-release-order-gate)).

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

```bash
# 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](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:

```toml
# ~/.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](docs/installation.md#rollback-manifests-and-uninstall).

## Indexing from the CLI

```bash
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

```bash
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](docs/ui.md) and
[docs/adr/0001-browser-ui.md](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:

| Client | File (current user's profile) | Container |
|---|---|---|
| Codex | `~/.codex/config.toml` | `[mcp_servers.roo_code_index_bridge]` |
| Claude Code | `~/.claude.json` (or `CLAUDE_CONFIG_DIR/.claude.json`) | `mcpServers` root entry (+ existing `projects.*.mcpServers` entries) |
| ZCode | `~/.zcode/cli/setting.json` (existing legacy `config.json` also maintained) | `mcp.servers` |
| VS Code | platform path, see [installation.md](docs/installation.md#locations-by-platform) | `servers` |
| OpenCode | `~/.config/opencode/opencode.json` (XDG) | Stable v1 `mcp`; existing v2 `mcp.servers` preserved |

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](docs/installation.md#manual-registration-reference).

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

## CLI

| Command | Purpose |
|---|---|
| `roo-code-index-bridge-mcp serve` | Run the MCP server (default; `--transport stdio\|sse\|streamable-http`) |
| `... setup` | Register clients, install agent skills, self-heal (see [docs/installation.md](docs/installation.md)) |
| `... doctor` | Probe Qdrant, embedder, SQLite, parsers (+ `--registrations`, `--fix`) |
| `... index <workspace> [--force] [--watch]` | Build or rebuild the standalone index |
| `... sync <workspace>` | Incremental sync of changed/added/deleted files |
| `... search <workspace> [query] [--prefix P] [--limit N] [--min-score S] [--language L] [--glob G]` | Semantic search (omit workspace = federated) |
| `... status <workspace>` | Collection, counts, watcher, jobs, last error |
| `... delete <workspace> --confirm <workspace>` | Ownership-checked deletion |
| `... enrich <workspace>` | Backfill import/similarity edges and communities |
| `... ui [--open] [--host H] [--port P]` | Local browser UI |

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](docs/installation.md#privacy-and-autonomous-search)).
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](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](docs/installation.md#privacy-and-autonomous-search).
- 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](docs/installation.md#recovering-from-an-accidentally-applied-unpublished-pin).

## Development (source checkout)

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

```powershell
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](docs/installation.md#development-mode-local-wheels)
and [RELEASING.md](RELEASING.md).

## License

MIT — see [LICENSE](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.
