agent-asset-mcp

Out-of-repo companion to LLMTamagotchi. Generates paper-doll sprite layers (hats, outfits, hair, accessories) for the Tamagotchi's customization system.

The Tamagotchi instance calls this service over HTTPS to grow its catalog at runtime. Without this service, the catalog is whatever the LLMTamagotchi repo ships with (Seliel's hand-drawn art for v1).

Status

v0.1.0 — scaffold. No working generator yet. The service exposes POST /v1/layers (the contract the Tamagotchi will call) but the endpoint currently returns a 501 Not Implemented stub. The ComfyUI workflow definition is a placeholder.

API

The Tamagotchi calls:

POST /v1/layers
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "slot": "hat" | "outfit" | "hair" | "accessory",
  "prompt": "wizard hat with a glowing purple star",
  "reference_layers": [
    "seliel_humn_v02",   // base body — the generator must match this style
    "seliel_fstr_v01"    // outfit (optional — to match the outfit's color palette)
  ],
  "size_px": 60
}

Response:

200 OK
Content-Type: application/json

{
  "id": "wizard_hat_purple_v01",
  "slot": "hat",
  "png_base64": "iVBORw0KGgo...",
  "width_px": 60,
  "height_px": 64,
  "alignment_check": {
    "subject_bbox": { "x": 12, "y": 8, "w": 36, "h": 48 },
    "cell_size": { "w": 60, "h": 64 },
    "subject_pct": 78.4
  },
  "model": {
    "name": "sdxl-pixart-character-2d",
    "version": "1.0.0"
  },
  "cost_usd": 0.003,
  "created_at": "2026-07-15T18:00:00Z"
}

The Tamagotchi takes the png_base64, decodes it, slices it into the catalog, and the user can equip the new layer via the customization modal.

What's in this repo

• src/server.ts — the HTTP API (Fastify, AGPL-3.0). Exposes POST /v1/layers, plus a /health endpoint and a stand-alone /v1/preview HTML page for designers to test prompts without an agent.
• src/mcp.ts — the Model Context Protocol adapter. The Tamagotchi agent can talk to this service as an MCP tool, exposing generate_sprite_layer({ slot, prompt, reference_layers }).
• src/pipeline/comfyui.ts — the ComfyUI workflow driver. Sends the prompt to a self-hosted ComfyUI instance, waits for the result, post-processes the PNG (transparent background, paper-doll alignment check, color-match to reference layer).
• src/pipeline/sdxl.ts — fallback when no ComfyUI is available. Uses a hosted SDXL endpoint (Replicate, FAL, etc.) instead.
• comfyui/workflows/character-layer.json — the ComfyUI workflow definition. v1 uses SDXL + a controlnet pose hint + a post-processing pass for transparent background.
• docs/scope.md — what this repo owns vs. what stays in LLMTamagotchi.

What's NOT in this repo

Per the directive (2026-07-15), the Tamagotchi does not include an in-tree MCP tool, a ComfyUI workflow, or any GPU-side code. The Tamagotchi treats this service as an external dependency over HTTPS.

Specifically, the Tamagotchi does NOT have:

• An agent-asset-mcp dependency in package.json
• A ComfyUI installation script
• A mcp/server.ts tool wrapper for sprite generation
• Any GPU-side configuration

The Tamagotchi also doesn't bundle the actual models — they're downloaded on first run of this service and cached in models/.

Stack

• Runtime: Node.js 20+ (TypeScript)
• HTTP framework: Fastify
• MCP adapter: @modelcontextprotocol/sdk
• Image generation: ComfyUI (self-hosted, primary) or hosted SDXL endpoint (fallback)
• Image post-processing: sharp (background removal, alignment check, PNG export)
• Database: SQLite (better-sqlite3) for the layer catalog and usage tracking
• License: AGPL-3.0 (matches the Tamagotchi)

Setup

# 1. Clone
git clone https://git.rossfox.xyz/ross/agent-asset-mcp
cd agent-asset-mcp

# 2. Install deps
npm install

# 3. Configure
cp .env.example .env
# Edit .env: set AGENT_ASSET_API_KEY, COMFYUI_URL, COMFYUI_API_KEY

# 4. Start ComfyUI (or skip if you're using the hosted fallback)
# See docs/comfyui-setup.md

# 5. Run
npm run dev

The service listens on 127.0.0.1:8765 by default. The Tamagotchi configures the URL via AGENT_ASSET_URL (e.g. http://localhost:8765).

Cost

ComfyUI on a rented 24GB GPU (RunPod, Vast.ai) costs ~$0.40/hour. A single generate_sprite_layer call takes 8-15 seconds, so the amortized cost is ~$0.001-0.005 per call. The Tamagotchi should rate-limit agent-initiated generation (suggested: max 5 per day per agent) to keep the bill reasonable.

License

AGPL-3.0. See LICENSE.