MCP 與 AI 工具

Islumina 目前沒有遠端 MCP endpoint。套件文件以靜態檔提供，AI 直接讀取即可；MCP 只用在 AI Sprite Studio 的本機產圖流程，因為它需要讀寫本機檔案。

讀文件不需要 MCP

/llms.txt：生態系索引。
/llms-full.txt：單檔生態系背景與 0.6.0 共通規則。
各套件的 llms-full.txt：位於 GitHub repo 根目錄，也隨 npm 套件發佈，安裝後在 node_modules/<pkg>/llms-full.txt。

選型與驗證流程見 AI 快速開始。

AI Sprite Studio 本機 MCP server

aisprite-studio 內附 stdio MCP server，讓支援 MCP 的 AI client 檢視 sprite workspace、修復 canonical reference、取得 row 或 frame 產圖任務、提交 PNG，並執行附分數摘要的 deterministic QA。伺服器不呼叫任何生圖 API，也不保存模型 API key，產圖由連接的 AI host 自己完成。

安裝

clone aisprite-studio 後，在 repository root 執行：

npm ci
npm run test:mcp

test:mcp 會 build mcp-server/dist/index.js 並執行測試。需要 web editor 時再執行 npm run serve，editor 的 AI Agent Handoff 卡片會產生已填好路徑的 client config。

Client 設定

以下範例請把 /absolute/path/to/aisprite-studio 換成實際路徑。舊設定的 AIPLAYBOOK_ROOT 暫時仍可用，新設定請用 AISPRITE_STUDIO_ROOT。

Codex，加到 ~/.codex/config.toml：

[mcp_servers.aisprite-studio]
command = "node"
args = ["/absolute/path/to/aisprite-studio/mcp-server/dist/index.js"]

[mcp_servers.aisprite-studio.env]
AISPRITE_STUDIO_ROOT = "/absolute/path/to/aisprite-studio"

Claude Code 的 project .mcp.json 與 Claude Desktop 的 claude_desktop_config.json 使用同一個 mcpServers 物件：

{
  "mcpServers": {
    "aisprite-studio": {
      "command": "node",
      "args": ["/absolute/path/to/aisprite-studio/mcp-server/dist/index.js"],
      "env": { "AISPRITE_STUDIO_ROOT": "/absolute/path/to/aisprite-studio" }
    }
  }
}

Claude Code 也可以用指令註冊：

claude mcp add aisprite-studio -e AISPRITE_STUDIO_ROOT=/absolute/path/to/aisprite-studio -- node /absolute/path/to/aisprite-studio/mcp-server/dist/index.js

Gemini CLI：把同一個 mcpServers["aisprite-studio"] 物件加進 .gemini/settings.json，再於 Gemini CLI 內執行 /mcp list，確認 9 個工具都已就緒。

Antigravity 或沒有 MCP client 的生圖 agent：host 支援本機 stdio MCP 時用同一份 JSON；否則在 editor 按 Copy active frame task，產圖後交給已連接 MCP 的 agent 呼叫 aisprite_studio_submit_generated_frame 提交。

工具與呼叫順序

aisprite_studio_list_assets：列出產圖 workspace、frame 進度、reference 與 QA 狀態，唯讀。
reference 標為 failed 時，用 aisprite_studio_get_reference_task 取得任務，產出一張替代圖，再以 aisprite_studio_submit_reference 提交。
reference 通過人工 visual review 後，以下兩種方式擇一產圖，都要帶著回傳的全部參考圖：
- Row：aisprite_studio_get_row_task 回傳整個動畫的 prompt、參考圖與有編號的 layout guide。把所有姿勢畫在同一張圖，再以 aisprite_studio_submit_generated_row 提交；伺服器會去背、依內容切出宣告數量的姿勢，並以同一個縮放比例寫成影格，數量不符時一張都不寫並說明找到幾個。姿勢一起畫，角色樣貌、比例與色盤比較一致。若 warning 指出姿勢需要放大超過 1.25 倍，改用 frame task。
- Frame：aisprite_studio_get_generation_task 回傳單一 frame 任務，產圖後以 aisprite_studio_submit_generated_frame 提交。
執行 aisprite_studio_run_deterministic_qa。回傳的 summary 包含整體狀態、最低的動畫分數（0–100）、各動畫的修復提示，以及每個失敗影格的 repair_hint；依提示重新產圖。完整報告用 aisprite_studio_get_qa_report 讀取。

repo 內既有生圖都視為未通過 visual QA 的失敗素材。提交替代圖不等於核准，deterministic QA 也不等於 visual approval，打包前仍須另外通過 visual QA。

信任邊界

官網的 Sprite Playground 是 read-only，沒有寫入 endpoint。
本機提交只接受已宣告的 frame 或動畫名稱與合法 PNG，上限 20 MiB。frame 尺寸必須與 frame_size 完全相符，寫入路徑限定在 assets/{asset}/frames/{frame}.png；row 圖寫入 assets/{asset}/raw/{animation}.png，找到的姿勢數量與宣告相符時才會寫成影格。
覆蓋既有 frame 必須明確指定，MCP annotations 會標示為 destructive。

Browser agent 與 editor

官網容器與 editor 之間使用 aibridgejs 的 exact-origin iframe adapter。Browser agent 可透過 window.aispriteStudioBridge.requestContext() 取得 aisprite-studio:context event，或用 selectAsset(asset)／reloadAssets() 操作受限的 editor 指令。這條通道不能產圖或寫檔，這些操作只能走本機 MCP。