# draft1-mcp

MCP server for [draft1.ai](https://draft1.ai) — generate and iterate on draw.io-style architecture diagrams from natural language or code (Terraform, docker-compose, Kubernetes, SQL, Mermaid, PlantUML) directly from Claude Code, Claude Desktop, Cursor, or any MCP client.

## Tools

| Tool | Arguments | What it does |
|---|---|---|
| `generate_diagram` | `prompt` (string, required), `format` (optional: `auto` \| `terraform` \| `docker-compose` \| `kubernetes` \| `sql` \| `mermaid` \| `plantuml`, default `auto`) | Creates a diagram from a description or pasted source code. Returns the share URL, a `diagram_id` for follow-up edits, and an XML summary. |
| `edit_diagram` | `diagram_id` (string, required), `instruction` (string, required) | Applies a plain-English change to an existing diagram (e.g. "add a redis cache between the api and the db"). |

## Requirements

- Node.js >= 18.17
- A draft1 API key — create one at [app.draft1.ai](https://app.draft1.ai) (account settings)

## Configuration

| Environment variable | Required | Description |
|---|---|---|
| `DRAFT1_API_KEY` | yes | Your draft1 API key |
| `DRAFT1_API_URL` | no | API base URL override (default `https://api.app.draft1.ai`) |

## Install

### Claude Code

```sh
# once the package is published to npm:
claude mcp add draft1 --env DRAFT1_API_KEY=YOUR_KEY -- npx -y github:abdelhadi-azouni/draft1-mcp

# from a local checkout (this repo):
npm install && npm run build
claude mcp add draft1 --env DRAFT1_API_KEY=YOUR_KEY -- node /absolute/path/to/draft1-mcp/dist/index.js
```

Then in Claude Code: "generate a diagram of my terraform in ./infra".

### Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "draft1": {
      "command": "npx",
      "args": ["-y", "draft1-mcp"],
      "env": { "DRAFT1_API_KEY": "YOUR_KEY" }
    }
  }
}
```

(For a local checkout, use `"command": "node", "args": ["/absolute/path/to/draft1-mcp/dist/index.js"]` instead.)

Alternatively, bundle it as a one-click Claude Desktop extension: `npx @anthropic-ai/mcpb pack` in this directory (uses `manifest.json`; prompts the user for the API key on install).

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "draft1": {
      "command": "npx",
      "args": ["-y", "draft1-mcp"],
      "env": { "DRAFT1_API_KEY": "YOUR_KEY" }
    }
  }
}
```

## Errors

- **401** — invalid `DRAFT1_API_KEY`; create/rotate a key at app.draft1.ai (account settings).
- **402** — out of credits; top up at app.draft1.ai. Both are returned as tool errors with the server's message, so the calling agent can relay them.

## Development

```sh
npm install    # also builds via the prepare script
npm test       # builds, then runs node --test against dist/ with a mocked fetch
npm start      # run the stdio server locally (requires DRAFT1_API_KEY)
```

The server speaks MCP over stdio; stdout is reserved for the protocol and all logging goes to stderr.