@arvoretech/db-diagram-mcp 1.0.0

package/src/mermaid.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { parseDDL, extractInlineForeignKeys } from "./parser.js";
+import {
+  generateErd,
+  generateDomainMap,
+  explainTable,
+  traceFlow,
+} from "./mermaid.js";
+
+const sampleDDL = `
+CREATE TABLE users (
+  id INT NOT NULL AUTO_INCREMENT,
+  email VARCHAR(255) NOT NULL,
+  name VARCHAR(100),
+  PRIMARY KEY (id),
+  UNIQUE KEY (email)
+);
+
+CREATE TABLE posts (
+  id INT NOT NULL AUTO_INCREMENT,
+  user_id INT NOT NULL,
+  title VARCHAR(255) NOT NULL,
+  PRIMARY KEY (id),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+CREATE TABLE comments (
+  id INT NOT NULL AUTO_INCREMENT,
+  post_id INT NOT NULL,
+  user_id INT NOT NULL,
+  content TEXT NOT NULL,
+  PRIMARY KEY (id),
+  FOREIGN KEY (post_id) REFERENCES posts(id),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+`;
+
+function getSchema() {
+  let schema = parseDDL(sampleDDL);
+  schema = extractInlineForeignKeys(sampleDDL, schema);
+  return schema;
+}
+
+describe("generateErd", () => {
+  it("generates valid mermaid erDiagram", () => {
+    const schema = getSchema();
+    const diagram = generateErd(schema);
+    expect(diagram).toContain("erDiagram");
+    expect(diagram).toContain("users {");
+    expect(diagram).toContain("posts {");
+    expect(diagram).toContain("comments {");
+  });
+
+  it("includes relationship lines", () => {
+    const schema = getSchema();
+    const diagram = generateErd(schema);
+    expect(diagram).toContain("users");
+    expect(diagram).toContain("posts");
+  });
+
+  it("filters to specific tables", () => {
+    const schema = getSchema();
+    const diagram = generateErd(schema, { tables: ["users", "posts"] });
+    expect(diagram).toContain("users {");
+    expect(diagram).toContain("posts {");
+    expect(diagram).not.toContain("comments {");
+  });
+
+  it("adds title when provided", () => {
+    const schema = getSchema();
+    const diagram = generateErd(schema, { title: "My ERD" });
+    expect(diagram).toContain("title: My ERD");
+  });
+});
+
+describe("generateDomainMap", () => {
+  it("traverses from entry table", () => {
+    const schema = getSchema();
+    const diagram = generateDomainMap(schema, "posts", 1);
+    expect(diagram).toContain("posts {");
+    expect(diagram).toContain("users {");
+    expect(diagram).toContain("comments {");
+  });
+
+  it("respects depth limit", () => {
+    const schema = getSchema();
+    const diagram = generateDomainMap(schema, "comments", 0);
+    expect(diagram).toContain("comments {");
+  });
+});
+
+describe("explainTable", () => {
+  it("shows column details", () => {
+    const schema = getSchema();
+    const explanation = explainTable(schema, "posts");
+    expect(explanation).toContain("# posts");
+    expect(explanation).toContain("user_id");
+    expect(explanation).toContain("## Foreign Keys");
+    expect(explanation).toContain("users");
+  });
+
+  it("shows incoming references", () => {
+    const schema = getSchema();
+    const explanation = explainTable(schema, "users");
+    expect(explanation).toContain("## Referenced By");
+    expect(explanation).toContain("posts");
+    expect(explanation).toContain("comments");
+  });
+
+  it("returns error for unknown table", () => {
+    const schema = getSchema();
+    const explanation = explainTable(schema, "nonexistent");
+    expect(explanation).toContain("not found");
+  });
+});
+
+describe("traceFlow", () => {
+  it("finds path between tables", () => {
+    const schema = getSchema();
+    const flow = traceFlow(schema, "comments", "users");
+    expect(flow).toContain("# Flow:");
+    expect(flow).toContain("comments");
+    expect(flow).toContain("users");
+  });
+
+  it("returns message when no path exists", () => {
+    const ddl = `
+CREATE TABLE a (id INT PRIMARY KEY);
+CREATE TABLE b (id INT PRIMARY KEY);
+`;
+    const schema = parseDDL(ddl);
+    const flow = traceFlow(schema, "a", "b");
+    expect(flow).toContain("No relationship path found");
+  });
+});

package/src/mermaid.ts

@@ -0,0 +1,250 @@
+import { Schema, Table } from "./types.js";
+
+export function generateErd(
+  schema: Schema,
+  options?: { tables?: string[]; title?: string }
+): string {
+  const filteredTables = options?.tables
+    ? schema.tables.filter((t) => options.tables!.includes(t.name))
+    : schema.tables;
+
+  if (filteredTables.length === 0) return "erDiagram";
+
+  const lines: string[] = [];
+  if (options?.title) lines.push(`---\ntitle: ${options.title}\n---`);
+  lines.push("erDiagram");
+
+  for (const table of filteredTables) {
+    lines.push(`    ${table.name} {`);
+    for (const col of table.columns) {
+      const markers: string[] = [];
+      if (col.primaryKey) markers.push("PK");
+      if (col.unique && !col.primaryKey) markers.push("UK");
+
+      const isFk = schema.tables.some((t) =>
+        t.foreignKeys.some(
+          (fk) =>
+            fk.referencedTable === table.name &&
+            fk.referencedColumns.includes(col.name)
+        )
+      );
+      const isLocalFk = table.foreignKeys.some((fk) =>
+        fk.columns.includes(col.name)
+      );
+      if (isFk || isLocalFk) markers.push("FK");
+
+      const markerStr = markers.length > 0 ? ` ${markers.join(",")}` : "";
+      lines.push(
+        `        ${normalizeType(col.type)} ${col.name}${markerStr}`
+      );
+    }
+    lines.push("    }");
+  }
+
+  const tableNames = new Set(filteredTables.map((t) => t.name));
+  for (const table of filteredTables) {
+    for (const fk of table.foreignKeys) {
+      if (!tableNames.has(fk.referencedTable)) continue;
+
+      const cardinality = inferCardinality(table, fk.columns);
+      lines.push(
+        `    ${fk.referencedTable} ${cardinality} ${table.name} : "${fk.columns.join(", ")}"`
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function generateDomainMap(
+  schema: Schema,
+  entryTable: string,
+  depth: number
+): string {
+  const visited = new Set<string>();
+  const queue: Array<{ table: string; level: number }> = [
+    { table: entryTable, level: 0 },
+  ];
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current.table) || current.level > depth) continue;
+    visited.add(current.table);
+
+    const table = schema.tables.find((t) => t.name === current.table);
+    if (!table) continue;
+
+    for (const fk of table.foreignKeys) {
+      if (!visited.has(fk.referencedTable)) {
+        queue.push({ table: fk.referencedTable, level: current.level + 1 });
+      }
+    }
+
+    for (const other of schema.tables) {
+      for (const fk of other.foreignKeys) {
+        if (
+          fk.referencedTable === current.table &&
+          !visited.has(other.name)
+        ) {
+          queue.push({ table: other.name, level: current.level + 1 });
+        }
+      }
+    }
+  }
+
+  const filteredSchema: Schema = {
+    tables: schema.tables.filter((t) => visited.has(t.name)),
+  };
+
+  return generateErd(filteredSchema, {
+    title: `Domain: ${entryTable} (depth ${depth})`,
+  });
+}
+
+export function explainTable(schema: Schema, tableName: string): string {
+  const table = schema.tables.find((t) => t.name === tableName);
+  if (!table) return `Table "${tableName}" not found in schema.`;
+
+  const lines: string[] = [`# ${tableName}`, ""];
+
+  lines.push("## Columns", "");
+  lines.push("| Column | Type | PK | Nullable | Unique | Default |");
+  lines.push("|--------|------|----|---------:|--------|---------|");
+  for (const col of table.columns) {
+    lines.push(
+      `| ${col.name} | ${col.type} | ${col.primaryKey ? "✓" : ""} | ${col.nullable ? "✓" : ""} | ${col.unique ? "✓" : ""} | ${col.defaultValue ?? ""} |`
+    );
+  }
+
+  if (table.foreignKeys.length > 0) {
+    lines.push("", "## Foreign Keys (outgoing)", "");
+    for (const fk of table.foreignKeys) {
+      lines.push(
+        `- ${fk.columns.join(", ")} → ${fk.referencedTable}(${fk.referencedColumns.join(", ")})`
+      );
+    }
+  }
+
+  const incomingFks = schema.tables.filter((t) =>
+    t.foreignKeys.some((fk) => fk.referencedTable === tableName)
+  );
+  if (incomingFks.length > 0) {
+    lines.push("", "## Referenced By (incoming)", "");
+    for (const t of incomingFks) {
+      for (const fk of t.foreignKeys) {
+        if (fk.referencedTable === tableName) {
+          lines.push(
+            `- ${t.name}(${fk.columns.join(", ")}) → ${tableName}(${fk.referencedColumns.join(", ")})`
+          );
+        }
+      }
+    }
+  }
+
+  const relatedTables = new Set<string>();
+  for (const fk of table.foreignKeys) relatedTables.add(fk.referencedTable);
+  for (const t of incomingFks) relatedTables.add(t.name);
+
+  if (relatedTables.size > 0) {
+    const miniSchema: Schema = {
+      tables: schema.tables.filter(
+        (t) => t.name === tableName || relatedTables.has(t.name)
+      ),
+    };
+    lines.push("", "## Diagram", "", "```mermaid");
+    lines.push(generateErd(miniSchema, { title: tableName }));
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}
+
+export function traceFlow(
+  schema: Schema,
+  from: string,
+  to: string
+): string {
+  const paths = findPaths(schema, from, to, 6);
+
+  if (paths.length === 0) {
+    return `No relationship path found between "${from}" and "${to}" within 6 hops.`;
+  }
+
+  const allTables = new Set<string>();
+  for (const path of paths) {
+    for (const table of path) allTables.add(table);
+  }
+
+  const lines: string[] = [
+    `# Flow: ${from} → ${to}`,
+    "",
+    `Found ${paths.length} path(s):`,
+    "",
+  ];
+
+  for (let i = 0; i < paths.length; i++) {
+    lines.push(`${i + 1}. ${paths[i].join(" → ")}`);
+  }
+
+  const filteredSchema: Schema = {
+    tables: schema.tables.filter((t) => allTables.has(t.name)),
+  };
+
+  lines.push("", "```mermaid");
+  lines.push(generateErd(filteredSchema, { title: `${from} → ${to}` }));
+  lines.push("```");
+
+  return lines.join("\n");
+}
+
+function findPaths(
+  schema: Schema,
+  from: string,
+  to: string,
+  maxDepth: number
+): string[][] {
+  const results: string[][] = [];
+
+  function dfs(current: string, target: string, path: string[]): void {
+    if (path.length > maxDepth) return;
+    if (current === target) {
+      results.push([...path]);
+      return;
+    }
+
+    const table = schema.tables.find((t) => t.name === current);
+    if (!table) return;
+
+    for (const fk of table.foreignKeys) {
+      if (!path.includes(fk.referencedTable)) {
+        path.push(fk.referencedTable);
+        dfs(fk.referencedTable, target, path);
+        path.pop();
+      }
+    }
+
+    for (const other of schema.tables) {
+      for (const fk of other.foreignKeys) {
+        if (fk.referencedTable === current && !path.includes(other.name)) {
+          path.push(other.name);
+          dfs(other.name, target, path);
+          path.pop();
+        }
+      }
+    }
+  }
+
+  dfs(from, to, [from]);
+  return results.slice(0, 5);
+}
+
+function inferCardinality(table: Table, fkColumns: string[]): string {
+  const hasUnique = table.columns.some(
+    (c) => fkColumns.includes(c.name) && (c.unique || c.primaryKey)
+  );
+  return hasUnique ? "||--||" : "||--o{";
+}
+
+function normalizeType(type: string): string {
+  return type.replace(/[(),\s]/g, "_").replace(/_+$/, "");
+}

package/src/parser.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import { parseDDL, extractInlineForeignKeys } from "./parser.js";
+
+const sampleDDL = `
+CREATE TABLE users (
+  id INT NOT NULL AUTO_INCREMENT,
+  email VARCHAR(255) NOT NULL,
+  name VARCHAR(100),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (id),
+  UNIQUE KEY (email)
+);
+
+CREATE TABLE posts (
+  id INT NOT NULL AUTO_INCREMENT,
+  user_id INT NOT NULL,
+  title VARCHAR(255) NOT NULL,
+  body TEXT,
+  published_at TIMESTAMP,
+  PRIMARY KEY (id),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+CREATE TABLE comments (
+  id INT NOT NULL AUTO_INCREMENT,
+  post_id INT NOT NULL,
+  user_id INT NOT NULL,
+  content TEXT NOT NULL,
+  PRIMARY KEY (id),
+  FOREIGN KEY (post_id) REFERENCES posts(id),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+CREATE TABLE tags (
+  id INT NOT NULL AUTO_INCREMENT,
+  name VARCHAR(50) NOT NULL UNIQUE,
+  PRIMARY KEY (id)
+);
+
+CREATE TABLE post_tags (
+  post_id INT NOT NULL,
+  tag_id INT NOT NULL,
+  PRIMARY KEY (post_id, tag_id),
+  FOREIGN KEY (post_id) REFERENCES posts(id),
+  FOREIGN KEY (tag_id) REFERENCES tags(id)
+);
+`;
+
+describe("parseDDL", () => {
+  it("parses all tables", () => {
+    const schema = parseDDL(sampleDDL);
+    expect(schema.tables).toHaveLength(5);
+    expect(schema.tables.map((t) => t.name)).toEqual([
+      "users",
+      "posts",
+      "comments",
+      "tags",
+      "post_tags",
+    ]);
+  });
+
+  it("parses columns correctly", () => {
+    const schema = parseDDL(sampleDDL);
+    const users = schema.tables.find((t) => t.name === "users")!;
+    expect(users.columns).toHaveLength(4);
+
+    const idCol = users.columns.find((c) => c.name === "id")!;
+    expect(idCol.primaryKey).toBe(true);
+    expect(idCol.nullable).toBe(false);
+
+    const emailCol = users.columns.find((c) => c.name === "email")!;
+    expect(emailCol.nullable).toBe(false);
+  });
+
+  it("parses foreign keys", () => {
+    const schema = parseDDL(sampleDDL);
+    const posts = schema.tables.find((t) => t.name === "posts")!;
+    expect(posts.foreignKeys).toHaveLength(1);
+    expect(posts.foreignKeys[0]).toEqual({
+      columns: ["user_id"],
+      referencedTable: "users",
+      referencedColumns: ["id"],
+    });
+  });
+
+  it("parses composite primary keys", () => {
+    const schema = parseDDL(sampleDDL);
+    const postTags = schema.tables.find((t) => t.name === "post_tags")!;
+    const pkCols = postTags.columns.filter((c) => c.primaryKey);
+    expect(pkCols.map((c) => c.name)).toEqual(["post_id", "tag_id"]);
+  });
+
+  it("parses multiple foreign keys on one table", () => {
+    const schema = parseDDL(sampleDDL);
+    const comments = schema.tables.find((t) => t.name === "comments")!;
+    expect(comments.foreignKeys).toHaveLength(2);
+  });
+
+  it("handles PostgreSQL inline references", () => {
+    const pgDDL = `
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INT NOT NULL REFERENCES customers(id),
+  total DECIMAL(10,2)
+);
+
+CREATE TABLE customers (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100) NOT NULL
+);
+`;
+    let schema = parseDDL(pgDDL);
+    schema = extractInlineForeignKeys(pgDDL, schema);
+    const orders = schema.tables.find((t) => t.name === "orders")!;
+    expect(orders.foreignKeys).toHaveLength(1);
+    expect(orders.foreignKeys[0].referencedTable).toBe("customers");
+  });
+});

package/src/parser.ts

@@ -0,0 +1,185 @@
+import { Schema, Table, Column, ForeignKey } from "./types.js";
+
+export function parseDDL(ddl: string): Schema {
+  const tables: Table[] = [];
+  const createTableRegex =
+    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?(\w+)[`"']?\s*\(([\s\S]*?)\)\s*(?:ENGINE|;|\n\n)/gi;
+
+  let match: RegExpExecArray | null;
+  while ((match = createTableRegex.exec(ddl)) !== null) {
+    const tableName = match[1];
+    const body = match[2];
+    const table = parseTableBody(tableName, body);
+    tables.push(table);
+  }
+
+  if (tables.length === 0) {
+    const simpleRegex =
+      /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?(\w+)[`"']?\s*\(([\s\S]*?)\)/gi;
+    while ((match = simpleRegex.exec(ddl)) !== null) {
+      const tableName = match[1];
+      const body = match[2];
+      const table = parseTableBody(tableName, body);
+      tables.push(table);
+    }
+  }
+
+  return { tables };
+}
+
+function parseTableBody(tableName: string, body: string): Table {
+  const columns: Column[] = [];
+  const foreignKeys: ForeignKey[] = [];
+  const primaryKeyColumns: string[] = [];
+
+  const lines = splitTableBody(body);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    const pkMatch = trimmed.match(
+      /^\s*(?:CONSTRAINT\s+[`"']?\w+[`"']?\s+)?PRIMARY\s+KEY\s*\(([^)]+)\)/i
+    );
+    if (pkMatch) {
+      const cols = pkMatch[1]
+        .split(",")
+        .map((c) => c.trim().replace(/[`"']/g, ""));
+      primaryKeyColumns.push(...cols);
+      continue;
+    }
+
+    const fkMatch = trimmed.match(
+      /^\s*(?:CONSTRAINT\s+[`"']?\w+[`"']?\s+)?FOREIGN\s+KEY\s*\(([^)]+)\)\s*REFERENCES\s+[`"']?(\w+)[`"']?\s*\(([^)]+)\)/i
+    );
+    if (fkMatch) {
+      foreignKeys.push({
+        columns: fkMatch[1]
+          .split(",")
+          .map((c) => c.trim().replace(/[`"']/g, "")),
+        referencedTable: fkMatch[2],
+        referencedColumns: fkMatch[3]
+          .split(",")
+          .map((c) => c.trim().replace(/[`"']/g, "")),
+      });
+      continue;
+    }
+
+    const uniqueConstraint = trimmed.match(
+      /^\s*(?:CONSTRAINT\s+[`"']?\w+[`"']?\s+)?UNIQUE\s+(?:KEY|INDEX)?\s*(?:[`"']?\w+[`"']?\s*)?\(([^)]+)\)/i
+    );
+    if (uniqueConstraint) continue;
+
+    const indexMatch = trimmed.match(/^\s*(?:KEY|INDEX)\s/i);
+    if (indexMatch) continue;
+
+    const column = parseColumn(trimmed);
+    if (column) columns.push(column);
+  }
+
+  for (const col of columns) {
+    if (primaryKeyColumns.includes(col.name)) {
+      col.primaryKey = true;
+    }
+  }
+
+  return { name: tableName, columns, foreignKeys };
+}
+
+function splitTableBody(body: string): string[] {
+  const lines: string[] = [];
+  let current = "";
+  let parenDepth = 0;
+
+  for (const char of body) {
+    if (char === "(") parenDepth++;
+    if (char === ")") parenDepth--;
+    if (char === "," && parenDepth === 0) {
+      lines.push(current);
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  if (current.trim()) lines.push(current);
+
+  return lines;
+}
+
+function parseColumn(line: string): Column | null {
+  const match = line.match(
+    /^\s*[`"']?(\w+)[`"']?\s+([\w(),.]+(?:\s*\(\d+(?:,\s*\d+)?\))?)/i
+  );
+  if (!match) return null;
+
+  const name = match[1];
+  const type = match[2].toUpperCase();
+
+  const upperLine = line.toUpperCase();
+  const nullable = !upperLine.includes("NOT NULL");
+  const primaryKey =
+    upperLine.includes("PRIMARY KEY") ||
+    (upperLine.includes("SERIAL") && !upperLine.includes("BIGSERIAL"));
+  const unique =
+    upperLine.includes("UNIQUE") || upperLine.includes("PRIMARY KEY");
+
+  let defaultValue: string | undefined;
+  const defaultMatch = line.match(/DEFAULT\s+([^,\s]+)/i);
+  if (defaultMatch) defaultValue = defaultMatch[1].replace(/['"]/g, "");
+
+  const inlineFkMatch = line.match(
+    /REFERENCES\s+[`"']?(\w+)[`"']?\s*\(([^)]+)\)/i
+  );
+
+  return {
+    name,
+    type,
+    nullable,
+    primaryKey,
+    unique,
+    defaultValue,
+    ...(inlineFkMatch ? { _inlineRef: inlineFkMatch } : {}),
+  } as Column;
+}
+
+export function extractInlineForeignKeys(ddl: string, schema: Schema): Schema {
+  const createTableRegex =
+    /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?(\w+)[`"']?\s*\(([\s\S]*?)\)(?:\s*(?:ENGINE|;|\n\n))/gi;
+
+  let match: RegExpExecArray | null;
+  while ((match = createTableRegex.exec(ddl)) !== null) {
+    const tableName = match[1];
+    const body = match[2];
+    const table = schema.tables.find((t) => t.name === tableName);
+    if (!table) continue;
+
+    const lines = splitTableBody(body);
+    for (const line of lines) {
+      const colMatch = line.match(/^\s*[`"']?(\w+)[`"']?\s+/);
+      const fkMatch = line.match(
+        /REFERENCES\s+[`"']?(\w+)[`"']?\s*\(([^)]+)\)/i
+      );
+      if (colMatch && fkMatch) {
+        const colName = colMatch[1].replace(/[`"']/g, "");
+        const refTable = fkMatch[1];
+        const refCols = fkMatch[2]
+          .split(",")
+          .map((c) => c.trim().replace(/[`"']/g, ""));
+
+        const exists = table.foreignKeys.some(
+          (fk) =>
+            fk.columns.includes(colName) && fk.referencedTable === refTable
+        );
+        if (!exists) {
+          table.foreignKeys.push({
+            columns: [colName],
+            referencedTable: refTable,
+            referencedColumns: refCols,
+          });
+        }
+      }
+    }
+  }
+
+  return schema;
+}