@trohde/agentic-canvas 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 - Unreleased
+
+- Initial local-first Agentic Canvas implementation.
+- Added Excalidraw-backed browser canvas, MCP Streamable HTTP tools, WebSocket scene sync, save/open, and screenshot support.
+- Added production npm package metadata, CI, release documentation, and package smoke checks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Klok Rohde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Agentic Canvas
+
+Agentic Canvas is a local-first visual canvas that an AI agent drives through a local MCP server. The first plugin embeds Excalidraw in a browser page, while a single local Node process serves the page, exposes MCP over Streamable HTTP, and syncs scene changes over WebSocket.
+
+Published package: `@trohde/agentic-canvas`
+
+Executable: `agentic-canvas`
+
+## Prerequisites
+
+- Node.js 20.19 or newer
+- npm
+- A modern browser
+- An MCP-capable client, such as Claude Code or Claude Desktop
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Run
+
+```bash
+npm start -- --canvas excalidraw
+```
+
+For package usage after publishing:
+
+```bash
+npx @trohde/agentic-canvas --canvas excalidraw
+```
+
+Flags:
+
+- `--canvas <name>`: canvas plugin, currently only `excalidraw`
+- `--port <n>`: port, default `3333`
+- `--host <host>`: bind host, default `127.0.0.1`
+- `--workspace <dir>`: root for save/open/screenshot files, default current directory
+- `--open` / `--no-open`: open the browser on startup, default open
+
+Optional environment overrides are `AGENTIC_CANVAS_PORT`, `AGENTIC_CANVAS_HOST`, and `AGENTIC_CANVAS_WORKSPACE`. No secrets or `.env` file are required.
+
+## Develop
+
+For backend, MCP tool, plugin, or workspace changes:
+
+```bash
+npm run dev
+```
+
+For browser HMR, run the backend and Vite dev server in separate terminals:
+
+```bash
+npm run dev:server
+npm run dev:web
+```
+
+Open `http://127.0.0.1:5173` for the Vite UI. MCP clients should still connect to the backend at `http://127.0.0.1:3333/mcp`.
+
+See `docs/mcp-dev.md` for Codex configuration, MCP Inspector usage, and restart expectations.
+
+## Connect An MCP Client
+
+With the server running on the default port:
+
+```bash
+claude mcp add --transport http agentic-canvas http://127.0.0.1:3333/mcp
+```
+
+Example tool flow:
+
+1. Call `draw_rectangle` with `{ "x": 100, "y": 100, "width": 200, "height": 120, "text": "Hello" }`; a labeled rectangle appears in the browser.
+2. Select the rectangle in the browser and call `get_selected_objects`; the tool returns the selected normalized object.
+3. Call `screenshot`; the tool returns a PNG image.
+4. Call `save_canvas` with `{ "path": "demo.excalidraw" }`; the file is written inside the workspace.
+5. Call `clear_canvas`, then `open_canvas` with `{ "path": "demo.excalidraw" }`; the saved scene is restored.
+
+## Test And Build
+
+```bash
+npm run verify
+npm run build
+```
+
+Individual checks:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+```
+
+Built-server smoke test:
+
+```bash
+node dist/cli/index.js --no-open --port 3939
+```
+
+Then probe `http://127.0.0.1:3939/healthz` and call `get_canvas_state` through an MCP Streamable HTTP client.
+
+MCP Inspector:
+
+```bash
+npm run inspect:mcp
+```
+
+## Manual UI Verification
+
+1. Run `npm run build && npm start -- --canvas excalidraw`.
+2. Connect an MCP client to `http://127.0.0.1:3333/mcp`.
+3. Call `draw_rectangle`, `add_text`, `draw_arrow`, and `create_flowchart`.
+4. Confirm the shapes appear live in the browser.
+5. Call `save_canvas`, `clear_canvas`, and `open_canvas`; confirm the scene clears and reloads.
+6. Select a shape in the browser, then call `get_selected_objects`; confirm the selected object id is returned.
+7. Call `screenshot`; confirm a PNG is returned and, when `path` is provided, written in the workspace.
+8. Drag or edit a shape by hand in the browser, then call `list_objects`; confirm the listing reflects the human edit.
+
+## Release Checks
+
+This project follows Semantic Versioning. Version scripts update `package.json` and `package-lock.json` without committing or tagging:
+
+```bash
+npm run version:patch
+npm run version:minor
+npm run version:major
+```
+
+Before publishing, run:
+
+```bash
+npm run release:dry-run
+```
+
+See `docs/release.md` for the GitHub Actions and npm trusted publishing flow.
+
+## Project Structure
+
+```text
+src/cli/                 CLI entry
+src/server/              Express, MCP HTTP, WebSocket bridge, workspace safety
+src/mcp/                 MCP server registration and baseline tools
+src/core/                Plugin interface and normalized scene types
+src/plugins/excalidraw/  Excalidraw plugin, element builder, adapter, tools
+src/web/                 React + Excalidraw browser app
+src/shared/              Shared protocol and logger
+tests/                   Vitest unit and integration tests
+docs/                    Architecture notes
+scripts/                 Release and package smoke scripts
+.github/workflows/       CI and npm publish workflows
+```
+
+## Known Limitations
+
+- HTTP MCP transport only; no stdio transport in v1.
+- Single browser session is the expected mode.
+- Full-scene sync is used instead of diffs or CRDT collaboration.
+- Screenshot and selected-object lookup require a connected browser.
+- The Excalidraw tool surface is intentionally small: shapes, text, frames, groups, arrows, flowcharts, save/open, and screenshot.

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+The project is pre-1.0. Security fixes target the latest published version unless otherwise noted in the release notes.
+
+## Reporting A Vulnerability
+
+Report security issues privately by emailing Thomas Klok Rohde at <rohde.thomas@gmail.com>.
+
+Please include:
+
+- affected version or commit;
+- operating system and Node.js version;
+- steps to reproduce;
+- expected and observed behavior;
+- any relevant logs or sample files.
+
+Do not include real secrets in reports. Agentic Canvas is local-first and should not require secrets for normal use.