control-spriteboy-studio

name	control-spriteboy-studio
description	Inspect and control a connected SpriteBoy Studio tab through its local MCP server. Use for project state, selection, workspace navigation, jobs, supported imports, model actions, export, and ACP sessions that receive the SpriteBoy MCP.

Control SpriteBoy Studio

Use the local bridge and MCP server. Read docs/control/LOCAL_BRIDGE.md and docs/control/MCP_SERVER.md before changing the control path.

Start and connect

1. Set a fresh 32-or-more character SPRITEBOY_CONTROL_TOKEN in the process environment. Never put it in arguments, Git, chat output, or logs.
2. Run bun run control:bridge and keep its loopback URL. Add one --file-root <absolute directory> for each directory that may feed an import. The checkout is the only default root.
3. Run bun run dev. In Preferences -> Local control, enter the loopback URL and token, connect, then clear any copied token.
4. Set SPRITEBOY_CONTROL_BRIDGE_URL and the same token for the MCP host.
5. Configure the host to run bun scripts/studio-control-mcp.ts from the repo root over stdio.

Keep MCP stdout reserved for protocol data. Treat any non-loopback URL or short token as a hard failure.

Operate safely

1. Read spriteboy://capabilities, spriteboy://project, and spriteboy://jobs before a mutation.
2. Use the current project revision as expectedRevision.
3. Use a new idempotency key for each new action. Reuse a key only when retrying the exact same action and arguments.
4. Call the narrow SpriteBoy tool. Do not seek a shell or unrestricted path.
5. Read project, jobs, or selection again and verify the result.

For an import, pass an absolute path under a declared root. Image import accepts PNG, JPEG, or WebP up to 10 MiB. Video import queues a real job and caps the brokered source at 256 MiB; read spriteboy://jobs until it reaches a terminal state. Model setup jobs appear in the same job resource. RMBG license approval cannot be granted through this MCP. The broker holds one file-transfer lease at a time. Treat import retries as session-scoped: reuse the same idempotency key only against the same live bridge session.

Use spriteboy_navigate for Compose, then verify the workspace in the project resource. The current capabilities omit export. Do not call or claim export until export.run appears there and its result contains a verified receipt, allowed path or handle, and byte size.

ACP

ACP clients pass this same stdio server in mcpServers on session/new or session/load. Use examples/acp/spriteboy-session-new.json as the v1 shape. Fill the absolute paths in memory. Bind the token placeholder from a secret or process environment immediately before sending the request; never save the materialized request. After session creation, list the MCP resources to prove the agent connected. Do not add a second ACP command catalog.

Failures and cleanup

• stale-revision: reread the project, decide whether the action still fits, then send a new request and idempotency key.
• Timeout or lost tab: inspect status before retrying. The old key is safe only for an exact retry.
• Cancel jobs with spriteboy_jobs_cancel; then verify their terminal state.
• Stop the MCP and bridge processes when done. Disconnect the tab and clear the session token from the environment.

Verification and claim limit

Run the control protocol, service, bridge, browser-client, and MCP integration tests after control changes, then bun run check. Claim only what the current capabilities resource and follow-up reads prove. A live bridge alone does not prove a browser tab, model, import, or export is ready.