@rog0x/mcp-database-tools 1.0.0

package/src/tools/query-builder.ts

@@ -0,0 +1,469 @@
+/**
+ * Query Builder — convert natural language descriptions into SQL queries.
+ * Uses pattern matching and heuristics to generate SQL from plain English.
+ */
+
+interface QueryBuildResult {
+  sql: string;
+  dialect: string;
+  explanation: string;
+  assumptions: string[];
+  warnings: string[];
+}
+
+interface ParsedIntent {
+  action: "select" | "insert" | "update" | "delete" | "count" | "aggregate";
+  tables: string[];
+  columns: string[];
+  conditions: ConditionClause[];
+  orderBy: OrderClause[];
+  groupBy: string[];
+  limit: number | null;
+  joins: JoinClause[];
+  aggregates: AggregateClause[];
+  distinct: boolean;
+}
+
+interface ConditionClause {
+  column: string;
+  operator: string;
+  value: string;
+  connector: "AND" | "OR";
+}
+
+interface OrderClause {
+  column: string;
+  direction: "ASC" | "DESC";
+}
+
+interface JoinClause {
+  table: string;
+  onLeft: string;
+  onRight: string;
+  type: "INNER" | "LEFT" | "RIGHT";
+}
+
+interface AggregateClause {
+  func: string;
+  column: string;
+  alias: string;
+}
+
+type Dialect = "mysql" | "postgresql" | "sqlite" | "generic";
+
+function parseNaturalLanguage(text: string): ParsedIntent {
+  const lower = text.toLowerCase().trim();
+  const assumptions: string[] = [];
+
+  // Detect action
+  let action: ParsedIntent["action"] = "select";
+  if (/^(count|how many)/i.test(lower)) action = "count";
+  else if (/^(add|insert|create a|create new)/i.test(lower)) action = "insert";
+  else if (/^(update|change|modify|set)/i.test(lower)) action = "update";
+  else if (/^(delete|remove|drop all)/i.test(lower)) action = "delete";
+  else if (/\b(average|sum|total|minimum|maximum|avg|min|max)\b/i.test(lower)) action = "aggregate";
+
+  // Extract tables
+  const tables: string[] = [];
+  const tablePatterns = [
+    /\bfrom\s+(?:the\s+)?(\w+)\s+table/i,
+    /\bfrom\s+(\w+)/i,
+    /\bin\s+(?:the\s+)?(\w+)\s+table/i,
+    /\bin\s+(\w+)/i,
+    /\b(?:all|get|find|show|list|fetch|retrieve)\s+(\w+)/i,
+    /\b(?:update|modify|change)\s+(?:the\s+)?(\w+)/i,
+    /\b(?:delete|remove)\s+(?:from\s+)?(?:the\s+)?(\w+)/i,
+    /\b(?:insert|add)\s+(?:into\s+|to\s+)?(?:the\s+)?(\w+)/i,
+    /\b(\w+)\s+who\b/i,
+    /\b(\w+)\s+that\b/i,
+    /\b(\w+)\s+where\b/i,
+    /\b(\w+)\s+with\b/i,
+  ];
+
+  const stopWords = new Set([
+    "get", "find", "show", "list", "fetch", "retrieve", "all", "the",
+    "count", "how", "many", "number", "total", "average", "sum",
+    "minimum", "maximum", "each", "every", "and", "have", "has",
+    "are", "were", "been", "being", "their", "them", "more", "than",
+    "least", "most", "between", "not", "top", "first", "last",
+    "update", "delete", "insert", "add", "remove", "change", "modify",
+    "set", "new", "old", "create",
+  ]);
+
+  for (const pattern of tablePatterns) {
+    const match = lower.match(pattern);
+    if (match && !stopWords.has(match[1].toLowerCase())) {
+      const tbl = match[1];
+      if (!tables.includes(tbl)) tables.push(tbl);
+      break;
+    }
+  }
+
+  if (tables.length === 0) {
+    tables.push("table_name");
+    assumptions.push("Could not determine table name — used placeholder 'table_name'");
+  }
+
+  // Detect JOINs from "who have" or "with at least N" patterns
+  const joins: JoinClause[] = [];
+  const joinPatterns = [
+    /\bwho\s+(?:have|has)\s+(?:at\s+least\s+)?(?:\d+\s+)?(\w+)/i,
+    /\bwith\s+(?:at\s+least\s+)?(?:\d+\s+)?(\w+)/i,
+    /\bjoin(?:ed)?\s+(?:with\s+)?(?:the\s+)?(\w+)/i,
+  ];
+
+  for (const pattern of joinPatterns) {
+    const match = lower.match(pattern);
+    if (match && !stopWords.has(match[1])) {
+      const joinTable = match[1];
+      if (!tables.includes(joinTable) && joinTable !== tables[0]) {
+        joins.push({
+          table: joinTable,
+          onLeft: `${tables[0]}.id`,
+          onRight: `${joinTable}.${tables[0].replace(/s$/, "")}_id`,
+          type: "INNER",
+        });
+      }
+    }
+  }
+
+  // Extract conditions
+  const conditions: ConditionClause[] = [];
+
+  // "signed up this month" / "created this month"
+  if (/\b(?:this month|current month)\b/i.test(lower)) {
+    const colGuess = /\bsigned up\b/i.test(lower) ? "created_at" :
+                     /\bcreated\b/i.test(lower) ? "created_at" :
+                     /\bregistered\b/i.test(lower) ? "registered_at" :
+                     "created_at";
+    conditions.push({
+      column: colGuess,
+      operator: ">=",
+      value: "DATE_TRUNC('month', CURRENT_DATE)",
+      connector: "AND",
+    });
+  }
+
+  // "this year" / "current year"
+  if (/\b(?:this year|current year)\b/i.test(lower)) {
+    conditions.push({
+      column: "created_at",
+      operator: ">=",
+      value: "DATE_TRUNC('year', CURRENT_DATE)",
+      connector: "AND",
+    });
+  }
+
+  // "last N days"
+  const lastDaysMatch = lower.match(/\blast\s+(\d+)\s+days?\b/i);
+  if (lastDaysMatch) {
+    conditions.push({
+      column: "created_at",
+      operator: ">=",
+      value: `CURRENT_DATE - INTERVAL '${lastDaysMatch[1]} days'`,
+      connector: "AND",
+    });
+  }
+
+  // "older than N"
+  const olderMatch = lower.match(/\bolder\s+than\s+(\d+)/i);
+  if (olderMatch) {
+    conditions.push({
+      column: "age",
+      operator: ">",
+      value: olderMatch[1],
+      connector: "AND",
+    });
+  }
+
+  // "where X is Y" / "where X = Y"
+  const whereMatch = lower.match(/\bwhere\s+(\w+)\s+(?:is|=|equals?)\s+['"]?(\w+)['"]?/i);
+  if (whereMatch) {
+    conditions.push({
+      column: whereMatch[1],
+      operator: "=",
+      value: `'${whereMatch[2]}'`,
+      connector: "AND",
+    });
+  }
+
+  // "active" / "inactive" / "enabled" / "disabled"
+  if (/\bactive\b/i.test(lower) && !/\binactive\b/i.test(lower)) {
+    conditions.push({ column: "active", operator: "=", value: "TRUE", connector: "AND" });
+  }
+  if (/\binactive\b/i.test(lower)) {
+    conditions.push({ column: "active", operator: "=", value: "FALSE", connector: "AND" });
+  }
+
+  // "at least N"
+  const atLeastMatch = lower.match(/\bat\s+least\s+(\d+)\s+(\w+)/i);
+  let havingClause: { column: string; op: string; value: string } | null = null;
+  if (atLeastMatch) {
+    havingClause = {
+      column: atLeastMatch[2],
+      op: ">=",
+      value: atLeastMatch[1],
+    };
+  }
+
+  // "more than N"
+  const moreThanMatch = lower.match(/\bmore\s+than\s+(\d+)\s+(\w+)/i);
+  if (moreThanMatch && !havingClause) {
+    havingClause = {
+      column: moreThanMatch[2],
+      op: ">",
+      value: moreThanMatch[1],
+    };
+  }
+
+  // Aggregates
+  const aggregates: AggregateClause[] = [];
+  const groupBy: string[] = [];
+
+  if (action === "aggregate" || action === "count" || havingClause) {
+    if (/\baverage\b|\bavg\b/i.test(lower)) {
+      const avgMatch = lower.match(/\b(?:average|avg)\s+(\w+)/i);
+      aggregates.push({
+        func: "AVG",
+        column: avgMatch ? avgMatch[1] : "*",
+        alias: `avg_${avgMatch ? avgMatch[1] : "value"}`,
+      });
+    }
+    if (/\btotal\b|\bsum\b/i.test(lower)) {
+      const sumMatch = lower.match(/\b(?:total|sum)\s+(?:of\s+)?(\w+)/i);
+      aggregates.push({
+        func: "SUM",
+        column: sumMatch ? sumMatch[1] : "*",
+        alias: `total_${sumMatch ? sumMatch[1] : "value"}`,
+      });
+    }
+    if (/\bminimum\b|\bmin\b|\blowest\b/i.test(lower)) {
+      const minMatch = lower.match(/\b(?:minimum|min|lowest)\s+(\w+)/i);
+      aggregates.push({
+        func: "MIN",
+        column: minMatch ? minMatch[1] : "*",
+        alias: `min_${minMatch ? minMatch[1] : "value"}`,
+      });
+    }
+    if (/\bmaximum\b|\bmax\b|\bhighest\b/i.test(lower)) {
+      const maxMatch = lower.match(/\b(?:maximum|max|highest)\s+(\w+)/i);
+      aggregates.push({
+        func: "MAX",
+        column: maxMatch ? maxMatch[1] : "*",
+        alias: `max_${maxMatch ? maxMatch[1] : "value"}`,
+      });
+    }
+  }
+
+  // "per" or "for each" or "by" → GROUP BY
+  const perMatch = lower.match(/\b(?:per|for each|by|grouped by|group by)\s+(\w+)/i);
+  if (perMatch) {
+    groupBy.push(perMatch[1]);
+  }
+
+  // Detect DISTINCT
+  const distinct = /\bunique\b|\bdistinct\b/i.test(lower);
+
+  // Detect ORDER BY
+  const orderBy: OrderClause[] = [];
+  if (/\b(?:sorted|ordered|order)\s+by\s+(\w+)\s*(asc|desc|ascending|descending)?/i.test(lower)) {
+    const orderMatch = lower.match(
+      /\b(?:sorted|ordered|order)\s+by\s+(\w+)\s*(asc|desc|ascending|descending)?/i
+    );
+    if (orderMatch) {
+      orderBy.push({
+        column: orderMatch[1],
+        direction: orderMatch[2] && /desc/i.test(orderMatch[2]) ? "DESC" : "ASC",
+      });
+    }
+  }
+  if (/\bnewest\s+first\b/i.test(lower)) {
+    orderBy.push({ column: "created_at", direction: "DESC" });
+  }
+  if (/\boldest\s+first\b/i.test(lower)) {
+    orderBy.push({ column: "created_at", direction: "ASC" });
+  }
+
+  // Detect LIMIT
+  let limit: number | null = null;
+  const topMatch = lower.match(/\b(?:top|first|limit)\s+(\d+)/i);
+  if (topMatch) limit = parseInt(topMatch[1], 10);
+
+  // Columns
+  const columns: string[] = [];
+
+  // Build the intent
+  const intent: ParsedIntent = {
+    action,
+    tables,
+    columns,
+    conditions,
+    orderBy,
+    groupBy,
+    limit,
+    joins,
+    aggregates,
+    distinct,
+  };
+
+  return intent;
+}
+
+function buildSql(intent: ParsedIntent, dialect: Dialect): { sql: string; assumptions: string[]; warnings: string[] } {
+  const assumptions: string[] = [];
+  const warnings: string[] = [];
+  const parts: string[] = [];
+  const mainTable = intent.tables[0];
+
+  switch (intent.action) {
+    case "select": {
+      let selectCols = intent.columns.length > 0 ? intent.columns.join(", ") : "*";
+      if (intent.distinct) selectCols = `DISTINCT ${selectCols}`;
+      parts.push(`SELECT ${selectCols}`);
+      parts.push(`FROM ${mainTable}`);
+      break;
+    }
+    case "count": {
+      if (intent.groupBy.length > 0) {
+        parts.push(`SELECT ${intent.groupBy.join(", ")}, COUNT(*) AS count`);
+      } else {
+        parts.push("SELECT COUNT(*) AS total_count");
+      }
+      parts.push(`FROM ${mainTable}`);
+      break;
+    }
+    case "aggregate": {
+      const aggCols = intent.aggregates.map((a) => `${a.func}(${a.column}) AS ${a.alias}`);
+      const selectParts = intent.groupBy.length > 0
+        ? [...intent.groupBy, ...aggCols]
+        : aggCols;
+      parts.push(`SELECT ${selectParts.join(", ")}`);
+      parts.push(`FROM ${mainTable}`);
+      break;
+    }
+    case "insert": {
+      parts.push(`INSERT INTO ${mainTable} (column1, column2)`);
+      parts.push("VALUES ('value1', 'value2')");
+      assumptions.push("Placeholder columns and values used — replace with actual data");
+      break;
+    }
+    case "update": {
+      parts.push(`UPDATE ${mainTable}`);
+      parts.push("SET column1 = 'new_value'");
+      assumptions.push("Placeholder SET clause — replace with actual columns and values");
+      break;
+    }
+    case "delete": {
+      parts.push(`DELETE FROM ${mainTable}`);
+      break;
+    }
+  }
+
+  // JOINs
+  for (const join of intent.joins) {
+    parts.push(`${join.type} JOIN ${join.table}`);
+    parts.push(`  ON ${join.onLeft} = ${join.onRight}`);
+    assumptions.push(
+      `Assumed join condition: ${join.onLeft} = ${join.onRight} — adjust if your schema differs`
+    );
+  }
+
+  // WHERE
+  if (intent.conditions.length > 0) {
+    const condStrs = intent.conditions.map((c, i) => {
+      const prefix = i === 0 ? "WHERE" : `  ${c.connector}`;
+      return `${prefix} ${c.column} ${c.operator} ${c.value}`;
+    });
+    parts.push(...condStrs);
+  } else if (intent.action === "update" || intent.action === "delete") {
+    warnings.push("No WHERE clause detected — this will affect ALL rows");
+  }
+
+  // GROUP BY
+  if (intent.groupBy.length > 0) {
+    parts.push(`GROUP BY ${intent.groupBy.join(", ")}`);
+  } else if (intent.joins.length > 0 && intent.action === "select") {
+    // If there's a join that implies aggregation, add GROUP BY
+    parts.push(`GROUP BY ${mainTable}.id`);
+    assumptions.push(`Added GROUP BY ${mainTable}.id — adjust based on your primary key`);
+  }
+
+  // HAVING (for "at least N" type conditions)
+  const havingAgg = intent.joins.length > 0 ? intent.joins[0] : null;
+  if (havingAgg) {
+    // Check for "at least" or "more than" in the original conditions context
+    // This is handled via the aggregates/havingClause approach
+  }
+
+  // ORDER BY
+  if (intent.orderBy.length > 0) {
+    parts.push(
+      `ORDER BY ${intent.orderBy.map((o) => `${o.column} ${o.direction}`).join(", ")}`
+    );
+  }
+
+  // LIMIT
+  if (intent.limit !== null) {
+    if (dialect === "mysql" || dialect === "postgresql" || dialect === "sqlite" || dialect === "generic") {
+      parts.push(`LIMIT ${intent.limit}`);
+    }
+  }
+
+  return {
+    sql: parts.join("\n"),
+    assumptions,
+    warnings,
+  };
+}
+
+export function queryBuilder(
+  description: string,
+  dialect: string = "postgresql",
+  schemaHint: string = ""
+): QueryBuildResult {
+  const d = (["mysql", "postgresql", "sqlite"].includes(dialect)
+    ? dialect
+    : "generic") as Dialect;
+
+  const intent = parseNaturalLanguage(description);
+
+  // If schema hint is provided, try to use real column names
+  if (schemaHint) {
+    // Simple extraction of table and column names from schema hint
+    const tableMatch = schemaHint.match(/\b(\w+)\s*\(/g);
+    if (tableMatch) {
+      const hintTables = tableMatch.map((t) => t.replace(/\s*\(/, "").trim());
+      // If the first detected table is a placeholder, try to find a real one
+      if (intent.tables[0] === "table_name" && hintTables.length > 0) {
+        intent.tables[0] = hintTables[0];
+      }
+    }
+  }
+
+  const { sql, assumptions, warnings } = buildSql(intent, d);
+
+  // Generate explanation
+  const explanation = [
+    `Generates a ${intent.action.toUpperCase()} query against the "${intent.tables[0]}" table.`,
+    intent.joins.length > 0
+      ? `Joins with ${intent.joins.map((j) => j.table).join(", ")}.`
+      : "",
+    intent.conditions.length > 0
+      ? `Filters: ${intent.conditions.map((c) => `${c.column} ${c.operator} ${c.value}`).join(", ")}.`
+      : "",
+    intent.orderBy.length > 0
+      ? `Sorted by ${intent.orderBy.map((o) => `${o.column} ${o.direction}`).join(", ")}.`
+      : "",
+    intent.limit ? `Limited to ${intent.limit} results.` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return {
+    sql,
+    dialect: d,
+    explanation,
+    assumptions,
+    warnings,
+  };
+}