<p align="center">
  <img src="https://raw.githubusercontent.com/HermesSilva/DASE-MCP/master/media/icon.png" width="96" alt="DASE logo" />
</p>

<h1 align="center">DASE ORM Designer MCP</h1>

<p align="center">
  <i>Give your AI agent hands on the data model: read, edit and organize the
  <code>.dsorm</code> diagram open in DASE — through 43 Model Context Protocol tools.</i>
</p>

---

## Overview

[DASE](https://marketplace.visualstudio.com/items?itemName=HermesSilva.dase) turns VS Code into a
visual ORM modeling workbench. This extension publishes DASE's whole API as an **MCP server**, so
GitHub Copilot agent mode — and any other MCP client — can work on the **live** diagram: the tables
it adds appear on the canvas immediately, positioned, colored and validated.

Install it and the server shows up ready to use; there is nothing to configure, no port to pick and
no JSON to paste into `mcp.json`.

> "Add an `Invoice` table with the usual audit fields, point it at `Customer`, and put it next to
> the other billing tables" — one prompt, applied to the open designer.

## Requirements

- **VS Code 1.101 or newer** (the version that lets extensions contribute MCP servers)
- The **DASE** extension — installed automatically as a dependency
- A DASE window with the model open; the tools act on the designer that owns your workspace

## Getting started

1. Install the extension (DASE comes with it).
2. Open a `.dsorm` file — that starts DASE's agent bridge.
3. Open Chat, switch to **Agent** mode, and open the tools picker: the **DASE ORM Designer** server
   is listed with its tools already enabled.
4. Ask for what you want. Run **DASE MCP: Show Bridge Status** from the Command Palette if you ever
   need to confirm the connection.

## What the agent can do

**43 tools** — the same surface DASE exposes to itself:

| Group | Tools | Examples |
|-------|------:|----------|
| Read | 12 | inspect the model, tables, fields, data types, validation issues, seed data, DBML export |
| Write | 23 | add/rename/delete tables, fields and FK references, move and color, edit any property, save |
| Commands | 7 | generate ORM code, create the SQL script, import DBML, organize tables with AI |
| Status | 1 | report connectivity and how to bring the designer online |

Destructive tools are annotated as such, so the client can ask before running them. Every tool
accepts an optional `document`, which targets a specific model — opening it when needed — instead of
whichever designer happens to be focused.

Full reference: [docs/MCP_API_SPEC.md](https://github.com/HermesSilva/DASE-MCP/blob/master/docs/MCP_API_SPEC.md).

## Settings

Both settings exist for unusual setups; leave them empty and discovery does the right thing.

| Setting | Default | Purpose |
|---------|---------|---------|
| `daseMcp.bridgeUrl` | `""` | Fixed bridge address, e.g. `http://127.0.0.1:39100/bridge`. Skips discovery. |
| `daseMcp.discoveryDir` | `""` | Directory holding DASE's `bridge-endpoint*.json` files. Defaults to the installed DASE extension's global storage. |

Commands: **DASE MCP: Show Bridge Status** and **DASE MCP: Refresh MCP Server**.

## How it works

```
Copilot agent mode ──stdio──> dase-mcp server ──HTTP (dase-bridge/1)──> DASE agent bridge
   (or Claude Code,            server/dase-mcp.cjs                       (VS Code extension host)
    Cursor, Windsurf…)         │  discovery: bridge-endpoint.<hash>.json           │
                               └── globalStorage/hermessilva.dase ◄─── written by ─┘
```

The full MCP implementation — server, 43 tools, protocol handling — lives **outside** VS Code, in
`src/server/`. DASE itself carries no MCP code: it only exposes a loopback **agent bridge** (plain
JSON over HTTP) and writes discovery files into its global storage. Each tool call becomes one HTTP
round trip; when a call fails (say, the ephemeral port changed after a reload), the server
re-discovers and retries once.

This extension is the thin part: it tells VS Code how to spawn that same server, hands it the
workspace folder as `cwd` — which is how the right DASE window gets picked when several are open —
and points it at DASE's exact global-storage directory.

Bridge protocol: `POST /bridge` with `{ "method": "...", "args": [...] }` →
`{ "ok": true, "result": ... }` or `{ "ok": false, "error": "..." }`. `GET /bridge` lists the
available methods. The bridge binds to `127.0.0.1` only and checks the `Origin` header; it is on by
default (`dase.agentBridge.enabled`).

## Other MCP clients

The same server drives DASE from outside VS Code. As a **Claude Code plugin**:

```
/plugin marketplace add https://github.com/HermesSilva/DASE-MCP
/plugin install dase-mcp
```

The editor registers MCP servers in-process, so the **Claude Code CLI does not inherit** this
extension's server — it reads its own config. The extension takes care of that: when it activates
and finds the CLI installed with no `dase` server registered, it asks once whether it may add it
(*Register* / *Not now* / *Never*). Every later activation checks the entry the CLI holds and
silently repairs it — the recorded path lives inside the versioned extension folder, so each
update moves it. **DASE MCP: Register with Claude Code CLI** in the Command Palette forces the
same registration, and is the way back for anyone who answered *Never*. Either way the CLI ends
up with:

```powershell
claude mcp add dase --scope user -e "DASE_MCP_DISCOVERY_DIR=<globalStorage>\hermessilva.dase" -- node "<extension>\server\dase-mcp.cjs"
```

For Claude Desktop, Cursor, Windsurf or any generic client, run the bundle over stdio:

```json
{
  "mcpServers": {
    "dase": { "command": "node", "args": ["<repo>/claude-plugin/server/dase-mcp.cjs"] }
  }
}
```

Environment overrides: `DASE_BRIDGE_URL` (skip discovery), `DASE_MCP_DISCOVERY_DIR` (extra discovery
directory).

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Tools fail with "no live DASE agent bridge" | Open a `.dsorm` file; check that `dase.agentBridge.enabled` is on. |
| The wrong model is edited | Pass `document`, or open the intended model — the server matches your workspace folder. |
| Nothing after an upgrade | **DASE MCP: Refresh MCP Server**, then re-run the request. |

## Build

```bash
npm install
npm run build   # typecheck + esbuild: server bundle, staged copy, extension bundle
npm run smoke   # fake bridge + stdio round trip
```

`claude-plugin/server/dase-mcp.cjs` is a committed build artifact — Claude Code plugin installs
clone the repo and must not need `npm install`. `server/` and `out/` are generated, and only those
two (plus `media/`) ship inside the VSIX.

## Release

Two channels, one version — both call `scripts/Set-Version.ps1`, which writes `package.json`, the
Claude plugin manifest and `SERVER_VERSION`:

```powershell
./build-package.ps1            # VSIX          (no -Version → increments the build)
./publish-package.ps1 -Pat …   # VS Code Marketplace
./prepare-release.ps1          # npm tarball + Claude Code plugin zip
```

## License

MIT © Hermes Silva. Integration and security notes:
[docs/MCP_INTEGRATION.md](https://github.com/HermesSilva/DASE-MCP/blob/master/docs/MCP_INTEGRATION.md).