First ticket of the MCP server Phase 1 execution plan (see docs/MCP_SERVER_DESIGN.md, added by this ticket).

Context

We are building an MCP server inside the code-graph repo so AI coding agents (Claude Code, Cursor, Copilot, Roo/Cline) can query the indexed codebase as a graph. This is the foundation ticket: scaffold the module, register the CLI entry point, add the mcp SDK dependency, and ship a smoke test that proves the server starts.

The full Phase 1 plan decomposes into 18 vertical tickets (T1–T18). T1 is the prerequisite for everything else.

Module location decision: under api/mcp/, NOT top-level mcp/. A top-level directory called mcp/ would shadow the installed mcp PyPI SDK and break from mcp.server.fastmcp import FastMCP everywhere. Entry point will be cgraph-mcp = "api.mcp.server:app".

Scope

In:

• Create api/mcp/__init__.py and api/mcp/server.py with a FastMCP instance and stdio runner.
• Add cgraph-mcp = "api.mcp.server:app" to pyproject.toml [project.scripts].
• Add mcp>=1.0,<2.0 to [project] dependencies.
• Copy the local design doc into the repo: docs/MCP_SERVER_DESIGN.md and docs/code-graph-mcp-v4.docx.
• Ship tests/mcp/__init__.py and tests/mcp/test_scaffold.py — an in-process protocol smoke test that spawns the server, lists tools (expects 0 in this ticket), and exits cleanly. The helper used here will be reused by every subsequent tool ticket's protocol round-trip test.

Out:

• Tools (T4–T8, T11)
• CI workflow (T2)
• HTTP/SSE transport (deferred to Phase 1.5)
• Auto-init (T12)

Files to create / modify

• new api/mcp/__init__.py
• new api/mcp/server.py — from mcp.server.fastmcp import FastMCP; app = FastMCP("code-graph"); def main(): app.run()
• pyproject.toml — add entry point and mcp>=1.0,<2.0 dependency
• new docs/MCP_SERVER_DESIGN.md
• new docs/code-graph-mcp-v4.docx
• new tests/mcp/__init__.py
• new tests/mcp/test_scaffold.py

Acceptance criteria

• uv pip install -e . succeeds.
• cgraph-mcp command is on PATH after install.
• Running cgraph-mcp starts a stdio MCP server that exposes 0 tools and responds correctly to initialize and tools/list.
• uv run pytest tests/mcp/test_scaffold.py passes locally — the smoke test spawns the server, calls session.list_tools(), asserts the result is empty, and exits cleanly.
• make lint is clean.
• docs/MCP_SERVER_DESIGN.md exists in the repo.

Dependencies

None. This is the first ticket of Phase 1.

Out of scope (do NOT do in this PR)

• Any tool registration
• Any CI changes (T2)
• HTTP/SSE transport (Phase 1.5)
• GraphRAG / ask plumbing (T9–T11)
• Auto-init (T12)

Notes for the implementer

• The smoke test should use the mcp SDK's own client (from mcp.client.stdio import stdio_client, StdioServerParameters; from mcp import ClientSession). Keep the helper small and re-usable — subsequent tool tickets will copy it.
• Pin mcp>=1.0,<2.0 to avoid 0.x churn and 2.x breakage.
• Verify the new dep doesn't bloat the install — mcp is pure Python with minimal transitive deps.