[MCP T12] Auto-init: ensure FalkorDB + auto-index CWD

[DvirDukhan]

Phase 1 ticket T12. Depends on #648 (T1 scaffold) and #652 (T4 index_repo).

Context

Zero-config startup is the difference between "this MCP server is annoying to install" and "this just works." Two automation behaviors make this real:

1. Ensure FalkorDB is running: when the MCP server boots, ping FalkorDB; if unreachable, start the existing Docker container automatically. The CLI already has cgraph ensure-db machinery — reuse it, don't duplicate.

2. Auto-index CWD on first tool call: when CODE_GRAPH_AUTO_INDEX=true is set (opt-in for safety), the first tool call indexes the current working directory automatically so the agent doesn't have to call index_repo first. Lazy and idempotent — second call is a no-op.

Both behaviors are gated and conservative: ensure-db is on-by-default but only takes action if FalkorDB is missing; auto-index requires explicit opt-in.

Scope

In:

• New api/mcp/auto_init.py containing:
  • ensure_falkordb() — pings FalkorDB; if unreachable, calls the existing cgraph ensure-db Docker bootstrap from api/cli.py. Reuses the function — does not duplicate the Docker logic.
  • maybe_auto_index(project, branch) — checks CODE_GRAPH_AUTO_INDEX env var; if set and the (project, branch) graph is empty, indexes CWD via Project.from_local_directory() + analyze_sources(). Tracks "already auto-indexed this session" in a module-level flag so subsequent tool calls skip.
• Modified api/mcp/server.py:
  • On startup: call ensure_falkordb() before any tool is registered.
  • First tool-call middleware: call maybe_auto_index() once per session per (project, branch).
• Tests in tests/mcp/test_auto_init.py:
  • ensure_falkordb test: mock subprocess.run to simulate FalkorDB unreachable → assert the Docker bootstrap is invoked.
  • ensure_falkordb test: simulate FalkorDB reachable → assert no Docker call is made.
  • auto-index test: env var set, empty graph → first tool call triggers index_repo; second tool call does not.
  • auto-index test: env var unset → first tool call does not trigger indexing.

Out:

• Auto-detection of MODEL_NAME or other config (env-only).
• Auto-cleanup / shutdown teardown.
• Re-indexing on file change (Phase 2 or Phase 3 watch mode).
• Container management beyond what cgraph ensure-db already does.

Files to create / modify

• new api/mcp/auto_init.py
• api/mcp/server.py — startup hook + first-tool-call middleware
• new tests/mcp/test_auto_init.py

Acceptance criteria

• Starting cgraph-mcp against an unreachable FalkorDB triggers the existing cgraph ensure-db Docker bootstrap and continues to start the server.
• Starting cgraph-mcp against a reachable FalkorDB does not invoke any Docker subprocess.
• With CODE_GRAPH_AUTO_INDEX=true and an empty graph, the first tool call (e.g. search_code) triggers index_repo(".") automatically before the tool's own logic runs.
• Subsequent tool calls in the same session do not re-trigger auto-indexing (idempotent flag).
• Without CODE_GRAPH_AUTO_INDEX=true, no auto-indexing occurs (default off).
• Auto-index respects T17 per-branch naming — auto-indexes CWD's branch.
• Unit tests cover all four scenarios with mocked subprocess + graph.
• CI workflow [MCP T2] CI workflow with FalkorDB service for MCP tests #649 green.

Dependencies

• Blocks: T14 (#TBD — packaging refers to auto-init in the README quickstart).
• Blocked by: [MCP T1] Scaffold api/mcp/ module + cgraph-mcp entry point #648 (T1), [MCP T4] index_repo MCP tool #652 (T4 — needs index_repo to call).

Out of scope (do NOT do in this PR)

• Watch-mode / re-indexing on filesystem change.
• Auto-pulling the FalkorDB Docker image if missing (the existing cgraph ensure-db already handles that).
• Cross-session state (tracking which projects were auto-indexed across server restarts).
• Telemetry.

Notes for the implementer

• Critical: the cgraph ensure-db logic already exists in api/cli.py. Find it and call it directly — do not reimplement Docker/subprocess code in api/mcp/.
• The "first tool call" middleware can be a FastMCP tool-call hook (check the SDK's hook API) or a small wrapper around each registered tool. Prefer the SDK hook if it exists.
• The auto-index flag should be a module-level set[tuple[str, str]] of (project, branch) tuples already auto-indexed this session — that way different projects in the same session each get one auto-index.
• Default CODE_GRAPH_AUTO_INDEX to off because indexing can take minutes on large repos and surprising the user with that on first call is bad UX. Document the env var clearly in T13's agent guidance.
• For unit tests, mock redis.Redis.ping to simulate reachable/unreachable.