@imgly/codesign-mcp 0.1.0

package/LICENSE.md

@@ -0,0 +1,16 @@
+# Proprietary License
+
+Copyright (c) IMG.LY GmbH. All rights reserved.
+
+This software and its source code are proprietary and confidential. During the
+beta period it is provided to authorized testers solely for evaluation. No
+license or right to use, copy, modify, distribute, sublicense, or create
+derivative works is granted except as expressly agreed in writing with
+IMG.LY GmbH.
+
+Use of the CreativeEditor SDK (CE.SDK) engine bundled or fetched as a dependency
+is additionally governed by the IMG.LY CE.SDK license terms.
+
+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.

package/README.md

@@ -0,0 +1,158 @@
+# @imgly/codesign-mcp
+
+MCP server exposing a CE.SDK CreativeEngine for vector design + print-quality
+PDF output. Ships skills (Iris design loop, cesdk-api signatures, cesdk-guide
+docs), tools (`design_exec`, `design_capture`), and prompts as MCP resources.
+
+## Install
+
+The recommended install is via npm — hosts spawn it with `npx`, so there's no
+separate install step:
+
+```bash
+# Claude Code
+claude mcp add codesign -- npx -y @imgly/codesign-mcp stdio
+```
+
+For Claude Desktop (JSON `mcpServers` block) and Codex (TOML
+`[mcp_servers.codesign]`), see
+[docs/codesign-mcp-beta-install.md](../../docs/codesign-mcp-beta-install.md)
+for the exact per-host snippets — all spawn
+`npx -y @imgly/codesign-mcp stdio`.
+
+Set `CESDK_LICENSE` in the server's `env` to use your own CE.SDK node license;
+during the internal beta a 30-day trial is bundled, so it's optional.
+
+### From a GitHub Release tarball (offline / air-gapped)
+
+Releases also ship a self-contained tarball with a date-based, commit-derived
+version — `0.1.0-<YYYYMMDD>-g<shortSHA>`:
+
+```bash
+npm i -g https://github.com/imgly/imgly-codesign/releases/download/<tag>/imgly-codesign-mcp-0.1.0-<YYYYMMDD>-g<sha>.tgz
+codesign-mcp --help
+```
+
+Build the tarball locally (output in `<repo>/release/`):
+
+```bash
+pnpm run release:tarball        # from the repo root
+```
+
+## Run
+
+One bin, two transports:
+
+```bash
+codesign-mcp stdio              # MCP over stdin/stdout
+codesign-mcp http               # MCP over Streamable HTTP (default :3030)
+codesign-mcp --help
+```
+
+Env: `CESDK_LICENSE` (CE.SDK headless engine license string). For `stdio` it is
+optional when a trial license is bundled in the build (see Install); otherwise
+required.
+
+### Stdio mode
+
+Spawned by hosts that manage MCP servers as subprocesses (Claude Desktop,
+Claude Code via `command`).
+
+```bash
+CESDK_LICENSE=… codesign-mcp stdio
+```
+
+Host config example:
+
+```jsonc
+{
+  "mcpServers": {
+    "codesign": {
+      "command": "codesign-mcp",
+      "args": ["stdio"],
+      "env": { "CESDK_LICENSE": "..." }
+    }
+  }
+}
+```
+
+### HTTP mode
+
+Long-running listener; hosts connect via URL. Useful for multiple clients,
+keeping engines warm across requests, and running on a different host than
+the MCP client.
+
+```bash
+CESDK_LICENSE=… codesign-mcp http \
+  --port 3030 --host 127.0.0.1 \
+  --max-sessions 10 --idle-timeout-ms 1800000
+```
+
+All flags fall back to env vars (`PORT`, `HOST`, `MAX_SESSIONS`,
+`IDLE_TIMEOUT_MS`).
+
+Endpoint: `POST/GET/DELETE http://<host>:<port>/mcp` (Streamable HTTP).
+
+Host config example:
+
+```jsonc
+{
+  "mcpServers": {
+    "codesign": {
+      "type": "http",
+      "url": "http://127.0.0.1:3030/mcp"
+    }
+  }
+}
+```
+
+### Per-session engine
+
+HTTP mode allocates a fresh CE.SDK headless engine for every MCP session
+(scoped by the `Mcp-Session-Id` header). Engines are isolated — two
+concurrent sessions cannot corrupt each other's scenes. Idle sessions (no
+activity for `idle-timeout-ms`) are evicted on a periodic sweep; new
+sessions over `max-sessions` get `503 Service Unavailable` with `Retry-After: 30`.
+
+Stdio mode uses a single engine for the lifetime of the process.
+
+## Embedding
+
+The HTTP server is also exposed as a programmatic factory for callers that
+want to mount it inside a larger Express app or compose multiple MCP
+servers behind a single port:
+
+```ts
+import { createCodesignHttpServer } from '@imgly/codesign-mcp';
+import { ensureHeadlessEngine } from '@imgly/codesign-mcp';
+import { buildDesignToolRegistrations } from '@imgly/codesign-mcp';
+import { loadNodeAssets } from '@imgly/codesign-mcp/assets/node';
+
+const license = process.env.CESDK_LICENSE!;
+const app = await createCodesignHttpServer({
+  assets: loadNodeAssets(),
+  maxSessions: 10,
+  idleTimeoutMs: 30 * 60 * 1000,
+  createEngine: () => ensureHeadlessEngine(license),
+  buildTools: (engine) => buildDesignToolRegistrations({ license, engine }),
+  // optional auth + cors hooks (no-op by default)
+  auth: (req, res, next) => {
+    /* check Bearer token, etc. */ next();
+  },
+  cors: { origin: ['https://my.frontend'] }
+});
+app.listen(3030, '127.0.0.1');
+```
+
+## Going remote
+
+The defaults (`HOST=127.0.0.1`, no auth, no CORS) target localhost dev. To
+expose remotely:
+
+1. **TLS:** front with caddy / nginx, or terminate in your own Express app.
+2. **Auth:** wire `auth` middleware (Bearer token / OAuth / mTLS).
+3. **CORS:** wire `cors` for browser clients (Claude.ai web, custom UIs).
+4. **Resource limits:** tune `max-sessions` and `idle-timeout-ms` for the
+   target hardware (each engine is ~200–500 MB resident).
+
+The hooks are pluggable from day one — going remote is config, not refactor.

package/assets/docs/api/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: api
+description: |
+  Authoritative TypeScript signatures for the CE.SDK CreativeEngine. Use this skill
+  whenever you need the exact signature, parameter types, or return type of an
+  `engine.*` method — especially before calling a method you haven't used in the
+  current scene, or when the markdown docs in `cesdk-guide` are ambiguous.
+
+  This is THE source of truth for method signatures. The hand-written cheatsheets
+  in SYSTEM.md and the markdown docs in `cesdk-guide` can drift; this `.d.ts`
+  ships with the same `@cesdk/node` package the engine runs.
+
+  Triggered when you need to verify an `engine.block.*` or `engine.scene.*`
+  signature, look up a parameter type, or confirm an enum/string-property name.
+---
+
+## Single file: `index.d.ts`
+
+The whole CE.SDK TypeScript surface is in `index.d.ts` (~9000 lines). Use
+`read --offset --limit` to fetch the slice you need; never read the whole file.
+
+## Line anchors
+
+The most-used classes are at known line offsets. Pass these directly to `read`:
+
+| Class        | Start line | Read example                                      |
+| ------------ | ---------- | ------------------------------------------------- |
+| AssetAPI     | 260        | `read path=… offset=260  limit=200`               |
+| **BlockAPI** | **1421**   | `read path=… offset=1421 limit=400` (largest API) |
+| EditorAPI    | 6300       | `read path=… offset=6300 limit=300`               |
+| EventAPI     | 7382       | `read path=… offset=7382 limit=200`               |
+| **SceneAPI** | **8114**   | `read path=… offset=8114 limit=300`               |
+| VariableAPI  | 9531       | `read path=… offset=9531 limit=100`               |
+
+## How to look up a method
+
+1. Identify which class owns it (e.g. `engine.block.setFont` → BlockAPI).
+2. `grep pattern="setFont\\(" path="**/skills/cesdk-api/index.d.ts" maxResults=5`
+3. `read path=… offset=<grep-line - 5> limit=30` to get the JSDoc + signature.
+
+The JSDoc above each method tells you the canonical usage and lists `@param`
+types. When a method has multiple overloads, prefer the one without
+`@deprecated`.
+
+## When to NOT use this skill
+
+- Reading conceptual prose ("how does XYZ work") → use `cesdk-guide` instead.
+- General topic guides (text, fills, export, rules) → `cesdk-guide`.
+- This skill is signatures only — use `cesdk-guide` for everything else.