{
  "markdown": "# sketchdex\n\n[![ci](https://github.com/lucasr1b/sketchdex/actions/workflows/ci.yml/badge.svg)](https://github.com/lucasr1b/sketchdex/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/sketchdex)](https://www.npmjs.com/package/sketchdex)\n\nGive your agent a whiteboard. [sketchdex.dev](https://sketchdex.dev)\n\nSketchdex is an MCP server that lets Claude, Codex, Cursor and any other MCP\nclient draw hand-drawn Excalidraw diagrams while it explains something. Scenes\nare real `.excalidraw` files in a folder on your machine. The agent can draw,\nlook at what it drew, and fix it; you can open the result in the bundled\nlibrary app or on excalidraw.com and keep editing.\n\nBuilt on the official `@excalidraw/excalidraw` package, so the canvas is the\nreal thing. MIT.\n\n## Install\n\nNeeds Node 20 or newer. Rendering (`render_scene`) needs a Chromium-based\nbrowser on the machine: Chrome, Chromium, Edge or Brave. Everything else works\nwithout one.\n\nThe quickest way is to let the agent you already have do it. Paste this into\nany agent that can run commands:\n\n> install the sketchdex mcp server for me. run `npx -y sketchdex docs install` for the steps.\n\nOr by hand:\n\n**Claude Code**\n\n```bash\nclaude mcp add --scope user sketchdex -- npx -y sketchdex\n```\n\n**Codex**\n\n```bash\ncodex mcp add sketchdex -- npx -y sketchdex\n```\n\n**Cursor**\n\n[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=sketchdex&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNrZXRjaGRleCJdfQ==), or in `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sketchdex\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"sketchdex\"]\n    }\n  }\n}\n```\n\n**VS Code**\n\n```bash\ncode --add-mcp '{\"name\":\"sketchdex\",\"command\":\"npx\",\"args\":[\"-y\",\"sketchdex\"]}'\n```\n\n**Claude Desktop, Windsurf, Gemini CLI, anything else** takes the same\n`mcpServers` block as Cursor, or the command `npx -y sketchdex` as a stdio\nserver. `npx -y sketchdex docs install` has the exact file for each.\n\nThen, in a session: *draw me how the event loop works using sketchdex*.\n\nScenes are saved to `~/Documents/sketchdex`. Point them somewhere else with\n`--vault /path/to/folder` after the package name, or `SKETCHDEX_VAULT` in the\nserver's environment. An iCloud or Dropbox folder works.\n\n## Docs, for the agent\n\nThe manual ships inside the package so an agent can answer setup questions\nand fix problems without anyone reading a page:\n\n- `npx -y sketchdex docs [topic]` prints it (topics: `install`, `vault`,\n  `app`, `rendering`, `tools`, `drawing`, `troubleshooting`, or `all`).\n- The `sketchdex_docs` tool returns the same text once the server is\n  connected, and the server instructions tell the agent to use it for\n  anything about setup or errors.\n- The same topics are MCP resources at `sketchdex://docs/<topic>`.\n\n## The app\n\n```bash\nnpx sketchdex app\n```\n\nOpens the library in your browser: a grid of scenes with live previews,\nsearch, pin, rename, duplicate, import; a full Excalidraw editor for each; a\n`⌥K` switcher; and a **History** sidebar showing every agent write with the\nlabel the agent gave it, so you can preview, keep or revert each one. The app\nnotices agent writes as they happen.\n\nThe same process serves the tools over HTTP at `POST /mcp` and as plain REST at\n`POST /api/agent/:op`, localhost only.\n\n## What the agent gets\n\nNineteen tools over stdio. The ones that matter:\n\n| Tool | Does |\n|---|---|\n| `describe_scene` | Structure, not pixels: bounds, counts, a rounded summary per element. Start here. |\n| `add_elements` | Boxes, arrows, text, generated shapes (`polygon`, `star`, `arc`, `capsule`, `path`). `label` on a shape adds bound text; `start`/`end` on an arrow bind it. |\n| `update_elements` | One id and the fields that change. The read-modify-write happens server-side, so a two-line edit costs two lines. |\n| `import_svg` | Write an SVG, get hand-drawn editable elements grouped as one piece. The way to draw anything that has to look like something. |\n| `render_scene` | A real canvas render as PNG, whole scene or a region, so the agent can look at its own work. |\n| `check_scene` | Layout problems found by geometry: hidden text, overlapping labels, dangling arrows, strays. |\n| `snapshot_scene`, `list_history`, `restore_snapshot` | The safety net. Every write snapshots the previous state first. |\n| `sketchdex_docs` | The manual by topic, so the agent can answer setup questions and fix errors itself. |\n\nThe full manual the agent reads is [`BRIEF.md`](BRIEF.md): the element format,\nthe hand-drawn contract (roughness, sparse anchors, flat colour, no clip-art),\npaper and ink rules, and the things that will bite.\n\n## How it holds up\n\n- **Files are the truth.** Every scene is a plain `.excalidraw` file. Atomic\n  writes (temp file, rename), deletes go to `trash/`, and `index.json` is a\n  cache the server rebuilds from the files if it is lost.\n- **Every agent write is undoable.** Snapshots are gzipped, capped at 20 per\n  scene, images excluded, and never expire on their own.\n- **Deltas, not rewrites.** Edits you make in the editor while the agent works\n  survive: writes carry a revision token and conflicting saves are merged.\n- **Local only.** No account, no upload, no telemetry. The server binds\n  127.0.0.1.\n\n```\n~/Documents/sketchdex/\n├── index.json              names, timestamps, pins (a cache, not the truth)\n├── scenes/<id>.excalidraw  the scene itself, real Excalidraw format\n├── thumbs/<id>.svg         library previews\n├── history/<id>/           snapshots taken before agent writes, gzipped\n└── trash/<stamp>-<id>.excalidraw\n```\n\n## Node API\n\n```js\nimport { createAgentApi } from \"sketchdex\";\nconst api = createAgentApi(); // or createAgentApi(\"/path/to/vault\")\nawait api.describeScene(\"Brain Dump\");\n```\n\nSame implementation as the MCP and REST surfaces. Works with the app closed.\n\n## Development\n\n```bash\ngit clone https://github.com/lucasr1b/sketchdex\ncd sketchdex\nnpm install          # also retunes Excalidraw's colour picker for dark paper\nnpm run dev          # app + API + HTTP MCP on http://localhost:5173\nnpm run build        # dist/, which the CLI and the render page need\nnode bin/sketchdex.js app\n```\n\nFor an MCP client pointed at a checkout, use `node /path/to/sketchdex/mcp/server.js`\nas the command. In a checkout the server hot-reloads its worker when a file\nunder `server/` or `mcp/` changes, so edits are live on the next tool call\nwithout restarting the client.\n\n`npm run lint`, `npx tsc -p tsconfig.app.json --noEmit` and `npm test` before\ncommitting. The test packs the package, installs it into a clean project and\ndrives it through a real MCP client, including a render; CI runs it on macOS,\nLinux and Windows.\n[`AGENTS.md`](AGENTS.md) maps the codebase and the rules that must survive\nedits. There is also a macOS desktop shell: `npm run electron:dev`.\n\n## Notes\n\n- New scenes are dark paper (`#121212`) and nothing is ever colour-inverted:\n  the canvas, thumbnails and renders show every hex exactly as written. Paper\n  colour is per scene (`viewBackgroundColor`).\n- The first render on a fresh install takes a few seconds while the browser\n  starts; after that about a second and a half.\n- Set `SKETCHDEX_BROWSER=/path/to/browser` if the browser is somewhere unusual.\n- The server only answers requests whose Host is localhost and refuses\n  cross-site writes, so a web page open in your browser cannot touch the\n  vault. It still binds a plain local port: anything running as you on the\n  same machine can reach it, which is the point.\n- In the app, `⌘K` opens the scene switcher, which shadows Excalidraw's own\n  \"add link\" shortcut; use the context menu for links.\n- The app registers a small service worker (for install-as-app). It does no\n  caching, but if you run another project on the same port later it will show\n  up in that project's devtools until you unregister it.\n",
  "bytes": 7830,
  "sha": "b73f023dada81a1f74b3dad6ea7279b5cde20c70dfe742e5da144c68e5219325",
  "repo_slug": "lucasr1b/sketchdex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lucasr1b_sketchdex_c85d9589/readme"
}