MCP T13 — Agent guidance bundle (AGENTS.md, .cursorrules, cgraph init-agent)

[DvirDukhan]

Context

Once the MCP server exposes its 8 tools, AI coding agents (Claude Code, Cursor, Copilot, Roo/Cline) need guidance on when to call each tool. Without this, agents either ignore the tools or call the wrong one. This ticket ships the agent-facing documentation and a one-shot CLI to drop equivalent guidance into any user repo.

AGENTS.md is the canonical agent instructions file in this repo (CLAUDE.md is a symlink to it — edit AGENTS.md).

Scope (in)

Three deliverables in one PR:

1. Section in AGENTS.md documenting the 8 MCP tools and when an agent should call each:

   • index_repo — first call in a new repo
   • search_code — find a symbol by name/prefix
   • get_callers / get_callees — local call-graph traversal
   • get_dependencies — multi-relation traversal (imports, calls, defines)
   • impact_analysis — "what breaks if I change X" (transitive upstream)
   • find_path — call-chain between two known symbols
   • ask — natural-language question over the graph (last resort, more expensive)
     Each tool gets a one-line "call this when…" trigger and a tiny example.

2. .cursorrules template under api/mcp/templates/cursorrules.template with the equivalent guidance, formatted for Cursor's rules system.

3. cgraph init-agent Typer command in api/cli.py:

   • Copies claude_mcp_section.md and cursorrules.template into the user's CWD as CLAUDE.md (or appended to existing) and .cursorrules.
   • --force overwrites; without it, refuses to clobber existing files.
   • Reports what it wrote to stderr.

Scope (out)

• Copilot / Roo / Cline templates — Cursor and Claude cover the v1 audience; others can be added on request.
• Auto-detection of which agent is in use.
• Updating these templates from CI when new tools are added (manual sync for v1).

Files

• modified AGENTS.md
• new api/mcp/templates/cursorrules.template
• new api/mcp/templates/claude_mcp_section.md
• modified api/cli.py (new init-agent command)
• new tests/mcp/test_init_agent.py

Acceptance criteria

• cgraph init-agent writes CLAUDE.md and .cursorrules into CWD.
• Without --force, refuses to overwrite an existing file at either destination and exits non-zero.
• With --force, overwrites both.
• AGENTS.md section reviewed and merged; covers all 8 tools with trigger conditions.
• Unit test invokes the Typer command via CliRunner against a temp directory; asserts file contents match the templates byte-for-byte.
• Overwrite-refusal test asserts non-zero exit and unchanged existing file.
• make lint clean.

Dependencies

• [MCP T1] Scaffold api/mcp/ module + cgraph-mcp entry point #648 (T1 — scaffold) — needs api/mcp/ to exist for the templates directory.

Notes for the implementer

• Templates live in api/mcp/templates/ so they're packaged with the wheel — verify they ship via pyproject.toml package data if needed.
• Keep the template content concise. Agents truncate long instructions; one tight paragraph per tool beats a wall of text.
• The init-agent command should be discoverable from cgraph --help.