# Codex Plugin: SpriteOps Director

The local package is [`plugins/spriteops-director`](../plugins/spriteops-director/README.md),
version `0.1.0`. It bundles two skills and a working Node.js stdio MCP server
using the official `@modelcontextprotocol/sdk`. The plugin's own `package.json`
and lockfile contain its dependencies; the root package is not changed.

## Supported Workflow

**Browser export -> local MCP -> browser import**, using the exact portable
`*.spriteops-board.json` format in [`contracts/studio-board.md`](../contracts/studio-board.md).
No live browser sync, remote connector, asset fetch, media generation, render,
upload, arbitrary shell/eval, or hooks are provided.

Existing scenes also retain the additive [v2 scene properties](../contracts/scene-and-template-v2.md)
without changing board version 1: optional/null backgrounds, bounded output,
duration/loop, background placement/order, layer IDs/transforms/motion/sizing,
composer output/asset kinds, and source frame timing. Empty overlay lists require
a valid background; transparent scenes need at least one overlay. Validation uses
the runtime bounds, preserves unknown non-sensitive metadata and full image
strings, and rejects unsupported models in saved generation requests. This is
portable-data support only, not new rendering or publishing capability; the eight
tool APIs, including storyboard inputs, are unchanged.

| Tool | Operation |
| --- | --- |
| `list_boards` | Read paginated summaries of valid workspace boards |
| `read_board` | Read IDs, nodes, metadata and revision; omit images by default |
| `create_board` | Create an approved empty board, never overwrite |
| `add_note` | Append approved plaintext annotations, optionally asset-anchored |
| `select_cells` | Change approved row/column/ordered cells without pixel edits |
| `draft_generation_plan` | Return a read-only draft; zero provider calls/spend |
| `build_storyboard` | Add approved groups, scene cards and local composites |
| `export_shot_list` | Write an approved new shot-list JSON, never overwrite |

Write tools require explicit user invocation/approval and an `approved: true`
attestation; existing-board operations also require the project ID and current
SHA-256 `expectedRevision`. The host must enforce ordinary approvals: neither
the attestation nor annotations are an authorization bypass. Selection is
marked destructive because it replaces prior state; other writes are additive
or create-only. All tools are local and closed-world.

## Setup Boundary

Only run setup or a server after explicit setup authorization. Exact dependency,
start and test commands are in the [package README](../plugins/spriteops-director/README.md#local-setup).
Default storage is the plugin-local writable `data/` directory, not the home
directory or caller cwd. Override with an existing absolute, normalized,
non-symlink directory via `--workspace` or `SPRITEOPS_BOARD_DIR`.

Official [packaging docs](https://developers.openai.com/plugins/build/plugins.md)
checked 2026-09-07 confirm `.mcp.json` direct maps or wrapped `mcp_servers` maps
and `./` manifest paths. The bundle uses `node` with
`${PLUGIN_ROOT}/mcp/server.mjs`. The docs establish that variable for **hooks**,
not explicitly for stdio MCP argument interpolation. Host expansion remains
unverified. A host that does not expand it needs an explicitly configured
absolute server script path and, optionally, the approved workspace argument.
Node itself will not expand it.

**Installation blocker:** no host registration, install, marketplace discovery
or placeholder-expansion proof is included. The project now includes a local
marketplace descriptor at `.agents/plugins/marketplace.json`, a source-only ZIP
at `assets/spriteops-director-plugin.zip`, and `capabilities.json`. These are
authoring/testing artifacts, not an installed or published plugin. No global
configuration was changed.

## Safety And Proof

Boards are capped at 64 MiB/250 nodes, with stable IDs and same-project typed
references. Only bounded embedded PNG/JPEG/WebP images are accepted. Flat
filenames, regular-file checks, no-follow opens, pinned workspace identity,
revision checks, locking and atomic local publication guard file operations.
Source image data and unknown non-sensitive metadata survive annotations;
default reads remove image data. Explicit image reads have a 1 MiB response
cap. This user-controlled local workspace is not an OS sandbox against hostile
processes already running as the same user.

The skills cover physical-person consent, private-upload consent and verified
capability/cost gates for any separate media workflow; they cannot generate
media or infer consent. Drafting never means approved spending or execution.

The [SDK test suite](../plugins/spriteops-director/tests/server.test.mjs) calls
all eight tools through `StdioClientTransport`. It includes malformed boards,
approval refusals, traversal/link attacks, size limits, metadata/image
preservation and browser serializer/parser roundtrip checks. The
[schema boundary tests](../plugins/spriteops-director/tests/schema.test.mjs)
cover extended scenes and compare bounds against the runtime validator.
The fixture and skill eval cases ship inside the plugin. See the
[verification receipt](../plugins/spriteops-director/tests/RECEIPT.md).
No live browser UI synchronization or installed-host test is claimed.

The plugin [LICENSE](../plugins/spriteops-director/LICENSE) states private-source
status, not a made-up open-source grant. Third-party dependencies keep their
own licenses; the plugin contains no copied third-party implementation code.