truss-db-mcp 1.0.0

package/src/lib/query-optimizer.ts

@@ -0,0 +1,191 @@
+import { explainQuery, getDb, listTables } from './connection.js';
+import type { QueryOptimizationResult, OptimizationSuggestion } from '../types.js';
+
+export function optimizeQuery(sql: string): QueryOptimizationResult {
+  const explainPlan = explainQuery(sql);
+  const suggestions = analyzeExplainPlan(explainPlan, sql);
+  const estimatedImprovement = estimateImprovement(suggestions);
+
+  return {
+    explainPlan,
+    suggestions,
+    estimatedImprovement,
+  };
+}
+
+function analyzeExplainPlan(plan: string, sql: string): OptimizationSuggestion[] {
+  const suggestions: OptimizationSuggestion[] = [];
+  const lines = plan.split('\n');
+
+  // Detect full table scans
+  const scanPattern = /SCAN (?:TABLE )?(\w+)/gi;
+  const scannedTables = new Set<string>();
+
+  for (const line of lines) {
+    let match;
+    while ((match = scanPattern.exec(line)) !== null) {
+      scannedTables.add(match[1]);
+    }
+  }
+
+  // For each full scan, check if WHERE clause references columns that could be indexed
+  if (scannedTables.size > 0) {
+    const whereColumns = extractWhereColumns(sql);
+
+    for (const table of scannedTables) {
+      const tableCols = whereColumns.filter(wc => {
+        // Column might be qualified (table.col) or unqualified
+        return wc.table === table || wc.table === null;
+      });
+
+      if (tableCols.length > 0) {
+        const existingIndexes = getExistingIndexes(table);
+        const indexedColumns = new Set(existingIndexes.flatMap(idx => idx.columns));
+
+        for (const col of tableCols) {
+          if (!indexedColumns.has(col.column)) {
+            suggestions.push({
+              type: 'index',
+              description: `Table "${table}" is doing a full scan. Consider adding an index on column "${col.column}" used in WHERE clause.`,
+              sql: `CREATE INDEX idx_${table}_${col.column} ON "${table}"("${col.column}");`,
+            });
+          }
+        }
+
+        if (tableCols.length === 0) {
+          suggestions.push({
+            type: 'warning',
+            description: `Full table scan on "${table}". This may be intentional if you need all rows, but can be slow on large tables.`,
+          });
+        }
+      } else {
+        suggestions.push({
+          type: 'warning',
+          description: `Full table scan on "${table}". No WHERE clause filtering detected for this table.`,
+        });
+      }
+    }
+  }
+
+  // Detect subquery patterns that could be JOINs
+  if (/\bIN\s*\(\s*SELECT\b/i.test(sql)) {
+    suggestions.push({
+      type: 'rewrite',
+      description: 'Consider rewriting IN (SELECT ...) as a JOIN, which is often faster for large datasets.',
+    });
+  }
+
+  // Detect SELECT * usage
+  if (/SELECT\s+\*/i.test(sql)) {
+    suggestions.push({
+      type: 'rewrite',
+      description: 'Consider selecting only the columns you need instead of SELECT *. This reduces I/O and memory usage.',
+    });
+  }
+
+  // Detect missing LIMIT
+  if (!/\bLIMIT\b/i.test(sql) && /^\s*SELECT\b/i.test(sql)) {
+    suggestions.push({
+      type: 'warning',
+      description: 'Query has no LIMIT clause. For large tables, consider adding LIMIT to avoid returning excessive rows.',
+    });
+  }
+
+  // Detect LIKE with leading wildcard
+  if (/LIKE\s+['"]%/i.test(sql)) {
+    suggestions.push({
+      type: 'warning',
+      description: 'LIKE pattern with leading wildcard (%) prevents index usage. Consider full-text search for better performance.',
+    });
+  }
+
+  // Detect ORDER BY without index
+  const orderByMatch = sql.match(/ORDER\s+BY\s+(\w+(?:\.\w+)?)/i);
+  if (orderByMatch) {
+    const orderCol = orderByMatch[1].includes('.') ? orderByMatch[1].split('.')[1] : orderByMatch[1];
+    suggestions.push({
+      type: 'index',
+      description: `If sorting is slow, consider indexing the ORDER BY column "${orderCol}".`,
+    });
+  }
+
+  // If no scan detected, query uses indexes well
+  if (scannedTables.size === 0 && suggestions.length === 0) {
+    suggestions.push({
+      type: 'rewrite',
+      description: 'Query already uses indexes effectively. No major optimizations needed.',
+    });
+  }
+
+  return suggestions;
+}
+
+interface WhereColumn {
+  table: string | null;
+  column: string;
+}
+
+function extractWhereColumns(sql: string): WhereColumn[] {
+  const columns: WhereColumn[] = [];
+
+  // Match WHERE and AND/OR conditions
+  const whereMatch = sql.match(/WHERE\s+([\s\S]*?)(?:ORDER\s+BY|GROUP\s+BY|HAVING|LIMIT|$)/i);
+  if (!whereMatch) return columns;
+
+  const whereClause = whereMatch[1];
+
+  // Extract column references from conditions
+  const colPattern = /(\w+)\.(\w+)\s*(?:=|!=|<>|>=|<=|>|<|LIKE|IN|IS|BETWEEN)/gi;
+  let match;
+
+  while ((match = colPattern.exec(whereClause)) !== null) {
+    columns.push({ table: match[1], column: match[2] });
+  }
+
+  // Also match unqualified columns
+  const unqualPattern = /(?:^|\bAND\b|\bOR\b|\bWHERE\b)\s+(\w+)\s*(?:=|!=|<>|>=|<=|>|<|LIKE|IN|IS|BETWEEN)/gi;
+  while ((match = unqualPattern.exec(whereClause)) !== null) {
+    if (!['AND', 'OR', 'NOT', 'WHERE', 'BETWEEN', 'IN', 'LIKE', 'IS'].includes(match[1].toUpperCase())) {
+      columns.push({ table: null, column: match[1] });
+    }
+  }
+
+  return columns;
+}
+
+function getExistingIndexes(tableName: string): Array<{ name: string; columns: string[] }> {
+  try {
+    const db = getDb();
+    const indexes = db.pragma(`index_list("${tableName}")`) as Array<{
+      name: string;
+      unique: number;
+    }>;
+
+    return indexes.map(idx => {
+      const cols = db.pragma(`index_info("${idx.name}")`) as Array<{ name: string }>;
+      return { name: idx.name, columns: cols.map(c => c.name) };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function estimateImprovement(suggestions: OptimizationSuggestion[]): string {
+  const indexSuggestions = suggestions.filter(s => s.type === 'index').length;
+  const rewriteSuggestions = suggestions.filter(s => s.type === 'rewrite').length;
+  const warnings = suggestions.filter(s => s.type === 'warning').length;
+
+  if (indexSuggestions === 0 && rewriteSuggestions === 0) {
+    return 'Query is already well-optimized.';
+  }
+
+  if (indexSuggestions > 0) {
+    return `Adding ${indexSuggestions} index(es) could improve performance significantly, especially on large tables (10x-100x for indexed lookups vs full scans).`;
+  }
+
+  if (rewriteSuggestions > 0) {
+    return 'Query rewrite may improve performance by 2x-10x depending on data size.';
+  }
+
+  return 'Minor optimizations possible. See suggestions for details.';
+}

package/src/tools/connect.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { connectSqlite } from '../lib/connection.js';
+
+export function registerConnect(server: McpServer): void {
+  server.tool(
+    'connect',
+    'Connect to a SQLite database file. Provide the path to the .db or .sqlite file.',
+    {
+      path: z.string().describe('Path to the SQLite database file'),
+    },
+    async ({ path }) => {
+      try {
+        const info = connectSqlite(path);
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              connected: info.connected,
+              dialect: info.dialect,
+              tables: info.tables,
+              tableCount: info.tables.length,
+              version: info.version,
+              path: info.path,
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              connected: false,
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/describe-table.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { describeTable, isConnected } from '../lib/connection.js';
+
+export function registerDescribeTable(server: McpServer): void {
+  server.tool(
+    'describe_table',
+    'Get detailed schema for a table: columns, types, indexes, foreign keys, and CREATE statement.',
+    {
+      table: z.string().describe('Name of the table to describe'),
+    },
+    async ({ table }) => {
+      try {
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const schema = describeTable(table);
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              name: schema.name,
+              row_count: schema.rowCount,
+              columns: schema.columns.map(c => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable,
+                default_value: c.defaultValue,
+                primary_key: c.primaryKey,
+              })),
+              indexes: schema.indexes.map(i => ({
+                name: i.name,
+                columns: i.columns,
+                unique: i.unique,
+              })),
+              foreign_keys: schema.foreignKeys.map(fk => ({
+                column: fk.column,
+                references: `${fk.referencedTable}(${fk.referencedColumn})`,
+              })),
+              create_sql: schema.createSql,
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/export-data.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeReadOnlyQuery, isConnected } from '../lib/connection.js';
+import { requirePro } from '../lib/license.js';
+
+function toCsv(rows: Record<string, unknown>[], columns: string[]): string {
+  if (rows.length === 0) return '';
+
+  const header = columns.map(escapeCsvField).join(',');
+  const dataRows = rows.map(row =>
+    columns.map(col => escapeCsvField(String(row[col] ?? ''))).join(',')
+  );
+
+  return [header, ...dataRows].join('\n');
+}
+
+function escapeCsvField(field: string): string {
+  if (field.includes(',') || field.includes('"') || field.includes('\n')) {
+    return `"${field.replace(/"/g, '""')}"`;
+  }
+  return field;
+}
+
+export function registerExportData(server: McpServer): void {
+  server.tool(
+    'export_data',
+    'Export query results as CSV or JSON. Requires Pro license.',
+    {
+      sql: z.string().describe('SELECT query to export'),
+      format: z.enum(['csv', 'json']).describe('Export format: csv or json'),
+    },
+    async ({ sql, format }) => {
+      try {
+        await requirePro();
+
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        // Always read-only for exports
+        const result = executeReadOnlyQuery(sql);
+
+        let data: string;
+        if (format === 'csv') {
+          data = toCsv(result.rows, result.columns);
+        } else {
+          data = JSON.stringify(result.rows, null, 2);
+        }
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              data,
+              row_count: result.rowCount,
+              format,
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/generate-migration.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requirePro } from '../lib/license.js';
+import { generateMigrationSql } from '../lib/ai-query.js';
+
+export function registerGenerateMigration(server: McpServer): void {
+  server.tool(
+    'generate_migration',
+    'Generate SQL migration (up + down) from a natural language description. Requires Pro license and AI API key.',
+    {
+      description: z.string().describe('Description of the database change (e.g. "add email column to users table")'),
+      dialect: z.enum(['sqlite', 'postgresql', 'mysql']).optional().describe('SQL dialect (default: sqlite)'),
+    },
+    async ({ description, dialect }) => {
+      try {
+        await requirePro();
+
+        const result = await generateMigrationSql(description, dialect ?? 'sqlite');
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              up_sql: result.upSql,
+              down_sql: result.downSql,
+              dialect: dialect ?? 'sqlite',
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/list-tables.ts

@@ -0,0 +1,52 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { listTables, isConnected } from '../lib/connection.js';
+
+export function registerListTables(server: McpServer): void {
+  server.tool(
+    'list_tables',
+    'List all tables in the connected database with row counts and column info.',
+    {},
+    async () => {
+      try {
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const tables = listTables();
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify(tables.map(t => ({
+              name: t.name,
+              columns: t.columns.map(c => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable,
+              })),
+              row_count: t.rowCount,
+            })), null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/natural-language-query.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { isConnected } from '../lib/connection.js';
+import { requirePro } from '../lib/license.js';
+import { naturalLanguageToSql } from '../lib/ai-query.js';
+
+export function registerNaturalLanguageQuery(server: McpServer): void {
+  server.tool(
+    'natural_language_query',
+    'Convert a natural language question to SQL and execute it. Requires Pro license and ANTHROPIC_API_KEY or OPENAI_API_KEY.',
+    {
+      question: z.string().describe('Natural language question about your data'),
+      tables: z.array(z.string()).optional().describe('Limit query generation to these tables'),
+    },
+    async ({ question, tables }) => {
+      try {
+        await requirePro();
+
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const result = await naturalLanguageToSql(question, tables);
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              sql: result.sql,
+              explanation: result.explanation,
+              results: {
+                rows: result.results.rows,
+                columns: result.results.columns,
+                row_count: result.results.rowCount,
+                execution_time_ms: result.results.executionTimeMs,
+              },
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/optimize-query.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { isConnected } from '../lib/connection.js';
+import { requirePro } from '../lib/license.js';
+import { optimizeQuery } from '../lib/query-optimizer.js';
+
+export function registerOptimizeQuery(server: McpServer): void {
+  server.tool(
+    'optimize_query',
+    'Analyze a SQL query for performance issues. Shows EXPLAIN plan, suggests indexes, and estimates improvement. Requires Pro license.',
+    {
+      sql: z.string().describe('SQL query to analyze'),
+    },
+    async ({ sql }) => {
+      try {
+        await requirePro();
+
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const result = optimizeQuery(sql);
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              explain_plan: result.explainPlan,
+              suggestions: result.suggestions.map(s => ({
+                type: s.type,
+                description: s.description,
+                ...(s.sql ? { suggested_sql: s.sql } : {}),
+              })),
+              estimated_improvement: result.estimatedImprovement,
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/query.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { executeReadOnlyQuery, executeQuery, isConnected, isWriteQuery } from '../lib/connection.js';
+import { getLicenseStatus } from '../lib/license.js';
+
+export function registerQuery(server: McpServer): void {
+  server.tool(
+    'query',
+    'Execute a SQL query. Free tier: SELECT only. Pro tier: full read/write with confirmation flag.',
+    {
+      sql: z.string().describe('SQL query to execute'),
+      params: z.array(z.unknown()).optional().describe('Query parameters for prepared statement'),
+      confirm_write: z.boolean().optional().describe('Set to true to confirm write operations (Pro tier only)'),
+    },
+    async ({ sql, params, confirm_write }) => {
+      try {
+        if (!isConnected()) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                error: 'No database connected. Use the connect tool first.',
+              }),
+            }],
+            isError: true,
+          };
+        }
+
+        const license = await getLicenseStatus();
+        const isWrite = isWriteQuery(sql);
+
+        // Free tier: read-only only
+        if (license.tier === 'free') {
+          const result = executeReadOnlyQuery(sql, params ?? []);
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                rows: result.rows,
+                columns: result.columns,
+                row_count: result.rowCount,
+                execution_time_ms: result.executionTimeMs,
+              }, null, 2),
+            }],
+          };
+        }
+
+        // Pro tier: write operations require confirmation
+        if (isWrite && !confirm_write) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify({
+                warning: 'This is a write operation. Set confirm_write: true to execute.',
+                sql: sql,
+                operation_type: sql.trim().split(/\s+/)[0].toUpperCase(),
+              }, null, 2),
+            }],
+          };
+        }
+
+        const result = executeQuery(sql, params ?? []);
+
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              rows: result.rows,
+              columns: result.columns,
+              row_count: result.rowCount,
+              execution_time_ms: result.executionTimeMs,
+              ...(isWrite ? { write_operation: true } : {}),
+            }, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              error: err instanceof Error ? err.message : String(err),
+            }),
+          }],
+          isError: true,
+        };
+      }
+    }
+  );
+}