[OCI] Ship LOCAL_MODE / codeintel-local: standalone zero-cloud MCP package

[DevanshuNEU]

Why this exists

OCI requires 5 hard-mandatory external services to start (Supabase x3, OpenAI, Pinecone — see `backend/config/startup_checks.py:13-19`). The MCP server (`mcp-server/api_client.py:18-25`) is a thin HTTP proxy to that backend; without the backend, every MCP tool call fails. The maker (F1/OPT student, locked-axis constraint from strategy v0.2 "What we cannot fight on") cannot sustainably keep the prod stack running. Per F-011, prod has been degraded since 2026-05-11 because Railway's healthcheck failed silently — and the maker discovered it via an ad-hoc curl test, not an alert.

Move 4 (`oci orient `, the wedge made shippable, target ship 2026-06-19) is structurally blocked: there is no path for an agent or human to run OCI against one repo for 5 minutes without committing to 4 cloud accounts. Locked belief #2 ("$0 install is the discovery vector") fails when the actual cost is $50/month and 30-60 minutes of account creation.

Source: static audit 2026-05-13. Logged as dogfood finding F-014. Full ADR: `oci/decisions/2026-05-13-local-mode-v0.1.md`.

What ships

• New Python package `codeintel-local` (separate `pyproject.toml`, separate FastMCP entrypoint) that does NOT use the FastAPI backend
• Self-contained backends: ChromaDB (vector store, file-backed at `~/.codeintel/local/`), SQLite (metadata), `sentence-transformers/all-MiniLM-L6-v2` (embeddings, ~80MB local model)
• CLI: `codeintel-local index `, `codeintel-local search `, `codeintel-local mcp` (stdio server)
• MCP tool surface parity with cloud: `search_code`, `get_codebase_dna`, `analyze_impact`, `get_dependencies`
• Shared contracts package `mcp-server/contracts/` imported by both cloud and local MCP servers; CI test asserts JSON-schema equivalence
• PyPI publish workflow + `pipx install codeintel-local` install path
• Documentation: `docs/local-mode.md` covering install, first-run, limitations vs cloud tier

Acceptance criteria

• `pipx install codeintel-local` from PyPI works on macOS, Linux, and Windows (CI matrix)
• `codeintel-local index /path/to/repo` indexes a 100-file Python repo in under 30s with no network access (airgapped CI job)
• `codeintel-local mcp` responds to MCP `list_tools` with the same 4 tools as cloud MCP server
• Claude Code (configured via stdio in `.mcp.json`) completes one round of search with zero outbound HTTP (verified via packet capture)
• Tool-response JSON schema is byte-equivalent to cloud MCP output on a fixed test repo (CI diff)
• No regression in cloud-mode bring-up: `make up` and prod `api.opencodeintel.com` continue to pass health checks
• Backend tests pass: `cd backend && pytest tests/ -v`
• MCP tests pass: `cd mcp-server && pytest tests/ -v`

Wave

pre-thesis (Move 4 enabler; ships well before 2026-06-22 validation gate)

Type

feat

Stack scope

• backend (contracts package extraction)
• mcp-server (new local variant)
• cross-cutting (PyPI publish workflow, ADR, docs)

Priority

high

ADR required

yes - `oci/decisions/2026-05-13-local-mode-v0.1.md` (already drafted, status: Proposed)

Dogfooding signal

yes - audit finding F-014 from 2026-05-13. Also enables the dogfood loop to work without student-budget pain: dogfood-pipeline currently requires the same Pinecone + Supabase provisioning that strangers would. LOCAL_MODE recursive-validates strategy locked belief #4 (dogfooding is non-negotiable).

Related

• Wave: pre-thesis, Move 4 (`oci orient` operationalized)
• Prior ADRs: `oci/decisions/2026-05-13-local-mode-v0.1.md`, `oci/decisions/2026-05-13-dogfood-pipeline-v0.1.md`
• Linked: [OCI] Submit OCI to all major MCP registries (Smithery, mcp.so, PulseMCP, Manufact, official) #304 (registry submission, blocked by this)
• External: Chroma docs, sentence-transformers, FastMCP, DDIA Ch 1 (Reliability + Operability framing)
• Blocks: registry submission ([OCI] Submit OCI to all major MCP registries (Smithery, mcp.so, PulseMCP, Manufact, official) #304), `oci orient` Move 4 ship

---

Filed from OCI audit 2026-05-13. Full context: `oci/dogfood-findings.md` F-014 + ADR `2026-05-13-local-mode-v0.1.md`.