@rog0x/mcp-database-tools 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# mcp-database-tools
+
+MCP server providing SQL and database tools for AI agents. All analysis is performed on SQL text — no actual database connection required.
+
+## Tools
+
+### sql_format
+Format and prettify SQL queries with proper indentation, uppercased keywords, and aligned columns. Supports MySQL, PostgreSQL, and SQLite syntax.
+
+### sql_explain
+Take a SQL query and explain what it does in plain English, step by step. Identifies query type, tables, columns, conditions, and provides optimization tips.
+
+### schema_analyze
+Parse CREATE TABLE statements to extract tables, columns, types, constraints, foreign keys, and indexes. Generates an ER diagram in Mermaid format.
+
+### query_build
+Build SQL queries from natural language descriptions. Supports common patterns like filtering by date, aggregation, joins, ordering, and pagination.
+
+### migration_generate
+Compare two schemas (old vs new CREATE TABLE statements) and generate ALTER TABLE migration statements. Produces both up (forward) and down (rollback) migrations.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "database-tools": {
+      "command": "node",
+      "args": ["path/to/mcp-database-tools/dist/index.js"]
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+npm start
+```
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm start        # Run the server
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const sql_formatter_js_1 = require("./tools/sql-formatter.js");
+const sql_explainer_js_1 = require("./tools/sql-explainer.js");
+const schema_analyzer_js_1 = require("./tools/schema-analyzer.js");
+const query_builder_js_1 = require("./tools/query-builder.js");
+const migration_generator_js_1 = require("./tools/migration-generator.js");
+const server = new index_js_1.Server({
+    name: "mcp-database-tools",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "sql_format",
+            description: "Format and prettify SQL queries with proper indentation, uppercased keywords, and aligned columns. Supports MySQL, PostgreSQL, and SQLite syntax.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: {
+                        type: "string",
+                        description: "The SQL query to format",
+                    },
+                    dialect: {
+                        type: "string",
+                        enum: ["mysql", "postgresql", "sqlite", "generic"],
+                        description: "SQL dialect (default: generic)",
+                    },
+                    indent_size: {
+                        type: "number",
+                        description: "Number of spaces for indentation (default: 2)",
+                    },
+                    uppercase: {
+                        type: "boolean",
+                        description: "Uppercase SQL keywords (default: true)",
+                    },
+                    align_columns: {
+                        type: "boolean",
+                        description: "Place each SELECT column on its own line (default: true)",
+                    },
+                },
+                required: ["sql"],
+            },
+        },
+        {
+            name: "sql_explain",
+            description: "Take a SQL query and explain what it does in plain English, step by step. Identifies tables, columns, conditions, and provides optimization tips.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: {
+                        type: "string",
+                        description: "The SQL query to explain",
+                    },
+                },
+                required: ["sql"],
+            },
+        },
+        {
+            name: "schema_analyze",
+            description: "Parse CREATE TABLE statements to extract tables, columns, types, constraints, foreign keys, and indexes. Generates an ER diagram in Mermaid format.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: {
+                        type: "string",
+                        description: "SQL containing CREATE TABLE statements (can include multiple tables)",
+                    },
+                },
+                required: ["sql"],
+            },
+        },
+        {
+            name: "query_build",
+            description: 'Build SQL queries from natural language descriptions. Example: "get all users who signed up this month and have at least 3 orders" generates the corresponding SQL.',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    description: {
+                        type: "string",
+                        description: "Natural language description of the desired query",
+                    },
+                    dialect: {
+                        type: "string",
+                        enum: ["mysql", "postgresql", "sqlite", "generic"],
+                        description: "SQL dialect (default: postgresql)",
+                    },
+                    schema_hint: {
+                        type: "string",
+                        description: "Optional schema context (table/column names) to improve accuracy",
+                    },
+                },
+                required: ["description"],
+            },
+        },
+        {
+            name: "migration_generate",
+            description: "Compare two schemas (old vs new CREATE TABLE statements) and generate ALTER TABLE migration statements with both up and down migrations.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    old_schema: {
+                        type: "string",
+                        description: "The old/current schema (CREATE TABLE statements)",
+                    },
+                    new_schema: {
+                        type: "string",
+                        description: "The new/target schema (CREATE TABLE statements)",
+                    },
+                    dialect: {
+                        type: "string",
+                        enum: ["mysql", "postgresql", "sqlite", "generic"],
+                        description: "SQL dialect for migration syntax (default: postgresql)",
+                    },
+                },
+                required: ["old_schema", "new_schema"],
+            },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "sql_format": {
+                const result = (0, sql_formatter_js_1.sqlFormatter)(args?.sql, args?.dialect, args?.indent_size, args?.uppercase, args?.align_columns);
+                return {
+                    content: [{ type: "text", text: result }],
+                };
+            }
+            case "sql_explain": {
+                const result = (0, sql_explainer_js_1.sqlExplainer)(args?.sql);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            case "schema_analyze": {
+                const result = (0, schema_analyzer_js_1.schemaAnalyzer)(args?.sql);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            case "query_build": {
+                const result = (0, query_builder_js_1.queryBuilder)(args?.description, args?.dialect, args?.schema_hint);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            case "migration_generate": {
+                const result = (0, migration_generator_js_1.migrationGenerator)(args?.old_schema, args?.new_schema, args?.dialect);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Database Tools server running on stdio");
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rog0x/mcp-database-tools",
+  "version": "1.0.0",
+  "description": "MCP server providing SQL and database tools for AI agents - format, explain, analyze, build, and migrate SQL without a DB connection",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-database-tools": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "ai",
+    "sql",
+    "database",
+    "formatter",
+    "migration",
+    "schema"
+  ],
+  "author": "rog0x",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rog0x/mcp-database-tools"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { sqlFormatter } from "./tools/sql-formatter.js";
+import { sqlExplainer } from "./tools/sql-explainer.js";
+import { schemaAnalyzer } from "./tools/schema-analyzer.js";
+import { queryBuilder } from "./tools/query-builder.js";
+import { migrationGenerator } from "./tools/migration-generator.js";
+
+const server = new Server(
+  {
+    name: "mcp-database-tools",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "sql_format",
+      description:
+        "Format and prettify SQL queries with proper indentation, uppercased keywords, and aligned columns. Supports MySQL, PostgreSQL, and SQLite syntax.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          sql: {
+            type: "string",
+            description: "The SQL query to format",
+          },
+          dialect: {
+            type: "string",
+            enum: ["mysql", "postgresql", "sqlite", "generic"],
+            description: "SQL dialect (default: generic)",
+          },
+          indent_size: {
+            type: "number",
+            description: "Number of spaces for indentation (default: 2)",
+          },
+          uppercase: {
+            type: "boolean",
+            description: "Uppercase SQL keywords (default: true)",
+          },
+          align_columns: {
+            type: "boolean",
+            description:
+              "Place each SELECT column on its own line (default: true)",
+          },
+        },
+        required: ["sql"],
+      },
+    },
+    {
+      name: "sql_explain",
+      description:
+        "Take a SQL query and explain what it does in plain English, step by step. Identifies tables, columns, conditions, and provides optimization tips.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          sql: {
+            type: "string",
+            description: "The SQL query to explain",
+          },
+        },
+        required: ["sql"],
+      },
+    },
+    {
+      name: "schema_analyze",
+      description:
+        "Parse CREATE TABLE statements to extract tables, columns, types, constraints, foreign keys, and indexes. Generates an ER diagram in Mermaid format.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          sql: {
+            type: "string",
+            description:
+              "SQL containing CREATE TABLE statements (can include multiple tables)",
+          },
+        },
+        required: ["sql"],
+      },
+    },
+    {
+      name: "query_build",
+      description:
+        'Build SQL queries from natural language descriptions. Example: "get all users who signed up this month and have at least 3 orders" generates the corresponding SQL.',
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          description: {
+            type: "string",
+            description: "Natural language description of the desired query",
+          },
+          dialect: {
+            type: "string",
+            enum: ["mysql", "postgresql", "sqlite", "generic"],
+            description: "SQL dialect (default: postgresql)",
+          },
+          schema_hint: {
+            type: "string",
+            description:
+              "Optional schema context (table/column names) to improve accuracy",
+          },
+        },
+        required: ["description"],
+      },
+    },
+    {
+      name: "migration_generate",
+      description:
+        "Compare two schemas (old vs new CREATE TABLE statements) and generate ALTER TABLE migration statements with both up and down migrations.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          old_schema: {
+            type: "string",
+            description: "The old/current schema (CREATE TABLE statements)",
+          },
+          new_schema: {
+            type: "string",
+            description: "The new/target schema (CREATE TABLE statements)",
+          },
+          dialect: {
+            type: "string",
+            enum: ["mysql", "postgresql", "sqlite", "generic"],
+            description: "SQL dialect for migration syntax (default: postgresql)",
+          },
+        },
+        required: ["old_schema", "new_schema"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "sql_format": {
+        const result = sqlFormatter(
+          args?.sql as string,
+          args?.dialect as string | undefined,
+          args?.indent_size as number | undefined,
+          args?.uppercase as boolean | undefined,
+          args?.align_columns as boolean | undefined
+        );
+        return {
+          content: [{ type: "text", text: result }],
+        };
+      }
+
+      case "sql_explain": {
+        const result = sqlExplainer(args?.sql as string);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      }
+
+      case "schema_analyze": {
+        const result = schemaAnalyzer(args?.sql as string);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      }
+
+      case "query_build": {
+        const result = queryBuilder(
+          args?.description as string,
+          args?.dialect as string | undefined,
+          args?.schema_hint as string | undefined
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      }
+
+      case "migration_generate": {
+        const result = migrationGenerator(
+          args?.old_schema as string,
+          args?.new_schema as string,
+          args?.dialect as string | undefined
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: any) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP Database Tools server running on stdio");
+}
+
+main().catch(console.error);