@arvoretech/db-diagram-mcp 1.0.0

package/src/server.ts

@@ -0,0 +1,163 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { parseDDL, extractInlineForeignKeys } from "./parser.js";
+import { generateErd, generateDomainMap, explainTable, traceFlow } from "./mermaid.js";
+import { visualize } from "./visualizer.js";
+import {
+  GenerateErdParamsSchema,
+  GenerateDomainMapParamsSchema,
+  ExplainTableParamsSchema,
+  TraceFlowParamsSchema,
+  VisualizeParamsSchema,
+  McpToolResult,
+  GenerateErdParams,
+  GenerateDomainMapParams,
+  ExplainTableParams,
+  TraceFlowParams,
+  VisualizeParams,
+} from "./types.js";
+
+export class DbDiagramMCPServer {
+  private server: McpServer;
+
+  constructor() {
+    this.server = new McpServer({
+      name: "db-diagram-mcp-server",
+      version: "1.0.0",
+    });
+    this.setupTools();
+  }
+
+  private setupTools(): void {
+    this.server.registerTool(
+      "generate_erd",
+      {
+        title: "Generate ERD",
+        description:
+          "Generate a Mermaid ER diagram from SQL DDL. Optionally filter to specific tables.",
+        inputSchema: {
+          ddl: GenerateErdParamsSchema.shape.ddl,
+          tables: GenerateErdParamsSchema.shape.tables,
+          title: GenerateErdParamsSchema.shape.title,
+        },
+      },
+      async (params): Promise<McpToolResult> => {
+        const { ddl, tables, title } = params as GenerateErdParams;
+        let schema = parseDDL(ddl);
+        schema = extractInlineForeignKeys(ddl, schema);
+        const diagram = generateErd(schema, { tables, title });
+        return { content: [{ type: "text", text: diagram }] };
+      }
+    );
+
+    this.server.registerTool(
+      "generate_domain_map",
+      {
+        title: "Generate Domain Map",
+        description:
+          "Generate a Mermaid diagram showing all tables related to an entry table within N hops.",
+        inputSchema: {
+          ddl: GenerateDomainMapParamsSchema.shape.ddl,
+          entryTable: GenerateDomainMapParamsSchema.shape.entryTable,
+          depth: GenerateDomainMapParamsSchema.shape.depth,
+        },
+      },
+      async (params): Promise<McpToolResult> => {
+        const { ddl, entryTable, depth } = params as GenerateDomainMapParams;
+        let schema = parseDDL(ddl);
+        schema = extractInlineForeignKeys(ddl, schema);
+        const diagram = generateDomainMap(schema, entryTable, depth ?? 3);
+        return { content: [{ type: "text", text: diagram }] };
+      }
+    );
+
+    this.server.registerTool(
+      "explain_table",
+      {
+        title: "Explain Table",
+        description:
+          "Show a table's columns, relationships (incoming and outgoing), and a mini ER diagram of its neighborhood.",
+        inputSchema: {
+          ddl: ExplainTableParamsSchema.shape.ddl,
+          table: ExplainTableParamsSchema.shape.table,
+        },
+      },
+      async (params): Promise<McpToolResult> => {
+        const { ddl, table } = params as ExplainTableParams;
+        let schema = parseDDL(ddl);
+        schema = extractInlineForeignKeys(ddl, schema);
+        const explanation = explainTable(schema, table);
+        return { content: [{ type: "text", text: explanation }] };
+      }
+    );
+
+    this.server.registerTool(
+      "trace_flow",
+      {
+        title: "Trace Flow",
+        description:
+          "Find relationship paths between two tables and generate a Mermaid diagram of the connecting tables.",
+        inputSchema: {
+          ddl: TraceFlowParamsSchema.shape.ddl,
+          from: TraceFlowParamsSchema.shape.from,
+          to: TraceFlowParamsSchema.shape.to,
+        },
+      },
+      async (params): Promise<McpToolResult> => {
+        const { ddl, from, to } = params as TraceFlowParams;
+        let schema = parseDDL(ddl);
+        schema = extractInlineForeignKeys(ddl, schema);
+        const flow = traceFlow(schema, from, to);
+        return { content: [{ type: "text", text: flow }] };
+      }
+    );
+
+    this.server.registerTool(
+      "visualize",
+      {
+        title: "Visualize Diagram",
+        description:
+          "Render a Mermaid ER diagram in the browser. Accepts DDL (generates ERD) or raw Mermaid code.",
+        inputSchema: {
+          ddl: VisualizeParamsSchema.shape.ddl,
+          mermaid: VisualizeParamsSchema.shape.mermaid,
+          tables: VisualizeParamsSchema.shape.tables,
+          title: VisualizeParamsSchema.shape.title,
+        },
+      },
+      async (params): Promise<McpToolResult> => {
+        const { ddl, mermaid: rawMermaid, tables, title } = params as VisualizeParams;
+
+        let mermaidCode: string;
+        if (rawMermaid) {
+          mermaidCode = rawMermaid;
+        } else if (ddl) {
+          let schema = parseDDL(ddl);
+          schema = extractInlineForeignKeys(ddl, schema);
+          mermaidCode = generateErd(schema, { tables, title });
+        } else {
+          return { content: [{ type: "text", text: "Provide either 'ddl' or 'mermaid' parameter." }] };
+        }
+
+        const url = await visualize(mermaidCode);
+        return { content: [{ type: "text", text: `Diagram opened at ${url} (auto-closes in 5 minutes)` }] };
+      }
+    );
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error("DB Diagram MCP Server started successfully");
+  }
+
+  setupGracefulShutdown(): void {
+    const shutdown = async (signal: string): Promise<void> => {
+      console.error(`Received ${signal}, shutting down gracefully...`);
+      process.exit(0);
+    };
+
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+  }
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+export interface Column {
+  name: string;
+  type: string;
+  nullable: boolean;
+  primaryKey: boolean;
+  unique: boolean;
+  defaultValue?: string;
+}
+
+export interface ForeignKey {
+  columns: string[];
+  referencedTable: string;
+  referencedColumns: string[];
+}
+
+export interface Table {
+  name: string;
+  columns: Column[];
+  foreignKeys: ForeignKey[];
+}
+
+export interface Schema {
+  tables: Table[];
+}
+
+export const GenerateErdParamsSchema = z.object({
+  ddl: z.string().min(1).describe("SQL DDL statements (CREATE TABLE)"),
+  tables: z
+    .array(z.string())
+    .optional()
+    .describe("Filter to specific tables (omit for all)"),
+  title: z.string().optional().describe("Diagram title"),
+});
+
+export type GenerateErdParams = z.infer<typeof GenerateErdParamsSchema>;
+
+export const GenerateDomainMapParamsSchema = z.object({
+  ddl: z.string().min(1).describe("SQL DDL statements (CREATE TABLE)"),
+  entryTable: z
+    .string()
+    .describe("Starting table to trace relationships from"),
+  depth: z
+    .number()
+    .min(1)
+    .max(10)
+    .default(3)
+    .describe("How many relationship hops to follow (default: 3)"),
+});
+
+export type GenerateDomainMapParams = z.infer<
+  typeof GenerateDomainMapParamsSchema
+>;
+
+export const ExplainTableParamsSchema = z.object({
+  ddl: z.string().min(1).describe("SQL DDL statements (CREATE TABLE)"),
+  table: z.string().describe("Table name to explain"),
+});
+
+export type ExplainTableParams = z.infer<typeof ExplainTableParamsSchema>;
+
+export const TraceFlowParamsSchema = z.object({
+  ddl: z.string().min(1).describe("SQL DDL statements (CREATE TABLE)"),
+  from: z.string().describe("Source table"),
+  to: z.string().describe("Target table"),
+});
+
+export type TraceFlowParams = z.infer<typeof TraceFlowParamsSchema>;
+
+export const VisualizeParamsSchema = z.object({
+  ddl: z.string().optional().describe("SQL DDL statements (CREATE TABLE). Provide either ddl or mermaid."),
+  mermaid: z.string().optional().describe("Raw Mermaid diagram code to render directly."),
+  tables: z.array(z.string()).optional().describe("Filter to specific tables (only when using ddl)"),
+  title: z.string().optional().describe("Diagram title"),
+});
+
+export type VisualizeParams = z.infer<typeof VisualizeParamsSchema>;
+
+
+
+export interface McpToolResult {
+  [x: string]: unknown;
+  content: Array<{
+    type: "text";
+    text: string;
+  }>;
+}

package/src/visualizer.ts

@@ -0,0 +1,116 @@
+import { createServer, Server } from "node:http";
+import { exec } from "node:child_process";
+import { platform } from "node:os";
+
+export function visualize(mermaidCode: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const html = buildHtml(mermaidCode);
+    const server: Server = createServer((req, res) => {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        reject(new Error("Failed to get server address"));
+        return;
+      }
+
+      const url = `http://127.0.0.1:${address.port}`;
+      openBrowser(url);
+
+      setTimeout(() => {
+        server.close();
+      }, 300_000);
+
+      resolve(url);
+    });
+
+    server.on("error", reject);
+  });
+}
+
+function openBrowser(url: string): void {
+  const cmd =
+    platform() === "darwin"
+      ? `open "${url}"`
+      : platform() === "win32"
+        ? `start "${url}"`
+        : `xdg-open "${url}"`;
+
+  exec(cmd, () => {});
+}
+
+function buildHtml(mermaidCode: string): string {
+  const escaped = mermaidCode.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>DB Diagram</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  html, body { width: 100%; height: 100%; overflow: hidden; background: #1a1a2e; }
+  #viewport { width: 100%; height: 100%; cursor: grab; overflow: hidden; }
+  #viewport.dragging { cursor: grabbing; }
+  #diagram { display: inline-block; padding: 2rem; transform-origin: 0 0; }
+</style>
+</head>
+<body>
+<div id="viewport">
+  <div id="diagram">
+    <pre class="mermaid">${escaped}</pre>
+  </div>
+</div>
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+  mermaid.initialize({ startOnLoad: true, theme: 'dark', er: { useMaxWidth: false, layoutDirection: 'LR' } });
+
+  const viewport = document.getElementById('viewport');
+  const diagram = document.getElementById('diagram');
+  let isPanning = false;
+  let startX = 0, startY = 0;
+  let offsetX = 0, offsetY = 0;
+  let scale = 1;
+
+  function applyTransform() {
+    diagram.style.transform = \`translate(\${offsetX}px, \${offsetY}px) scale(\${scale})\`;
+  }
+
+  viewport.addEventListener('mousedown', (e) => {
+    isPanning = true;
+    startX = e.clientX - offsetX;
+    startY = e.clientY - offsetY;
+    viewport.classList.add('dragging');
+  });
+
+  window.addEventListener('mousemove', (e) => {
+    if (!isPanning) return;
+    offsetX = e.clientX - startX;
+    offsetY = e.clientY - startY;
+    applyTransform();
+  });
+
+  window.addEventListener('mouseup', () => {
+    isPanning = false;
+    viewport.classList.remove('dragging');
+  });
+
+  viewport.addEventListener('wheel', (e) => {
+    e.preventDefault();
+    const delta = e.deltaY > 0 ? 0.9 : 1.1;
+    const newScale = Math.min(Math.max(scale * delta, 0.1), 5);
+    const rect = viewport.getBoundingClientRect();
+    const mx = e.clientX - rect.left;
+    const my = e.clientY - rect.top;
+    offsetX -= (mx - offsetX) * (newScale / scale - 1);
+    offsetY -= (my - offsetY) * (newScale / scale - 1);
+    scale = newScale;
+    applyTransform();
+  }, { passive: false });
+</script>
+</body>
+</html>`;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}