MCP-T13 + T14: cgraph init-agent + Docker dual-mode

[DvirDukhan]

Prerequisites (merge order)

Merge in order — this PR is stacked on:

1. feat(mcp): index_repo tool (T4 #652) #678 — index_repo (T4)
2. feat(mcp): query tools — get_callers/callees/deps, find_path, search_code (T5/T7/T8) #679 — query tools (T5/T7/T8)
3. feat(mcp): impact_analysis tool — variable-depth Cypher (T6) #680 — impact_analysis (T6)
4. feat(mcp): GraphRAG ask tool — init + prompt seam + tool (T9/T10/T11) #681 — GraphRAG ask (T9/T10/T11)
5. feat(mcp): auto-init — ensure FalkorDB + opt-in auto-index (T12) #682 — auto-init (T12)

Base: #682.

---

MCP-T13 + T14 — agent guidance bundle & Docker dual-mode

Stacked on #682 (T12 auto-init). Closes #661 and #662.

T13 — cgraph init-agent

Two canonical guidance files now ship as package data under
api/mcp/templates/:

• claude_mcp_section.md — full 8-tool table + rules of thumb
  (start with search_code; prefer structural tools over ask;
  run impact_analysis before refactoring).
• cursorrules.template — Cursor-flavoured tool-selection rules.

New Typer command drops them into the current directory:

cgraph init-agent          # refuses to overwrite
cgraph init-agent --force  # clobber

AGENTS.md updated with the MCP section pointing at this command and
the supported env vars (CODE_GRAPH_AUTO_INDEX, CGRAPH_MODE).

T14 — Dockerised dual-mode

Same image now runs either the FastAPI web app or the MCP stdio
server based on CGRAPH_MODE:

# web (default, unchanged behaviour)
docker compose up code-graph

# mcp stdio
docker compose --profile mcp run --rm -i code-graph-mcp

start.sh dispatches on CGRAPH_MODE=web|mcp. docker-compose.yml
gains an opt-in code-graph-mcp service guarded by the mcp
profile (no impact on the default up). README quickstart covers
both claude mcp add-json and the Docker path.

Tests

• 4 new CliRunner tests in tests/mcp/test_init_agent.py (write,
  refuse-overwrite, force-overwrite, package-data sanity).
• Full MCP suite green: 61 passed in 23.3s locally.
• bash -n start.sh clean.

Followups

• T18 (incremental indexing, MCP T18 — Incremental indexing (file-hash based) #665) is the only Phase-1 ticket left;
  non-trivial and out of scope for this PR.

Summary by CodeRabbit

• New Features

  • Added MCP server with support for code indexing, searching symbols, analyzing impacts, and finding call paths
  • New cgraph init-agent CLI command to generate agent guidance files
  • Docker Compose profile for MCP server deployment

• Documentation

  • Added MCP server documentation with quickstart guides, tool descriptions, and configuration details

• Tests

  • Added test suite for the init-agent command and MCP server functionality

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces MCP (Model Context Protocol) agent guidance by bundling structured templates, a bootstrapping CLI command (cgraph init-agent), comprehensive test coverage, documentation, container configuration for MCP mode, and an integration smoke test. The changes enable AI coding agents to efficiently use the code-graph knowledge graph.

Changes

MCP Agent Guidance Bundle

Layer / File(s)	Summary
Agent guidance templates api/mcp/templates/claude_mcp_section.md, api/mcp/templates/cursorrules.template	Two Markdown templates guide AI agents on when and how to call each MCP tool (index_repo, search_code, find_symbol, get_neighbors, impact_analysis, find_path), with tool-selection rules and environment variable documentation.
CLI init-agent command and template packaging api/cli.py, pyproject.toml	The init-agent Typer command writes guidance templates to user CWD as CLAUDE.md and .cursorrules, refuses to overwrite without --force, and outputs JSON status. Templates are packaged via pyproject.toml setuptools configuration.
CLI init-agent command tests tests/mcp/test_init_agent.py	Four test cases validate file creation, overwrite refusal, force-overwrite behavior, and template packaging; shared CliRunner fixture and temporary directory helpers ensure isolated test execution.
User-facing documentation for MCP AGENTS.md, README.md	AGENTS.md documents the MCP toolset and cgraph init-agent command; README.md adds MCP server overview, quickstarts for Claude Code and Docker Compose, FalkorDB auto-bootstrap notes, and Docker examples for web and MCP modes.
Container and startup configuration for MCP mode start.sh, docker-compose.yml	start.sh introduces CGRAPH_MODE variable (defaults to web) that dispatches between cgraph-mcp and uvicorn startup paths; docker-compose.yml adds an opt-in code-graph-mcp service behind the mcp profile with FalkorDB dependency and stdio configuration.
MCP server integration smoke test scripts/mcp_smoke.py	Async end-to-end smoke test that initializes an MCP client over stdio, validates tool availability, indexes api/ via index_repo, and exercises search_code, find_symbol, get_neighbors, and impact_analysis with flexible response-shape handling and failure tracking.

---

🎯 3 (Moderate) | ⏱️ ~25 minutes

---

Suggested reviewers

• gkorland
• galshubeli

---

🐰 Templates flow to agents true,
init-agent shows them what to do,
MCP guides with rules so tight,
Smoke tests prove the code runs right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'MCP-T13 + T14: cgraph init-agent + Docker dual-mode' clearly references the two main feature additions (T13 init-agent command and T14 Docker dual-mode support) and is specific enough to convey the scope.
Linked Issues check	✅ Passed	All objectives from issue #661 are fully addressed: AGENTS.md documented with MCP tools, two template files created (claude_mcp_section.md and cursorrules.template), cgraph init-agent command with --force flag implemented, test suite added, and package data configured.
Out of Scope Changes check	✅ Passed	All changes are aligned with PR objectives. T13 additions (templates, init-agent CLI, documentation) and T14 additions (Docker dual-mode via CGRAPH_MODE) are within scope; smoke test and fixes are supporting implementation details.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dvirdukhan/mcp-t13-t14-packaging

---

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

[Copilot]

Pull request overview

Adds end-user/agent onboarding for the MCP server and enables running the same Docker image in either web or MCP-stdio mode, improving agent usability and deployment ergonomics.

Changes:

• Introduces cgraph init-agent to write bundled agent guidance templates (CLAUDE.md, .cursorrules) into the current directory.
• Adds Docker “dual-mode” startup via CGRAPH_MODE=web|mcp with a compose code-graph-mcp profile/service for MCP stdio.
• Updates docs and adds tests + a smoke script for MCP setup/verification.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
api/cli.py	Adds init-agent CLI command to copy bundled guidance templates into CWD.
api/mcp/templates/claude_mcp_section.md	Provides canonical MCP tool guidance for Claude-style agent instructions.
api/mcp/templates/cursorrules.template	Provides Cursor rules template for tool selection/usage.
tests/mcp/test_init_agent.py	Adds CliRunner tests covering write/refuse-overwrite/force-overwrite and package-data presence.
pyproject.toml	Ensures MCP templates ship as package data (api.mcp/templates/*).
start.sh	Dispatches container startup between web and MCP stdio mode using CGRAPH_MODE.
docker-compose.yml	Adds an opt-in code-graph-mcp service under the mcp profile for stdio MCP.
README.md	Documents MCP server usage and Docker dual-mode quickstarts.
scripts/mcp_smoke.py	Adds an end-to-end stdio smoke test for tool availability and basic flows.
AGENTS.md	Adds agent-focused MCP section and points to cgraph init-agent.

Comments suppressed due to low confidence (1)

start.sh:12

• In CGRAPH_MODE=mcp, anything written to stdout before cgraph-mcp starts can corrupt the MCP stdio transport. The local redis-server ... | cat & pipeline currently writes its logs to stdout, which can break MCP when FALKORDB_HOST is localhost/127.0.0.x.

# Start FalkorDB Redis server in background only if using a local address (not an external instance)
if [ "${FALKORDB_HOST}" = "localhost" ] || [[ "${FALKORDB_HOST}" =~ ^127\.0\.0\.[0-9]+$ ]]; then
    redis-server --loadmodule /var/lib/falkordb/bin/falkordb.so | cat &
fi

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The base branch was changed.