{"_id":"@aawejpathan/openboard","name":"@aawejpathan/openboard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aawejpathan/openboard","version":"0.1.0","description":"Local-first whiteboard for humans and AI agents","type":"module","bin":{"openboard":"bin/openboard.js","open-board":"bin/openboard.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","publishConfig":{"access":"public"},"author":{"name":"Aawej & OpenBoard Contributors"},"license":"MIT","homepage":"https://github.com/atpaawej/openboard#readme","repository":{"type":"git","url":"git+https://github.com/atpaawej/openboard.git"},"bugs":{"url":"https://github.com/atpaawej/openboard/issues"},"keywords":["whiteboard","tldraw","mcp","model-context-protocol","ai-agents","local-first","diagrams","canvas","architecture","claude-code","cursor","opencode","codex"],"engines":{"node":">=18.0.0"},"scripts":{"build":"node ./build.js","clean":"rm -rf dist web tsconfig.tsbuildinfo","typecheck":"tsc --noEmit"},"dependencies":{"better-sqlite3":"^13.0.3","commander":"^13.1.0","cors":"^2.8.5","express":"^4.21.2","tldraw":"^3.15.6"},"devDependencies":{"@types/better-sqlite3":"^9.6.0","@types/cors":"^2.8.17","@types/express":"^5.0.0","@types/node":"^22.13.4","esbuild":"^0.25.0","typescript":"^5.7.3"},"gitHead":"05c077a4f7784e3205aba513fbb61c88c452b6e3","_id":"@aawejpathan/openboard@0.1.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-0QRCLcGKs8lfRZStejPtzTYCBZzOIWsX+VlVkU5duYRZAMZ+MKBt1DE05fua6NVoxI9aiPRAMtTF4shJycyMLQ==","shasum":"706f9af4c18dd3de318e1bee7535a1ccecbbc13b","tarball":"https://registry.npmjs.org/@aawejpathan/openboard/-/openboard-0.1.0.tgz","fileCount":9,"unpackedSize":2005093,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD5DmBOeiGVbdrjRAFuhvWG5Sr+tuSFUGLb5MrmUO2S8gIgZgKEEg4vPHagKUwSFfWfNpSsqzYFrj5JhOfAs2ODeMM="}]},"_npmUser":{"name":"aawejpathan","email":"pathanaawej786@gmail.com"},"directories":{},"maintainers":[{"name":"aawejpathan","email":"pathanaawej786@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openboard_0.1.0_1786688038286_0.6985411963419865"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T06:13:58.134Z","0.1.0":"2026-08-14T06:13:58.462Z","modified":"2026-08-14T06:13:58.669Z"},"maintainers":[{"name":"aawejpathan","email":"pathanaawej786@gmail.com"}],"description":"Local-first whiteboard for humans and AI agents","homepage":"https://github.com/atpaawej/openboard#readme","keywords":["whiteboard","tldraw","mcp","model-context-protocol","ai-agents","local-first","diagrams","canvas","architecture","claude-code","cursor","opencode","codex"],"repository":{"type":"git","url":"git+https://github.com/atpaawej/openboard.git"},"author":{"name":"Aawej & OpenBoard Contributors"},"bugs":{"url":"https://github.com/atpaawej/openboard/issues"},"license":"MIT","readme":"# OpenBoard\n\nLocal-first whiteboard for humans and AI agents.\n\n```bash\nnpm install -g open-board\nopenboard start\n```\n\nOpenBoard runs entirely on your local machine. Whiteboards and canvas metadata are stored in your local SQLite database at:\n\n```text\n~/.openboard/openboard.db\n```\n\n---\n\n## ✦ Connect Your AI Agent via MCP\n\nOpenBoard includes a native Model Context Protocol (MCP) server over `stdio` for external AI agents.\n\n### Generic MCP stdio Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"openboard\": {\n      \"command\": \"openboard\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThe configuration tells your MCP client to launch the local `openboard mcp` command. Stdio JSON-RPC frames are exchanged directly with the server runtime without requiring a running browser.\n\n### Equivalent Shell Command\n\n```bash\nopenboard mcp\n```\n\n---\n\n## ✦ What is OpenBoard?\n\nOpenBoard is a lightweight, local-first infinite whiteboard pairing an interactive **tldraw** canvas with an **MCP stdio server**. It allows developers and autonomous AI coding agents (Claude Code, Cursor, OpenCode, Codex, OpenClaw, Hermes) to create, inspect, and update software architecture diagrams, workflows, and visual notes collaboratively.\n\n### Why OpenBoard?\n\n- **Local-First & Private:** All data resides in a local SQLite file (`~/.openboard/openboard.db`). Zero telemetry, zero cloud lock-in, zero external API dependencies.\n- **AI Agent Native:** Autonomous coding agents can discover, create, update, and organize whiteboards using 13 high-level semantic tools.\n- **Headless Canvas Inspection:** Agents can inspect semantic canvas structures and render vector SVG screenshots without a browser or GUI environment.\n- **Live SSE Projection:** When a human has a board open in their browser, agent modifications stream seamlessly in real time via Server-Sent Events (SSE).\n- **Browser Optional for Agents:** AI agents can manipulate boards whether the web UI is open or closed.\n\n---\n\n## ✦ Architecture Flow\n\n```text\nExternal AI Agent\n       │\n       │ MCP client\n       ▼\nstdio\n       │\n       ▼\nopenboard mcp\n       │\n       ▼\nOpenBoard MCP Server\n       │\n       ▼\nBoardService / CanvasService\n       │\n       ├───────────────┐\n       ▼               ▼\n    SQLite          Canvas\n                       │\n                     tldraw\n                       │\n                 optional browser\n```\n\n### Architectural Guarantees:\n\n1. **MCP does not connect directly to SQLite:** All operations pass through domain-validated `BoardService` and `CanvasService`.\n2. **MCP does not connect directly to React:** Canvas operations execute against a headless tldraw store engine.\n3. **MCP does not require a browser:** Boards can be created, updated, and queried while no browser window is running.\n4. **Explicit `board_id` targeting:** Every canvas operation explicitly references the target board ID.\n5. **Live Projection:** If a user opens the board in a browser, changes made by external agents project into the active view instantly.\n\n---\n\n## ✦ Supported MCP Clients & Quick Setup\n\n| AI Client / Tool | Setup Command or Configuration Path                           | Format                         |\n| :--------------- | :------------------------------------------------------------ | :----------------------------- |\n| **Claude Code**  | `claude mcp add openboard --command=\"openboard\" --args=\"mcp\"` | CLI / `~/.claude.json`         |\n| **Cursor**       | `~/.cursor/mcp.json`                                          | JSON (`mcpServers`)            |\n| **OpenCode**     | `~/.config/opencode/opencode.jsonc`                           | JSONC (`mcp.openboard`)        |\n| **OpenAI Codex** | `~/.codex/config.toml`                                        | TOML (`mcp_servers.openboard`) |\n| **OpenClaw**     | `~/.openclaw/config.json`                                     | JSON (`mcpServers`)            |\n| **Hermes Agent** | `~/.hermes/config.yaml`                                       | YAML (`mcp_servers`)           |\n| **Generic MCP**  | Any client supporting stdio MCP JSON-RPC 2.0                  | `openboard mcp`                |\n\n---\n\n## ✦ MCP Tools Reference (13 Semantic Tools)\n\nOpenBoard exposes 13 semantic tools to connected agents:\n\n### Board Lifecycle & Organization\n\n1. `list_boards`: List whiteboards with filtering (all, recent, favorites, trash) and keyword search.\n2. `create_board`: Create a new whiteboard with title and optional description.\n3. `get_board`: Retrieve board metadata, document summary, and timestamps.\n4. `rename_board`: Rename an existing whiteboard.\n5. `duplicate_board`: Clone a board and its complete canvas document.\n6. `favorite_board`: Bookmark or toggle favorite status.\n7. `delete_board`: Move a whiteboard to Trash (soft delete).\n8. `restore_board`: Recover a deleted whiteboard from Trash.\n\n### Canvas Inspection & Manipulation\n\n9. `get_canvas_state`: Retrieve semantic shapes, positions, dimensions, text, and arrow bindings.\n10. `get_canvas_screenshot`: Capture a headless vector SVG visual screenshot of the canvas.\n11. `create_shapes`: Create shapes (geo rectangles, ellipses, notes, text, frames, arrows).\n12. `update_shapes`: Modify shape positions, dimensions, text, colors, or arrow connections.\n13. `delete_shapes`: Remove shapes and automatically clean attached bindings.\n\n---\n\n## ✦ CLI Reference\n\n```bash\nopenboard start      # Start local workspace server & open web dashboard (default port: 3000)\nopenboard mcp        # Start Model Context Protocol server on stdio for AI agents\nopenboard info       # Display local configuration, database path, and agent MCP details\nopenboard -v         # Display installed version\nopenboard --help     # Display CLI help\n```\n\n### Options for `openboard start`\n\n- `-p, --port <number>`: Port to listen on (default: `3000`)\n- `-h, --host <host>`: Host address to bind to (default: `localhost`)\n- `--db <path>`: Custom SQLite database path (default: `~/.openboard/openboard.db`)\n- `--no-open`: Do not automatically open browser on startup\n\n---\n\n## ✦ Complete Documentation\n\nDetailed technical guides are available in the repository and in the interactive web UI at `http://localhost:3000/docs`:\n\n- [Getting Started](docs/getting-started.md)\n- [System Architecture](docs/architecture.md)\n- [MCP Architecture](docs/mcp-architecture.md)\n- [MCP Overview](docs/mcp/overview.md)\n- [MCP Tools Reference](docs/mcp/tools.md)\n- [MCP Stdio Connection](docs/mcp/connection.md)\n- [Troubleshooting Guide](docs/mcp/troubleshooting.md)\n- **Agent Integration Guides:**\n  - [Claude Code](docs/agents/claude-code.md)\n  - [Cursor](docs/agents/cursor.md)\n  - [OpenCode](docs/agents/opencode.md)\n  - [OpenAI Codex / Agents](docs/agents/codex.md)\n  - [OpenClaw](docs/agents/openclaw.md)\n  - [Hermes Agent](docs/agents/hermes.md)\n  - [Generic MCP Client](docs/agents/generic-mcp.md)\n\n---\n\n## ✦ Development & Monorepo\n\n```bash\n# Clone the repository\ngit clone https://github.com/atpaawej/openboard.git\ncd openboard\n\n# Install dependencies\nnpm install\n\n# Run test suite across all workspaces\nnpm run test\n\n# Typecheck and build\nnpm run typecheck\nnpm run build\n```\n\n---\n\n## ✦ License\n\nMIT License — Copyright (c) 2026 OpenBoard Contributors. See [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md","_rev":"1-229c5e6989c190634f21e223d25bb0df"}