Metadata-Version: 2.5
Name: roo-code-index-bridge-mcp
Version: 0.2.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: fastmcp>=2.3.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pathspec>=0.12.1
Requires-Dist: pydantic>=2.10.0
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.2.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](docs/architecture.md) · Tools: [docs/mcp-tools.md](docs/mcp-tools.md) ·
Configuration: [docs/configuration.md](docs/configuration.md) · Problems: [docs/troubleshooting.md](docs/troubleshooting.md)

## Requirements

- Python 3.11+ and [uv](https://docs.astral.sh/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)

```powershell
# 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"
```

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

**ZCode / VS Code (`mcp.json`)**
```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**
```bash
claude mcp add roo-code-index-bridge -- uv run --directory "D:\Github\roo-code-index-bridge-mcp" roo-code-index-bridge-mcp
```
```toml
[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

| Command | Purpose |
|---|---|
| `roo-code-index-bridge-mcp serve` | Run the MCP server (default; `--transport stdio\|sse\|streamable-http`) |
| `... 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 |
| `... status <workspace>` | Collection, counts, watcher, jobs, last error |
| `... delete <workspace> --confirm <workspace>` | Ownership-checked deletion |
| `... doctor` | Probe Qdrant, embedder, SQLite, parsers |

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](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](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.2.0; run `uv sync` after pulling.

## Local Validation

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

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