<p align="center">
  <a href="https://letdraw.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="docs/assets/letdraw-logo-dark.svg">
      <img src="docs/assets/letdraw-logo.svg" alt="LetDraw" width="320">
    </picture>
  </a>
</p>

<h1 align="center">LetDraw MCP + REST</h1>

<p align="center">
  Connect AI assistants and your own scripts to <a href="https://letdraw.com">LetDraw</a> —
  read and author diagrams in your account through the
  <b>Model Context Protocol (MCP)</b> or the <b>public REST API</b>.
</p>

<p align="center">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  <img alt="Node 18+" src="https://img.shields.io/badge/node-18%2B-brightgreen">
  <img alt="MCP: stdio + HTTP" src="https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-8A2BE2">
</p>

LetDraw is a hand-drawn–style online whiteboard and diagramming app. With this
integration an MCP client (desktop AI apps, Cursor, VS Code, Codex, …) or any HTTP client
can list workspaces, create and update diagrams, build a diagram from code
(compose / Kubernetes / DOT / Terraform / SQL / …), stamp real product icons,
export to Mermaid or D2, and share read-only links.

> This repository ships the **client-side integration**: a zero-config MCP
> bridge, a typed REST SDK, the API spec, and setup docs. The LetDraw app and
> server are not part of this repo.

## What's here

| Path | What it is |
|---|---|
| [`packages/mcp`](packages/mcp) | `@letdraw/mcp` — zero-config stdio bridge to the hosted MCP server (`npx @letdraw/mcp`) |
| [`packages/sdk`](packages/sdk) | `@letdraw/sdk` — typed REST client for scripting |
| [`spec/mcp-tools.md`](spec/mcp-tools.md) | The MCP tools, resources, and scopes |
| [`spec/openapi.yaml`](spec/openapi.yaml) | OpenAPI 3.1 spec for the REST API |
| [`spec/capabilities.md`](spec/capabilities.md) | "How to draw well in LetDraw" guide for AI clients |
| [`docs/`](docs) | Getting started + per-client setup (desktop apps, HTTP clients, Cursor, VS Code, Codex) |
| [`examples/`](examples) | Copy-paste recipes |

## Endpoints

```
REST base   https://api.letdraw.com/api-v1
MCP URL     https://api.letdraw.com/mcp
```

Both authenticate with a **personal API token** (`Authorization: Bearer
ld_live_…`), not a login session. Create one in the LetDraw app under
**Account → Developer**. The exact URLs and a ready-to-paste client config are
shown there too.

## 60-second start (MCP)

The hosted server speaks Streamable-HTTP, so most clients connect directly. For
a stdio client, or for the simplest possible setup, use the bridge:

```jsonc
// MCP client config (mcpServers block)
{
  "mcpServers": {
    "letdraw": {
      "command": "npx",
      "args": ["-y", "@letdraw/mcp"],
      "env": { "LETDRAW_TOKEN": "ld_live_YOUR_TOKEN" }
    }
  }
}
```

See [docs/clients](docs/clients) for desktop apps, HTTP clients, Cursor, VS Code and Codex.

## 60-second start (REST)

```bash
curl https://api.letdraw.com/api-v1/workspaces \
  -H "Authorization: Bearer ld_live_YOUR_TOKEN"
```

Or with the SDK:

```ts
import { LetdrawClient } from '@letdraw/sdk';
const ld = new LetdrawClient({ token: process.env.LETDRAW_TOKEN! });
const { workspaces } = await ld.listWorkspaces();
```

## Scopes

Tokens carry scopes; each tool/route requires one:

- `diagrams:read` — list/get workspaces, folders, diagrams, icons
- `diagrams:write` — create/update/delete/share diagrams, from-code
- `export` — export to Mermaid / D2
- `ai:generate` — generate a diagram from a prompt (uses your own AI key)

## License

MIT — see [LICENSE](LICENSE). "LetDraw" and the LetDraw logo are trademarks of
their owner; see [NOTICE.md](NOTICE.md).