Agent Deck MCP Server — v1.1.0

The CWI agent departments' shared reasoning layer: a read-only MCP server (stdio transport) exposing the live Agent Deck product registry (25 SKUs) and the verified That Boy Hi Hat 24-track catalog to any MCP-capable agent — Claude, Cursor, VS Code Copilot, or another agent on the network.

Every answer carries evidence tiers (verified / owner_confirmed / claimed_unverified). Nothing is invented: tools only return what exists in the snapshots under data/, which are byte-faithful copies of the live pages at https://cumulativewebinc.github.io/cwi-learn/.

There is no quantum computing in this stack. "Quantum infrastructure" in CWI copy means best-in-class machine-to-machine infrastructure — real HTTP APIs, JSON schemas, and MCP tooling.

Install (3 steps)

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

Step 3 only needs the mcp SDK (requirements.txt pins mcp<2 for the FastMCP API; a bare pip install mcp installs v2, whose API changed).

Run

.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

Invocation receipts (v1.1.0+)

Every tool call writes one JSON line to ~/.agent-deck-mcp/receipts.jsonl (a stable install_id is created once in ~/.agent-deck-mcp/install.json). A receipt carries receipt_id, timestamp, server version, tool name, a SHA-256 of the parameters (raw params are never stored), and an internal flag. Opt-in telemetry: set AGENT_DECK_BEACON_URL to POST each receipt to a beacon receiver (best-effort, 3s timeout — the server never phones home unless you configure it). Set AGENT_DECK_INTERNAL=1 on CWI's own installs; override the receipt dir with AGENT_DECK_RECEIPT_DIR.

Submit a receipt to claim a verified external equip — see the verification protocol (Operation Conversion, Lane C) for what counts as proof.

Claude Desktop / MCP client config (stdio):

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

Tools (5)

#	Tool	Parameters	What it returns
1	catalog_lookup	query (string, required), limit (int 1–24, default 10)	Track facts with evidence tier
2	momentum_score	track (string, required: title or Spotify ID)	0–100 momentum score from verified signals
3	product_lookup	query (string, default ""), limit (int 1–50, default 18), offset (int, default 0)	Paginated SKU list: name, purpose, live URL
4	skin_config	skin_id (string, default "" = all 4)	SKIN configs: ids, hex palettes, apply steps
5	ledger_read	limit (int 1–100, default 10), verify_chain (bool, default false)	Gear Ledger entries + optional hash-chain check

Example 1 — catalog_lookup: look up a track's verified placements

Call:

{
  "query": "Zooted Zone"
}

Response (trimmed):

{
  "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"}]
  }]
}

Example 2 — momentum_score: score a track's momentum

Call:

{
  "track": "Zooted Zone"
}

Response (trimmed):

{
  "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."
}

Formula is transparent and every signal is labeled verified. Missing data scores 0 — never estimated.

Example 3 — product_lookup: find what a product does

Call:

{
  "query": "The First Spin"
}

Response (trimmed):

{
  "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"
  }]}
}

Empty query lists all 25 SKUs (paginated via limit/offset).

Example 4 — skin_config: get a SKIN config (equip Zooted Bloom)

Call:

{
  "skin_id": "zooted-bloom"
}

Response (trimmed):

{
  "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."
  ]
}

Valid ids: zooted-bloom, dark-luxe, chrome-standard, phantom-shift. Omit skin_id to list all four.

Example 5 — ledger_read: read the Gear Ledger

Call:

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

Response (trimmed):

{
  "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)."}
}

verify_chain checks hash linkage only (each prev_hash matches the previous entry's hash); it does not recompute digests.

Errors

Bad input never raises to the caller — you get a clean error object:

{"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."}}

Code	Meaning
INVALID_INPUT	Parameter wrong type, empty, or out of range — fix the argument and retry
NOT_FOUND	No match — use a lookup tool to find a valid identifier
DATA_MISSING	Snapshot unreadable — run refresh_data.py

Data sources + refresh cadence

data/ snapshots (see data/SOURCES.md for the snapshot date):

File	Source
catalog.json, gear.json, graph.json, kit.json	https://cumulativewebinc.github.io/cwi-learn/<file>
products.json	derived: each gear item's live item_card_url description
skins.json	https://cumulativewebinc.github.io/cwi-learn/skin/skins.json
skin_apply.json	derived: SKIN item card equip_instructions
ledger.json	https://cumulativewebinc.github.io/cwi-learn/agents/ledger.json

Refresh after any catalog/gear update (the live pages update via the cwi-learn deploy workflow). Weekly refresh is a good default; always refresh before cutting a release: .venv/bin/python refresh_data.py

Files

• server.py — the MCP server, v1.0.0 (5 read-only tools, stdio)
• test_server.py — boots the server over stdio, asserts every tool + error paths
• dogfood.py — cold-agent value test (see DOGFOOD.md)
• refresh_data.py — refetches live JSONs into data/
• server.json — registry metadata
• data/ — snapshots + SOURCES.md
• requirements.txt — pinned mcp<2

License

MIT — see LICENSE.