<p align="center">
  <img src="assets/logo.svg" alt="erdlens" width="96" height="96" />
</p>

<h1 align="center">erdlens</h1>

<p align="center"><b>Your schema becomes an ER diagram, straight into your docs. And it tells you when the diagram goes stale.</b></p>

<p align="center">
  🇺🇸 English · <a href="README.id.md">🇮🇩 Bahasa Indonesia</a> · <a href="README.zh-CN.md">🇨🇳 简体中文</a>
</p>

<p align="center">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-6C8EEF" />
  <img alt="runtime deps" src="https://img.shields.io/badge/runtime%20deps-0-6C8EEF" />
  <img alt="tests" src="https://img.shields.io/badge/tests-57%20passing-6C8EEF" />
  <img alt="mcp" src="https://img.shields.io/badge/MCP-server-6C8EEF" />
  <img alt="typescript" src="https://img.shields.io/badge/TypeScript-MVVM-6C8EEF" />
</p>

<p align="center">
  <img src="assets/showcase.gif" alt="erdlens turning a schema into an ER diagram, a workflow into a flowchart, and catching drift after a migration" width="720" />
</p>

---

You ask Claude Code to document your database. It writes the doc, you generate an ER diagram in some
other tool, then you copy-paste the diagram back in. Two tools, double work, and the moment someone
runs a migration the diagram in the doc is quietly wrong.

**erdlens** is an MCP server that closes that loop. Claude Code reads your schema, turns it into a
Mermaid ER diagram, and writes it **into** the document in one pass. No second tool, no copy-paste.
And it can check later whether that diagram still matches the schema.

## Why it's different

The existing diagram MCP servers render Mermaid you already wrote. erdlens starts a step earlier: it
**reads the schema for you**, and a step later: it **watches for drift**.

|  | render your Mermaid | read the schema | write into the doc | drift-check |
|--|:--:|:--:|:--:|:--:|
| mermaid-preview MCPs | ✅ | ❌ | partial | ❌ |
| mermerd (CLI, not MCP) | ❌ | ✅ (DB only) | ❌ | ❌ |
| **erdlens** | ✅ | ✅ (5 sources) | ✅ | ✅ |

Schema sources: **SQL DDL, Prisma, Drizzle, TypeORM, SQLAlchemy** — file or text, auto-detected.

## Install (Claude Code)

```bash
claude mcp add erdlens -- npx -y github:ryanda9910/erdlens
```

Or point at a local clone:

```bash
git clone https://github.com/ryanda9910/erdlens
claude mcp add erdlens -- node /abs/path/to/erdlens/bin/erdlens.js
```

Then just ask Claude Code: *"document the database and put an ER diagram in docs/schema.md"*. It calls
`render_erd` and the diagram lands in the file.

## Tools

| tool | what it does |
|--|--|
| `schema_to_erd` | schema (path or text) → Mermaid `erDiagram` + a ```mermaid fenced block to paste anywhere |
| `render_erd` | writes the ERD to disk: `.mmd` source, an embeddable `.md`, and a self-contained `.html` preview — so it goes straight into a doc, no copy-paste |
| `drift_check` | compares an ERD already in a `.mmd`/`.md` against the current schema, and reports every table, column, and relation added or removed since. Run it in CI so a stale diagram fails the build |
| `workflow_to_diagram` | a workflow spec (a tiny text DSL or JSON steps) → Mermaid `flowchart` + fenced block. Document a process, pipeline, or state machine next to the ERD |
| `render_workflow` | same as `render_erd`, for workflows — writes the flowchart to disk, embeddable |

## The drift check

This is the part that keeps docs honest. After a migration:

```
$ erdlens drift docs/schema.md db/schema.sql
Diagram is stale. It drifted from the current schema:
  + tables added since: audit_logs
  ~ posts: +published +slug
  + relations added: posts->users
Regenerate with render_erd to fix.
```

Exit code is non-zero when stale, so it drops into a CI step or a pre-commit hook.

## Workflows too

Not just data. Give it a workflow and it draws the flowchart — same "into your docs" path.

```
# publish.flow
start -> draft
draft -> review
review -> publish : approved
review -> draft : changes
publish -> done
```

```bash
erdlens flow publish.flow
```
```
flowchart TD
  start(["start"])
  ...
  review -->|approved| publish
  review -->|changes| draft
```

Ask Claude Code *"put the publish workflow in docs/flow.md"* and it calls `render_workflow`.

## Also a CLI

Without an MCP client:

```bash
erdlens erd db/schema.sql            # print the Mermaid ERD
erdlens erd prisma/schema.prisma     # auto-detects Prisma
erdlens flow pipeline.flow           # print a Mermaid flowchart
erdlens drift docs/erd.mmd db/schema.sql   # exit 1 if drifted
erdlens tune                         # run the self-check loop (below)
```

## Self-improving loop

`erdlens tune` is a maker → checker → reflect loop: it runs every parser on a fixture plus a drift
scenario (maker), an independent grader flags anything that passed before and fails now (checker),
and it persists per-source pass state to `~/.erdlens/memory.json` (reflect). It's how the parsers stay
honest as new schema dialects get added — a regression surfaces instead of slipping through.

## Tests

```bash
npm test    # builds, then 57 assertions: 24 schema engine + 14 workflow + 19 MCP stdio
```

There's also an end-to-end script that drives the whole thing through a real Claude Code run
(`bash test/e2e.sh`, needs the `claude` CLI logged in).

## How it's built

TypeScript, laid out MVVM:

- **Model** (`src/model/`) — pure logic: schema parsers, workflow parser, drift diff, types.
- **ViewModel** (`src/viewmodel/`) — orchestration: the tool operations and the self-improving loop.
- **View** (`src/view/`) — surfaces: the JSON-RPC MCP server, the CLI, and Mermaid/HTML rendering.

Zero **runtime** dependencies. The MCP server is a from-scratch JSON-RPC stdio implementation; the HTML
preview loads Mermaid from a CDN only when you open it in a browser.

## License

MIT