@deepsql/mcp 0.2.0

package/README.md

@@ -0,0 +1,42 @@
+# DeepSQL MCP
+
+DeepSQL MCP V1 is a local stdio server for Claude Desktop, Codex, and similar MCP clients.
+
+## What V1 Supports
+
+- Local stdio MCP process
+- Remote DeepSQL backend over HTTPS
+- MCP personal access tokens for authentication
+- Read-only SQL execution and explain through backend-enforced MCP endpoints
+
+V1 does **not** provide a shared remote MCP server URL. Each user runs the MCP process locally on their own machine.
+
+## Environment Variables
+
+| Variable | Required | Example |
+|----------|----------|---------|
+| `DEEPSQL_API_BASE_URL` | yes | `https://customer-deepsql.example.com/api/` |
+| `DEEPSQL_AUTH_TOKEN` | yes | `dsql_mcp_...` |
+| `DEEPSQL_MCP_TIMEOUT_MS` | no | `120000` |
+| `DEEPSQL_MCP_USER_ID` | no | `codex-mcp` |
+| `DEEPSQL_MCP_PROJECT_ID` | no | `codex-mcp` |
+
+## Claude Desktop
+
+Use `claude_desktop_config.customer.example.json` as a template.
+
+## Codex
+
+Use `codex_config.customer.example.toml` as a template.
+
+## Run
+
+```bash
+npx -y @deepsql/mcp
+```
+
+For local repo development, you can also run:
+
+```bash
+npm run mcp:phase1
+```

package/bin/deepsql.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+"use strict";
+
+const { main } = require("../src/cli");
+
+main()
+  .then((code) => {
+    if (typeof code === "number") process.exit(code);
+  })
+  .catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+  });

package/claude_desktop_config.customer.example.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "deepsql": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@deepsql/mcp"
+      ],
+      "env": {
+        "DEEPSQL_API_BASE_URL": "https://customer-deepsql.example.com/api/",
+        "DEEPSQL_AUTH_TOKEN": "dsql_mcp_replace_me",
+        "DEEPSQL_MCP_USER_ID": "claude-desktop",
+        "DEEPSQL_MCP_PROJECT_ID": "claude-desktop"
+      }
+    }
+  }
+}

package/codex_config.customer.example.toml

@@ -0,0 +1,9 @@
+[mcp_servers.deepsql]
+command = "npx"
+args = ["-y", "@deepsql/mcp"]
+
+[mcp_servers.deepsql.env]
+DEEPSQL_API_BASE_URL = "https://customer-deepsql.example.com/api/"
+DEEPSQL_AUTH_TOKEN = "dsql_mcp_replace_me"
+DEEPSQL_MCP_USER_ID = "codex-mcp"
+DEEPSQL_MCP_PROJECT_ID = "codex-mcp"

package/deepsql-phase1-lib.js

@@ -0,0 +1,586 @@
+const ALLOWED_READ_ONLY_KEYWORDS = new Set([
+  "SELECT",
+  "WITH",
+  "SHOW",
+  "DESCRIBE",
+  "DESC",
+  "EXPLAIN",
+]);
+
+const FORBIDDEN_SQL_KEYWORDS = [
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "ALTER",
+  "DROP",
+  "TRUNCATE",
+  "CREATE",
+  "MERGE",
+  "REPLACE",
+  "GRANT",
+  "REVOKE",
+  "CALL",
+  "COPY",
+  "VACUUM",
+  "COMMENT",
+];
+
+const TOOL_DEFINITIONS = [
+  {
+    name: "list_connections",
+    description: "List DeepSQL database connections available to this user.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_schema",
+    description: "Fetch cached schema metadata for a DeepSQL connection.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "DeepSQL connection ID.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_database_objects",
+    description: "Fetch tables, views, functions, and procedures for a DeepSQL connection.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "DeepSQL connection ID.",
+        },
+      },
+      required: ["connectionId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "answer_question",
+    description: "Ask DeepSQL a natural-language database question using the full chat pipeline.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "DeepSQL connection ID.",
+        },
+        question: {
+          type: "string",
+          description: "Natural-language database question.",
+        },
+        chatId: {
+          type: "string",
+          description: "Optional DeepSQL chat ID for conversation continuity.",
+        },
+        userId: {
+          type: "string",
+          description: "Optional user ID for attribution in feedback/history.",
+        },
+      },
+      required: ["connectionId", "question"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "execute_readonly_sql",
+    description: "Execute a read-only SQL query through DeepSQL with client-side and backend safety checks.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "DeepSQL connection ID.",
+        },
+        query: {
+          type: "string",
+          description: "Read-only SQL query. Multi-statement SQL is rejected in phase 1.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 1000,
+          description: "Optional row limit override. Defaults to 100.",
+        },
+        timeoutSeconds: {
+          type: "integer",
+          minimum: 1,
+          maximum: 60,
+          description: "Optional per-query timeout override. Defaults to backend default.",
+        },
+      },
+      required: ["connectionId", "query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "explain_readonly_sql",
+    description: "Run EXPLAIN (without ANALYZE) for a read-only SQL query through DeepSQL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        connectionId: {
+          type: "string",
+          description: "DeepSQL connection ID.",
+        },
+        query: {
+          type: "string",
+          description: "Read-only SQL query to explain. Do not include EXPLAIN or EXPLAIN ANALYZE.",
+        },
+      },
+      required: ["connectionId", "query"],
+      additionalProperties: false,
+    },
+  },
+];
+
+class DeepSqlApiError extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.name = "DeepSqlApiError";
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+function compactWhitespace(value) {
+  return String(value || "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function stripSqlComments(sql) {
+  return String(sql || "")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/--.*$/gm, " ");
+}
+
+function stripSqlStringLiterals(sql) {
+  return String(sql || "")
+    .replace(/'(?:''|[^'])*'/g, "''")
+    .replace(/"(?:[""]|[^"])*"/g, '""')
+    .replace(/`(?:``|[^`])*`/g, "``");
+}
+
+function normalizeSqlForInspection(sql) {
+  return compactWhitespace(stripSqlStringLiterals(stripSqlComments(sql)));
+}
+
+function firstKeyword(sql) {
+  const match = normalizeSqlForInspection(sql).match(/^([A-Za-z]+)/);
+  return match ? match[1].toUpperCase() : null;
+}
+
+function splitStatements(sql) {
+  const normalized = normalizeSqlForInspection(sql);
+  return normalized
+    .split(";")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function stripTrailingSemicolons(sql) {
+  return String(sql || "")
+    .trim()
+    .replace(/;+\s*$/, "");
+}
+
+function containsForbiddenKeyword(sql) {
+  const normalized = normalizeSqlForInspection(sql);
+  return FORBIDDEN_SQL_KEYWORDS.find((keyword) =>
+    new RegExp(`\\b${keyword}\\b`, "i").test(normalized),
+  );
+}
+
+function validateReadOnlySql(sql, { allowExplain = true } = {}) {
+  if (!sql || !String(sql).trim()) {
+    return {
+      ok: false,
+      reason: "Query is required.",
+    };
+  }
+
+  const statements = splitStatements(sql);
+  if (statements.length !== 1) {
+    return {
+      ok: false,
+      reason: "Phase 1 MCP only allows a single SQL statement.",
+    };
+  }
+
+  const statement = statements[0];
+  const keyword = firstKeyword(statement);
+  if (!keyword || !ALLOWED_READ_ONLY_KEYWORDS.has(keyword)) {
+    return {
+      ok: false,
+      reason: "Only read-only SQL is allowed (SELECT, WITH, SHOW, DESCRIBE, DESC, EXPLAIN).",
+    };
+  }
+
+  if (!allowExplain && keyword === "EXPLAIN") {
+    return {
+      ok: false,
+      reason: "Pass the underlying SELECT/WITH query, not EXPLAIN itself.",
+    };
+  }
+
+  if (keyword === "EXPLAIN" && /\bANALYZ[EA]\b/i.test(statement)) {
+    return {
+      ok: false,
+      reason: "EXPLAIN ANALYZE is blocked in phase 1 MCP because it executes the query.",
+    };
+  }
+
+  const forbiddenKeyword = containsForbiddenKeyword(statement);
+  if (forbiddenKeyword) {
+    return {
+      ok: false,
+      reason: `Blocked potentially mutating SQL keyword: ${forbiddenKeyword}.`,
+    };
+  }
+
+  return {
+    ok: true,
+    normalizedQuery: stripTrailingSemicolons(sql),
+    firstKeyword: keyword,
+  };
+}
+
+function clampInteger(value, min, max, fallback) {
+  if (value == null) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+
+  return Math.min(max, Math.max(min, parsed));
+}
+
+function buildHeaders(config, extraHeaders = {}) {
+  const headers = {
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+
+  if (config.authToken) {
+    headers.Authorization = `Bearer ${config.authToken}`;
+  }
+
+  return headers;
+}
+
+function resolveApiUrl(baseUrl, path) {
+  const normalizedPath = String(path || "").replace(/^\/+/, "");
+  return new URL(normalizedPath, baseUrl).toString();
+}
+
+async function callDeepSqlApi(config, path, { method = "GET", json, headers } = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+  const url = resolveApiUrl(config.baseUrl, path);
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: buildHeaders(
+        config,
+        json == null
+          ? headers
+          : {
+              "Content-Type": "application/json",
+              ...headers,
+            },
+      ),
+      body: json == null ? undefined : JSON.stringify(json),
+      signal: controller.signal,
+    });
+
+    const rawBody = await response.text();
+    let payload = null;
+    if (rawBody) {
+      try {
+        payload = JSON.parse(rawBody);
+      } catch {
+        payload = rawBody;
+      }
+    }
+
+    if (!response.ok) {
+      const message =
+        (payload && typeof payload === "object" && payload.message) ||
+        response.statusText ||
+        "DeepSQL API request failed";
+      throw new DeepSqlApiError(message, response.status, payload);
+    }
+
+    return payload;
+  } catch (error) {
+    if (error.name === "AbortError") {
+      throw new DeepSqlApiError(
+        `DeepSQL API request timed out after ${config.timeoutMs}ms.`,
+        408,
+      );
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function summarizeConnections(connections) {
+  const lines = connections.map((connection) => {
+    const name = connection.connectionName || connection.name || connection.id;
+    const type = connection.dbType || "unknown";
+    return `- ${name} (${type}) — ${connection.id}`;
+  });
+
+  return lines.length
+    ? `Found ${connections.length} connection(s):\n${lines.join("\n")}`
+    : "No connections were returned by DeepSQL.";
+}
+
+function summarizeSchema(payload) {
+  const schema = payload?.schema || payload;
+  const tableCount = schema?.totalTables ?? schema?.tables?.length ?? 0;
+  const viewCount = schema?.totalViews ?? 0;
+  const databaseName = schema?.databaseName || "unknown";
+  const dbType = schema?.dbType || "unknown";
+
+  return `Schema for ${databaseName} (${dbType}) with ${tableCount} tables and ${viewCount} views.`;
+}
+
+function summarizeObjects(payload) {
+  const objects = payload?.objects || [];
+  const preview = objects
+    .slice(0, 10)
+    .map((object) => `${object.type}:${object.name}`)
+    .join(", ");
+  return preview
+    ? `Fetched ${objects.length} database object(s). Preview: ${preview}`
+    : "No database objects were returned.";
+}
+
+function summarizeChat(payload) {
+  const lines = [];
+  if (payload?.chatId) {
+    lines.push(`chatId: ${payload.chatId}`);
+  }
+  if (payload?.sql) {
+    lines.push(`sql: ${compactWhitespace(payload.sql)}`);
+  }
+  if (payload?.message) {
+    lines.push(`answer: ${payload.message}`);
+  }
+  return lines.join("\n");
+}
+
+function summarizeQueryResult(payload) {
+  const result = payload?.result || payload?.data || payload;
+  const rowCount = result?.rowCount ?? 0;
+  const columns = Array.isArray(result?.columns) ? result.columns.join(", ") : "";
+  const limited = result?.isLimited ? " (limited)" : "";
+  return `Query returned ${rowCount} row(s)${limited}${columns ? ` with columns: ${columns}` : ""}.`;
+}
+
+function summarizeExplain(payload) {
+  const summaryStats = payload?.summaryStats;
+  if (summaryStats) {
+    return `EXPLAIN completed. Summary: ${summaryStats}`;
+  }
+  const planType = payload?.queryType || "query";
+  return `EXPLAIN completed for ${planType}.`;
+}
+
+function buildToolResult(name, payload) {
+  let summary;
+
+  switch (name) {
+    case "list_connections":
+      summary = summarizeConnections(payload);
+      break;
+    case "get_schema":
+      summary = summarizeSchema(payload);
+      break;
+    case "get_database_objects":
+      summary = summarizeObjects(payload);
+      break;
+    case "answer_question":
+      summary = summarizeChat(payload);
+      break;
+    case "execute_readonly_sql":
+      summary = summarizeQueryResult(payload);
+      break;
+    case "explain_readonly_sql":
+      summary = summarizeExplain(payload);
+      break;
+    default:
+      summary = JSON.stringify(payload, null, 2);
+      break;
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: summary,
+      },
+    ],
+    structuredContent: payload,
+  };
+}
+
+function buildToolError(message, extra = {}) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: message,
+      },
+    ],
+    structuredContent: {
+      error: message,
+      ...extra,
+    },
+    isError: true,
+  };
+}
+
+async function handleToolCall(config, name, args = {}) {
+  switch (name) {
+    case "list_connections": {
+      const payload = await callDeepSqlApi(config, "/connections");
+      return buildToolResult(name, payload);
+    }
+
+    case "get_schema": {
+      const connectionId = String(args.connectionId || "").trim();
+      const payload = await callDeepSqlApi(
+        config,
+        `/connections/${encodeURIComponent(connectionId)}/schema`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "get_database_objects": {
+      const connectionId = String(args.connectionId || "").trim();
+      const payload = await callDeepSqlApi(
+        config,
+        `/connections/${encodeURIComponent(connectionId)}/objects`,
+      );
+      return buildToolResult(name, payload);
+    }
+
+    case "answer_question": {
+      const connectionId = String(args.connectionId || "").trim();
+      const question = String(args.question || "").trim();
+      const chatId = args.chatId ? String(args.chatId) : null;
+      const userId = args.userId ? String(args.userId) : config.defaultUserId;
+
+      const payload = await callDeepSqlApi(config, "/chat", {
+        method: "POST",
+        json: {
+          connectionId,
+          message: question,
+          chatId,
+          userId,
+          projectId: config.defaultProjectId,
+        },
+      });
+
+      return buildToolResult(name, payload);
+    }
+
+    case "execute_readonly_sql": {
+      const connectionId = String(args.connectionId || "").trim();
+      const validation = validateReadOnlySql(args.query, { allowExplain: true });
+      if (!validation.ok) {
+        return buildToolError(validation.reason);
+      }
+
+      const payload = await callDeepSqlApi(
+        config,
+        "/mcp/query-readonly",
+        {
+          method: "POST",
+          json: {
+            connectionId,
+            query: validation.normalizedQuery,
+            limit: clampInteger(args.limit, 1, 1000, 100),
+            timeoutSeconds: clampInteger(args.timeoutSeconds, 1, 60, null),
+          },
+        },
+      );
+
+      return buildToolResult(name, payload);
+    }
+
+    case "explain_readonly_sql": {
+      const connectionId = String(args.connectionId || "").trim();
+      const validation = validateReadOnlySql(args.query, { allowExplain: false });
+      if (!validation.ok) {
+        return buildToolError(validation.reason);
+      }
+
+      const payload = await callDeepSqlApi(config, "/mcp/explain-readonly", {
+        method: "POST",
+        json: {
+          connectionId,
+          query: validation.normalizedQuery,
+        },
+      });
+
+      return buildToolResult(name, payload);
+    }
+
+    default:
+      return buildToolError(`Unknown tool: ${name}`);
+  }
+}
+
+function createConfigFromEnv(env = process.env) {
+  const rawBaseUrl = env.DEEPSQL_API_BASE_URL || "http://localhost:8080/api/";
+  const baseUrl = rawBaseUrl.endsWith("/") ? rawBaseUrl : `${rawBaseUrl}/`;
+
+  return {
+    baseUrl,
+    authToken: env.DEEPSQL_AUTH_TOKEN || "",
+    timeoutMs: clampInteger(env.DEEPSQL_MCP_TIMEOUT_MS, 1000, 600000, 120000),
+    defaultUserId: env.DEEPSQL_MCP_USER_ID || "mcp-phase1",
+    defaultProjectId: env.DEEPSQL_MCP_PROJECT_ID || "mcp-phase1",
+  };
+}
+
+module.exports = {
+  DeepSqlApiError,
+  TOOL_DEFINITIONS,
+  buildToolError,
+  buildToolResult,
+  callDeepSqlApi,
+  clampInteger,
+  compactWhitespace,
+  containsForbiddenKeyword,
+  createConfigFromEnv,
+  firstKeyword,
+  handleToolCall,
+  normalizeSqlForInspection,
+  resolveApiUrl,
+  splitStatements,
+  stripTrailingSemicolons,
+  stripSqlComments,
+  stripSqlStringLiterals,
+  validateReadOnlySql,
+};