# schema-viz MCP server

A local [MCP](https://modelcontextprotocol.io) server that renders a database
schema as an **interactive, dbdiagram.io-style ER diagram** in your browser:
draggable table cards, color-coded headers, PK/FK/unique badges, relationship
lines, pan, and zoom. No internet, no account — it runs entirely on this machine.

## How it works

- You give it **DBML** (the same syntax as dbdiagram.io) — either inline text or
  a path to a `.dbml` file. With no input it shows the bundled `schema.dbml`
  (the LLM-Tinder schema).
- It parses the DBML (small dependency-free parser in `lib/parseDbml.js`),
  renders a self-contained HTML page, serves it from a local HTTP server
  (`http://127.0.0.1:4477`), and opens your browser.
- Call it again with an updated schema and the open tab **auto-reloads**.

## Tools

| Tool | What it does |
| --- | --- |
| `display_schema` | Render & open a schema. Args: `dbml` (text), `filePath` (path to `.dbml`), `title`, `open` (bool). |
| `get_schema_viewer_status` | Report whether the viewer is running and its URL. |

## Register with Claude Code

A project-scoped `.mcp.json` is already created at the repo root pointing at
`schema-mcp/index.js`. Restart Claude Code (or approve the server when prompted)
and the `schema-viz` tools become available. Verify with `/mcp`.

To register it globally instead:

```bash
claude mcp add schema-viz -- node "$(pwd)/schema-mcp/index.js"
```

## Try it without MCP

```bash
cd schema-mcp
npm install
npm run demo        # parses schema.dbml, serves it, opens the browser
```

## Diagram controls

- **Drag a table header** to move it; relationship lines follow.
- **Drag the background** to pan; **scroll** to zoom (or use the toolbar `+ / −`).
- **Auto-arrange** re-packs the tables; **Reset** restores the default view.

## Config

- Port: set `SCHEMA_VIZ_PORT` (default `4477`).

## Slash commands (bonus)

`commands/` holds the versioned source for the companion Claude Code slash commands:

- `schema.md` → `/schema` — render the current project's `.dbml` as the interactive diagram.
- `xray.md` → `/xray` — explain any project (structure, stack, backend, live runtime) and feed
  the visualizer's Infrastructure / How-it-was-built tabs via `display_schema`'s `context` arg.

These must live in `~/.claude/commands/` to work — this folder is the backup / source of truth.
Install with: `cp commands/*.md ~/.claude/commands/`

## Tabbed dashboard (optional)

Pass a `context` object to `display_schema` to turn the diagram into a multi-tab dashboard:

- **Schema** — the ER diagram (always present).
- **Infrastructure** — cards of `{ title, rows: [[label, value]] }`: database, auth, hosting,
  env var *names* (never values), MCPs. Reproducible from a project's files.
- **How it was built** — `buildSteps: [{ phase, items: [{ what, why }] }]`, a step-by-step story.

With no `context`, only the Schema tab shows (backward compatible). The `/xray` command assembles
this context automatically from the project.