sqlite-hub 1.5.0 → 2.0.1

package/server/mcp/stdioServer.js

@@ -0,0 +1,272 @@
+const path = require("node:path");
+const { AppStateStore } = require("../services/storage/appStateStore");
+const { DatabaseCommandService } = require("../services/databaseCommandService");
+const { McpStatusService } = require("../services/mcpStatusService");
+const { MCP_TOOL_DEFINITIONS, McpToolService } = require("../services/mcpToolService");
+const { resolveAppStatePaths } = require("../utils/appPaths");
+
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+
+function createAppStateStore() {
+  const packageRoot = path.resolve(__dirname, "../..");
+  const {
+    appStateDbPath,
+    legacyStatePath,
+    legacyDatabasePaths,
+  } = resolveAppStatePaths(packageRoot);
+
+  return new AppStateStore(appStateDbPath, {
+    legacyFilePath: legacyStatePath,
+    legacyDatabasePaths,
+  });
+}
+
+function createMcpServices({ appStateStore = createAppStateStore(), transport = "stdio" } = {}) {
+  const databaseService = new DatabaseCommandService({ appStateStore });
+  const statusService = new McpStatusService({
+    appStateStore,
+    exposedTools: MCP_TOOL_DEFINITIONS,
+    transport,
+  });
+  const toolService = new McpToolService({
+    databaseService,
+    statusService,
+  });
+
+  return {
+    appStateStore,
+    databaseService,
+    statusService,
+    toolService,
+  };
+}
+
+function createJsonRpcResult(id, result) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result,
+  };
+}
+
+function createJsonRpcError(id, error) {
+  const code = error?.code === "MCP_TOOL_NOT_FOUND" ? -32601 : -32603;
+
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: {
+      code,
+      message: error?.message ?? "MCP request failed.",
+      data: {
+        code: error?.code ?? error?.name ?? "MCP_ERROR",
+      },
+    },
+  };
+}
+
+async function handleMcpRequest(message, services) {
+  const { id, method, params = {} } = message ?? {};
+
+  if (!method) {
+    throw new Error("MCP JSON-RPC method is required.");
+  }
+
+  if (method === "initialize") {
+    services.statusService.markConnected();
+
+    return createJsonRpcResult(id, {
+      protocolVersion: params.protocolVersion || MCP_PROTOCOL_VERSION,
+      capabilities: {
+        tools: {},
+      },
+      serverInfo: {
+        name: "sqlite-hub",
+        version: require("../../package.json").version,
+      },
+    });
+  }
+
+  if (method === "notifications/initialized") {
+    services.statusService.markConnected();
+    return null;
+  }
+
+  if (method === "ping") {
+    return createJsonRpcResult(id, {});
+  }
+
+  if (method === "tools/list") {
+    return createJsonRpcResult(id, {
+      tools: services.toolService.listTools(),
+    });
+  }
+
+  if (method === "tools/call") {
+    const result = await services.toolService.callTool(params.name, params.arguments ?? {});
+
+    return createJsonRpcResult(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+      structuredContent: result,
+    });
+  }
+
+  if (method === "shutdown") {
+    services.statusService.markStopped();
+    return createJsonRpcResult(id, {});
+  }
+
+  const error = new Error(`Unsupported MCP method: ${method}`);
+  error.code = "MCP_METHOD_NOT_FOUND";
+  throw error;
+}
+
+function encodeMessage(message) {
+  const json = JSON.stringify(message);
+  return `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n${json}`;
+}
+
+function tryReadFramedMessage(buffer) {
+  const headerSeparator = buffer.indexOf("\r\n\r\n");
+
+  if (headerSeparator === -1) {
+    return null;
+  }
+
+  const header = buffer.slice(0, headerSeparator).toString("ascii");
+  const lengthMatch = header.match(/Content-Length:\s*(\d+)/i);
+
+  if (!lengthMatch) {
+    throw new Error("MCP stdio message is missing Content-Length.");
+  }
+
+  const contentLength = Number(lengthMatch[1]);
+  const bodyStart = headerSeparator + 4;
+  const bodyEnd = bodyStart + contentLength;
+
+  if (buffer.length < bodyEnd) {
+    return null;
+  }
+
+  const body = buffer.slice(bodyStart, bodyEnd).toString("utf8");
+
+  return {
+    message: JSON.parse(body),
+    rest: buffer.slice(bodyEnd),
+  };
+}
+
+function tryReadLineMessage(buffer) {
+  if (/^Content-Length:/i.test(buffer.slice(0, Math.min(buffer.length, 32)).toString("ascii"))) {
+    return null;
+  }
+
+  const newlineIndex = buffer.indexOf("\n");
+
+  if (newlineIndex === -1) {
+    return null;
+  }
+
+  const line = buffer.slice(0, newlineIndex).toString("utf8").trim();
+
+  if (!line) {
+    return {
+      message: null,
+      rest: buffer.slice(newlineIndex + 1),
+    };
+  }
+
+  return {
+    message: JSON.parse(line),
+    rest: buffer.slice(newlineIndex + 1),
+  };
+}
+
+async function startMcpStdioServer({ input = process.stdin, output = process.stdout, services = createMcpServices() } = {}) {
+  let buffer = Buffer.alloc(0);
+  let stopped = false;
+
+  services.statusService.markServerRunning();
+
+  async function processMessage(message) {
+    if (!message) {
+      return;
+    }
+
+    try {
+      const response = await handleMcpRequest(message, services);
+
+      if (response && message.id !== undefined) {
+        output.write(encodeMessage(response));
+      }
+    } catch (error) {
+      services.statusService.markError(error);
+
+      if (message.id !== undefined) {
+        output.write(encodeMessage(createJsonRpcError(message.id, error)));
+      }
+    }
+  }
+
+  async function drainBuffer() {
+    while (buffer.length) {
+      const framed = tryReadFramedMessage(buffer) ?? tryReadLineMessage(buffer);
+
+      if (!framed) {
+        return;
+      }
+
+      buffer = framed.rest;
+      await processMessage(framed.message);
+    }
+  }
+
+  input.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+    drainBuffer().catch((error) => {
+      services.statusService.markError(error);
+      process.stderr.write(`SQLite Hub MCP error: ${error.message}\n`);
+    });
+  });
+
+  function stop() {
+    if (stopped) {
+      return;
+    }
+
+    stopped = true;
+    services.statusService.markStopped();
+    services.appStateStore?.db?.close?.();
+  }
+
+  input.on("end", stop);
+  process.once("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  process.once("SIGTERM", () => {
+    stop();
+    process.exit(0);
+  });
+
+  return {
+    services,
+    stop,
+  };
+}
+
+module.exports = {
+  MCP_PROTOCOL_VERSION,
+  createAppStateStore,
+  createMcpServices,
+  createJsonRpcError,
+  createJsonRpcResult,
+  encodeMessage,
+  handleMcpRequest,
+  startMcpStdioServer,
+};

package/server/routes/settings.js

@@ -1,4 +1,5 @@
 const express = require("express");
+const path = require("node:path");
 const { AppError, DatabaseRequiredError, route, successResponse } = require("../utils/errors");
 const {
   checkLatestAppVersion,
@@ -7,6 +8,8 @@ const {
   readSettingsMetadata,
   readSqliteVersion,
 } = require("../services/appInfoService");
+const { McpStatusService } = require("../services/mcpStatusService");
+const { MCP_TOOL_DEFINITIONS } = require("../services/mcpToolService");
 
 function getActiveTokenContext({ connectionManager, tokenService }) {
   const activeDatabase = connectionManager?.getActiveConnection?.() ?? null;
@@ -34,6 +37,56 @@ function buildSettingsMetadata(context) {
   };
 }
 
+function buildMcpHttpUrl(req) {
+  const host = String(req?.get?.("host") ?? "127.0.0.1:4173").trim() || "127.0.0.1:4173";
+  return `http://${host}/mcp`;
+}
+
+function buildMcpCodexConfig({ url = null, commandPath = null } = {}) {
+  if (url) {
+    return [
+      "[mcp_servers.sqlitehub]",
+      `url = ${JSON.stringify(url)}`,
+      "startup_timeout_sec = 10",
+      "tool_timeout_sec = 60",
+    ].join("\n");
+  }
+
+  const serverPath = commandPath ?? path.resolve(__dirname, "../../bin/sqlite-hub-mcp.js");
+
+  return [
+    "[mcp_servers.sqlitehub]",
+    'command = "node"',
+    `args = [${JSON.stringify(serverPath)}]`,
+    "startup_timeout_sec = 10",
+    "tool_timeout_sec = 60",
+  ].join("\n");
+}
+
+function buildMcpSettingsStatus(appStateStore, options = {}) {
+  const httpUrl = options.httpUrl ?? null;
+  const stdioCommandPath = path.resolve(__dirname, "../../bin/sqlite-hub-mcp.js");
+  const statusService = new McpStatusService({
+    appStateStore,
+    exposedTools: MCP_TOOL_DEFINITIONS,
+    transport: httpUrl ? "http" : "stdio",
+  });
+  const status = statusService.getStatus();
+
+  return {
+    ...status,
+    toolDetails: MCP_TOOL_DEFINITIONS.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+    })),
+    command: httpUrl ?? `node ${stdioCommandPath}`,
+    codexConfig: buildMcpCodexConfig({ url: httpUrl, commandPath: stdioCommandPath }),
+    httpUrl,
+    stdioCommand: `node ${stdioCommandPath}`,
+    stdioCodexConfig: buildMcpCodexConfig({ commandPath: stdioCommandPath }),
+  };
+}
+
 function createSettingsRouter({ appStateStore, connectionManager, tokenService, versionCheckService }) {
   const router = express.Router();
   const context = { connectionManager, tokenService };
@@ -89,6 +142,19 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService,
     })
   );
 
+  router.get(
+    "/mcp",
+    route((req, res) => {
+      res.json(
+        successResponse({
+          data: buildMcpSettingsStatus(appStateStore, {
+            httpUrl: buildMcpHttpUrl(req),
+          }),
+        })
+      );
+    })
+  );
+
   router.post(
     "/api-tokens",
     route((req, res) => {
@@ -126,6 +192,9 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService,
 
 module.exports = {
   createSettingsRouter,
+  buildMcpCodexConfig,
+  buildMcpHttpUrl,
+  buildMcpSettingsStatus,
   buildSettingsMetadata,
   checkLatestAppVersion,
   compareSemver,

package/server/server.js

@@ -23,6 +23,8 @@ const { TableDesignerService } = require("./services/sqlite/tableDesignerService
 const { MediaTaggingService } = require("./services/sqlite/mediaTaggingService");
 const { ApiTokenService } = require("./services/apiTokenService");
 const { DatabaseCommandService } = require("./services/databaseCommandService");
+const { createMcpServices } = require("./mcp/stdioServer");
+const { createMcpHttpRouter } = require("./mcp/httpRouter");
 const { createConnectionsRouter } = require("./routes/connections");
 const { createBackupsRouter } = require("./routes/backups");
 const { createOverviewRouter } = require("./routes/overview");
@@ -71,6 +73,7 @@ const tableDesignerService = new TableDesignerService({ connectionManager });
 const mediaTaggingService = new MediaTaggingService({ connectionManager, appStateStore });
 const apiTokenService = new ApiTokenService({ appStateStore });
 const databaseCommandService = new DatabaseCommandService({ appStateStore });
+const mcpServices = createMcpServices({ appStateStore, transport: "http" });
 
 connectionManager.initialize();
 
@@ -91,6 +94,16 @@ app.use(
     legacyHeaders: false,
   })
 );
+app.use("/mcp", localRequestSecurity);
+app.use(
+  "/mcp",
+  rateLimit({
+    windowMs: 60 * 1000,
+    max: 300,
+    standardHeaders: true,
+    legacyHeaders: false,
+  })
+);
 app.use(express.json({ limit: "10mb" }));
 app.use(express.urlencoded({ extended: false }));
 
@@ -143,6 +156,7 @@ app.use(
     appStateStore,
   })
 );
+app.use("/mcp", createMcpHttpRouter({ services: mcpServices }));
 
 // auth: public favicon response; it exposes no application data.
 app.get("/favicon.ico", (req, res) => {
@@ -254,6 +268,7 @@ module.exports = {
   apiTokenService,
   connectionManager,
   databaseCommandService,
+  mcpServices,
   DEFAULT_HOST,
   DEFAULT_PORT,
   parsePortArgument,

package/server/services/databaseCommandService.js

@@ -4,9 +4,11 @@ const { ConnectionManager } = require("./sqlite/connectionManager");
 const { BackupService } = require("./sqlite/backupService");
 const { DataBrowserService } = require("./sqlite/dataBrowserService");
 const { ExportService } = require("./sqlite/exportService");
-const { getTableDetail } = require("./sqlite/introspection");
-const { SqlExecutor } = require("./sqlite/sqlExecutor");
+const { getTableDetail, listSchema } = require("./sqlite/introspection");
+const { OverviewService } = require("./sqlite/overviewService");
+const { SqlExecutor, splitSqlStatements } = require("./sqlite/sqlExecutor");
 const { TypeGenerationService } = require("./typeGenerationService");
+const { detectQueryType } = require("./storage/queryHistoryUtils");
 
 function normalizeLookupValue(value, label) {
   const normalized = String(value ?? "").trim();
@@ -65,6 +67,99 @@ function normalizeMarkdownExportFilename(filename, fallback = "document.md") {
   return normalizedFilename;
 }
 
+function stripSqlTerminators(sql) {
+  return String(sql ?? "").trim().replace(/;+\s*$/g, "").trim();
+}
+
+function removeLeadingSqlComments(sql) {
+  let text = String(sql ?? "").trim();
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    const nextText = text
+      .replace(/^--[^\n]*(?:\n|$)/, "")
+      .replace(/^\/\*[\s\S]*?\*\//, "")
+      .trim();
+
+    if (nextText !== text) {
+      changed = true;
+      text = nextText;
+    }
+  }
+
+  return text;
+}
+
+function explainInnerSql(statement) {
+  return removeLeadingSqlComments(statement)
+    .replace(/^EXPLAIN\s+QUERY\s+PLAN\s+/i, "")
+    .replace(/^EXPLAIN\s+/i, "")
+    .trim();
+}
+
+function isAllowedReadonlyStatement(statement) {
+  const text = removeLeadingSqlComments(statement);
+  const queryType = detectQueryType(text);
+
+  if (queryType === "select" || queryType === "pragma") {
+    return true;
+  }
+
+  if (/^EXPLAIN\b/i.test(text)) {
+    const innerType = detectQueryType(explainInnerSql(text));
+    return innerType === "select" || innerType === "pragma";
+  }
+
+  return false;
+}
+
+function assertReadOnlySql(db, sql) {
+  const statements = splitSqlStatements(sql);
+
+  if (!statements.length) {
+    throw new ValidationError("No executable SQL statements were found.");
+  }
+
+  statements.forEach((statement, index) => {
+    if (!isAllowedReadonlyStatement(statement)) {
+      throw new ValidationError(
+        `Statement ${index + 1} is not allowed for read-only MCP queries. Only SELECT, PRAGMA, and EXPLAIN statements are allowed.`,
+        { code: "MCP_READONLY_SQL_REQUIRED" }
+      );
+    }
+
+    const prepared = db.prepare(statement);
+
+    if (!prepared.reader) {
+      throw new ValidationError(
+        `Statement ${index + 1} does not return rows and is blocked by the read-only query guard.`,
+        { code: "MCP_READONLY_SQL_REQUIRED" }
+      );
+    }
+  });
+
+  return statements;
+}
+
+function buildExplainQueryPlanSql(sql) {
+  const stripped = stripSqlTerminators(sql);
+
+  if (/^EXPLAIN\s+QUERY\s+PLAN\b/i.test(removeLeadingSqlComments(stripped))) {
+    return stripped;
+  }
+
+  return `EXPLAIN QUERY PLAN ${stripped}`;
+}
+
+function buildQueryPlanHints(rows = []) {
+  return rows
+    .map((row) => String(row.detail ?? row["QUERY PLAN"] ?? "").trim())
+    .filter(Boolean)
+    .filter((detail) => /\bSCAN\b/i.test(detail) && !/\bUSING\s+(?:COVERING\s+)?INDEX\b/i.test(detail))
+    .map((detail) => `Review whether an index would help: ${detail}`);
+}
+
 function coerceIdentityValue(column, value) {
   const text = String(value ?? "");
   const affinity = String(column?.affinity ?? "").toUpperCase();
@@ -216,6 +311,7 @@ class DatabaseCommandService {
         connectionManager,
         sqlExecutor,
       }),
+      overviewService: new OverviewService({ connectionManager }),
       sqlExecutor,
       close() {
         connectionManager.closeCurrent();
@@ -257,6 +353,10 @@ class DatabaseCommandService {
     return this.withDatabase(databaseReference, ({ runtime }) => runtime.dataBrowserService.listTables());
   }
 
+  getDatabaseOverview(databaseReference) {
+    return this.withDatabase(databaseReference, ({ runtime }) => runtime.overviewService.getOverview());
+  }
+
   getTable(databaseReference, tableName) {
     const normalizedTableName = normalizeLookupValue(tableName, "Table name");
     return this.withDatabase(databaseReference, ({ runtime }) =>
@@ -264,6 +364,33 @@ class DatabaseCommandService {
     );
   }
 
+  getSchema(databaseReference) {
+    return this.withDatabase(databaseReference, ({ runtime }) => listSchema(runtime.db));
+  }
+
+  getIndexes(databaseReference, tableName = null) {
+    const normalizedTableName = normalizeOptionalValue(tableName);
+
+    if (normalizedTableName) {
+      return this.getTable(databaseReference, normalizedTableName).indexes ?? [];
+    }
+
+    return this.getSchema(databaseReference).indexes ?? [];
+  }
+
+  getForeignKeys(databaseReference, tableName = null) {
+    const normalizedTableName = normalizeOptionalValue(tableName);
+
+    if (normalizedTableName) {
+      return this.getTable(databaseReference, normalizedTableName).foreignKeys ?? [];
+    }
+
+    return this.getSchema(databaseReference).tables.map((table) => ({
+      tableName: table.name,
+      foreignKeys: table.foreignKeys ?? [],
+    }));
+  }
+
   generateTableTypes(databaseReference, tableName, target, options = {}) {
     const normalizedTableName = normalizeLookupValue(tableName, "Table name");
     return this.withDatabase(databaseReference, ({ runtime }) =>
@@ -276,6 +403,98 @@ class DatabaseCommandService {
     );
   }
 
+  generateTypes(databaseReference, { tableName = null, allTables = false, target, options = {} } = {}) {
+    const normalizedTableName = normalizeOptionalValue(tableName);
+
+    return this.withDatabase(databaseReference, ({ runtime }) => {
+      const tables = allTables || !normalizedTableName
+        ? runtime.dataBrowserService.listTables().map((table) => table.name)
+        : [normalizedTableName];
+      const files = tables.map((name) =>
+        this.typeGenerationService.generateTypesFromDatabase(runtime.db, name, target, options)
+      );
+
+      return {
+        target: files[0]?.target ?? target,
+        files,
+        warnings: files.flatMap((file) =>
+          (file.warnings ?? []).map((warning) => `${file.tableName}: ${warning}`)
+        ),
+      };
+    });
+  }
+
+  executeReadOnlyQuery(databaseReference, sql, options = {}) {
+    return this.withDatabase(databaseReference, ({ runtime }) => {
+      const statements = assertReadOnlySql(runtime.db, sql);
+      const result = runtime.sqlExecutor.execute(sql, {
+        executedBy: options.executedBy ?? "mcp",
+        maxRows: options.maxRows ?? 500,
+        persistHistory: options.persistHistory,
+        requireReader: true,
+      });
+
+      return {
+        statementsValidated: statements.length,
+        result,
+      };
+    });
+  }
+
+  explainQueryPlan(databaseReference, sql) {
+    return this.withDatabase(databaseReference, ({ runtime }) => {
+      assertReadOnlySql(runtime.db, sql);
+      const explainSql = buildExplainQueryPlanSql(sql);
+      const rows = runtime.db.prepare(explainSql).all();
+
+      return {
+        sql: explainSql,
+        rows,
+        hints: buildQueryPlanHints(rows),
+      };
+    });
+  }
+
+  createChartFromQuery(databaseReference, { sql, name, chartType = "bar", config, resultColumns, tableVisible = true } = {}) {
+    const normalizedSql = normalizeLookupValue(sql, "SQL");
+
+    if (/^EXPLAIN\b/i.test(removeLeadingSqlComments(normalizedSql)) || detectQueryType(normalizedSql) !== "select") {
+      throw new ValidationError("Charts can only be created from read-only SELECT queries.", {
+        code: "CHART_SELECT_QUERY_REQUIRED",
+      });
+    }
+
+    return this.withDatabase(databaseReference, ({ connection, runtime }) => {
+      assertReadOnlySql(runtime.db, normalizedSql);
+      const result = runtime.sqlExecutor.execute(normalizedSql, {
+        executedBy: "mcp",
+        maxRows: 500,
+        requireReader: true,
+      });
+      const chart = this.appStateStore.createQueryHistoryChart({
+        databaseKey: connection.id,
+        queryHistoryId: result.historyId,
+        name,
+        chartType,
+        config,
+        resultColumns: resultColumns ?? result.columns.map((column) => ({
+          name: column,
+          type: "unknown",
+        })),
+        tableVisible,
+      });
+
+      return {
+        chart,
+        queryHistoryId: result.historyId,
+        export: {
+          png: false,
+          message: "Charts are saved in SQLite Hub. PNG export is available from the Charts UI.",
+        },
+      };
+    });
+  }
+
   getTableRow(databaseReference, tableName, exportTarget) {
     const normalizedTableName = normalizeLookupValue(tableName, "Table name");
     normalizeLookupValue(exportTarget, "Row key");
@@ -440,6 +659,22 @@ class DatabaseCommandService {
     return this.appStateStore.listDatabaseDocuments(connection.id);
   }
 
+  readDocuments(databaseReference, documentName = null) {
+    const normalizedDocumentName = normalizeOptionalValue(documentName);
+
+    if (normalizedDocumentName) {
+      return {
+        items: [this.getDocument(databaseReference, normalizedDocumentName)],
+      };
+    }
+
+    return {
+      items: this.listDocuments(databaseReference).map((document) =>
+        this.appStateStore.getDatabaseDocument(this.getDatabase(databaseReference).id, document.id)
+      ),
+    };
+  }
+
   findDocument(databaseReference, documentName) {
     const connection = this.getDatabase(databaseReference);
     const normalizedDocumentName = normalizeLookupValue(documentName, "Document name").toLowerCase();
@@ -494,8 +729,10 @@ class DatabaseCommandService {
 
 module.exports = {
   DatabaseCommandService,
+  assertReadOnlySql,
   buildIdentityFromExportTarget,
   buildRowJsonObject,
+  isAllowedReadonlyStatement,
   getDocumentTitle,
   getQueryTitle,
   normalizeMarkdownExportFilename,