MCP T14 — Packaging: Dockerfile, docker-compose, README quickstart

[DvirDukhan]

Context

Once cgraph-mcp is wired up, end users need a frictionless way to run it: a Docker image they can pull, a docker compose up that brings up FalkorDB + the MCP server together, and a README section they can copy-paste to register the server in Claude Code or Cursor.

The existing Dockerfile builds the FastAPI web service. We extend it (env-var switch or new stage) so the same image can run as the MCP stdio server when invoked differently.

Scope (in)

1. Dockerfile changes — support running cgraph-mcp as the entrypoint via env-var switch or a dedicated stage. The default behavior (FastAPI server) must not regress.
2. docker-compose.yml — add an mcp service alongside the existing falkordb service. Wire the MCP service to the FalkorDB service via internal networking and the documented env vars.
3. README quickstart — new section showing:
   • The claude mcp add-json '{...}' snippet (from design doc §Configuration)
   • A worked example: clone the repo, docker compose up, register MCP, ask Claude Code a question
   • A note on the stdio transport (Phase 1) and that HTTP/SSE is deferred.

Scope (out)

• Publishing a separate falkordb/code-graph-mcp image — for v1, the existing image just gains a new mode.
• Helm chart / k8s manifests.
• HTTP/SSE transport (deferred to Phase 1.5).

Files

• modified Dockerfile
• modified docker-compose.yml
• modified README.md

Acceptance criteria

• docker compose up brings up FalkorDB + MCP server; an MCP client can connect over stdio (verified via the smoke test pattern from T1).
• README copy-paste flow successfully registers code-graph MCP in Claude Code on a fresh checkout.
• make build-prod still passes.
• Existing release-image.yml CI Docker build job still green.
• Default Docker entrypoint behavior (FastAPI web server) is unchanged.
• README section calls out stdio-only Phase 1 limitation.

Dependencies

• [MCP T1] Scaffold api/mcp/ module + cgraph-mcp entry point #648 (T1 — scaffold)
• [MCP T12] Auto-init: ensure FalkorDB + auto-index CWD #660 (T12 — auto-init) — Docker entrypoint relies on the auto-init behavior to bootstrap on first run.

Notes for the implementer

• The cleanest separation is probably an env var like CGRAPH_MODE=mcp|web consumed by an entrypoint shim, rather than two separate stages — the image stays single, smaller to ship, and easier to test.
• For the README, prefer a one-screen quickstart over an exhaustive reference. Link to MCP_SERVER_DESIGN.md for the full story.