db-diagram-tool-mcp 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# db-diagram-tool-mcp
+
+A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server
+(stdio) that lets MCP clients — **Claude Code** and **OpenAI Codex** — read your
+[DB Diagram Tool](https://github.com/kai-exnodes) diagrams: list them, and fetch a
+diagram's schema as JSON, DBML, or SQL DDL.
+
+It talks to the DB Diagram Tool backend over its normal REST API, authenticated
+with a **Personal Access Token (PAT)**. It performs **only GET requests** — it can
+never modify your diagrams.
+
+## Tools
+
+| Tool | Args | Returns |
+|------|------|---------|
+| `list_diagrams` | — | The diagrams your token can access (id, name, role, visibility, updated time). |
+| `get_diagram` | `id` | Metadata + the full schema snapshot (tables, columns, relationships) as JSON. |
+| `get_diagram_dbml` | `id` | The diagram rendered as [DBML](https://dbml.dbdiagram.io) (dbdiagram.io text format). |
+| `get_diagram_sql` | `id`, `dialect?` (`postgres` \| `mysql`, default `postgres`) | Server-generated `CREATE TABLE` SQL DDL. |
+
+## Requirements
+
+- **Node.js ≥ 18** (uses the built-in `fetch`).
+- A **Personal Access Token** for your DB Diagram Tool account (create one in the
+  app's Settings → Personal Access Tokens). It looks like `ddt_pat_…`.
+- The backend **origin** URL (e.g. `http://localhost:8090` for local dev, or your
+  hosted instance).
+
+## Configuration
+
+The server reads two environment variables (set them in your MCP client's server
+config, below):
+
+| Variable | Required | Example | Notes |
+|----------|----------|---------|-------|
+| `DDT_BASE_URL` | yes | `http://localhost:8090` | Backend **origin** only — scheme + host[:port], **no** `/api/v1` path. |
+| `DDT_PAT` | yes | `ddt_pat_abc123…` | Your personal access token. Treat it like a password. |
+
+## Build
+
+Not published to npm yet — build it locally and point your client at the compiled
+entry (`dist/index.js`):
+
+```bash
+cd db-diagram-tool-mcp
+npm install
+npm run build
+# entry point: <this dir>/dist/index.js  (use its ABSOLUTE path below)
+```
+
+## Install in Claude Code
+
+**CLI (adds it for you):**
+
+```bash
+claude mcp add --transport stdio db-diagram-tool \
+  --env DDT_BASE_URL=http://localhost:8090 \
+  --env DDT_PAT=ddt_pat_your_token_here \
+  -- node /ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js
+```
+
+`--scope` defaults to `local` (this project, private to you); add `--scope user`
+to enable it everywhere, or `--scope project` to write a shared, git-tracked
+`.mcp.json`.
+
+**Or a project `.mcp.json`** (git-tracked; shared with your team):
+
+```json
+{
+  "mcpServers": {
+    "db-diagram-tool": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js"],
+      "env": {
+        "DDT_BASE_URL": "http://localhost:8090",
+        "DDT_PAT": "${DDT_PAT}"
+      }
+    }
+  }
+}
+```
+
+> **Don't commit your token.** Claude Code expands `${VAR}` (and `${VAR:-default}`)
+> in `.mcp.json`, so use `"DDT_PAT": "${DDT_PAT}"` and export `DDT_PAT` in your
+> shell — the raw token stays out of the repo.
+
+## Install in Codex
+
+**CLI:**
+
+```bash
+codex mcp add db-diagram-tool \
+  --env DDT_BASE_URL=http://localhost:8090 \
+  --env DDT_PAT=ddt_pat_your_token_here \
+  -- node /ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js
+```
+
+(The `--` before the command is required.)
+
+**Or `~/.codex/config.toml`** (global) — or `.codex/config.toml` in a project:
+
+```toml
+[mcp_servers.db-diagram-tool]
+command = "node"
+args = ["/ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js"]
+
+[mcp_servers.db-diagram-tool.env]
+DDT_BASE_URL = "http://localhost:8090"
+DDT_PAT = "ddt_pat_your_token_here"
+```
+
+> Codex TOML does **not** expand `${VAR}` — use literal values, and keep the file
+> private (don't commit a token).
+
+## Try it
+
+Once configured, ask your agent things like:
+
+- "List my DB Diagram Tool diagrams."
+- "Show the DBML for the diagram named _Blog_."
+- "Give me the Postgres DDL for diagram `<id>`."
+
+## Security
+
+- **Read-only.** Only GET endpoints are ever called.
+- Your PAT grants read access to your diagrams — store it like a password, prefer
+  `${DDT_PAT}` env expansion (Claude Code) over inlining, and never commit it.
+
+## Notes
+
+- `diagramToDbml.ts` is ported verbatim from the web app
+  (`db-diagram-tool-fe/src/lib/dbml/diagramToDbml.ts`); keep the two in sync.
+- Built against `@modelcontextprotocol/sdk` v1.30.

package/dist/client.js

@@ -0,0 +1,71 @@
+/**
+ * Read-only REST client for the DB Diagram Tool backend (frozen REST contract;
+ * same endpoints the web app uses). All requests are `Authorization: Bearer <pat>`
+ * and hit `${baseUrl}/api/v1<path>`. Only GETs — this package never writes.
+ */
+const API_PREFIX = "/api/v1";
+/** A structured API error carrying the HTTP status + the backend's error message. */
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ApiError";
+    }
+}
+export class DdtClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async get(path) {
+        const url = `${this.config.baseUrl}${API_PREFIX}${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: {
+                    Authorization: `Bearer ${this.config.pat}`,
+                    Accept: "application/json",
+                },
+            });
+        }
+        catch (e) {
+            throw new ApiError(0, `could not reach the backend at ${this.config.baseUrl} (${e.message}). Check DDT_BASE_URL and that the server is running.`);
+        }
+        const isJson = res.headers
+            .get("content-type")
+            ?.includes("application/json");
+        const payload = isJson ? await res.json().catch(() => undefined) : undefined;
+        if (!res.ok) {
+            const env = payload;
+            const message = env?.error?.message ?? env?.message ?? res.statusText ?? "request failed";
+            const hint = res.status === 401
+                ? " (check DDT_PAT — the token may be invalid or expired)"
+                : res.status === 403
+                    ? " (the token lacks access to this diagram)"
+                    : res.status === 404
+                        ? " (no such diagram, or it isn't shared with this token)"
+                        : "";
+            throw new ApiError(res.status, `${res.status} ${message}${hint}`, env?.error?.code);
+        }
+        return payload;
+    }
+    /** GET /diagrams → the token's accessible diagrams. */
+    listDiagrams() {
+        return this.get("/diagrams");
+    }
+    /** GET /diagrams/{id} → metadata. */
+    getDiagram(id) {
+        return this.get(`/diagrams/${encodeURIComponent(id)}`);
+    }
+    /** GET /diagrams/{id}/snapshot → the canonical Diagram JSON. */
+    getSnapshot(id) {
+        return this.get(`/diagrams/${encodeURIComponent(id)}/snapshot`);
+    }
+    /** GET /diagrams/{id}/export/ddl?dialect=… → server-generated SQL DDL. */
+    getDdl(id, dialect) {
+        return this.get(`/diagrams/${encodeURIComponent(id)}/export/ddl?dialect=${encodeURIComponent(dialect)}`);
+    }
+}

package/dist/config.js

@@ -0,0 +1,17 @@
+export function loadConfig(env = process.env) {
+    const baseUrl = (env.DDT_BASE_URL ?? "").trim().replace(/\/+$/, "");
+    const pat = (env.DDT_PAT ?? "").trim();
+    const missing = [];
+    if (!baseUrl) {
+        missing.push("DDT_BASE_URL — the backend origin, e.g. http://localhost:8090");
+    }
+    if (!pat) {
+        missing.push("DDT_PAT — a personal access token (ddt_pat_…)");
+    }
+    if (missing.length > 0) {
+        throw new Error(`db-diagram-tool-mcp: missing required environment variable(s):\n` +
+            missing.map((m) => `  - ${m}`).join("\n") +
+            `\nSet them in your MCP client's server config (see the README).`);
+    }
+    return { baseUrl, pat };
+}

package/dist/diagramToDbml.js

@@ -0,0 +1,98 @@
+/**
+ * Serialize a Diagram to DBML text (dbdiagram.io format). Pure text emit — no
+ * dependency. Ported verbatim from db-diagram-tool-fe/src/lib/dbml/diagramToDbml.ts
+ * (only the type import path differs); keep in sync with that source of truth.
+ *
+ * Mapping:
+ * - Column: `name type [settings]`, settings from pk/unique/not-null/default/note.
+ * - Composite PK (>1 pk column, order = column order): an `indexes { (a,b) [pk] }`
+ *   block instead of inline `[pk]` (DBML's composite-PK form).
+ * - Relationship: `Ref: from.col <op> to.col` where op = `<` (1:N, from=one),
+ *   `-` (1:1), `<>` (M:N). Our `from` is the one/parent (referenced key) side.
+ * - Table note → `Note:`; column note → `[note: …]`; default → `[default: \`…\`]`.
+ */
+const SIMPLE_IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** DBML identifier: bare when simple, else double-quoted. */
+function ident(name) {
+    return SIMPLE_IDENT.test(name)
+        ? name
+        : `"${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** DBML string literal: single-quoted, or triple-quoted when multi-line. */
+function str(s) {
+    if (s.includes("\n"))
+        return `'''${s}'''`;
+    return `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+/**
+ * A column TYPE. DBML accepts `name` / `name(args)` bare; anything else (a space
+ * like "double precision", odd chars) is double-quoted so the parser keeps it
+ * whole. Empty type (mid-edit) falls back to a placeholder so the DBML stays
+ * parseable.
+ */
+function typeLit(type) {
+    const t = type.trim();
+    if (!t)
+        return "unknown";
+    if (/^[A-Za-z_][A-Za-z0-9_ ]*(\([^)]*\))?$/.test(t) && !t.includes("  ")) {
+        // A plain type or type(args); DBML tolerates a single internal space.
+        return /\s/.test(t) ? `"${t}"` : t;
+    }
+    return `"${t.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function columnSettings(col, inComposite) {
+    const parts = [];
+    // A single PK is inline [pk]; composite PK goes in the indexes block instead.
+    if (col.isPrimaryKey && !inComposite)
+        parts.push("pk");
+    if (col.isUnique)
+        parts.push("unique");
+    if (!col.isNullable)
+        parts.push("not null");
+    if (col.default != null && col.default !== "")
+        parts.push(`default: \`${col.default}\``);
+    if (col.note)
+        parts.push(`note: ${str(col.note)}`);
+    return parts.length ? ` [${parts.join(", ")}]` : "";
+}
+function tableToDbml(t) {
+    const pkCols = t.columns.filter((c) => c.isPrimaryKey);
+    const composite = pkCols.length > 1;
+    const lines = [`Table ${ident(t.name)} {`];
+    for (const c of t.columns) {
+        lines.push(`  ${ident(c.name)} ${typeLit(c.type)}${columnSettings(c, composite)}`);
+    }
+    if (composite) {
+        lines.push("  indexes {");
+        lines.push(`    (${pkCols.map((c) => ident(c.name)).join(", ")}) [pk]`);
+        lines.push("  }");
+    }
+    if (t.note)
+        lines.push(`  Note: ${str(t.note)}`);
+    lines.push("}");
+    return lines.join("\n");
+}
+const OP = {
+    "1:1": "-",
+    "1:N": "<",
+    "M:N": "<>",
+};
+function refToDbml(r, diagram) {
+    const from = diagram.tables.find((t) => t.id === r.fromTableId);
+    const to = diagram.tables.find((t) => t.id === r.toTableId);
+    const fromCol = from?.columns.find((c) => c.id === r.fromColumnId);
+    const toCol = to?.columns.find((c) => c.id === r.toColumnId);
+    if (!from || !to || !fromCol || !toCol)
+        return null;
+    return `Ref: ${ident(from.name)}.${ident(fromCol.name)} ${OP[r.cardinality]} ${ident(to.name)}.${ident(toCol.name)}`;
+}
+export function diagramToDbml(diagram) {
+    const blocks = diagram.tables.map(tableToDbml);
+    const refs = diagram.relationships
+        .map((r) => refToDbml(r, diagram))
+        .filter((x) => x !== null);
+    const out = [...blocks];
+    if (refs.length)
+        out.push(refs.join("\n"));
+    return out.join("\n\n").trim() + "\n";
+}

package/dist/index.js

@@ -0,0 +1,137 @@
+#!/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 { loadConfig } from "./config.js";
+import { ApiError, DdtClient } from "./client.js";
+import { diagramToDbml } from "./diagramToDbml.js";
+/**
+ * db-diagram-tool-mcp — a read-only stdio MCP server exposing your DB Diagram Tool
+ * diagrams to MCP clients (Claude Code, Codex). Four tools: list_diagrams,
+ * get_diagram (schema JSON), get_diagram_dbml, get_diagram_sql. Auth is a PAT.
+ *
+ * stdio protocol note: stdout is the JSON-RPC channel — NEVER write to stdout.
+ * All diagnostics go to stderr.
+ */
+const SERVER_NAME = "db-diagram-tool";
+const SERVER_VERSION = "0.1.0";
+/** A successful text result. */
+function text(body) {
+    return { content: [{ type: "text", text: body }] };
+}
+/** A tool-level error result (isError so the client shows it as a failure, but the
+ * server keeps running for the next call). */
+function errorResult(e) {
+    const msg = e instanceof ApiError
+        ? e.message
+        : e instanceof Error
+            ? e.message
+            : String(e);
+    return {
+        content: [{ type: "text", text: `Error: ${msg}` }],
+        isError: true,
+    };
+}
+function buildServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    const readOnly = { readOnlyHint: true, openWorldHint: true };
+    server.registerTool("list_diagrams", {
+        title: "List diagrams",
+        description: "List the DB Diagram Tool diagrams this token can access. Returns id, name, your role, visibility, and last-updated time for each. Use an id with the other tools.",
+        annotations: readOnly,
+    }, async () => {
+        try {
+            const { diagrams } = await client.listDiagrams();
+            const rows = (diagrams ?? []).map((d) => ({
+                id: d.id,
+                name: d.name,
+                role: d.role,
+                visibility: d.visibility,
+                updatedAt: d.updatedAt,
+            }));
+            return text(JSON.stringify(rows, null, 2));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.registerTool("get_diagram", {
+        title: "Get diagram (schema JSON)",
+        description: "Get a diagram's metadata plus its schema (tables, columns with types/keys/nullability, and relationships) as JSON, by id. This is a DENOISED read-view: the editor's table layout coordinates are omitted (use get_diagram_dbml or get_diagram_sql for other views).",
+        inputSchema: {
+            id: z.string().describe("The diagram id (from list_diagrams)."),
+        },
+        annotations: readOnly,
+    }, async ({ id }) => {
+        try {
+            const [meta, diagram] = await Promise.all([
+                client.getDiagram(id),
+                client.getSnapshot(id),
+            ]);
+            // Denoise for coding agents: drop each table's editor layout coords
+            // (position x,y) — pure UI cruft that just adds token noise. Everything
+            // schema-relevant stays. (Not the raw contract; see the DBML/SQL tools.)
+            const schema = {
+                ...diagram,
+                tables: diagram.tables.map(({ position: _position, ...table }) => table),
+            };
+            return text(JSON.stringify({ meta, diagram: schema }, null, 2));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.registerTool("get_diagram_dbml", {
+        title: "Get diagram as DBML",
+        description: "Get a diagram rendered as DBML (the dbdiagram.io text format: Table/Ref blocks), by id. Compact and human-readable.",
+        inputSchema: {
+            id: z.string().describe("The diagram id (from list_diagrams)."),
+        },
+        annotations: readOnly,
+    }, async ({ id }) => {
+        try {
+            const diagram = await client.getSnapshot(id);
+            return text(diagramToDbml(diagram));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.registerTool("get_diagram_sql", {
+        title: "Get diagram as SQL DDL",
+        description: "Get a diagram's CREATE TABLE SQL DDL for a dialect (postgres or mysql), generated by the backend. Defaults to postgres.",
+        inputSchema: {
+            id: z.string().describe("The diagram id (from list_diagrams)."),
+            dialect: z
+                .enum(["postgres", "mysql"])
+                .default("postgres")
+                .describe("SQL dialect: postgres (default) or mysql."),
+        },
+        annotations: readOnly,
+    }, async ({ id, dialect }) => {
+        try {
+            const { sql, warnings } = await client.getDdl(id, dialect);
+            const header = warnings?.length
+                ? warnings.map((w) => `-- warning: ${w}`).join("\n") + "\n"
+                : "";
+            return text(header + sql);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    return server;
+}
+async function main() {
+    const config = loadConfig(); // throws with a clear message if unset
+    const client = new DdtClient(config);
+    const server = buildServer(client);
+    await server.connect(new StdioServerTransport());
+    // stderr only — stdout carries the MCP protocol.
+    process.stderr.write(`db-diagram-tool-mcp v${SERVER_VERSION} connected (backend: ${config.baseUrl})\n`);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${msg}\n`);
+    process.exit(1);
+});

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Diagram document types — a copy of the DB Diagram Tool contract-1 models
+ * (db-diagram-tool-fe/src/types/diagram.ts, frozen Diagram JSON schema v1.0.0).
+ * Kept in sync manually; this package only READS snapshots, so it needs the shape
+ * to (a) render DBML and (b) type the API responses.
+ */
+export const SCHEMA_VERSION = "1.0";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "db-diagram-tool-mcp",
+  "version": "0.1.0",
+  "description": "Read-only Model Context Protocol (stdio) server for DB Diagram Tool — lets Claude Code / Codex read your diagrams (list, schema JSON, DBML, SQL DDL).",
+  "type": "module",
+  "bin": {
+    "db-diagram-tool-mcp": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}