adl-toolkit 0.0.0-stage → 0.1.3

package/adl_drift/server/mcp_server.py

@@ -0,0 +1,127 @@
+"""MCP Server implementation.
+
+Runs an HTTP/SSE server that exposes ADL Drift analysis as MCP tools.
+AI agents (Claude, Cursor, Copilot) connect to this server to get
+context about the codebase.
+
+Equivalent to the TypeScript MCP server in Drift v2.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, Request
+from fastapi.responses import StreamingResponse
+from sse_starlette.sse import EventSourceResponse
+import uvicorn
+
+from adl_drift.server.protocol import MCPRequest, MCPResponse
+from adl_drift.server.handlers import MCPHandlers
+
+
+class DriftMCPServer:
+    """MCP server for ADL Drift.
+
+    Supports two transport modes:
+    1. SSE (Server-Sent Events) - for real-time streaming
+    2. HTTP POST - for request/response
+
+    The server watches files for changes and updates its index.
+    """
+
+    def __init__(self, project_path: Path, port: int = 3000):
+        self.project_path = project_path
+        self.port = port
+        self.handlers = MCPHandlers(project_path)
+        self.app = FastAPI(title="ADL Drift MCP")
+        self._setup_routes()
+
+    def _setup_routes(self) -> None:
+        """Setup FastAPI routes."""
+
+        @self.app.post("/mcp/initialize")
+        async def initialize():
+            return self.handlers.initialize().model_dump()
+
+        # P2.11: dict dispatch (replaces the if/elif chain). Kept as an
+        # instance attribute (not a local) so a test can assert it stays in
+        # parity with initialize()'s tool list -- this list drifted out of
+        # sync with mcp_stdio.py's tools before (handlers.py's schema vs.
+        # code defaults, see run log 2026-09-29 (2)); nothing previously
+        # caught the same class of drift for this dispatch table.
+        self._dispatch = {
+            "drift_scan": self.handlers.handle_scan,
+            "drift_query": self.handlers.handle_query,
+            "drift_search": self.handlers.handle_search,
+            "drift_node": self.handlers.handle_node,
+            "drift_graph": self.handlers.handle_graph,
+            "drift_callers": self.handlers.handle_callers,
+            "drift_callees": self.handlers.handle_callees,
+            "drift_impact": self.handlers.handle_impact,
+            "drift_explore": self.handlers.handle_explore,
+            "drift_path": self.handlers.handle_path,
+            "drift_status": self.handlers.handle_status,
+            "drift_communities": self.handlers.handle_communities,
+            "drift_why": self.handlers.handle_why,
+            "drift_context": self.handlers.handle_context,
+            "drift_learn": self.handlers.handle_learn,
+            "drift_approve": self.handlers.handle_approve,
+            "drift_plan_change": self.handlers.handle_plan_change,
+            "drift_verify_change": self.handlers.handle_verify_change,
+        }
+
+        @self.app.post("/mcp/tools/call")
+        async def call_tool(request: Request):
+            body = await request.json()
+            # P2.11 Part 1c: JSON-RPC permits int ids but MCPRequest.id is
+            # str-typed — coerce at the boundary instead of 500-ing on
+            # pydantic validation.
+            if isinstance(body.get("id"), int):
+                body["id"] = str(body["id"])
+            mcp_request = MCPRequest(**body)
+
+            params = mcp_request.params or {}
+            params["request_id"] = mcp_request.id
+
+            handler = self._dispatch.get(mcp_request.method)
+            if handler is None:
+                response = MCPResponse(
+                    id=mcp_request.id,
+                    error={"code": -32601, "message": f"Method {mcp_request.method} not found"}
+                )
+            else:
+                response = handler(params)
+
+            return response.model_dump()
+
+        @self.app.get("/mcp/sse")
+        async def sse_endpoint():
+            """SSE endpoint for streaming updates."""
+            async def event_generator():
+                while True:
+                    # Send heartbeat every 30 seconds
+                    yield {
+                        "event": "heartbeat",
+                        "data": json.dumps({"status": "alive"})
+                    }
+                    await asyncio.sleep(30)
+
+            return EventSourceResponse(event_generator())
+
+        @self.app.get("/health")
+        async def health():
+            return {"status": "ok", "project": str(self.project_path)}
+
+    def run(self) -> None:
+        """Start the server."""
+        uvicorn.run(self.app, host="0.0.0.0", port=self.port)
+
+    async def run_async(self) -> None:
+        """Async version for embedding in other apps."""
+        config = uvicorn.Config(self.app, host="0.0.0.0", port=self.port)
+        server = uvicorn.Server(config)
+        await server.serve()

package/adl_drift/server/mcp_stdio.py

@@ -0,0 +1,335 @@
+"""MCP stdio server using the official `mcp` Python SDK (FastMCP).
+
+Exposes ADL Drift analysis as MCP tools so Claude Code, Cursor, and Claude Desktop
+can call them. Wraps existing MCPHandlers logic.
+
+Run: adl-drift-mcp [--project PATH]
+Or:  python -m adl_drift.server.mcp_stdio --project .
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from adl_drift.server.handlers import MCPHandlers
+
+# Surfaced in the MCP `initialize` handshake (InitializeResult.instructions) --
+# many clients inject this straight into the system prompt, separate from the
+# individual tool descriptions. Without it, a client that defers large tool
+# lists (17 tools here) behind an explicit activation step may never notice
+# ADL Drift's tools are worth activating at all -- this is the fix for exactly
+# that: it gives the agent a reason to look before it decides grep is enough.
+DRIFT_INSTRUCTIONS = """\
+ADL Drift: a persistent call-graph index for this codebase, kept current \
+incrementally. Use it before grep/Read for questions about Python or Java \
+symbols; use text search for literals, comments, logs, and unsupported files.
+
+- Read-only symbol question -- source/details, callers/blast radius, \
+  dependencies, "what breaks if I delete/change X?", or refactor safety? \
+  -> drift_explore.
+- About to edit a Python/Java function, method, constructor, class, field, \
+  constant, or parameter? -> call drift_plan_change FIRST. It resolves the \
+  target itself, so drift_explore is not required first. Save its baseline; \
+  after editing call drift_verify_change with that baseline and every modified \
+  Python/Java file in changed_files.
+- Target still uncertain? -> inspect drift_explore's resolved/ambiguous \
+  matches; use drift_search only when an exact qualified symbol still needs \
+  confirmation. Include parameter types for Java overloads.
+- Does a drift_path step order reflect a real call direction? -> check its \
+  `factual` field and each hop's `direction`; uncertain hops prove only \
+  connectivity.
+- Before the first graph query in a task, call drift_status. If the index is \
+  stale or missing, run drift_scan on the project root before exploring or \
+  planning. Recheck with drift_status after external source changes; after your own edits, use \
+  drift_verify_change with the original baseline. Inspect or report scan_errors.
+- Found a non-obvious constraint? -> drift_learn (future sessions get it via drift_why).
+- A result comes back with `truncated: {...}`? Re-request with a moderate \
+  max_tokens bump (e.g. 2-4x) before requesting unbounded output.
+"""
+
+
+def build_server(project_path: Path) -> FastMCP:
+    project_path = Path(project_path).resolve()
+    handlers = MCPHandlers(project_path)
+    mcp = FastMCP("adl-drift", instructions=DRIFT_INSTRUCTIONS)
+
+    def _unwrap(resp) -> Dict[str, Any]:
+        data = resp.model_dump()
+        if data.get("error"):
+            return {"error": data["error"]}
+        return data.get("result") or {}
+
+    @mcp.tool()
+    def drift_scan(
+        path: str,
+        category: Optional[str] = None,
+        limit: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Scan a Python or Java file/directory for supported code patterns."""
+        target = Path(path)
+        if not target.is_absolute():
+            target = (project_path / target).resolve()
+        return _unwrap(handlers.handle_scan({
+            "path": str(target), "category": category, "limit": limit, "max_tokens": max_tokens,
+            "cursor": cursor,
+        }))
+
+    @mcp.tool()
+    def drift_query(
+        category: Optional[str] = None,
+        approved_only: bool = False,
+        limit: int = 50,
+        max_tokens: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Query stored patterns from Cortex memory."""
+        return _unwrap(
+            handlers.handle_query({
+                "category": category, "approved_only": approved_only,
+                "limit": limit, "max_tokens": max_tokens, "cursor": cursor,
+            })
+        )
+
+    @mcp.tool()
+    def drift_search(
+        query: Optional[str] = None,
+        queries: Optional[List[str]] = None,
+        kind: Optional[str] = None,
+        limit: int = 20,
+        max_tokens: Optional[int] = None,
+        cursor: Optional[str] = None,
+        include_source: bool = False,
+        snippet_lines: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Search symbols by name. Ranked: exact id > exact name > substring; degree-boosted. If no exact/substring match is found, falls back to a token-overlap guess (set fuzzy_fallback=true) so a behavior-phrased query (e.g. "verify detectViolations") still returns candidates instead of an empty result. kind filters to function/class/module/variable. include_source=true embeds a source snippet on each match (like drift_node) so a single-symbol question skips the follow-up drift_node call — pass a small limit when using it, since every match's snippet counts against the response; snippet_lines, left unset, sizes each snippet to that symbol's real body length (capped at 200 lines) instead of a flat default. max_tokens default 2000, 0 = unbounded; pass next_cursor back as cursor for the next page. Pass queries (list) instead of query to run several searches in one call — the result then has a top-level `results` list instead of a single match list; batch mode does not support cursor."""
+        return _unwrap(handlers.handle_search({
+            "query": query, "queries": queries, "kind": kind, "limit": limit, "max_tokens": max_tokens,
+            "cursor": cursor, "include_source": include_source, "snippet_lines": snippet_lines,
+        }))
+
+    @mcp.tool()
+    def drift_node(
+        node_id: Optional[str] = None,
+        node_ids: Optional[List[str]] = None,
+        snippet_lines: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+        max_source_lines: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Node detail: file/line/signature/docstring, a source snippet, and in/out edge counts by type. node_id can be an exact id/qualified name or a loose symbol name; if nothing matches exactly, a token-overlap guess is used instead (fuzzy_fallback=true, alternates listed in ambiguous_matches). Pass node_ids (list) instead of node_id to fetch several nodes in one call — the result then has a top-level `nodes` list instead of a single node payload; a missing/ambiguous id in the batch doesn't fail the others. snippet_lines, left unset, sizes the snippet to the symbol's real body length (capped at 200 lines) instead of a flat default — pass it explicitly to override. max_tokens trims the snippet(s), split across items in batch mode; max_source_lines caps snippet length."""
+        return _unwrap(handlers.handle_node({
+            "node_id": node_id, "node_ids": node_ids, "snippet_lines": snippet_lines, "max_tokens": max_tokens,
+            "max_source_lines": max_source_lines,
+        }))
+
+    @mcp.tool()
+    def drift_graph(
+        symbol: Optional[str] = None,
+        symbols: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Get callers + dependencies for a symbol (qualified name), with file/line and edge type/confidence per item. If the symbol doesn't match exactly, a token-overlap guess is used instead (fuzzy_fallback=true, alternates listed in ambiguous_matches). Pass symbols (list) instead of symbol to fetch call graphs for several symbols in one call — the result then has a top-level `graphs` list instead of a single graph payload; a missing/ambiguous symbol in the batch doesn't fail the others. max_tokens default 2000 per list per symbol, 0 = unbounded."""
+        return _unwrap(handlers.handle_graph({
+            "symbol": symbol, "symbols": symbols, "limit": limit, "max_tokens": max_tokens,
+        }))
+
+    @mcp.tool()
+    def drift_callers(
+        symbol: str,
+        max_depth: int = 1,
+        limit: int = 50,
+        max_tokens: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Who depends on this symbol: depth-bounded reverse walk over calls/references/type-uses/instantiations/overrides. Falls back to a token-overlap guess when the symbol doesn't match exactly (fuzzy_fallback=true, alternates in ambiguous_matches). Ordered depth asc, confidence desc; max_tokens default 2000, 0 = unbounded."""
+        return _unwrap(handlers.handle_callers({
+            "symbol": symbol, "max_depth": max_depth,
+            "limit": limit, "max_tokens": max_tokens, "cursor": cursor,
+        }))
+
+    @mcp.tool()
+    def drift_callees(
+        symbol: str,
+        max_depth: int = 1,
+        limit: int = 50,
+        max_tokens: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """What this symbol depends on: depth-bounded forward walk over calls + instantiations. Falls back to a token-overlap guess when the symbol doesn't match exactly (fuzzy_fallback=true, alternates in ambiguous_matches). Ordered depth asc, confidence desc; max_tokens default 2000, 0 = unbounded."""
+        return _unwrap(handlers.handle_callees({
+            "symbol": symbol, "max_depth": max_depth,
+            "limit": limit, "max_tokens": max_tokens, "cursor": cursor,
+        }))
+
+    @mcp.tool()
+    def drift_path(
+        from_symbol: str,
+        to_symbol: str,
+        max_tokens: Optional[int] = None,
+        alternates: int = 0,
+    ) -> Dict[str, Any]:
+        """Shortest dependency path from one symbol to another (directed first, undirected fallback). Either endpoint falls back to a token-overlap guess when it doesn't match exactly (alternates in ambiguous_matches.from/to). Under max_tokens the middle is elided; `length` stays the true hop count. alternates=N adds up to N further simple paths (ids only)."""
+        return _unwrap(handlers.handle_path({
+            "from_symbol": from_symbol, "to_symbol": to_symbol, "max_tokens": max_tokens,
+            "alternates": alternates,
+        }))
+
+    @mcp.tool()
+    def drift_status() -> Dict[str, Any]:
+        """Index health: file/node/edge counts, last scan time, staleness flag. Call before trusting other graph answers."""
+        return _unwrap(handlers.handle_status({}))
+
+    @mcp.tool()
+    def drift_communities(
+        limit: int = 20,
+        max_tokens: Optional[int] = None,
+        god_nodes_top_n: int = 10,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Module clusters (Louvain): sizes, top members by degree, dominant module — repo orientation. Also god_nodes (highest-degree linchpins). max_tokens default 2000, 0 = unbounded."""
+        return _unwrap(handlers.handle_communities({
+            "limit": limit, "max_tokens": max_tokens, "god_nodes_top_n": god_nodes_top_n,
+            "cursor": cursor,
+        }))
+
+    @mcp.tool()
+    def drift_learn(
+        topic: str,
+        content: str,
+        tags: Optional[list] = None,
+    ) -> Dict[str, Any]:
+        """Record tribal knowledge for future drift_why queries (append-only DB write)."""
+        return _unwrap(handlers.handle_learn({
+            "topic": topic, "content": content, "tags": tags,
+        }))
+
+    @mcp.tool()
+    def drift_approve(pattern_id: str) -> Dict[str, Any]:
+        """Approve a detected pattern by id (flag-only DB write; id must exist)."""
+        return _unwrap(handlers.handle_approve({"pattern_id": pattern_id}))
+
+    @mcp.tool()
+    def drift_impact(
+        symbol: str,
+        max_tokens: Optional[int] = None,
+        limit: Optional[int] = None,
+        max_depth: Optional[int] = None,
+        max_nodes: Optional[int] = None,
+        include_initializers: bool = False,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Blast-radius analysis: direct + transitive callers, affected files/entry points. symbol can be an exact/substring name; if that finds nothing, a token-overlap guess is used instead (fuzzy_fallback=true) -- no need to call drift_search first just to get the exact name. Counts are exact; lists are cut to max_tokens (0 = unbounded) / limit / max_nodes and `truncated` says what was dropped; max_depth bounds the transitive horizon; pass next_cursor back as cursor for the rest."""
+        return _unwrap(handlers.handle_impact({
+            "symbol": symbol, "max_tokens": max_tokens, "limit": limit, "max_depth": max_depth,
+            "max_nodes": max_nodes, "include_initializers": include_initializers,
+            "cursor": cursor,
+        }))
+
+    @mcp.tool()
+    def drift_explore(
+        symbol: str,
+        max_tokens: Optional[int] = None,
+        limit: Optional[int] = None,
+        max_depth: Optional[int] = None,
+        max_nodes: Optional[int] = None,
+        callees_depth: int = 1,
+        include_initializers: bool = False,
+        snippet_lines: Optional[int] = None,
+        max_source_lines: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Everything about one symbol in a single call: resolved `detail` (signature/docstring/snippet, like drift_node), `impact` (direct + transitive callers, affected files/entry points, like drift_impact), and `dependencies` (what it calls, like drift_graph's dependencies) -- instead of drift_node + drift_impact + drift_graph as 3 separate round trips for the same symbol. symbol falls back to a fuzzy guess like drift_impact when nothing matches exactly (fuzzy_fallback=true). Additive: drift_node/drift_impact/drift_graph/drift_callers/drift_callees are unchanged and still the right call for a single aspect, or to page a huge list with `cursor` (not supported here -- re-request with a larger max_tokens or call the underlying tool directly instead). max_tokens (default 6000; 0 = unbounded, capped at 11000) is split across the three sections, impact getting the largest share; detail_truncated/impact.truncated/dependencies_truncated report what was cut in each. callees_depth bounds the dependencies walk (default 1); max_depth bounds impact's transitive caller horizon."""
+        return _unwrap(handlers.handle_explore({
+            "symbol": symbol, "max_tokens": max_tokens, "limit": limit, "max_depth": max_depth,
+            "max_nodes": max_nodes, "callees_depth": callees_depth,
+            "include_initializers": include_initializers,
+            "snippet_lines": snippet_lines, "max_source_lines": max_source_lines,
+        }))
+
+    @mcp.tool()
+    def drift_why(topic: str) -> Dict[str, Any]:
+        """Retrieve tribal knowledge + similar patterns for a topic."""
+        return _unwrap(handlers.handle_why({"topic": topic}))
+
+    @mcp.tool()
+    def drift_context(
+        query: str,
+        file_path: Optional[str] = None,
+        max_tokens: int = 2000,
+    ) -> Dict[str, Any]:
+        """Graph-ranked project context for a query: seed symbols, 2-hop dependency closure, patterns + tribal knowledge, trimmed to max_tokens."""
+        params: Dict[str, Any] = {"query": query, "max_tokens": max_tokens}
+        if file_path:
+            fp = Path(file_path)
+            if not fp.is_absolute():
+                fp = (project_path / fp).resolve()
+            params["file_path"] = str(fp)
+        return _unwrap(handlers.handle_context(params))
+
+    @mcp.tool()
+    def drift_plan_change(
+        description: str,
+        symbol: Optional[str] = None,
+        max_depth: int = 2,
+        max_tokens: int = 3000,
+        limit: Optional[int] = None,
+        max_nodes: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Predict the blast radius of a planned change. Resolves the target symbol from a natural-language description, returns impact (depth/token-bounded) + an editable checklist + a baseline snapshot for drift_verify_change."""
+        params: Dict[str, Any] = {
+            "description": description, "max_depth": max_depth,
+            "max_tokens": max_tokens, "limit": limit, "max_nodes": max_nodes,
+        }
+        if symbol:
+            params["symbol"] = symbol
+        return _unwrap(handlers.handle_plan_change(params))
+
+    @mcp.tool()
+    def drift_verify_change(
+        baseline: Dict[str, Any],
+        changed_files: Optional[list] = None,
+        symbol: Optional[str] = None,
+        max_tokens: int = 3000,
+        limit: Optional[int] = None,
+        max_nodes: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Verify a code change: incrementally rescan changed files and compare the new impact against the baseline from drift_plan_change. The embedded impact report is token-bounded; the verdict uses the full graph."""
+        params: Dict[str, Any] = {"baseline": baseline, "max_tokens": max_tokens, "limit": limit, "max_nodes": max_nodes}
+        if changed_files:
+            params["changed_files"] = changed_files
+        if symbol:
+            params["symbol"] = symbol
+        return _unwrap(handlers.handle_verify_change(params))
+
+    return mcp
+
+
+def run_stdio(project_path: Path) -> None:
+    # P2.9: headless under an IDE/agent host — keep the worker pool modest
+    # unless the user explicitly sized it. Worker stdout is redirected in
+    # _init_worker, so the JSON-RPC stream on our stdout stays clean.
+    os.environ.setdefault("DRIFT_PARALLEL_WORKERS", "4")
+    server = build_server(project_path)
+    server.run(transport="stdio")
+
+
+def cli_entry() -> None:
+    parser = argparse.ArgumentParser(prog="adl-drift-mcp", description="ADL Drift MCP stdio server")
+    parser.add_argument(
+        "--project",
+        "-p",
+        default=os.environ.get("DRIFT_PROJECT_PATH", "."),
+        help="Project root directory (default: $DRIFT_PROJECT_PATH or cwd)",
+    )
+    args = parser.parse_args()
+    run_stdio(Path(args.project))
+
+
+if __name__ == "__main__":
+    cli_entry()

package/adl_drift/server/protocol.py

@@ -0,0 +1,71 @@
+"""MCP (Model Context Protocol) message definitions.
+
+Defines the JSON-RPC-like protocol for communicating with AI agents.
+Based on the MCP specification used by Claude, Cursor, etc.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, List, Dict, Any, Literal
+from pydantic import BaseModel
+from enum import Enum
+
+
+class MCPRole(str, Enum):
+    """Message roles in MCP."""
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+
+
+class MCPMessage(BaseModel):
+    """A single message in the MCP conversation."""
+    role: MCPRole
+    content: str
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class MCPRequest(BaseModel):
+    """Request from client (IDE/AI agent) to server."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: Optional[str] = None
+    method: str
+    params: Optional[Dict[str, Any]] = None
+
+
+class MCPResponse(BaseModel):
+    """Response from server to client."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: Optional[str] = None
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[Dict[str, Any]] = None
+
+
+class MCPToolDefinition(BaseModel):
+    """Definition of a tool the server exposes."""
+    name: str
+    description: str
+    parameters: Dict[str, Any]  # JSON Schema
+
+
+class MCPContextItem(BaseModel):
+    """A piece of context returned to the AI."""
+    type: str  # "pattern", "symbol", "graph", "tribal_knowledge"
+    content: str
+    source: Optional[str] = None  # file path
+    relevance_score: Optional[float] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class MCPInitializeRequest(BaseModel):
+    """Client initialization request."""
+    protocol_version: str = "2024-11-05"
+    client_info: Dict[str, str]
+    capabilities: Optional[Dict[str, Any]] = None
+
+
+class MCPInitializeResponse(BaseModel):
+    """Server initialization response."""
+    protocol_version: str = "2024-11-05"
+    server_info: Dict[str, str]
+    tools: List[MCPToolDefinition]