sqlite-hub 1.4.0 → 2.0.0

package/server/services/mcpToolService.js

@@ -0,0 +1,274 @@
+const { ValidationError } = require("../utils/errors");
+
+function objectSchema(properties = {}, required = []) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required,
+  };
+}
+
+function databaseIdProperty() {
+  return {
+    type: "string",
+    description: "SQLite Hub database id or exact imported database label.",
+  };
+}
+
+const MCP_TOOL_DEFINITIONS = [
+  {
+    name: "list_connections",
+    description: "List imported SQLite Hub database connections without exposing API tokens.",
+    inputSchema: objectSchema(),
+  },
+  {
+    name: "get_database_overview",
+    description: "Return operational overview, SQLite runtime metadata, and schema statistics for a database.",
+    inputSchema: objectSchema({ databaseId: databaseIdProperty() }, ["databaseId"]),
+  },
+  {
+    name: "list_tables",
+    description: "List tables in a database with column counts.",
+    inputSchema: objectSchema({ databaseId: databaseIdProperty() }, ["databaseId"]),
+  },
+  {
+    name: "describe_table",
+    description: "Describe one table including columns, indexes, foreign keys, triggers, and row count.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        tableName: { type: "string" },
+      },
+      ["databaseId", "tableName"]
+    ),
+  },
+  {
+    name: "get_schema",
+    description: "Return the database schema: tables, views, indexes, triggers, and schema entries.",
+    inputSchema: objectSchema({ databaseId: databaseIdProperty() }, ["databaseId"]),
+  },
+  {
+    name: "get_indexes",
+    description: "Return all indexes or indexes for one table.",
+    inputSchema: objectSchema({
+      databaseId: databaseIdProperty(),
+      tableName: { type: "string", description: "Optional table name." },
+    }, ["databaseId"]),
+  },
+  {
+    name: "get_foreign_keys",
+    description: "Return all foreign-key metadata or foreign keys for one table.",
+    inputSchema: objectSchema({
+      databaseId: databaseIdProperty(),
+      tableName: { type: "string", description: "Optional table name." },
+    }, ["databaseId"]),
+  },
+  {
+    name: "run_readonly_query",
+    description: "Run a read-only SELECT, PRAGMA, or EXPLAIN query. Mutating SQL is blocked server-side.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        sql: { type: "string" },
+        maxRows: { type: "integer", minimum: 1, maximum: 5000, default: 500 },
+      },
+      ["databaseId", "sql"]
+    ),
+  },
+  {
+    name: "explain_query_plan",
+    description: "Run SQLite EXPLAIN QUERY PLAN for a read-only query and return structured plan rows.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        sql: { type: "string" },
+      },
+      ["databaseId", "sql"]
+    ),
+  },
+  {
+    name: "read_documents",
+    description: "Read database-scoped Markdown documents, optionally filtered by filename or title.",
+    inputSchema: objectSchema({
+      databaseId: databaseIdProperty(),
+      documentName: { type: "string", description: "Optional document id, filename, or title." },
+    }, ["databaseId"]),
+  },
+  {
+    name: "create_backup",
+    description: "Create and verify a managed SQLite Hub backup using the existing backup mechanism.",
+    inputSchema: objectSchema({
+      databaseId: databaseIdProperty(),
+      name: { type: "string" },
+      notes: { type: "string" },
+    }, ["databaseId"]),
+  },
+  {
+    name: "generate_types",
+    description: "Generate TypeScript, Rust, Kotlin, or Swift types from one table or all tables.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        tableName: { type: "string", description: "Optional table name. Omit when allTables is true." },
+        allTables: { type: "boolean", default: false },
+        target: { type: "string", enum: ["typescript", "rust", "kotlin", "swift"] },
+        options: { type: "object", additionalProperties: true },
+      },
+      ["databaseId", "target"]
+    ),
+  },
+  {
+    name: "create_chart_from_query",
+    description: "Create a saved SQLite Hub chart from a read-only SELECT query without writing export files.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        sql: { type: "string" },
+        name: { type: "string" },
+        chartType: { type: "string", enum: ["bar", "line", "pie", "scatter"] },
+        config: { type: "object", additionalProperties: true },
+        resultColumns: { type: "array", items: { type: "object", additionalProperties: true } },
+        tableVisible: { type: "boolean", default: true },
+      },
+      ["databaseId", "sql", "chartType", "config"]
+    ),
+  },
+];
+
+function redactConnection(connection = {}) {
+  return {
+    id: connection.id,
+    label: connection.label,
+    readOnly: Boolean(connection.readOnly),
+    sizeBytes: connection.sizeBytes ?? null,
+    lastOpenedAt: connection.lastOpenedAt ?? null,
+    lastModifiedAt: connection.lastModifiedAt ?? null,
+  };
+}
+
+function redactOverview(overview = {}) {
+  return {
+    ...overview,
+    connection: redactConnection(overview.connection ?? {}),
+    file: {
+      filename: overview.file?.filename ?? overview.connection?.label ?? null,
+      sizeBytes: overview.file?.sizeBytes ?? null,
+      lastModifiedAt: overview.file?.lastModifiedAt ?? null,
+    },
+  };
+}
+
+function summarizeBackup(backup = {}) {
+  return {
+    backupId: backup.id,
+    id: backup.id,
+    createdAt: backup.createdAt ?? null,
+    databaseId: backup.connectionId ?? null,
+    sizeBytes: backup.sizeBytes ?? null,
+    verified: backup.status === "verified",
+    status: backup.status,
+    name: backup.name,
+  };
+}
+
+class McpToolService {
+  constructor({ databaseService, statusService } = {}) {
+    this.databaseService = databaseService;
+    this.statusService = statusService;
+    this.toolDefinitions = MCP_TOOL_DEFINITIONS;
+    this.toolNames = this.toolDefinitions.map((tool) => tool.name);
+  }
+
+  listTools() {
+    return this.toolDefinitions;
+  }
+
+  requireTool(name) {
+    const tool = this.toolDefinitions.find((definition) => definition.name === name);
+
+    if (!tool) {
+      throw new ValidationError(`Unknown MCP tool: ${name}`, { code: "MCP_TOOL_NOT_FOUND" });
+    }
+
+    return tool;
+  }
+
+  async callTool(name, args = {}) {
+    this.requireTool(name);
+    this.statusService?.markToolCall?.(name);
+
+    try {
+      switch (name) {
+        case "list_connections":
+          return {
+            items: this.databaseService.listDatabases().map(redactConnection),
+          };
+        case "get_database_overview":
+          return redactOverview(this.databaseService.getDatabaseOverview(args.databaseId));
+        case "list_tables":
+          return {
+            items: this.databaseService.listTables(args.databaseId),
+          };
+        case "describe_table":
+          return this.databaseService.getTable(args.databaseId, args.tableName);
+        case "get_schema":
+          return this.databaseService.getSchema(args.databaseId);
+        case "get_indexes":
+          return {
+            items: this.databaseService.getIndexes(args.databaseId, args.tableName),
+          };
+        case "get_foreign_keys":
+          return {
+            items: this.databaseService.getForeignKeys(args.databaseId, args.tableName),
+          };
+        case "run_readonly_query":
+          return this.databaseService.executeReadOnlyQuery(args.databaseId, args.sql, {
+            executedBy: "mcp",
+            maxRows: args.maxRows,
+          });
+        case "explain_query_plan":
+          return this.databaseService.explainQueryPlan(args.databaseId, args.sql);
+        case "read_documents":
+          return this.databaseService.readDocuments(args.databaseId, args.documentName);
+        case "create_backup":
+          return summarizeBackup(
+            await this.databaseService.createBackup(args.databaseId, {
+              name: args.name,
+              notes: args.notes,
+              context: "mcp",
+            })
+          );
+        case "generate_types":
+          return this.databaseService.generateTypes(args.databaseId, {
+            tableName: args.tableName,
+            allTables: Boolean(args.allTables),
+            target: args.target,
+            options: args.options ?? {},
+          });
+        case "create_chart_from_query":
+          return this.databaseService.createChartFromQuery(args.databaseId, {
+            sql: args.sql,
+            name: args.name,
+            chartType: args.chartType,
+            config: args.config,
+            resultColumns: args.resultColumns,
+            tableVisible: args.tableVisible,
+          });
+        default:
+          throw new ValidationError(`Unknown MCP tool: ${name}`, { code: "MCP_TOOL_NOT_FOUND" });
+      }
+    } catch (error) {
+      this.statusService?.markError?.(error);
+      throw error;
+    }
+  }
+}
+
+module.exports = {
+  MCP_TOOL_DEFINITIONS,
+  McpToolService,
+  redactConnection,
+  redactOverview,
+  summarizeBackup,
+};

package/server/services/sqlite/dataBrowserService.js

@@ -6,6 +6,12 @@ const {
   serializeRows,
 } = require("../../utils/sqliteTypes");
 const { getRawStructureEntries, getTableDetail } = require("./introspection");
+const {
+  PREVIEW_ROW_COUNT,
+  buildSyntheticRows,
+  insertSyntheticRows,
+} = require("./syntheticDataGenerator");
+const { analyzeTable } = require("./tableAdvisor");
 const { normalizeTableFilter } = require("./tableFilter");
 const { buildTableOrderClause, normalizeTableSort } = require("./tableSort");
 
@@ -272,6 +278,36 @@ class DataBrowserService {
     };
   }
 
+  previewSyntheticRows(tableName, payload = {}) {
+    const db = this.connectionManager.getActiveDatabase();
+    const tableDetail = getTableDetail(db, tableName, { includeRowCount: false });
+    const preview = buildSyntheticRows(db, tableDetail, payload, { limit: PREVIEW_ROW_COUNT });
+
+    return {
+      tableName: tableDetail.name,
+      rowCount: preview.rowCount,
+      previewRowCount: preview.previewRowCount,
+      columns: preview.columns,
+      rows: serializeRows(preview.rows),
+      mappings: preview.mappings,
+    };
+  }
+
+  insertSyntheticRows(tableName, payload = {}) {
+    this.connectionManager.assertWritable();
+
+    const db = this.connectionManager.getActiveDatabase();
+    const tableDetail = getTableDetail(db, tableName, { includeRowCount: false });
+
+    return insertSyntheticRows(db, tableDetail, payload);
+  }
+
+  analyzeTable(tableName) {
+    const db = this.connectionManager.getActiveDatabase();
+
+    return analyzeTable(db, tableName);
+  }
+
   buildWhereClause(tableDetail, identity) {
     if (tableDetail.identityStrategy?.type === "rowid") {
       const rowid = identity?.values?.rowid;

package/server/services/sqlite/introspection.js

@@ -160,35 +160,66 @@ function normalizeIdentifier(value) {
   return text.toLowerCase();
 }
 
-function parseSqlStringList(text = "") {
+function parseSqlStringLiteral(text = "", startIndex = 0) {
+  let value = "";
+  let index = startIndex + 1;
+
+  while (index < text.length) {
+    if (text[index] === "'") {
+      if (text[index + 1] === "'") {
+        value += "'";
+        index += 2;
+        continue;
+      }
+
+      return {
+        value,
+        nextIndex: index + 1,
+      };
+    }
+
+    value += text[index];
+    index += 1;
+  }
+
+  return null;
+}
+
+function parseSqlSimpleListValues(text = "") {
   const values = [];
   let index = 0;
 
   while (index < text.length) {
-    if (text[index] !== "'") {
+    const character = text[index];
+
+    if (/\s|,/.test(character)) {
       index += 1;
       continue;
     }
 
-    let value = "";
-    index += 1;
-
-    while (index < text.length) {
-      if (text[index] === "'") {
-        if (text[index + 1] === "'") {
-          value += "'";
-          index += 2;
-          continue;
-        }
+    if (character === "'") {
+      const parsed = parseSqlStringLiteral(text, index);
 
-        index += 1;
-        values.push(value);
-        break;
+      if (!parsed) {
+        return [];
       }
 
-      value += text[index];
-      index += 1;
+      values.push(parsed.value);
+      index = parsed.nextIndex;
+      continue;
+    }
+
+    const commaIndex = text.indexOf(",", index);
+    const endIndex = commaIndex === -1 ? text.length : commaIndex;
+    const token = text.slice(index, endIndex).trim();
+    const number = parseSqlNumberToken(token);
+
+    if (number === null) {
+      return [];
     }
+
+    values.push(number);
+    index = endIndex;
   }
 
   return values;
@@ -219,7 +250,7 @@ function findColumnInListExpression(expression, columnName) {
       continue;
     }
 
-    const values = parseSqlStringList(expression.slice(openIndex + 1, closeIndex));
+    const values = parseSqlSimpleListValues(expression.slice(openIndex + 1, closeIndex));
 
     if (values.length) {
       return values;
@@ -229,6 +260,137 @@ function findColumnInListExpression(expression, columnName) {
   return [];
 }
 
+const SQL_IDENTIFIER_SOURCE =
+  '(?:"(?:[^"]|"")+"|`(?:[^`]|``)+`|\\[[^\\]]+\\]|[A-Za-z_][A-Za-z0-9_$]*)';
+const SQL_NUMBER_SOURCE = "[+-]?(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:e[+-]?\\d+)?";
+const SQL_NUMBER_EXACT_PATTERN = new RegExp(`^${SQL_NUMBER_SOURCE}$`, "i");
+
+function parseSqlNumberToken(value) {
+  const text = String(value ?? "").trim();
+
+  if (!SQL_NUMBER_EXACT_PATTERN.test(text)) {
+    return null;
+  }
+
+  const number = Number(text);
+
+  return Number.isFinite(number) ? number : null;
+}
+
+function tokenMatchesColumn(token, columnName) {
+  return normalizeIdentifier(token) === normalizeIdentifier(columnName);
+}
+
+function applyIntegerLowerBound(range, value, inclusive) {
+  const min = inclusive ? Math.ceil(value) : Math.floor(value) + 1;
+
+  range.min = range.min === null ? min : Math.max(range.min, min);
+}
+
+function applyIntegerUpperBound(range, value, inclusive) {
+  const max = inclusive ? Math.floor(value) : Math.ceil(value) - 1;
+
+  range.max = range.max === null ? max : Math.min(range.max, max);
+}
+
+function applyIntegerComparison(range, operator, value) {
+  switch (operator) {
+    case ">":
+      applyIntegerLowerBound(range, value, false);
+      break;
+    case ">=":
+      applyIntegerLowerBound(range, value, true);
+      break;
+    case "<":
+      applyIntegerUpperBound(range, value, false);
+      break;
+    case "<=":
+      applyIntegerUpperBound(range, value, true);
+      break;
+    case "=":
+      applyIntegerLowerBound(range, value, true);
+      applyIntegerUpperBound(range, value, true);
+      break;
+    default:
+      break;
+  }
+}
+
+function reverseComparisonOperator(operator) {
+  return {
+    ">": "<",
+    ">=": "<=",
+    "<": ">",
+    "<=": ">=",
+    "=": "=",
+  }[operator];
+}
+
+function findColumnIntegerRangeInExpression(expression, columnName) {
+  const range = { min: null, max: null };
+  let found = false;
+  const betweenPattern = new RegExp(
+    `(${SQL_IDENTIFIER_SOURCE})\\s+BETWEEN\\s+(${SQL_NUMBER_SOURCE})\\s+AND\\s+(${SQL_NUMBER_SOURCE})`,
+    "gi"
+  );
+  const comparisonPattern = new RegExp(
+    `(${SQL_IDENTIFIER_SOURCE}|${SQL_NUMBER_SOURCE})\\s*(<=|>=|=|<|>)\\s*(${SQL_IDENTIFIER_SOURCE}|${SQL_NUMBER_SOURCE})`,
+    "gi"
+  );
+  let match;
+
+  while ((match = betweenPattern.exec(expression))) {
+    const identifier = match[1];
+    const min = parseSqlNumberToken(match[2]);
+    const max = parseSqlNumberToken(match[3]);
+
+    if (!tokenMatchesColumn(identifier, columnName) || min === null || max === null) {
+      continue;
+    }
+
+    applyIntegerLowerBound(range, min, true);
+    applyIntegerUpperBound(range, max, true);
+    found = true;
+  }
+
+  while ((match = comparisonPattern.exec(expression))) {
+    const left = match[1];
+    const operator = match[2];
+    const right = match[3];
+    const leftIsColumn = tokenMatchesColumn(left, columnName);
+    const rightIsColumn = tokenMatchesColumn(right, columnName);
+
+    if (leftIsColumn) {
+      const value = parseSqlNumberToken(right);
+
+      if (value !== null) {
+        applyIntegerComparison(range, operator, value);
+        found = true;
+      }
+      continue;
+    }
+
+    if (rightIsColumn) {
+      const value = parseSqlNumberToken(left);
+      const reversedOperator = reverseComparisonOperator(operator);
+
+      if (value !== null && reversedOperator) {
+        applyIntegerComparison(range, reversedOperator, value);
+        found = true;
+      }
+    }
+  }
+
+  if (!found) {
+    return null;
+  }
+
+  return {
+    ...(range.min !== null ? { min: range.min } : {}),
+    ...(range.max !== null ? { max: range.max } : {}),
+  };
+}
+
 function parseCheckAllowedValues(ddl = "", columns = []) {
   const allowedValuesByColumn = new Map();
   const expressions = extractCheckExpressions(ddl);
@@ -256,6 +418,42 @@ function parseCheckAllowedValues(ddl = "", columns = []) {
   return allowedValuesByColumn;
 }
 
+function parseCheckIntegerRanges(ddl = "", columns = []) {
+  const integerRangesByColumn = new Map();
+  const expressions = extractCheckExpressions(ddl);
+
+  columns
+    .filter((column) => column.affinity === "INTEGER")
+    .forEach((column) => {
+      const range = { min: null, max: null };
+
+      expressions.forEach((expression) => {
+        const expressionRange = findColumnIntegerRangeInExpression(expression, column.name);
+
+        if (!expressionRange) {
+          return;
+        }
+
+        if (Number.isSafeInteger(expressionRange.min)) {
+          range.min = range.min === null ? expressionRange.min : Math.max(range.min, expressionRange.min);
+        }
+
+        if (Number.isSafeInteger(expressionRange.max)) {
+          range.max = range.max === null ? expressionRange.max : Math.min(range.max, expressionRange.max);
+        }
+      });
+
+      if (range.min !== null || range.max !== null) {
+        integerRangesByColumn.set(column.name, {
+          ...(range.min !== null ? { min: range.min } : {}),
+          ...(range.max !== null ? { max: range.max } : {}),
+        });
+      }
+    });
+
+  return integerRangesByColumn;
+}
+
 function groupForeignKeys(rows) {
   const grouped = new Map();
 
@@ -336,11 +534,17 @@ function getTableDetail(db, tableName, options = {}) {
     .map((column) => normalizeColumn(column, visibleSet))
     .sort((left, right) => left.cid - right.cid);
   const allowedValuesByColumn = parseCheckAllowedValues(entry.sql, columns);
+  const integerRangesByColumn = parseCheckIntegerRanges(entry.sql, columns);
 
-  columns = columns.map((column) => ({
-    ...column,
-    allowedValues: allowedValuesByColumn.get(column.name) ?? [],
-  }));
+  columns = columns.map((column) => {
+    const integerRange = integerRangesByColumn.get(column.name);
+
+    return {
+      ...column,
+      allowedValues: allowedValuesByColumn.get(column.name) ?? [],
+      ...(integerRange ? { integerRange } : {}),
+    };
+  });
 
   const foreignKeys = groupForeignKeys(
     db.prepare(`PRAGMA foreign_key_list(${quoteIdentifier(tableName)})`).all()