{
  "markdown": "# Lousa\n\n**A whiteboard where your AI agent draws its explanations.**\n\n![Your agent drawing a rate limiter explanation, stroke by stroke](docs/demo.gif)\n\nAsk your agent *\"explain this visually\"* and it sketches an animated, hand-drawn diagram on a live board — instead of another wall of text. Lousa is an MCP server + web viewer: the agent authors a declarative scene (boxes, arrows, cylinders, notes), and the board renders it stroke by stroke, as if someone were drawing it in front of you.\n\n> *Lousa* is Portuguese for the classic school blackboard.\n\n## Why it's different\n\n- **The agent is the artist.** No prompt box, no OCR — your coding agent already has the context and draws through typed MCP tools.\n- **Live, incremental drawing.** Follow-ups edit the scene; the open tab animates only what changed, like watching the diagram evolve.\n- **Point at things.** Click elements in the viewer to select them, then tell your agent *\"improve what I selected\"* — it reads your selection through `get_selection` and targets exactly that.\n- **Boards expire by default** (12h, sliding) — a whiteboard, not a document graveyard. `ttlHours: 0` keeps a board forever.\n\n## Quick start\n\nRequires [Node.js 18.17+](https://nodejs.org).\n\n```bash\n# Claude Code\nclaude mcp add lousa -- npx -y lousa mcp\n\n# or run the server directly\nnpx lousa            # viewer at http://127.0.0.1:4666\n```\n\nAny MCP host works — for stdio configuration use command `npx`, args `[\"-y\", \"lousa\", \"mcp\"]`. The stdio endpoint auto-starts the local server, so the viewer is always available. Then ask your agent to *\"draw how our auth flow works\"* and open the URL it returns.\n\n## MCP tools\n\n| Tool | What it does |\n|---|---|\n| `create_board` | Creates a board from a scene, returns `{id, url}` |\n| `update_board` | Replaces the scene; unchanged elements stay byte-identical so only changes animate |\n| `get_board` / `list_boards` | Read boards |\n| `get_selection` | What the user selected in the viewer (ids + full elements) |\n| `delete_board` | Deletes a board |\n\nThe scene is a JSON array of elements — `box`, `ellipse`, `diamond`, `cylinder`, `arrow` (connects ids), `line`, `text`, `note` — rendered with [rough.js](https://roughjs.com). The full schema ships inside the tool definitions; agents need no extra setup.\n\n## Self-hosting a shared server\n\nRun `lousa` on any Node host and point machines at it:\n\n```bash\nLOUSA_TOKEN=<secret> HOST=0.0.0.0 npx lousa        # server\nLOUSA_URL=https://your-host LOUSA_TOKEN=<secret> npx lousa mcp   # each client\n```\n\n`LOUSA_TOKEN` gates board listing/creation/deletion and `/mcp`; per-board URLs act as capability links. AWS Lambda + S3 deployment is supported out of the box (`lambda.js` handler + `LOUSA_BUCKET` for storage); any HTTPS front (API Gateway, etc.) works.\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `PORT` / `HOST` | `4666` / `127.0.0.1` | server bind |\n| `LOUSA_DATA_DIR` | `~/.lousa/boards` | filesystem board storage |\n| `LOUSA_BUCKET` | — | use S3 storage instead of filesystem |\n| `LOUSA_TOKEN` | — | require bearer token (header or `?t=`) on global routes and MCP |\n| `LOUSA_URL` | — | `lousa mcp` proxies to this remote server |\n| `LOUSA_DEFAULT_TTL_HOURS` | `12` | default board expiry |\n\n## Development\n\n```bash\nnpm install\nnpm test          # node --test\nnode cli.js       # local server\n```\n\n## License\n\n[AGPL-3.0](LICENSE) © Henrique Pires\n",
  "bytes": 3388,
  "sha": "54edcae95b18fdeeb2bd8e8f879fb3552030bad4323a4b5c1f3349a92912fa76",
  "repo_slug": "henriquepe/lousa",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_henriquepe_lousa_aed414f5/readme"
}