feat(mcp): scaffold api/mcp module with FastMCP server and cgraph-mcp entry point

Add the bare MCP server module (api/mcp/) using the official FastMCP SDK,
wire the cgraph-mcp console script in pyproject.toml, and include a protocol
smoke test that spawns the server over stdio and verifies list_tools returns
an empty tool set. Also copies the MCP design docs into docs/.

Closes #648

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DvirDukhan

api/mcp/__init__.py

@@ -0,0 +1,8 @@
+"""MCP server module for code-graph.
+
+Exposes the code-graph indexer and graph queries as MCP tools so AI coding
+agents (Claude Code, Cursor, Copilot, Roo/Cline) can drive the indexer over
+the standard Model Context Protocol stdio transport.
+
+Entry point: ``cgraph-mcp`` (defined in ``pyproject.toml``).
+"""

api/mcp/server.py

@@ -0,0 +1,26 @@
+"""FastMCP server for code-graph.
+
+This is the scaffold (T1). It instantiates a single FastMCP app, exposes it
+as ``app`` for tests and embedders, and registers a ``main()`` entry point
+that runs the server over stdio. Tools are registered in later tickets
+(T4-T8, T11) by importing this module's ``app`` and decorating functions
+with ``@app.tool(...)``.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+app: FastMCP = FastMCP("code-graph")
+
+
+def main() -> None:
+    """Run the MCP server over stdio.
+
+    Console-script entry point for ``cgraph-mcp``.
+    """
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

docs/MCP_SERVER_DESIGN.md

@@ -23,10 +23,12 @@ dependencies = [
     "javatools>=1.6.0,<2.0.0",
     "pygit2>=1.17.0,<2.0.0",
     "typer>=0.24.0,<1.0.0",
+    "mcp>=1.0.0,<2.0.0",
 ]
 
 [project.scripts]
 cgraph = "api.cli:app"
+cgraph-mcp = "api.mcp.server:main"
 
 [project.optional-dependencies]
 test = [

docs/code-graph-mcp-v4.docx

@@ -0,0 +1,55 @@
+"""Scaffold smoke tests for the cgraph-mcp server (T1).
+
+These tests prove the bare module is wired correctly:
+
+1. The FastMCP ``app`` instance is importable.
+2. The ``cgraph-mcp`` console script spawns a working stdio MCP server.
+3. A client can complete the MCP handshake and ``list_tools`` returns 0
+   tools (no tools are registered yet — they land in T4-T8, T11).
+
+When tool tickets land they should ADD tests, not modify these — these
+guard the scaffold itself.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+import pytest
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+def test_app_is_importable() -> None:
+    """The FastMCP instance can be imported and is named ``code-graph``."""
+    from api.mcp.server import app
+
+    assert app is not None
+    assert app.name == "code-graph"
+
+
+def test_main_entry_point_exists() -> None:
+    """``main()`` is exposed for the console script."""
+    from api.mcp import server
+
+    assert callable(server.main)
+
+
+@pytest.mark.anyio
+async def test_stdio_server_lists_zero_tools() -> None:
+    """Spawn ``cgraph-mcp`` over stdio and verify the protocol handshake.
+
+    The scaffold registers no tools, so ``list_tools`` must return an
+    empty list. Tool tickets (T4-T8, T11) extend this expectation.
+    """
+    cgraph_mcp = shutil.which("cgraph-mcp")
+    assert cgraph_mcp is not None, (
+        "cgraph-mcp not on PATH; run `uv pip install -e .` first"
+    )
+
+    params = StdioServerParameters(command=cgraph_mcp, args=[])
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            result = await session.list_tools()
+            assert result.tools == []