scripts-api-mcp

name	scripts-api-mcp
description	Use when integrating AI or automation with MagickMonkey (Gist script CRUD via REST v1, MCP, or chat function calling). Read for auth headers, routes, and tool names.

Scripts API / MCP / function calling

Project: MagickMonkey. Scripts live in a private GitHub Gist; integration APIs mirror editor-safe files only (.ts/.js, excluding generated entry and rules).

Auth

• Session: admin login cookie (same as /editor).
• API key: configure env SCRIPTS_MCP_HEADERS (JSON string) on the server, and send x-api-key: …. Do not put keys in skills, commits, or client-only bundles.

REST

• OpenAPI: /api/v1/openapi.json
• CRUD base: /api/v1/scripts and /api/v1/scripts/{filename} (encode filename).

MCP (HTTP)

• /api/mcp — GET manifest; POST JSON-RPC initialize / tools/list / tools/call, or legacy { tool, params } (same shape as /api/mcp on the OpenAPI deployment).
• Tools: scripts_runtime_summary, scripts_list, scripts_get, scripts_upsert, scripts_rename, scripts_delete, scripts_find, scripts_search, scripts_snippet, scripts_replace, scripts_patch, scripts_batch_patch, scripts_validate, scripts_index_rebuild, scripts_index_update_metadata, scripts_ota_publish_stable, scripts_ota_lock_version, scripts_ota_unlock_version.
• Recommended generation flow: call scripts_runtime_summary first, then scripts_find / scripts_list / scripts_get, prefer scripts_search / scripts_snippet / scripts_patch for token-efficient edits, and use scripts_upsert only for large rewrites.
• MCP resources (markdown skills): skill://magickmonkey/scripts-routing.md, scripts-ai-skill.md, scripts-ui-skill.md, gme-webmcp-skill.md (page WebMCP authoring — see below).

Three integration paths (do not confuse)

Path	Where it runs	Use for
HTTP MCP /api/mcp	Server (Cursor, etc.)	Gist CRUD via scripts_* tools
Page WebMCP GME_registerWebMcpTool	Browser tab (preset)	Register page actions as vws.{scriptKey}.{name}
Extension WebMCP Agent (backlog)	Chrome side panel	Natural language → call tools on the current tab

HTTP MCP cannot control the user's open browser tab (e.g. toggle danmaku, fullscreen). That requires page WebMCP tools registered by Gist scripts (GME_registerWebMcpTool) and (when shipped) the MagickMonkey extension Agent as caller.

Page WebMCP (GME_registerWebMcpTool)

• Implemented in preset (shared/webmcp/, preset/src/helpers/webmcp.ts).
• Authors register tools in Gist userscripts; canonical name vws.{scriptKey}.{localName}; provider magickmonkey.
• Registry contract: globalThis.__VWS_WEBMCP_TOOL_REGISTRY__.
• Requires Chrome WebMCP flag (chrome://flags/#enable-webmcp-testing) and extension shell with __VWS_SCRIPT_KEY__ for full behavior.
• Not an HTTP MCP tool — do not add scripts_* calls for tab control.

Author docs: public/docs/gme-webmcp-skill.md (static /docs/gme-webmcp-skill.md, MCP resource skill://magickmonkey/gme-webmcp-skill.md). Spec: .ai/specs/preset-gme-webmcp.md. Downstream consumer: .ai/tasks/backlog/extension-webmcp-agent.md.

Maintenance note

If the preset adds/modifies any GM_* / GME_* interfaces, you must keep docs and the runtime summary tool in sync:

• Update public/docs/scripts-ai-skill.md capability summary table (and WebMCP section when GME_registerWebMcpTool changes).
• Update services/scripts/scriptMcpTools.ts output of scripts_runtime_summary.
• When adding overlay UI in Gist scripts, sync with public/docs/scripts-ui-skill.md and MCP resource skill://magickmonkey/scripts-ui-skill.md.
• When changing page WebMCP authoring, sync public/docs/gme-webmcp-skill.md, MCP resource skill://magickmonkey/gme-webmcp-skill.md, and .ai/specs/preset-gme-webmcp.md.

Human-readable skill copy

See public/docs/scripts-ai-skill.md in the repo (also served as static /docs/scripts-ai-skill.md). That file includes Runtime (preset) vs Gist and a capability summary (GM_* / GME_*); use it when generating or editing scripts so you do not need the full typings in context. For exact signatures, read preset/src/editor-typings.d.ts in the repo.

Overlay UI (Gist modals/panels): read public/docs/scripts-ui-skill.md or MCP resources/read → skill://magickmonkey/scripts-ui-skill.md. Align with preset vws-ui-tokens.css (command palette, notification, log viewer) — not light VS Code or WEB-only hex.

Page WebMCP (tab tools for extension Agent): read public/docs/gme-webmcp-skill.md or MCP resources/read → skill://magickmonkey/gme-webmcp-skill.md. Not HTTP MCP — authors use GME_registerWebMcpTool in Gist scripts.

Chat “function” definitions

See public/docs/scripts-function-tools.json — map names to your HTTP client or host that calls the REST API with the same auth.