mcp-db-analyzer 0.2.0

package/build/index.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { listTables, inspectTable } from "./analyzers/schema.js";
+import { analyzeIndexUsage, findMissingIndexes } from "./analyzers/indexes.js";
+import { explainQuery } from "./analyzers/query.js";
+import { analyzeTableBloat } from "./analyzers/bloat.js";
+import { suggestMissingIndexes } from "./analyzers/suggestions.js";
+import { analyzeSlowQueries } from "./analyzers/slow-queries.js";
+import { analyzeConnections } from "./analyzers/connections.js";
+import { analyzeTableRelationships } from "./analyzers/relationships.js";
+import { analyzeVacuum } from "./analyzers/vacuum.js";
+import { closePool, initDriver } from "./db.js";
+import { formatToolError } from "./errors.js";
+import { validateLicense, formatUpgradePrompt } from "./license.js";
+// License check (reads MCP_LICENSE_KEY env var once at startup)
+const license = validateLicense(process.env.MCP_LICENSE_KEY, "db-analyzer");
+// Handle --help
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(`mcp-db-analyzer v0.1.0 — MCP server for database analysis
+
+Usage:
+  mcp-db-analyzer [options]
+
+Options:
+  --driver <type>   Database driver: postgres (default), mysql, sqlite
+  --help, -h        Show this help message
+
+Environment:
+  DATABASE_URL      Connection string (required)
+  DB_DRIVER         Alternative to --driver flag
+  PGHOST/PGPORT/... PostgreSQL individual variables
+  MYSQL_HOST/...    MySQL individual variables
+
+Tools provided:
+  inspect_schema          List tables or inspect a specific table
+  analyze_indexes         Find unused and missing indexes
+  explain_query           EXPLAIN/EXPLAIN ANALYZE for SQL queries
+  analyze_table_bloat     Detect dead tuples and fragmentation
+  suggest_missing_indexes Actionable index recommendations
+  analyze_slow_queries    Find slowest queries from pg_stat_statements
+  analyze_connections     Detect idle-in-transaction, long queries, lock waits
+  analyze_table_relationships  FK dependency graph, orphans, cascade chains
+  analyze_vacuum          PostgreSQL vacuum health, dead tuples, autovacuum config`);
+    process.exit(0);
+}
+// Parse --driver flag from CLI args or DB_DRIVER env var
+const VALID_DRIVERS = new Set(["postgres", "mysql", "sqlite"]);
+function detectDriver() {
+    const driverArg = process.argv.find((a) => a.startsWith("--driver="));
+    if (driverArg) {
+        const val = driverArg.split("=")[1];
+        if (VALID_DRIVERS.has(val))
+            return val;
+        console.error(`Unknown driver: ${val}. Use 'postgres', 'mysql', or 'sqlite'.`);
+        process.exit(1);
+    }
+    const driverIdx = process.argv.indexOf("--driver");
+    if (driverIdx !== -1 && process.argv[driverIdx + 1]) {
+        const val = process.argv[driverIdx + 1];
+        if (VALID_DRIVERS.has(val))
+            return val;
+        console.error(`Unknown driver: ${val}. Use 'postgres', 'mysql', or 'sqlite'.`);
+        process.exit(1);
+    }
+    const envDriver = process.env.DB_DRIVER;
+    if (envDriver && VALID_DRIVERS.has(envDriver))
+        return envDriver;
+    return "postgres";
+}
+const server = new McpServer({
+    name: "mcp-db-analyzer",
+    version: "0.1.0",
+});
+// --- Tool: inspect_schema ---
+server.tool("inspect_schema", "List all tables in a schema with row counts and sizes, or inspect a specific table's columns, types, constraints, and foreign keys.", {
+    table: z
+        .string()
+        .optional()
+        .describe("Specific table name to inspect. Omit to list all tables."),
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to inspect (default: public)"),
+}, async ({ table, schema }) => {
+    try {
+        const result = table
+            ? await inspectTable(table, schema)
+            : await listTables(schema);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("inspecting schema", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: analyze_indexes ---
+server.tool("analyze_indexes", "Analyze index usage statistics to find unused indexes wasting space and missing indexes causing slow sequential scans. Also detects unindexed foreign keys.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to analyze (default: public)"),
+    mode: z
+        .enum(["usage", "missing", "all"])
+        .default("all")
+        .describe("Analysis mode: 'usage' for unused index detection, 'missing' for missing index suggestions, 'all' for both"),
+}, async ({ schema, mode }) => {
+    try {
+        const parts = [];
+        if (mode === "usage" || mode === "all") {
+            parts.push(await analyzeIndexUsage(schema));
+        }
+        if (mode === "missing" || mode === "all") {
+            parts.push(await findMissingIndexes(schema));
+        }
+        return { content: [{ type: "text", text: parts.join("\n\n---\n\n") }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing indexes", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: explain_query ---
+server.tool("explain_query", "Run EXPLAIN on a SQL query and return a formatted plan with cost estimates, node types, and optimization warnings. Optionally runs EXPLAIN ANALYZE for actual execution statistics (read-only queries only).", {
+    sql: z.string().describe("The SQL query to explain"),
+    analyze: z
+        .boolean()
+        .default(false)
+        .describe("Run EXPLAIN ANALYZE to get actual execution times (executes the query). Only allowed for SELECT queries."),
+}, async ({ sql, analyze }) => {
+    try {
+        const result = await explainQuery(sql, analyze);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("explaining query", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: analyze_table_bloat ---
+server.tool("analyze_table_bloat", "Analyze table bloat by checking dead tuple ratios (PostgreSQL) or InnoDB fragmentation (MySQL), vacuum history, and table sizes.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to analyze (default: public)"),
+}, async ({ schema }) => {
+    try {
+        const result = await analyzeTableBloat(schema);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing table bloat", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: suggest_missing_indexes ---
+server.tool("suggest_missing_indexes", "Find tables with high sequential scan counts and zero index usage, cross-referenced with unused indexes wasting space. Provides actionable CREATE INDEX and DROP INDEX recommendations.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to analyze (default: public)"),
+}, async ({ schema }) => {
+    if (!license.isPro) {
+        return {
+            content: [{
+                    type: "text",
+                    text: formatUpgradePrompt("suggest_missing_indexes", "Actionable index recommendations with:\n" +
+                        "- Tables with high sequential scan counts\n" +
+                        "- Cross-referenced unused indexes wasting space\n" +
+                        "- Ready-to-run CREATE INDEX and DROP INDEX statements"),
+                }],
+        };
+    }
+    try {
+        const result = await suggestMissingIndexes(schema);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("suggesting indexes", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: analyze_slow_queries ---
+server.tool("analyze_slow_queries", "Find the slowest queries using pg_stat_statements (PostgreSQL) or performance_schema (MySQL). Shows execution times, call counts, and optimization recommendations.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema (default: public)"),
+    limit: z
+        .number()
+        .default(10)
+        .describe("Number of slow queries to return (default: 10)"),
+}, async ({ schema, limit }) => {
+    if (!license.isPro) {
+        return {
+            content: [{
+                    type: "text",
+                    text: formatUpgradePrompt("analyze_slow_queries", "Slow query analysis with:\n" +
+                        "- Top queries ranked by total execution time\n" +
+                        "- Call counts, mean/max times, rows returned\n" +
+                        "- Optimization recommendations"),
+                }],
+        };
+    }
+    try {
+        const result = await analyzeSlowQueries(schema, limit);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing slow queries", err),
+                },
+            ],
+        };
+    }
+});
+// Tool 7: analyze_connections
+server.tool("analyze_connections", "Analyze active database connections. Detects idle-in-transaction sessions, long-running queries, lock contention, and connection pool utilization. PostgreSQL and MySQL only.", {}, async () => {
+    if (!license.isPro) {
+        return {
+            content: [{
+                    type: "text",
+                    text: formatUpgradePrompt("analyze_connections", "Connection analysis with:\n" +
+                        "- Idle-in-transaction session detection\n" +
+                        "- Long-running query identification\n" +
+                        "- Lock contention analysis\n" +
+                        "- Connection pool utilization metrics"),
+                }],
+        };
+    }
+    try {
+        const result = await analyzeConnections();
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing connections", err),
+                },
+            ],
+        };
+    }
+});
+// Tool 8: analyze_table_relationships
+server.tool("analyze_table_relationships", "Analyze foreign key relationships between tables. Builds a dependency graph showing entity connectivity, orphan tables (no FKs), cascading delete chains, and hub entities. Useful for understanding schema design and impact analysis.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to analyze (default: public)"),
+}, async ({ schema }) => {
+    if (!license.isPro) {
+        return {
+            content: [{
+                    type: "text",
+                    text: formatUpgradePrompt("analyze_table_relationships", "Table relationship analysis with:\n" +
+                        "- Foreign key dependency graph\n" +
+                        "- Orphan table detection\n" +
+                        "- Cascading delete chain analysis\n" +
+                        "- Hub entity identification"),
+                }],
+        };
+    }
+    try {
+        const result = await analyzeTableRelationships(schema);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing relationships", err),
+                },
+            ],
+        };
+    }
+});
+// --- Tool: analyze_vacuum ---
+server.tool("analyze_vacuum", "Analyze PostgreSQL VACUUM maintenance status. Checks dead tuple ratios, vacuum staleness, autovacuum configuration, and identifies tables needing manual VACUUM. PostgreSQL only.", {
+    schema: z
+        .string()
+        .default("public")
+        .describe("Database schema to analyze (default: public)"),
+}, async ({ schema }) => {
+    try {
+        const result = await analyzeVacuum(schema);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatToolError("analyzing vacuum status", err),
+                },
+            ],
+        };
+    }
+});
+// --- Start server ---
+async function main() {
+    const driver = detectDriver();
+    await initDriver(driver);
+    console.error(`MCP DB Analyzer running on stdio (driver: ${driver})`);
+    // Test database connectivity early — warn on stderr if unreachable
+    try {
+        const { query: testQuery } = await import("./db.js");
+        await testQuery("SELECT 1");
+        console.error("Database connection: OK");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const sanitized = msg.replace(/\/\/[^@]+@/g, "//****:****@");
+        console.error(`WARNING: Database connection failed: ${sanitized}`);
+        if (driver === "postgres") {
+            console.error("Configure via DATABASE_URL or PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE environment variables.");
+        }
+        else if (driver === "mysql") {
+            console.error("Configure via DATABASE_URL or MYSQL_HOST/MYSQL_PORT/MYSQL_USER/MYSQL_PASSWORD/MYSQL_DATABASE environment variables.");
+        }
+        else {
+            console.error("Configure via DATABASE_URL, SQLITE_PATH, or DB_PATH environment variable.");
+        }
+        console.error("The server will start, but tools will return errors until the database is reachable.");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Graceful shutdown
+process.on("SIGINT", async () => {
+    await closePool();
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    await closePool();
+    process.exit(0);
+});
+main().catch((error) => {
+    // Sanitize error to avoid leaking credentials from connection strings
+    const msg = error instanceof Error ? error.message : String(error);
+    const sanitized = msg.replace(/\/\/[^@]+@/g, "//****:****@");
+    console.error("Fatal error:", sanitized);
+    process.exit(1);
+});

package/build/license.js

@@ -0,0 +1,114 @@
+/**
+ * License validation for MCP Migration Advisor (Pro features).
+ *
+ * Validates license keys offline using HMAC-SHA256.
+ * Missing or invalid keys gracefully degrade to free mode — never errors.
+ *
+ * Key format: MCPJBS-XXXXX-XXXXX-XXXXX-XXXXX
+ * Payload (12 bytes = 20 base32 chars):
+ *   [0]     product mask (8 bits)
+ *   [1-2]   expiry days since 2026-01-01 (16 bits)
+ *   [3-5]   customer ID (24 bits)
+ *   [6-11]  HMAC-SHA256 truncated (48 bits)
+ */
+import { createHmac } from "node:crypto";
+const KEY_PREFIX = "MCPJBS-";
+const EPOCH = new Date("2026-01-01T00:00:00Z");
+const BASE32_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+const HMAC_SECRET = "mcp-java-backend-suite-license-v1";
+const PRODUCTS = {
+    "db-analyzer": 0,
+    "jvm-diagnostics": 1,
+    "migration-advisor": 2,
+    "spring-boot-actuator": 3,
+    "redis-diagnostics": 4,
+};
+export function validateLicense(key, product) {
+    const FREE = {
+        isPro: false,
+        expiresAt: null,
+        customerId: null,
+        reason: "No license key provided",
+    };
+    if (!key || key.trim().length === 0)
+        return FREE;
+    const trimmed = key.trim().toUpperCase();
+    if (!trimmed.startsWith(KEY_PREFIX)) {
+        return { ...FREE, reason: "Invalid key format: missing MCPJBS- prefix" };
+    }
+    const body = trimmed.slice(KEY_PREFIX.length).replace(/-/g, "");
+    if (body.length < 20) {
+        return { ...FREE, reason: "Invalid key format: too short" };
+    }
+    let decoded;
+    try {
+        decoded = base32Decode(body.slice(0, 20));
+    }
+    catch {
+        return { ...FREE, reason: "Invalid key format: bad base32 encoding" };
+    }
+    if (decoded.length < 12) {
+        return { ...FREE, reason: "Invalid key format: decoded data too short" };
+    }
+    const payload = decoded.subarray(0, 6);
+    const providedSignature = decoded.subarray(6, 12);
+    const expectedHmac = createHmac("sha256", HMAC_SECRET)
+        .update(payload)
+        .digest();
+    const expectedSignature = expectedHmac.subarray(0, 6);
+    if (!providedSignature.equals(expectedSignature)) {
+        return { ...FREE, reason: "Invalid license key: signature mismatch" };
+    }
+    const productMask = payload[0];
+    const daysSinceEpoch = (payload[1] << 8) | payload[2];
+    const customerId = (payload[3] << 16) | (payload[4] << 8) | payload[5];
+    const productBit = PRODUCTS[product];
+    if (productBit === undefined) {
+        return { ...FREE, reason: `Unknown product: ${product}` };
+    }
+    if ((productMask & (1 << productBit)) === 0) {
+        return { ...FREE, customerId, reason: `License does not include ${product}` };
+    }
+    const expiresAt = new Date(EPOCH.getTime() + daysSinceEpoch * 24 * 60 * 60 * 1000);
+    if (new Date() > expiresAt) {
+        return {
+            isPro: false,
+            expiresAt,
+            customerId,
+            reason: `License expired on ${expiresAt.toISOString().slice(0, 10)}`,
+        };
+    }
+    return { isPro: true, expiresAt, customerId, reason: "Valid Pro license" };
+}
+export function formatUpgradePrompt(toolName, featureDescription) {
+    return [
+        `## ${toolName} (Pro Feature)`,
+        "",
+        "This analysis is available with MCP Java Backend Suite Pro.",
+        "",
+        `**What you'll get:**`,
+        featureDescription,
+        "",
+        "**Upgrade**: https://mcpjbs.dev/pricing",
+        "**Price**: $19/month or $190/year",
+        "",
+        "> Already have a key? Set `MCP_LICENSE_KEY` in your Claude Desktop config.",
+    ].join("\n");
+}
+function base32Decode(encoded) {
+    const bytes = [];
+    let bits = 0;
+    let value = 0;
+    for (const char of encoded) {
+        const idx = BASE32_CHARS.indexOf(char);
+        if (idx === -1)
+            throw new Error(`Invalid base32 character: ${char}`);
+        value = (value << 5) | idx;
+        bits += 5;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((value >> bits) & 0xff);
+        }
+    }
+    return Buffer.from(bytes);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "mcp-db-analyzer",
+  "version": "0.2.0",
+  "description": "MCP server for PostgreSQL, MySQL, and SQLite schema analysis, index optimization, and query plan inspection",
+  "author": "Dmytro Lisnichenko",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "mcp-db-analyzer": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "test": "vitest run --exclude 'tests/integration/**' --exclude 'build/**'",
+    "test:integration": "vitest run tests/integration/",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "files": [
+    "build/**/*.js",
+    "!build/__tests__",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "database",
+    "schema-analyzer",
+    "index-optimization",
+    "query-plan",
+    "ai",
+    "claude"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Dmitriusan/mcp-db-analyzer"
+  },
+  "homepage": "https://github.com/Dmitriusan/mcp-db-analyzer#readme",
+  "bugs": {
+    "url": "https://github.com/Dmitriusan/mcp-db-analyzer/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "better-sqlite3": "^12.6.2",
+    "mysql2": "^3.19.0",
+    "pg": "^8.13.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/mysql": "^2.15.27",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "typescript": "^5.8.2",
+    "vitest": "^4.0.18"
+  }
+}