devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/cloud/devtorch-mcp-bridge.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * DevTorch MCP stdio ↔ SSE bridge.
+ *
+ * Allows any stdio-only MCP client (Claude Code, VS Code, Cursor, OpenCode in
+ * stdio/local mode) to connect to the Cloudflare (or any) DevTorch SSE MCP
+ * server.
+ *
+ * Resilience: for the DevTorch write tools (`devtorch_commit` and
+ * `devtorch_sensitivity_add`), the bridge will automatically fall back to the
+ * local `devtorch` CLI if the cloud server returns an error or does not answer
+ * within the configured timeout. This keeps the local `.GCC/` audit trail
+ * intact even when the cloud endpoint is unreachable or slow.
+ *
+ * Usage:
+ *   DEVTORCH_MCP_URL=https://devtorch-mcp.example.com/myorg/myrepo/sse \
+ *   DEVTORCH_API_KEY=... \
+ *   node devtorch-mcp-bridge.js
+ *
+ * Optional:
+ *   DEVTORCH_MCP_FALLBACK_TIMEOUT_MS=3000   (default: 8000)
+ *
+ * Then configure the IDE with:
+ *   { "type": "local", "command": ["node", "/path/to/devtorch-mcp-bridge.js"] }
+ */
+
+const { spawn } = require("child_process");
+const { TextDecoder } = require("util");
+
+const SSE_URL = process.env.DEVTORCH_MCP_URL;
+const API_KEY = process.env.DEVTORCH_API_KEY;
+const FALLBACK_TIMEOUT_MS = parseInt(
+  process.env.DEVTORCH_MCP_FALLBACK_TIMEOUT_MS || "8000",
+  10
+);
+const FALLBACK_TOOLS = new Set(["devtorch_commit", "devtorch_sensitivity_add"]);
+
+if (!SSE_URL || !API_KEY) {
+  console.error("Missing DEVTORCH_MCP_URL or DEVTORCH_API_KEY");
+  process.exit(1);
+}
+
+let messageUrl = null;
+let sessionId = null;
+
+// Requests we are waiting on and that require transparent local fallback.
+const pending = new Map(); // id -> { resolve, reject, timer, req }
+
+// Requests that were already handled locally (fallback or late response).
+// We keep this small set so a late cloud response does not leak to the client.
+const handledIds = new Set();
+
+async function main() {
+  const headers = { "X-DevTorch-Key": API_KEY };
+
+  const response = await fetch(SSE_URL, { headers });
+  if (!response.ok) {
+    console.error(
+      `SSE connection failed: ${response.status} ${response.statusText}`
+    );
+    process.exit(1);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  // Read incoming SSE events and either resolve a pending fallback request or
+  // forward the JSON-RPC payload to stdout.
+  (async () => {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n\n");
+      buffer = lines.pop() || "";
+      for (const chunk of lines) {
+        const event = parseEvent(chunk);
+        if (!event) continue;
+        if (event.type === "endpoint") {
+          messageUrl = event.data;
+          const url = new URL(messageUrl);
+          sessionId = url.searchParams.get("sessionId");
+        } else if (event.type === "message") {
+          handleMessage(event.data);
+        }
+      }
+    }
+  })();
+
+  // Read JSON-RPC requests from stdin and POST them to the messages endpoint.
+  const stdin = process.stdin;
+  stdin.setEncoding("utf8");
+  let inBuffer = "";
+  stdin.on("data", async (data) => {
+    inBuffer += data;
+    const lines = inBuffer.split("\n");
+    inBuffer = lines.pop() || "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      await handleStdinLine(line);
+    }
+  });
+
+  stdin.on("end", () => {
+    process.exit(0);
+  });
+}
+
+function handleMessage(data) {
+  let json;
+  try {
+    json = JSON.parse(data);
+  } catch (e) {
+    process.stdout.write(data + "\n");
+    return;
+  }
+
+  const id = json.id;
+  if (id !== undefined && handledIds.has(id)) {
+    // Late response after we already handled the request locally. Drop it.
+    return;
+  }
+
+  if (id !== undefined && pending.has(id)) {
+    const p = pending.get(id);
+    clearTimeout(p.timer);
+    pending.delete(id);
+    p.resolve({ data, json });
+    return;
+  }
+
+  process.stdout.write(data + "\n");
+}
+
+async function handleStdinLine(line) {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch (e) {
+    console.error(`Invalid JSON-RPC request: ${line}`);
+    return;
+  }
+
+  if (!messageUrl) {
+    console.error("Message endpoint not yet received from SSE");
+    return;
+  }
+
+  const toolName = req.method === "tools/call" && req.params && req.params.name;
+  if (toolName && FALLBACK_TOOLS.has(toolName)) {
+    await handleWithFallback(req, line);
+  } else {
+    await forwardRequest(line);
+  }
+}
+
+async function handleWithFallback(req, line) {
+  const id = req.id;
+  if (id === undefined) {
+    // Notification-style tool call; forward without waiting.
+    await forwardRequest(line);
+    return;
+  }
+
+  // Register the pending entry BEFORE the POST: the server may deliver the
+  // SSE response while the POST is still in flight (its 202 only returns
+  // after the tool has executed, which can exceed the fallback timeout).
+  const responsePromise = new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject, timer: null, req });
+  });
+  // A timeout rejection must never become an unhandled rejection while we
+  // are still awaiting the POST — that kills the whole bridge process and
+  // the IDE sees the MCP connection drop (issue #18).
+  responsePromise.catch(() => {});
+
+  try {
+    await forwardRequest(line);
+  } catch (e) {
+    pending.delete(id);
+    handledIds.add(id);
+    const result = await runLocalFallback(req);
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n"
+    );
+    return;
+  }
+
+  // The server accepted the request; the SSE response normally follows
+  // within moments. Only now start the fallback timer, so it measures
+  // response delivery — not tool execution time.
+  const entry = pending.get(id);
+  if (entry) {
+    entry.timer = setTimeout(() => {
+      const q = pending.get(id);
+      if (q) {
+        pending.delete(id);
+        handledIds.add(id);
+        q.reject(new Error("MCP timeout"));
+      }
+    }, FALLBACK_TIMEOUT_MS);
+  }
+
+  try {
+    const { data, json } = await responsePromise;
+    if (json.error) {
+      pending.delete(id);
+      handledIds.add(id);
+      throw new Error(
+        `MCP error: ${json.error.message || JSON.stringify(json.error)}`
+      );
+    }
+    pending.delete(id);
+    process.stdout.write(data + "\n");
+  } catch (e) {
+    if (!handledIds.has(id)) {
+      handledIds.add(id);
+    }
+    pending.delete(id);
+    const result = await runLocalFallback(req);
+    process.stdout.write(
+      JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n"
+    );
+  }
+}
+
+async function forwardRequest(line) {
+  const res = await fetch(messageUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-DevTorch-Key": API_KEY,
+    },
+    body: line,
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+}
+
+async function runLocalFallback(req) {
+  const args = (req.params && req.params.arguments) || {};
+  const toolName = req.params.name;
+  const cwd = process.env.DEVTORCH_GCC_PATH || process.cwd();
+
+  try {
+    const { exitCode, stdout, stderr } = await runLocalCommand(cwd, toolName, args);
+    if (exitCode !== 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Local fallback failed (${exitCode}): ${stderr || stdout || "unknown error"}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: stdout.trim() || "Recorded locally",
+        },
+      ],
+      isError: false,
+    };
+  } catch (e) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Local fallback error: ${e.message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+function runLocalCommand(cwd, toolName, args) {
+  return new Promise((resolve) => {
+    let cmd;
+    let cliArgs;
+
+    if (toolName === "devtorch_commit") {
+      cmd = "devtorch";
+      cliArgs = ["commit", "-m", String(args.message || "")];
+      // Note: the local CLI derives the branch from git; the optional `branch`
+      // parameter in the MCP tool is intentionally ignored for local fallback.
+    } else if (toolName === "devtorch_sensitivity_add") {
+      cmd = "devtorch";
+      const signal = String(args.signal || "");
+      cliArgs = [
+        "sensitivity",
+        "add",
+        "--source",
+        "mcp-fallback",
+        "--concept",
+        String(args.concept || ""),
+        "--confidence",
+        String(args.confidence || 0),
+      ];
+      if (signal) {
+        cliArgs.push("--counterfactuals", signal, "--message", signal);
+      }
+      const disclosure = String(
+        args.disclosure || args.disclosure_level || "PROTECTED"
+      ).toUpperCase();
+      if (["PUBLIC", "PROTECTED", "PRIVATE"].includes(disclosure)) {
+        cliArgs.push("--disclosure", disclosure);
+      }
+    } else {
+      return resolve({
+        exitCode: 1,
+        stdout: "",
+        stderr: `Unknown tool: ${toolName}`,
+      });
+    }
+
+    const proc = spawn(cmd, cliArgs, { cwd, env: process.env });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    proc.on("close", (exitCode) => {
+      resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+    });
+    proc.on("error", (err) => {
+      resolve({ exitCode: 1, stdout: "", stderr: err.message });
+    });
+  });
+}
+
+function parseEvent(text) {
+  const lines = text.split("\n");
+  let type = null;
+  let data = null;
+  for (const line of lines) {
+    if (line.startsWith("event:")) {
+      type = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      data = line.slice(5).trim();
+    }
+  }
+  if (!type || data === null) return null;
+  return { type, data };
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

devtorch_core/cloud/mcp_client.py

@@ -0,0 +1,229 @@
+"""
+devtorch_core.cloud.mcp_client
+==============================
+Reusable client for calling remote DevTorch MCP tools via JSON-RPC over SSE.
+
+The cloud MCP server accepts tool requests via POST to the messages endpoint
+and returns the JSON-RPC results as SSE ``message`` events. This client keeps
+the SSE connection open in a background reader thread, posts requests, and
+matches responses by request ID.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("devtorch.cloud.mcp_client")
+
+_USER_AGENT = "devtorch-mcp-client"
+
+
+class McpClient:
+    """Call remote DevTorch MCP tools via JSON-RPC over SSE.
+
+    Usage::
+
+        client = McpClient(url, api_key)
+        result = client.call_tool("devtorch_topics_list", {"all": True})
+        client.close()
+    """
+
+    def __init__(self, url: str, api_key: str, timeout: float = 10.0) -> None:
+        self._sse_url = url
+        self._api_key = api_key
+        self._timeout = timeout
+        self._messages_url: str | None = None
+        self._resp: Any | None = None
+        self._reader_thread: threading.Thread | None = None
+        self._results: dict[int | str, dict] = {}
+        self._lock = threading.Lock()
+        self._cv = threading.Condition(self._lock)
+        self._next_id = 1
+        self._closed = False
+
+    def __enter__(self) -> "McpClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def call_tool(self, tool_name: str, args: dict | None = None) -> str:
+        """Call a remote MCP tool and return the result text.
+
+        Raises ``RuntimeError`` on network errors, timeouts, or MCP-level errors.
+        """
+        self._ensure_connected()
+        req_id = self._next_id
+        self._next_id += 1
+
+        payload = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": "tools/call",
+            "params": {"name": tool_name, "arguments": args or {}},
+        }
+
+        self._post(payload)
+        body = self._wait_for_response(req_id)
+
+        if body.get("error"):
+            raise RuntimeError(f"MCP error: {json.dumps(body['error'])[:300]}")
+        if body.get("result", {}).get("isError"):
+            raise RuntimeError(f"MCP tool error: {json.dumps(body['result'])[:300]}")
+
+        content = body.get("result", {}).get("content", [])
+        if content and isinstance(content, list):
+            return content[0].get("text", "")
+        return json.dumps(body.get("result", {}))
+
+    def is_available(self) -> bool:
+        """Quick connectivity check — returns True if the SSE handshake succeeds."""
+        try:
+            self._ensure_connected()
+            return self._messages_url is not None
+        except Exception:
+            return False
+
+    def close(self) -> None:
+        """Close the SSE connection and stop the reader thread."""
+        self._closed = True
+        resp = self._resp
+        self._resp = None
+        if resp is not None:
+            try:
+                resp.close()
+            except Exception:
+                pass
+        with self._cv:
+            self._cv.notify_all()
+        reader = self._reader_thread
+        self._reader_thread = None
+        if reader is not None and reader.is_alive():
+            reader.join(timeout=2.0)
+
+    def _ensure_connected(self) -> None:
+        """Open the SSE connection and start the reader thread if needed."""
+        if self._closed:
+            raise RuntimeError("McpClient is closed")
+        if self._resp is not None and self._messages_url is not None:
+            return
+
+        req = urllib.request.Request(
+            self._sse_url,
+            headers={
+                "Accept": "text/event-stream",
+                "X-DevTorch-Key": self._api_key,
+                "User-Agent": _USER_AGENT,
+            },
+        )
+        self._resp = urllib.request.urlopen(req, timeout=self._timeout)
+        self._reader_thread = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader_thread.start()
+
+        # Wait for the endpoint event to set the messages URL.
+        deadline = time.time() + self._timeout
+        with self._cv:
+            while self._messages_url is None:
+                remaining = deadline - time.time()
+                if remaining <= 0:
+                    raise RuntimeError("SSE endpoint event not received in time")
+                self._cv.wait(remaining)
+
+    def _read_loop(self) -> None:
+        """Background thread: parse SSE events and store message responses."""
+        event_type: str | None = None
+        data: str | None = None
+        try:
+            while self._resp is not None:
+                line = self._resp.readline()
+                if not line:
+                    break
+                line = line.decode("utf-8", errors="replace")
+                if line.startswith("event:"):
+                    event_type = line[6:].strip()
+                elif line.startswith("data:"):
+                    data = line[5:].strip()
+                elif line.strip() == "":
+                    self._handle_event(event_type, data)
+                    event_type = None
+                    data = None
+        except Exception as exc:
+            logger.debug("SSE read loop ended: %s", exc)
+        finally:
+            self._resp = None
+            self._messages_url = None
+
+    def _handle_event(self, event_type: str | None, data: str | None) -> None:
+        """Process a single SSE event."""
+        if event_type == "endpoint" and data:
+            with self._cv:
+                self._messages_url = data
+                self._cv.notify_all()
+        elif event_type == "message" and data:
+            try:
+                body = json.loads(data)
+            except json.JSONDecodeError:
+                return
+            req_id = body.get("id")
+            if req_id is None:
+                return
+            with self._cv:
+                self._results[req_id] = body
+                self._cv.notify_all()
+
+    def _post(self, payload: dict) -> None:
+        """POST a JSON-RPC request to the messages endpoint."""
+        if self._messages_url is None:
+            raise RuntimeError("Message endpoint not available")
+        req = urllib.request.Request(
+            self._messages_url,
+            data=json.dumps(payload).encode(),
+            headers={
+                "Content-Type": "application/json",
+                "X-DevTorch-Key": self._api_key,
+                "User-Agent": _USER_AGENT,
+            },
+        )
+        with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+            # The server returns 202 Accepted; the actual response arrives via SSE.
+            pass
+
+    def _wait_for_response(self, req_id: int) -> dict:
+        """Wait for the JSON-RPC response matching ``req_id``."""
+        deadline = time.time() + self._timeout
+        with self._cv:
+            while req_id not in self._results:
+                remaining = deadline - time.time()
+                if remaining <= 0:
+                    raise RuntimeError(f"MCP call timed out waiting for response {req_id}")
+                self._cv.wait(remaining)
+            return self._results.pop(req_id)
+
+
+def detect_mcp_config(project_root: Path) -> tuple[str, str] | None:
+    """Check env vars then .mcp.json for MCP server URL and API key.
+
+    Returns ``(url, api_key)`` or ``None`` if not configured.
+    """
+    url = os.environ.get("DEVTORCH_MCP_URL", "").strip()
+    api_key = os.environ.get("DEVTORCH_API_KEY", "").strip()
+
+    if not url or not api_key:
+        mcp_path = project_root / ".mcp.json"
+        try:
+            data = json.loads(mcp_path.read_text(encoding="utf-8"))
+            env_cfg = data.get("mcpServers", {}).get("devtorch", {}).get("env", {})
+            url = url or env_cfg.get("DEVTORCH_MCP_URL", "").strip()
+            api_key = api_key or env_cfg.get("DEVTORCH_API_KEY", "").strip()
+        except (OSError, json.JSONDecodeError, KeyError, TypeError):
+            pass
+
+    if url and api_key:
+        return (url, api_key)
+    return None