feat(mcp): scaffold api/mcp module (T1 #648)

Dockerfile

@@ -21,7 +21,9 @@ COPY --from=node-base /usr/local/bin/node /usr/local/bin/node
 COPY --from=node-base /usr/local/lib/node_modules /usr/local/lib/node_modules
 
 # Install netcat for wait loop in start.sh and system build tools
-RUN apt-get update && apt-get install -y --no-install-recommends \
+RUN apt-get update \
+    && apt-get install -y -f \
+    && apt-get install -y --no-install-recommends \
     netcat-openbsd \
     git \
     build-essential \

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(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

e2e/seed_test_data.py

@@ -4,6 +4,9 @@
 import os
 import sys
 import logging
+from pathlib import Path
+
+import graphrag_sdk
 
 logging.basicConfig(
     level=logging.INFO,
@@ -14,8 +17,11 @@
 from falkordb import FalkorDB
 from api.project import Project
 
+# Use the installed graphrag-sdk (pinned to 0.8.2 via uv.lock) as the e2e
+# fixture. Upstream HEAD has the new v1.0 API which the tests aren't built for.
+GRAPHRAG_SDK_PATH = Path(graphrag_sdk.__file__).parent
+
 REPOS = [
-    "https://github.com/FalkorDB/GraphRAG-SDK",
     "https://github.com/pallets/flask",
 ]
 
@@ -61,6 +67,13 @@ def ensure_calls_edges(graph_name: str) -> None:
 
 
 def main():
+    logger.info(
+        "Seeding graphrag-sdk %s from %s",
+        getattr(graphrag_sdk, "__version__", "?"),
+        GRAPHRAG_SDK_PATH,
+    )
+    Project(name="GraphRAG-SDK", path=GRAPHRAG_SDK_PATH, url=None).analyze_sources()
+
     for url in REPOS:
         logger.info("Seeding %s ...", url)
         proj = Project.from_git_repository(url)

pyproject.toml

@@ -23,16 +23,19 @@ 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 = [
     "pytest>=9.0.2,<10.0.0",
     "ruff>=0.11.0,<1.0.0",
     "httpx>=0.28.0,<1.0.0",
+    "anyio>=4.0,<5.0",
 ]
 
 [build-system]

tests/mcp/test_scaffold.py

@@ -0,0 +1,65 @@
+"""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 anyio
+import pytest
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+STDIO_TIMEOUT = 10  # seconds — prevents CI from hanging if the server fails to start
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    """Pin the anyio backend to asyncio so transitive trio installs don't double-run tests."""
+    return "asyncio"
+
+
+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=[])
+    with anyio.fail_after(STDIO_TIMEOUT):
+        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 == []