mcp-db-analyzer 0.2.9 → 0.2.11

package/README.md

@@ -30,7 +30,7 @@ Other analytical MCP servers (CrystalDBA, pg-dash, MCP-PostgreSQL-Ops) cover Pos
 - Priority support
 
 <!-- TODO: replace placeholder Stripe Payment Link once STRIPE_SECRET_KEY is configured -->
-**$9.99/month** — [Get Pro License](https://buy.stripe.com/PLACEHOLDER)
+**$9.00/month** — [Get Pro License](https://buy.stripe.com/PLACEHOLDER)
 
 Pro license key activates the `generate_report` MCP tool in mcp-jvm-diagnostics.
 

package/build/analyzers/connections.js

@@ -162,6 +162,23 @@ async function analyzeMysqlConnections() {
     }
     lines.push(`| **Total** | **${total}** |`);
     lines.push("");
+    // 2. Max connections utilization
+    try {
+        const maxConn = await query(`SELECT @@max_connections AS max_connections`);
+        if (maxConn.rows.length > 0) {
+            const max = parseInt(maxConn.rows[0].max_connections, 10);
+            const utilization = total / max;
+            lines.push(`**Max connections**: ${max}`);
+            lines.push(`**Utilization**: ${(utilization * 100).toFixed(1)}%`);
+            if (utilization > 0.8) {
+                lines.push(`\n**WARNING**: Connection pool is ${(utilization * 100).toFixed(0)}% utilized. Consider increasing max_connections or using a connection pooler (e.g. ProxySQL).`);
+            }
+            lines.push("");
+        }
+    }
+    catch {
+        // Supplemental info — skip silently if unavailable
+    }
     const longQueries = await query(`SELECT ID AS id, USER AS user, TIME AS time, STATE AS state, LEFT(INFO, 100) AS info
      FROM information_schema.PROCESSLIST
      WHERE COMMAND = 'Query' AND TIME > 30

package/build/analyzers/indexes.js

@@ -72,8 +72,9 @@ async function analyzeIndexUsageMysql(schema) {
     `, [schema]);
         return formatIndexUsage(result.rows, schema);
     }
-    catch {
-        return `## Index Usage Analysis — schema '${schema}'\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.`;
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `## Index Usage Analysis — schema '${schema}'\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.\n\nDetails: ${detail}`;
     }
 }
 function formatIndexUsage(rows, schema) {
@@ -226,8 +227,9 @@ async function findMissingIndexesMysql(schema) {
         }
         return lines.join("\n");
     }
-    catch {
-        return "## Missing Index Analysis\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.";
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `## Missing Index Analysis\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.\n\nDetails: ${detail}`;
     }
 }
 function formatMissingIndexes(rows, schema) {

package/build/analyzers/relationships.js

@@ -99,6 +99,59 @@ async function analyzeSqliteRelationships() {
     }
     return formatRelationshipReport(tablesResult.rows.map(r => r.name), fks);
 }
+/**
+ * Detect cycles in the FK dependency graph using iterative DFS.
+ * Returns each unique cycle as an ordered list of table names with the
+ * first node repeated at the end to show closure (e.g. ["a","b","c","a"]).
+ */
+function findFkCycles(allTables, graph) {
+    const visited = new Set();
+    const onStack = new Set();
+    const stackPath = [];
+    const cycles = [];
+    const seenCycleKeys = new Set();
+    function dfs(node) {
+        visited.add(node);
+        onStack.add(node);
+        stackPath.push(node);
+        const nodeData = graph.get(node);
+        if (nodeData) {
+            for (const fk of nodeData.outgoing) {
+                const neighbor = fk.target_table;
+                if (onStack.has(neighbor)) {
+                    // Back edge found — extract the cycle
+                    const cycleStartIdx = stackPath.indexOf(neighbor);
+                    if (cycleStartIdx !== -1) {
+                        const cycleNodes = stackPath.slice(cycleStartIdx);
+                        // Normalize: rotate so lexicographically smallest node is first
+                        const minNode = cycleNodes.reduce((a, b) => (a < b ? a : b));
+                        const minIdx = cycleNodes.indexOf(minNode);
+                        const normalized = [
+                            ...cycleNodes.slice(minIdx),
+                            ...cycleNodes.slice(0, minIdx),
+                        ];
+                        const key = normalized.join("\0");
+                        if (!seenCycleKeys.has(key)) {
+                            seenCycleKeys.add(key);
+                            cycles.push([...normalized, normalized[0]]); // close the cycle
+                        }
+                    }
+                }
+                else if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+            }
+        }
+        stackPath.pop();
+        onStack.delete(node);
+    }
+    for (const table of allTables) {
+        if (!visited.has(table)) {
+            dfs(table);
+        }
+    }
+    return cycles;
+}
 function formatRelationshipReport(allTables, foreignKeys) {
     const lines = [];
     lines.push("## Table Relationships\n");
@@ -161,30 +214,57 @@ function formatRelationshipReport(allTables, foreignKeys) {
         lines.push("*Orphan tables may be lookup tables, denormalized tables, or tables missing FK constraints.*");
         lines.push("");
     }
+    // Circular FK dependencies
+    const cycles = findFkCycles(allTables, graph);
+    if (cycles.length > 0) {
+        lines.push("### Circular FK Dependencies\n");
+        lines.push("These tables form circular foreign key references. Cycles complicate cascade operations, " +
+            "schema migrations, and may cause issues with certain ORMs and migration tools:\n");
+        for (const cycle of cycles) {
+            lines.push(`- ${cycle.join(" → ")}`);
+        }
+        lines.push("\n**Note**: Circular FKs are sometimes intentional (e.g., a 'current_record' pointer back to a parent). " +
+            "Review each cycle to confirm the design is correct.\n");
+    }
     // Cascading delete chains
     const cascadeDeletes = foreignKeys.filter(fk => fk.on_delete === "CASCADE");
     if (cascadeDeletes.length > 0) {
         lines.push("### Cascading Delete Chains\n");
         lines.push("Deleting a row from these parent tables will cascade-delete rows in child tables:\n");
-        // Group by target (parent) table
-        const cascadeByParent = new Map();
+        // Build parent→children map for cascade edges only
+        const cascadeChildren = new Map();
         for (const fk of cascadeDeletes) {
-            const existing = cascadeByParent.get(fk.target_table) || [];
-            existing.push(fk);
-            cascadeByParent.set(fk.target_table, existing);
+            const existing = cascadeChildren.get(fk.target_table) || [];
+            if (!existing.includes(fk.source_table))
+                existing.push(fk.source_table);
+            cascadeChildren.set(fk.target_table, existing);
         }
-        for (const [parent, fks] of cascadeByParent) {
-            const children = fks.map(f => f.source_table).join(", ");
-            lines.push(`- **${parent}** → cascades to: ${children}`);
-            // Check for deep chains (cascade through multiple levels)
-            for (const fk of fks) {
-                const grandchildren = cascadeDeletes.filter(gfk => gfk.target_table === fk.source_table);
-                if (grandchildren.length > 0) {
-                    const gcNames = grandchildren.map(g => g.source_table).join(", ");
-                    lines.push(`  - **${fk.source_table}** → further cascades to: ${gcNames}`);
+        // Identify root cascade tables: have cascade children but are not cascade children themselves
+        const allCascadeChildTables = new Set(cascadeDeletes.map(fk => fk.source_table));
+        const cascadeRoots = [...cascadeChildren.keys()].filter(t => !allCascadeChildTables.has(t));
+        // Fall back to all parents if every parent is also a child (full cycle)
+        const parentsToShow = cascadeRoots.length > 0 ? cascadeRoots : [...cascadeChildren.keys()];
+        // Recursively render the cascade chain under a given parent
+        function renderCascadeChain(parent, indent, visited) {
+            const children = cascadeChildren.get(parent) || [];
+            const prefix = "  ".repeat(indent);
+            for (const child of children) {
+                if (visited.has(child)) {
+                    lines.push(`${prefix}- **${child}** *(circular)*`);
+                }
+                else if (cascadeChildren.has(child)) {
+                    lines.push(`${prefix}- **${child}** →`);
+                    renderCascadeChain(child, indent + 1, new Set([...visited, child]));
+                }
+                else {
+                    lines.push(`${prefix}- **${child}**`);
                 }
             }
         }
+        for (const root of parentsToShow) {
+            lines.push(`- **${root}** → cascades to:`);
+            renderCascadeChain(root, 1, new Set([root]));
+        }
         lines.push("");
         lines.push("**WARNING**: Cascading deletes can cause unexpected data loss. Ensure all CASCADE rules are intentional.\n");
     }
@@ -200,6 +280,9 @@ function formatRelationshipReport(allTables, foreignKeys) {
     if (hubs.length > 0) {
         issues.push(`Hub tables (${hubs.map(h => h.name).join(", ")}) have 5+ FK connections — changes to these tables affect many others`);
     }
+    if (cycles.length > 0) {
+        issues.push(`${cycles.length} circular FK reference(s) detected — review for unintended schema design`);
+    }
     if (issues.length > 0) {
         lines.push("### Recommendations\n");
         for (const issue of issues) {

package/build/analyzers/suggestions.js

@@ -127,8 +127,9 @@ async function suggestMissingIndexesMysql(schema) {
     `, [schema]);
         return formatSuggestions(needsIndex.rows, unused.rows, schema);
     }
-    catch {
-        return "## Index Suggestions\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.";
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `## Index Suggestions\n\nUnable to query performance_schema. Ensure performance_schema is enabled (it is ON by default in MySQL 5.7+) and the user has SELECT privilege on performance_schema tables.\n\nDetails: ${detail}`;
     }
 }
 function formatSuggestions(needsIndex, unused, schema) {

package/build/index.js

@@ -248,7 +248,7 @@ server.tool("analyze_slow_queries", "Find the slowest queries using pg_stat_stat
     }
 });
 // 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.", {
+server.tool("analyze_connections", "Analyze active database connections. Detects idle-in-transaction sessions (which hold locks and block other queries), long-running queries (flagged at >30 seconds), lock contention between sessions, and connection pool utilization. PostgreSQL and MySQL only.", {
     timeout_ms: timeoutParam,
 }, async ({ timeout_ms }) => {
     applyTimeout(timeout_ms);
@@ -268,7 +268,7 @@ server.tool("analyze_connections", "Analyze active database connections. Detects
     }
 });
 // 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.", {
+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 (shown at full depth), hub entities (tables with 5+ FK connections), and circular FK dependencies. Useful for understanding schema design, planning migrations, and impact analysis.", {
     schema: z
         .string()
         .default("public")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-db-analyzer",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "MCP server for PostgreSQL, MySQL, and SQLite schema analysis, index optimization, and query plan inspection",
   "mcpName": "io.github.dmitriusan/mcp-db-analyzer",
   "author": "Dmytro Lisnichenko",