Merge pull request #666 from FalkorDB/mcp/t1-scaffold

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

Author: DvirDukhan

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()

docs/MCP_SERVER_DESIGN.md

@@ -3,7 +3,12 @@
 
 import os
 import sys
+import shutil
 import logging
+import tempfile
+from pathlib import Path
+
+import graphrag_sdk
 
 logging.basicConfig(
     level=logging.INFO,
@@ -15,10 +20,17 @@
 from api.project import Project
 
 REPOS = [
-    "https://github.com/FalkorDB/GraphRAG-SDK",
     "https://github.com/pallets/flask",
 ]
 
+
+def prepare_graphrag_sdk_source() -> Path:
+    """Copy installed graphrag-sdk out of site-packages so LSP resolves calls as a project, not a library."""
+    src = Path(graphrag_sdk.__file__).parent
+    dst = Path(tempfile.mkdtemp(prefix="cgraph-e2e-sdk-")) / "graphrag_sdk"
+    shutil.copytree(src, dst)
+    return dst
+
 # CALLS edges required by E2E path tests (caller → callee)
 REQUIRED_CALLS_EDGES = [
     ("merge_with", "combine"),
@@ -44,30 +56,62 @@ def ensure_calls_edges(graph_name: str) -> None:
     logger.info("[%s] Analyzer created %d CALLS edges", graph_name, cnt)
 
     for caller, callee in REQUIRED_CALLS_EDGES:
-        res = g.query(
-            "MATCH (src:Function {name: $src}), (dest:Function {name: $dest}) "
-            "MERGE (src)-[e:CALLS]->(dest) "
-            "RETURN e",
+        # MERGE both Function nodes so a missing one (e.g. import_data, which
+        # has no `def` in graphrag-sdk 0.8.2) is synthesized with the minimal
+        # properties the UI needs (Searchable label for autocomplete).
+        g.query(
+            "MERGE (src:Function:Searchable {name: $src}) "
+            "ON CREATE SET src.path = 'synthesized.py', src.src_start = 1, src.src_end = 1, src.doc = '' "
+            "MERGE (dest:Function:Searchable {name: $dest}) "
+            "ON CREATE SET dest.path = 'synthesized.py', dest.src_start = 1, dest.src_end = 1, dest.doc = '' "
+            "MERGE (src)-[:CALLS]->(dest)",
             {"src": caller, "dest": callee},
         )
-        created = len(res.result_set) > 0
-        logger.info(
-            "[%s] CALLS %s → %s: %s",
-            graph_name,
-            caller,
-            callee,
-            "ensured" if created else "FAILED (node not found)",
+        logger.info("[%s] CALLS %s → %s: ensured", graph_name, caller, callee)
+
+
+def ensure_search_term_variety(graph_name: str) -> None:
+    """Synthesize Function nodes whose names contain the e2e search terms that
+    don't appear in graphrag-sdk 0.8.2 (e.g. 'test'). Without these, the
+    auto-scroll and auto-complete tests don't have enough matches.
+    """
+    db = FalkorDB(
+        host=os.getenv("FALKORDB_HOST", "localhost"),
+        port=int(os.getenv("FALKORDB_PORT", 6379)),
+    )
+    g = db.select_graph(graph_name)
+    for module in (
+        "ontology", "graph", "entity", "relation", "document", "chunk",
+        "query", "session", "agent", "chat", "attribute", "helpers",
+    ):
+        g.query(
+            "MERGE (f:Function:Searchable {name: $name}) "
+            "ON CREATE SET f.path = 'synthesized.py', f.src_start = 1, f.src_end = 1, f.doc = ''",
+            {"name": f"test_{module}"},
         )
 
 
 def main():
+    sdk_path = prepare_graphrag_sdk_source()
+    logger.info(
+        "Seeding graphrag-sdk %s from %s",
+        getattr(graphrag_sdk, "__version__", "?"),
+        sdk_path,
+    )
+    Project(
+        name="GraphRAG-SDK",
+        path=sdk_path,
+        url="https://github.com/FalkorDB/GraphRAG-SDK",
+    ).analyze_sources()
+
     for url in REPOS:
         logger.info("Seeding %s ...", url)
         proj = Project.from_git_repository(url)
         proj.analyze_sources()
         logger.info("Done seeding %s", url)
 
     ensure_calls_edges("GraphRAG-SDK")
+    ensure_search_term_variety("GraphRAG-SDK")
 
     logger.info("All test data seeded successfully.")
 

docs/code-graph-mcp-v4.docx

@@ -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]

e2e/seed_test_data.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 == []