@genart-dev/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,264 @@
+# @genart-dev/mcp-server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [genart.dev](https://genart.dev) — 33 tools, 4 resources, and 3 prompts for creating and manipulating generative art with AI agents.
+
+Works with any MCP client: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Claude Desktop](https://claude.ai/download), [Codex CLI](https://github.com/openai/codex), [Cursor](https://cursor.sh), and more.
+
+## Install
+
+```bash
+npm install -g @genart-dev/mcp-server
+```
+
+For screenshot/export capture, also install Puppeteer:
+
+```bash
+npm install -g puppeteer
+```
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add genart-mcp -- genart-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "genart": {
+      "command": "genart-mcp"
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Add to `.codex/config.toml`:
+
+```toml
+[mcp_servers.genart]
+command = "genart-mcp"
+```
+
+Then ask your AI agent to create generative art:
+
+> "Create a workspace with a p5.js sketch that draws a grid of rotating squares using the golden ratio"
+
+## Tools (33)
+
+### Workspace (5)
+
+| Tool | Description |
+|------|-------------|
+| `create_workspace` | Create a new `.genart-workspace` with optional initial sketches |
+| `open_workspace` | Open an existing `.genart-workspace` and load all sketches |
+| `add_sketch_to_workspace` | Add an existing `.genart` file to the active workspace |
+| `remove_sketch_from_workspace` | Remove a sketch from workspace (optionally delete file) |
+| `list_workspace_sketches` | List all sketches with metadata summaries |
+
+### Sketch Lifecycle (7)
+
+| Tool | Description |
+|------|-------------|
+| `create_sketch` | Create a new `.genart` sketch — supports all 5 renderers |
+| `open_sketch` | Open a sketch by ID and set selection |
+| `update_sketch` | Update metadata, parameters, colors, canvas |
+| `update_algorithm` | Replace algorithm source code with optional validation |
+| `save_sketch` | Persist in-memory state to disk |
+| `fork_sketch` | Create a variant with new ID and optional modifications |
+| `delete_sketch` | Delete sketch file and remove from workspace |
+
+### Selection & Context (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_selection` | Full context for selected sketch(es) — algorithm, params, colors, philosophy |
+| `select_sketch` | Set canvas selection to one or more sketches |
+| `get_editor_state` | Full snapshot of workspace, sketches, and selection |
+| `set_working_directory` | Set base directory for sandboxed file operations |
+
+### Parameters (5)
+
+| Tool | Description |
+|------|-------------|
+| `set_parameters` | Update runtime parameter values |
+| `set_colors` | Update runtime color palette values |
+| `set_seed` | Set random seed (or generate random) |
+| `set_canvas_size` | Change dimensions via preset or explicit W/H |
+| `randomize_parameters` | Generate random values for all/specific parameters |
+
+### Arrangement (3)
+
+| Tool | Description |
+|------|-------------|
+| `arrange_sketches` | Move sketches to explicit canvas positions |
+| `auto_arrange` | Auto-layout with grid, row, column, or masonry |
+| `group_sketches` | Create/update named groups of sketches |
+
+### Gallery (2)
+
+| Tool | Description |
+|------|-------------|
+| `list_sketches` | Scan a directory for `.genart` files with metadata |
+| `search_sketches` | Search loaded sketches by title, renderer, params, skills |
+
+### Merge (1)
+
+| Tool | Description |
+|------|-------------|
+| `merge_sketches` | Combine parameters, colors, and philosophies from 2+ sketches |
+
+### Capture (3)
+
+| Tool | Description |
+|------|-------------|
+| `capture_screenshot` | Headless capture of a sketch — returns metadata + inline JPEG for AI viewing |
+| `capture_batch` | Capture multiple sketches in parallel |
+| `snapshot_layout` | Structural summary of workspace layout for spatial reasoning |
+
+### Export (1)
+
+| Tool | Description |
+|------|-------------|
+| `export_sketch` | Export as standalone HTML, PNG, SVG, raw algorithm, or ZIP bundle |
+
+### Knowledge (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_skills` | List available design knowledge skills by category |
+| `load_skill` | Load a skill with full theory, principles, and examples |
+| `get_guidelines` | Design guidelines for composition, color, parameters, animation, performance |
+
+## Resources (4)
+
+| URI | Description |
+|-----|-------------|
+| `genart://skills` | Available design knowledge skills |
+| `genart://presets/canvas` | Canvas dimension presets (18 built-in) |
+| `genart://gallery` | Loaded sketches with metadata summaries |
+| `genart://renderers` | Available renderer types and metadata |
+
+## Prompts (3)
+
+| Prompt | Description |
+|--------|-------------|
+| `create-generative-art` | Guided workflow: concept → sketch → algorithm → capture → iterate |
+| `explore-variations` | Fork and explore parameter/seed space across multiple variants |
+| `apply-design-theory` | Apply Gestalt, color theory, composition, rhythm, or contrast principles |
+
+## Supported Renderers
+
+| Type | Runtime | Algorithm |
+|------|---------|-----------|
+| `p5` | p5.js | `function sketch(p, state) { ... }` |
+| `three` | Three.js | `function sketch(THREE, state, container) { ... }` |
+| `glsl` | WebGL2 | Fragment shader source |
+| `canvas2d` | Native | `function sketch(ctx, state) { ... }` |
+| `svg` | Native | `function sketch(state) { ... }` |
+
+## Library API
+
+For programmatic use (e.g., building a custom MCP host):
+
+```typescript
+import { createServer, EditorState } from "@genart-dev/mcp-server/lib";
+
+const state = new EditorState();
+const server = createServer(state);
+
+// Connect to any MCP transport
+// ...
+```
+
+### Exports from `@genart-dev/mcp-server/lib`
+
+| Export | Description |
+|--------|-------------|
+| `createServer(state)` | Create a configured `McpServer` instance |
+| `EditorState` | Server-scoped mutable state (workspace, sketches, selection) |
+| `LoadedSketch` | Type — sketch definition + file path + dirty flag |
+| `EditorMutationType` | Type — mutation event names (`sketch:created`, `workspace:loaded`, etc.) |
+| `EditorMutationEvent` | Type — mutation event payload |
+| `EditorStateSnapshot` | Type — serializable snapshot of all state |
+
+### EditorState
+
+```typescript
+const state = new EditorState();
+
+// Load from disk
+await state.loadWorkspace("/path/to/project.genart-workspace");
+
+// Access loaded sketches
+state.sketches;               // Map<string, LoadedSketch>
+state.selection;              // Set<string>
+state.workspace;              // WorkspaceDefinition | null
+
+// Sandbox file operations (for hosted environments)
+state.basePath = "/safe/dir";
+state.remoteMode = true;      // Return file content instead of writing to disk
+
+// Listen for mutations
+state.on("mutation", (event) => {
+  console.log(event.type);    // "sketch:created", "workspace:loaded", etc.
+});
+
+// Serializable snapshot
+const snapshot = state.getSnapshot();
+```
+
+## Modes
+
+### stdio (default)
+
+Standard MCP transport for CLI agents:
+
+```bash
+genart-mcp
+```
+
+### Sidecar
+
+Stdio transport + IPC mutation bridge for Electron app integration:
+
+```bash
+genart-mcp --mode sidecar
+```
+
+Mutations are forwarded to the parent process via Node IPC, enabling real-time UI updates when AI agents modify sketches.
+
+## Agent Attribution
+
+Most mutation tools accept optional `agent` and `model` parameters for provenance tracking:
+
+```json
+{
+  "agent": "claude-code",
+  "model": "claude-opus-4-6"
+}
+```
+
+Stored in sketch metadata to track which AI agent created or modified each sketch.
+
+## Related Packages
+
+| Package | Purpose |
+|---------|---------|
+| [`@genart-dev/format`](https://github.com/genart-dev/format) | File format types, parsers, presets |
+| [`@genart-dev/core`](https://github.com/genart-dev/core) | Renderer adapters, skill registry (dependency) |
+
+## Support
+
+Questions, bugs, or feedback — [support@genart.dev](mailto:support@genart.dev) or [open an issue](https://github.com/genart-dev/mcp-server/issues).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genart-dev/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for genart.dev — tools, resources, and prompts for generative art",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -35,6 +35,11 @@
     "dist"
   ],
   "license": "MIT",
+  "author": {
+    "name": "genart.dev",
+    "email": "support@genart.dev",
+    "url": "https://genart.dev"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/genart-dev/mcp-server.git"
@@ -50,13 +55,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@genart-dev/core": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
@@ -78,5 +76,11 @@
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
   }
-}
+}