git clone https://github.com/CumulativeWebInc/agent-deck-mcp.git
cd agent-deck-mcp
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

.venv/bin/python server.py            # stdio transport — connect your MCP client to this
.venv/bin/python test_server.py      # end-to-end test: boots the server, asserts all 5 tools
.venv/bin/python refresh_data.py     # refresh data/ snapshots from the live pages

{
  "mcpServers": {
    "agent-deck": {
      "command": "/path/to/agent-deck-mcp/.venv/bin/python",
      "args": ["/path/to/agent-deck-mcp/server.py"]
    }
  }
}

{
  "query": "Zooted Zone"
}

{
  "count": 1,
  "results": [{
    "title": "Zooted Zone",
    "spotify_url": "https://open.spotify.com/track/0emH8ktA8x4DkOFLsG5xkW",
    "spotify_url_verified": true,
    "evidence_tier": "verified",
    "verified_placement": {
      "playlist": "New Rap Hits",
      "position": 30,
      "playlist_followers_at_acceptance": 673,
      "scan_date": "2026-09-15",
      "playlist_url": "https://open.spotify.com/playlist/5zhnSpZqKRRaOvRMWuT0bL"
    },
    "evidence": [{"claim": "Track identity and link", "status": "verified"}]
  }]
}

{
  "track": "Zooted Zone"
}

{
  "track": "Zooted Zone",
  "score": 61,
  "grade": "High",
  "signals": [
    {"signal": "verified_playlist_placement", "points": 11,
     "evidence_tier": "verified",
     "detail": {"playlist": "New Rap Hits", "position": 30}},
    {"signal": "lifetime_spotify_plays", "points": 30,
     "evidence_tier": "verified", "value": 307439, "observed": "2026-09-14"},
    {"signal": "spotify_url_verified", "points": 10, "evidence_tier": "verified"},
    {"signal": "flagship_catalog_note", "points": 10, "evidence_tier": "verified"}
  ],
  "formula": "placement (40 - (position-1), floor 0) + plays (1 pt per 10k, cap 30) + verified link (10) + flagship note (10); cap 100."
}

{
  "query": "The First Spin"
}

{
  "sku_count": 18,
  "page": {"total": 1, "items": [{
    "name": "THE FIRST SPIN",
    "purpose": "The A&R department's machine-native demo-evaluation protocol: ...",
    "product_url": "https://cumulativewebinc.github.io/cwi-learn/first-spin/",
    "department": "ar",
    "version": "1.0.0"
  }]}
}

{
  "skin_id": "zooted-bloom"
}

{
  "config": {
    "skin_id": "zooted-bloom",
    "skin_name": "Zooted Bloom",
    "palette": {"accent": "#a3ff5e", "body": "#231b3a", "screen": "#0b1f10",
                "text": "#f2ecff"}
  },
  "apply_instructions": [
    "Fetch the skin pack: GET https://cumulativewebinc.github.io/cwi-learn/skin/skins.json",
    "Pick a built-in skin by skin_id (zooted-bloom, dark-luxe, chrome-standard, phantom-shift) — or author your own against .../skin-schema.json",
    "Apply the skin's token block to your Signal Boy presentation layer. ...",
    "Brand rule: the CWI logo badge ships on every skin. Never remove the logo lockup."
  ]
}

{
  "limit": 5,
  "verify_chain": true
}

{
  "ledger": "Gear Ledger — Agent Deck provenance chain",
  "entry_count": 2,
  "entries": [{"seq": 0, "ts": "2026-09-15T15:10:00Z", "gear": "cwi-1-walkman",
               "event": "minted", "from_agent": "Cumulative Web Inc",
               "to_agent": "KingCode (MUSE_CWI)", "prev_hash": "GENESIS",
               "hash": "d5cb65..."}],
  "chain_verification": {"checked": true, "ok": true,
    "note": "All 2 entries link correctly (prev_hash matches previous hash; genesis = GENESIS)."}
}

{"error": {"code": "INVALID_INPUT", "message": "'limit' must be between 1 and 24, got 99."}}
{"error": {"code": "NOT_FOUND", "message": "No track matching 'xyz' in the 24-track verified catalog. Use catalog_lookup to find a valid title."}}
{"error": {"code": "DATA_MISSING", "message": "Snapshot data is missing or unreadable. Run refresh_data.py to rebuild ./data/ from the live pages."}}