@mcteamster/white-mcp 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -0
- package/dist/index.js +66670 -0
- package/package.json +24 -0
package/README.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Blank White Cards MCP Server
|
|
2
|
+
|
|
3
|
+
An MCP (Model Context Protocol) server that lets AI agents play Blank White Cards — a creative, freeform card game where players write and play their own rules.
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- Node.js 20+
|
|
8
|
+
- A running Blank White Cards game server (boardgame.io)
|
|
9
|
+
- ffmpeg/ffprobe (optional, only needed for card images)
|
|
10
|
+
|
|
11
|
+
## Running
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx tsx mcp/index.ts
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Configuration
|
|
18
|
+
|
|
19
|
+
Environment variables:
|
|
20
|
+
|
|
21
|
+
| Variable | Default | Description |
|
|
22
|
+
|----------|---------|-------------|
|
|
23
|
+
| `GAME_SERVER_URL` | *(auto-detect)* | Override server URL for all connections. If unset, the server is resolved from the room code or timezone. |
|
|
24
|
+
| `MCP_MIN_REACT_SECONDS` | `5` | Seconds to wait before returning watch events (pacing) |
|
|
25
|
+
| `MCP_MAX_WATCH_SECONDS` | `30` | Seconds before watch times out with no event |
|
|
26
|
+
|
|
27
|
+
### Server resolution
|
|
28
|
+
|
|
29
|
+
When `GAME_SERVER_URL` is not set:
|
|
30
|
+
- **Joining a match** — the server is derived from the room code's last character (AP/EU/NA regions)
|
|
31
|
+
- **Creating a match** — auto-detects the closest region from your timezone, or accepts a `region` parameter
|
|
32
|
+
- **Unrecognised room codes** — falls back to `http://localhost:3000` (local development)
|
|
33
|
+
|
|
34
|
+
## MCP Client Config
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"blank-white-cards": {
|
|
39
|
+
"type": "stdio",
|
|
40
|
+
"command": "npx",
|
|
41
|
+
"args": ["--prefix", "/path/to/white", "tsx", "/path/to/white/mcp/index.ts"],
|
|
42
|
+
"env": {
|
|
43
|
+
"GAME_SERVER_URL": "http://localhost:3000"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Tools
|
|
50
|
+
|
|
51
|
+
### Match management
|
|
52
|
+
- `list_matches` — List active matches
|
|
53
|
+
- `create_match` — Create a new match and join as player 0
|
|
54
|
+
- `join_match` — Join an existing match
|
|
55
|
+
- `leave_match` — Leave a match
|
|
56
|
+
|
|
57
|
+
### Game state
|
|
58
|
+
- `get_state` — Get current game state (hand, pile, deck size, etc.)
|
|
59
|
+
- `get_card` — Get a single card by ID
|
|
60
|
+
- `search_cards` — Full-text search over card titles and descriptions
|
|
61
|
+
- `export_deck` — Export all cards in a match as JSON
|
|
62
|
+
|
|
63
|
+
### Actions
|
|
64
|
+
- `pickup_card` — Draw from the deck into your hand
|
|
65
|
+
- `move_card` — Move a card to a different location
|
|
66
|
+
- `claim_card` — Claim a card from the pile into your hand
|
|
67
|
+
- `submit_card` — Write a new card (optionally with an image)
|
|
68
|
+
- `like_card` — Like a card
|
|
69
|
+
- `shuffle_cards` — Reset and shuffle all cards (host only)
|
|
70
|
+
- `load_cards` — Bulk load cards into a match (host only)
|
|
71
|
+
|
|
72
|
+
### Observation
|
|
73
|
+
- `watch` — Block until a game event occurs, returns structured diff of what changed
|
|
74
|
+
|
|
75
|
+
## Card Images
|
|
76
|
+
|
|
77
|
+
Cards can optionally have images. The agent saves a square PNG to disk and passes the file path as `image_path` in `submit_card`. The server:
|
|
78
|
+
|
|
79
|
+
1. Validates the image is square (via ffprobe)
|
|
80
|
+
2. Resizes to 500x500
|
|
81
|
+
3. Converts to black and white (threshold at 128)
|
|
82
|
+
4. Attaches as a PNG data URI
|
|
83
|
+
|
|
84
|
+
Requires ffmpeg and ffprobe on the system PATH.
|
|
85
|
+
|
|
86
|
+
## Prompts
|
|
87
|
+
|
|
88
|
+
The server provides role prompts that shape how an agent uses the tools:
|
|
89
|
+
|
|
90
|
+
| Prompt | Description | Parameters |
|
|
91
|
+
|--------|-------------|------------|
|
|
92
|
+
| `autonomous_player` | Play the game in a loop | `tone`, `themes`, `aggression` |
|
|
93
|
+
| `referee` | Moderate and enforce rules | `rules` |
|
|
94
|
+
| `spectator` | Watch and comment only | — |
|
|
95
|
+
| `deck_builder` | Create and curate card decks | `theme`, `card_count` |
|
|
96
|
+
|
|
97
|
+
## Pacing
|
|
98
|
+
|
|
99
|
+
The server enforces pacing to prevent agents from acting too fast:
|
|
100
|
+
|
|
101
|
+
- When `watch` detects an event, it waits `MCP_MIN_REACT_SECONDS` before returning — giving human players time to read new cards
|
|
102
|
+
- When `watch` times out, the response nudges the agent to take action and re-watch
|