feat(mcp): auto-init — ensure FalkorDB + opt-in auto-index (T12)

[DvirDukhan]

Implements T12 (#660) — zero-config startup. Fresh users don't need to run cgraph ensure-db and index_repo manually before the agent can use the server.

Stacked on:

• feat(mcp): GraphRAG ask tool — init + prompt seam + tool (T9/T10/T11) #681 (T9/T10/T11 — GraphRAG ask)
• feat(mcp): impact_analysis tool — variable-depth Cypher (T6) #680 (T6 — impact_analysis)
• feat(mcp): query tools — get_callers/callees/deps, find_path, search_code (T5/T7/T8) #679 (T5/T7/T8 — query tools)
• feat(mcp): index_repo tool (T4 #652) #678 (T4 — index_repo)
• test(mcp): sample-project fixture + assertion contract (T3 #650) #677 (T3 — fixture + contract)
• ci(mcp): MCP-tests workflow (T2 #649) #676 (T2 — MCP CI)
• feat(graph): per-branch graph identity (T17 #651) #675 (T17 — per-branch graphs)
• feat(mcp): scaffold api/mcp module (T1 #648) #666 (T1 — MCP scaffold)

What ships

api/mcp/auto_init.py:

• ensure_falkordb() — pings FalkorDB on $FALKORDB_HOST:$FALKORDB_PORT; if unreachable on a localhost host, shells out to cgraph ensure-db (reuses the existing CLI Docker bootstrap; subprocess rather than in-process so the CLI's stdout JSON doesn't corrupt the MCP stdio transport). Never raises — server start continues even if bootstrap fails.
• maybe_auto_index(...) — gated by CODE_GRAPH_AUTO_INDEX=true|1|yes|on (off by default). Detects branch via git rev-parse, falls back to _default. Idempotent per-(project, branch).

api/mcp/server.py:

• main() runs both before app.run(). Module-level import is still I/O-free.

Tests

tests/mcp/test_auto_init.py — 9 tests, all mocked (no Docker, no real FalkorDB writes), <2s:

• ensure_falkordb: no-op when reachable / runs cgraph when not / refuses non-localhost / handles missing CLI binary.
• maybe_auto_index: skipped when env unset / indexes when opt-in / idempotent / per-branch / _truthy semantics.

Full MCP suite: 57 passed in 24.6s.

Out of scope (per ticket)

• Watch mode / re-indexing on FS change.
• Auto-pulling Docker image (already handled by cgraph ensure-db).
• Cross-session state.

Closes #660.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 862f5fe9-4424-49f5-b4ba-043832e2a5c2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dvirdukhan/mcp-t12-auto-init

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}