@deepsql/mcp 0.2.0

package/deepsql-phase1-server.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+// DeepSQL Phase 1 MCP Server — stdio transport for read-only database access
+
+const {
+  TOOL_DEFINITIONS,
+  DeepSqlApiError,
+  buildToolError,
+  createConfigFromEnv,
+  handleToolCall,
+} = require("./deepsql-phase1-lib");
+
+const SERVER_INFO = {
+  name: "deepsql-phase1",
+  version: "0.1.0",
+};
+
+class DeepSqlPhase1McpServer {
+  constructor(config) {
+    this.config = config;
+    this.inputBuffer = Buffer.alloc(0);
+    this.shuttingDown = false;
+    // "auto" until we observe the client's framing. The MCP spec mandates
+    // newline-delimited JSON-RPC over stdio (Claude Code, codex-cli, etc.),
+    // but older clients (legacy Claude Desktop, our own E2E driver) used
+    // LSP-style Content-Length framing. Detect on first frame and respond
+    // in the same format.
+    this.framing = "auto";
+  }
+
+  start() {
+    process.stdin.on("data", (chunk) => {
+      this.inputBuffer = Buffer.concat([this.inputBuffer, chunk]);
+      this.processInputBuffer();
+    });
+
+    process.stdin.on("end", () => {
+      process.exit(0);
+    });
+
+    process.stdin.resume();
+    this.log(
+      `DeepSQL phase 1 MCP server started. Base URL=${this.config.baseUrl}, timeout=${this.config.timeoutMs}ms`,
+    );
+  }
+
+  log(message) {
+    process.stderr.write(`[deepsql-phase1] ${message}\n`);
+  }
+
+  detectFraming() {
+    // Skip leading whitespace to find the first meaningful byte.
+    let i = 0;
+    while (i < this.inputBuffer.length) {
+      const b = this.inputBuffer[i];
+      if (b !== 0x20 && b !== 0x09 && b !== 0x0a && b !== 0x0d) break;
+      i += 1;
+    }
+    if (i >= this.inputBuffer.length) return false;
+    // A leading `{` means newline-delimited JSON-RPC (the MCP spec format).
+    // Anything else (e.g. `C` from "Content-Length") is LSP framing.
+    this.framing = this.inputBuffer[i] === 0x7b ? "ndjson" : "lsp";
+    this.log(`Detected client framing: ${this.framing}`);
+    return true;
+  }
+
+  processInputBuffer() {
+    if (this.framing === "auto" && !this.detectFraming()) return;
+    if (this.framing === "ndjson") return this.processNdjsonBuffer();
+    return this.processLspBuffer();
+  }
+
+  processNdjsonBuffer() {
+    while (true) {
+      const nl = this.inputBuffer.indexOf(0x0a);
+      if (nl < 0) return;
+      const lineBuf = this.inputBuffer.slice(0, nl);
+      this.inputBuffer = this.inputBuffer.slice(nl + 1);
+      const line = lineBuf.toString("utf8").replace(/\r$/, "").trim();
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (error) {
+        this.log(`Failed to parse incoming JSON: ${error.message}`);
+        continue;
+      }
+      void this.handleMessage(message);
+    }
+  }
+
+  processLspBuffer() {
+    while (true) {
+      const crlfIndex = this.inputBuffer.indexOf("\r\n\r\n");
+      const lfIndex = this.inputBuffer.indexOf("\n\n");
+      let headerEnd = -1;
+      let separatorLength = 0;
+
+      if (crlfIndex >= 0 && (lfIndex < 0 || crlfIndex < lfIndex)) {
+        headerEnd = crlfIndex;
+        separatorLength = 4;
+      } else if (lfIndex >= 0) {
+        headerEnd = lfIndex;
+        separatorLength = 2;
+      }
+
+      if (headerEnd < 0) {
+        return;
+      }
+
+      const headerText = this.inputBuffer.slice(0, headerEnd).toString("utf8");
+      const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+      if (!lengthMatch) {
+        this.log("Received frame without Content-Length header; discarding.");
+        this.inputBuffer = this.inputBuffer.slice(headerEnd + separatorLength);
+        continue;
+      }
+
+      const contentLength = Number.parseInt(lengthMatch[1], 10);
+      const totalLength = headerEnd + separatorLength + contentLength;
+      if (this.inputBuffer.length < totalLength) {
+        return;
+      }
+
+      const bodyBuffer = this.inputBuffer.slice(
+        headerEnd + separatorLength,
+        totalLength,
+      );
+      this.inputBuffer = this.inputBuffer.slice(totalLength);
+
+      let message;
+      try {
+        message = JSON.parse(bodyBuffer.toString("utf8"));
+      } catch (error) {
+        this.log(`Failed to parse incoming JSON: ${error.message}`);
+        continue;
+      }
+
+      void this.handleMessage(message);
+    }
+  }
+
+  send(payload) {
+    const body = JSON.stringify(payload);
+    if (this.framing === "lsp") {
+      const header = `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n`;
+      process.stdout.write(header + body);
+    } else {
+      // Default to newline-delimited JSON-RPC (MCP spec). Used when the
+      // framing is still "auto" (e.g. server-initiated message before any
+      // client frame, which Phase 1 doesn't actually do).
+      process.stdout.write(body + "\n");
+    }
+  }
+
+  sendResult(id, result) {
+    this.send({
+      jsonrpc: "2.0",
+      id,
+      result,
+    });
+  }
+
+  sendError(id, code, message, data) {
+    this.send({
+      jsonrpc: "2.0",
+      id,
+      error: {
+        code,
+        message,
+        ...(data === undefined ? {} : { data }),
+      },
+    });
+  }
+
+  async handleMessage(message) {
+    const { id, method, params } = message || {};
+
+    if (!method) {
+      if (id !== undefined) {
+        this.sendError(id, -32600, "Invalid request");
+      }
+      return;
+    }
+
+    try {
+      switch (method) {
+        case "initialize": {
+          this.sendResult(id, {
+            protocolVersion: params?.protocolVersion || "2025-03-26",
+            capabilities: {
+              tools: {},
+            },
+            serverInfo: SERVER_INFO,
+            instructions:
+              "DeepSQL phase 1 MCP exposes read-only database access through DeepSQL. Prefer answer_question for high-level tasks. execute_readonly_sql and explain_readonly_sql reject mutating SQL.",
+          });
+          return;
+        }
+
+        case "notifications/initialized":
+          return;
+
+        case "ping":
+          this.sendResult(id, {});
+          return;
+
+        case "shutdown":
+          this.shuttingDown = true;
+          this.sendResult(id, {});
+          return;
+
+        case "exit":
+          process.exit(this.shuttingDown ? 0 : 1);
+          return;
+
+        case "tools/list":
+          this.sendResult(id, {
+            tools: TOOL_DEFINITIONS,
+          });
+          return;
+
+        case "resources/list":
+          this.sendResult(id, {
+            resources: [],
+          });
+          return;
+
+        case "prompts/list":
+          this.sendResult(id, {
+            prompts: [],
+          });
+          return;
+
+        case "tools/call": {
+          const toolName = params?.name;
+          const toolArgs = params?.arguments || {};
+
+          if (!toolName) {
+            this.sendResult(id, buildToolError("Tool name is required."));
+            return;
+          }
+
+          const result = await handleToolCall(this.config, toolName, toolArgs);
+          this.sendResult(id, result);
+          return;
+        }
+
+        default:
+          this.sendError(id, -32601, `Method not found: ${method}`);
+      }
+    } catch (error) {
+      if (error instanceof DeepSqlApiError) {
+        this.sendResult(
+          id,
+          buildToolError(`DeepSQL API error (${error.status || "unknown"}): ${error.message}`, {
+            status: error.status,
+            payload: error.payload,
+          }),
+        );
+        return;
+      }
+
+      this.log(error?.stack || error?.message || String(error));
+      if (id !== undefined) {
+        this.sendError(id, -32000, error?.message || "Internal server error");
+      }
+    }
+  }
+}
+
+if (require.main === module) {
+  const server = new DeepSqlPhase1McpServer(createConfigFromEnv());
+  server.start();
+}
+
+module.exports = {
+  DeepSqlPhase1McpServer,
+  SERVER_INFO,
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@deepsql/mcp",
+  "version": "0.2.0",
+  "description": "DeepSQL CLI and stdio MCP server for self-hosted deployments",
+  "bin": {
+    "deepsql": "./bin/deepsql.js",
+    "deepsql-mcp": "./deepsql-phase1-server.js"
+  },
+  "main": "./deepsql-phase1-server.js",
+  "files": [
+    "README.md",
+    "bin",
+    "src",
+    "deepsql-phase1-server.js",
+    "deepsql-phase1-lib.js",
+    "claude_desktop_config.customer.example.json",
+    "codex_config.customer.example.toml"
+  ],
+  "scripts": {
+    "test": "node --test deepsql-phase1-lib.test.js src/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/src/api/client.js

@@ -0,0 +1,93 @@
+"use strict";
+
+/**
+ * HTTP client used by the CLI. Wraps fetch with sane defaults, base-URL
+ * normalization, and consistent error shapes.
+ *
+ * Distinct from `deepsql-phase1-lib.js`'s `callDeepSqlApi` because the CLI
+ * needs:
+ *   - profile-based base URL resolution (not env-only)
+ *   - to talk to the unauthenticated /auth/cli endpoints
+ *   - to stream responses for `ask`
+ */
+
+class ApiError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function normalizeBaseUrl(url) {
+  if (!url) throw new ApiError("No DeepSQL URL configured. Run `deepsql login --url <url>` first.");
+  return url.endsWith("/") ? url : `${url}/`;
+}
+
+function resolveUrl(baseUrl, path) {
+  const normalized = String(path || "").replace(/^\/+/, "");
+  // The backend mounts everything under /api. Accept paths with or without
+  // the prefix.
+  const withApi = normalized.startsWith("api/") ? normalized : `api/${normalized}`;
+  return new URL(withApi, normalizeBaseUrl(baseUrl)).toString();
+}
+
+async function request(baseUrl, pathOrUrl, { method = "GET", json, headers, token, timeoutMs = 120000, query } = {}) {
+  let url;
+  if (typeof pathOrUrl === "string" && /^https?:\/\//i.test(pathOrUrl)) {
+    url = pathOrUrl;
+  } else {
+    url = resolveUrl(baseUrl, pathOrUrl);
+  }
+  if (query && typeof query === "object") {
+    const u = new URL(url);
+    for (const [key, value] of Object.entries(query)) {
+      if (value == null) continue;
+      u.searchParams.set(key, String(value));
+    }
+    url = u.toString();
+  }
+
+  const requestHeaders = {
+    Accept: "application/json",
+    ...(headers || {}),
+  };
+  if (token) requestHeaders.Authorization = `Bearer ${token}`;
+  if (json != null) requestHeaders["Content-Type"] = "application/json";
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: requestHeaders,
+      body: json == null ? undefined : JSON.stringify(json),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    if (err.name === "AbortError") {
+      throw new ApiError(`Request to ${url} timed out after ${timeoutMs}ms`);
+    }
+    throw new ApiError(`Network error contacting ${url}: ${err.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const text = await response.text();
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+  if (!response.ok) {
+    const message = (body && typeof body === "object" && (body.message || body.error)) || `HTTP ${response.status}`;
+    throw new ApiError(message, { status: response.status, body });
+  }
+  return body;
+}
+
+module.exports = { ApiError, request, resolveUrl, normalizeBaseUrl };

package/src/auth/browser-flow.js

@@ -0,0 +1,152 @@
+"use strict";
+
+/**
+ * PKCE + loopback redirect flow.
+ *
+ * 1. Generate verifier/challenge/state.
+ * 2. Bind a one-shot HTTP server on 127.0.0.1:<random-port>.
+ * 3. POST /auth/cli/authorize → {authorization_id, authorize_url}.
+ * 4. Open the authorize URL in the user's browser.
+ * 5. Wait for the loopback callback (code + state). Verify state matches.
+ * 6. POST /auth/cli/exchange → MCP token.
+ *
+ * The loopback server only responds to the single expected callback path; any
+ * other request gets a 404 to avoid being a useful open-redirect target.
+ */
+
+const http = require("node:http");
+const { spawn } = require("node:child_process");
+
+const { challengeFor, generateState, generateVerifier } = require("./pkce");
+const { request } = require("../api/client");
+
+const CALLBACK_PATH = "/cb";
+const SUCCESS_HTML = `<!doctype html>
+<html><head><meta charset="utf-8"><title>DeepSQL CLI authorized</title>
+<style>body{font:16px/1.5 -apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;max-width:480px;margin:80px auto;padding:0 24px;color:#111}h1{font-size:24px;margin:0 0 12px}p{color:#555}</style>
+</head><body><h1>You're all set.</h1><p>You can close this tab and return to your terminal.</p></body></html>`;
+
+const FAILURE_HTML = `<!doctype html>
+<html><head><meta charset="utf-8"><title>DeepSQL CLI authorization failed</title>
+<style>body{font:16px/1.5 -apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;max-width:480px;margin:80px auto;padding:0 24px;color:#111}h1{font-size:24px;margin:0 0 12px;color:#b91c1c}p{color:#555}</style>
+</head><body><h1>Authorization failed.</h1><p>Return to your terminal for details.</p></body></html>`;
+
+function startLoopbackServer() {
+  return new Promise((resolve, reject) => {
+    const callbackPromise = new Promise((resolveCallback, rejectCallback) => {
+      const server = http.createServer((req, res) => {
+        const url = new URL(req.url, `http://127.0.0.1`);
+        if (url.pathname !== CALLBACK_PATH) {
+          res.writeHead(404, { "Content-Type": "text/plain" });
+          res.end("Not found");
+          return;
+        }
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+        if (error || !code) {
+          res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(FAILURE_HTML);
+          rejectCallback(new Error(error || "Loopback callback missing `code` parameter"));
+        } else {
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(SUCCESS_HTML);
+          resolveCallback({ code, state });
+        }
+        // Server can shut down once we've handled the one expected request.
+        setImmediate(() => server.close());
+      });
+
+      server.on("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const { port } = server.address();
+        resolve({
+          port,
+          redirectUri: `http://127.0.0.1:${port}${CALLBACK_PATH}`,
+          callback: callbackPromise,
+          close: () => server.close(),
+        });
+      });
+    });
+  });
+}
+
+function openInBrowser(url) {
+  const opener =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", '""', url]]
+        : ["xdg-open", [url]];
+  try {
+    const child = spawn(opener[0], opener[1], { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // Fall through silently — caller already prints the URL.
+  }
+}
+
+async function runBrowserFlow({
+  baseUrl,
+  hostname,
+  clientLabel,
+  openBrowser = true,
+  log = () => {},
+  timeoutMs = 5 * 60 * 1000,
+}) {
+  const verifier = generateVerifier();
+  const challenge = challengeFor(verifier);
+  const state = generateState();
+
+  const server = await startLoopbackServer();
+  log(`listening for callback on ${server.redirectUri}`);
+
+  let started;
+  try {
+    started = await request(baseUrl, "/auth/cli/authorize", {
+      method: "POST",
+      json: {
+        redirectUri: server.redirectUri,
+        codeChallenge: challenge,
+        state,
+        hostname,
+        clientLabel,
+      },
+    });
+  } catch (err) {
+    server.close();
+    throw err;
+  }
+
+  log(`open ${started.authorize_url}`);
+  if (openBrowser) openInBrowser(started.authorize_url);
+
+  const callbackTimer = setTimeout(() => {
+    server.close();
+  }, timeoutMs);
+
+  let callback;
+  try {
+    callback = await server.callback;
+  } finally {
+    clearTimeout(callbackTimer);
+  }
+
+  if (callback.state && callback.state !== state) {
+    throw new Error("State mismatch — possible CSRF; aborting.");
+  }
+
+  const issued = await request(baseUrl, "/auth/cli/exchange", {
+    method: "POST",
+    json: {
+      authorizationId: started.authorization_id,
+      code: callback.code,
+      codeVerifier: verifier,
+    },
+  });
+
+  return issued;
+}
+
+module.exports = { runBrowserFlow, startLoopbackServer };

package/src/auth/device-flow.js

@@ -0,0 +1,59 @@
+"use strict";
+
+/**
+ * OAuth 2.0 device-code flow (RFC 8628 shape, adapted for self-hosted DeepSQL).
+ *
+ * 1. POST /auth/cli/device/code → {device_code, user_code, verification_uri, interval, expires_in}
+ * 2. Print the user_code + verification_uri.
+ * 3. Poll POST /auth/cli/device/token with {deviceCode}.
+ *    - 200 → token issued
+ *    - 428 (PRECONDITION_REQUIRED) → keep polling
+ *    - 429 → bump interval (`slow_down`)
+ *    - 410 → expired
+ *    - 403 → user denied
+ */
+
+const { ApiError, request } = require("../api/client");
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function runDeviceFlow({ baseUrl, hostname, clientLabel, log = () => {} }) {
+  const started = await request(baseUrl, "/auth/cli/device/code", {
+    method: "POST",
+    json: { hostname, clientLabel },
+  });
+
+  log(
+    `Visit ${started.verification_uri} and enter code:\n\n  ${started.user_code}\n\n` +
+      `Waiting for approval (expires in ${Math.round((started.expires_in || 900) / 60)} min)…`,
+  );
+
+  let interval = (started.interval || 5) * 1000;
+  const deadline = Date.now() + (started.expires_in || 900) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    try {
+      const issued = await request(baseUrl, "/auth/cli/device/token", {
+        method: "POST",
+        json: { deviceCode: started.device_code },
+      });
+      return issued;
+    } catch (err) {
+      if (!(err instanceof ApiError)) throw err;
+      if (err.status === 428) continue; // authorization_pending
+      if (err.status === 429) {
+        interval = Math.min(interval * 2, 30000);
+        continue;
+      }
+      if (err.status === 410) throw new Error("Device code expired before approval. Run `deepsql login` again.");
+      if (err.status === 403) throw new Error("Authorization was denied.");
+      throw err;
+    }
+  }
+  throw new Error("Device authorization timed out.");
+}
+
+module.exports = { runDeviceFlow };

package/src/auth/pkce.js

@@ -0,0 +1,41 @@
+"use strict";
+
+/**
+ * PKCE helpers (RFC 7636).
+ *
+ *   verifier  = high-entropy random string (43–128 chars from the unreserved set)
+ *   challenge = base64url(sha256(verifier))   (S256 method)
+ *
+ * Splitting these out so the CLI tests can exercise the math without spinning
+ * up an HTTP server.
+ */
+
+const crypto = require("node:crypto");
+
+function base64UrlEncode(buffer) {
+  return buffer
+    .toString("base64")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+function generateVerifier(bytes = 48) {
+  return base64UrlEncode(crypto.randomBytes(bytes));
+}
+
+function challengeFor(verifier) {
+  const hash = crypto.createHash("sha256").update(verifier).digest();
+  return base64UrlEncode(hash);
+}
+
+function generateState() {
+  return base64UrlEncode(crypto.randomBytes(16));
+}
+
+module.exports = {
+  base64UrlEncode,
+  challengeFor,
+  generateState,
+  generateVerifier,
+};

package/src/auth/pkce.test.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const crypto = require("node:crypto");
+
+const { challengeFor, generateState, generateVerifier, base64UrlEncode } = require("./pkce");
+
+test("generateVerifier returns base64url with no padding", () => {
+  const verifier = generateVerifier();
+  assert.match(verifier, /^[A-Za-z0-9_-]+$/);
+  assert.ok(verifier.length >= 43, "verifier must meet RFC 7636 length minimum");
+});
+
+test("challengeFor matches the spec: base64url(sha256(verifier))", () => {
+  const verifier = "test-verifier-with-enough-entropy-for-rfc7636";
+  const expected = base64UrlEncode(crypto.createHash("sha256").update(verifier).digest());
+  assert.equal(challengeFor(verifier), expected);
+});
+
+test("two verifiers produce different challenges", () => {
+  const a = generateVerifier();
+  const b = generateVerifier();
+  assert.notEqual(a, b);
+  assert.notEqual(challengeFor(a), challengeFor(b));
+});
+
+test("generateState returns base64url state of meaningful length", () => {
+  const state = generateState();
+  assert.match(state, /^[A-Za-z0-9_-]+$/);
+  assert.ok(state.length >= 16);
+});