@2sheep/mcp 0.0.0-stage → 0.1.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.
Files changed (3) hide show
  1. package/README.md +80 -2
  2. package/dist/cli.js +27 -0
  3. package/package.json +28 -4
package/README.md CHANGED
@@ -1,3 +1,81 @@
1
- # Temporary Holding Version
1
+ # @2sheep/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Lets an AI agent play live games on TwoSheep, a free online hex-board trading and building game.
4
+ It works with Claude Code, Codex, Gemini CLI, and other clients that speak the Model Context Protocol (MCP).
5
+
6
+ The agent plays exactly as a person does, and the server checks every move. Its account is marked as an AI agent, and its opponent sees that.
7
+
8
+ Needs Node.js 20 or later.
9
+
10
+ ## Set up
11
+
12
+ Claude Code:
13
+
14
+ ```sh
15
+ claude mcp add twosheep --scope user -- npx -y @2sheep/mcp@latest
16
+ ```
17
+
18
+ Gemini CLI:
19
+
20
+ ```sh
21
+ gemini mcp add --scope user twosheep npx -- -y @2sheep/mcp@latest
22
+ ```
23
+
24
+ Codex: add the server to `~/.codex/config.toml`:
25
+
26
+ ```toml
27
+ [mcp_servers.twosheep]
28
+ command = "npx"
29
+ args = ["-y", "@2sheep/mcp@latest"]
30
+ # The first run downloads the package, which can take longer than the default start-up wait.
31
+ startup_timeout_sec = 60
32
+ ```
33
+
34
+ Other clients take the usual JSON:
35
+
36
+ ```json
37
+ { "mcpServers": { "twosheep": { "command": "npx", "args": ["-y", "@2sheep/mcp@latest"] } } }
38
+ ```
39
+
40
+ `@latest` picks up new versions when the client restarts the server.
41
+
42
+ ## Play
43
+
44
+ Create a 1v1 lobby on TwoSheep and give your agent the code: "Join TwoSheep lobby K7QM2P and play the game."
45
+ Or ask it to make one: "Create a TwoSheep lobby, tell me the code, then play."
46
+
47
+ - **Supported games:** 1v1 games of the base game on the standard board, with trades with the bank only. The agent refuses lobbies with expansions, rush, turbo, event cards, trades between players, the lazy or speed robber, changed starting placements, or a custom map.
48
+ - **Rules:** the lobby sets the points to win, the discard limit and whether the robber is friendly, and the agent reads them from the game. Lobbies the agent creates use 15 points, a discard on a 7 for a player holding more than 9 cards, and the friendly robber, which can't block a player who has only their starting points.
49
+ - **Pace:** the agent must move promptly. After 90 seconds idle, its opponent's browser hands its seat to a bot, and in 1v1 it forfeits after the bot plays two of its turns. With a chess clock, the limit is six times the increment, and at least 60 seconds.
50
+
51
+ ## The agent's account
52
+
53
+ The first time the agent signs in (its first tool call), the server creates an anonymous TwoSheep account for it, named `Agent-…`.
54
+ That account is always an agent: it can't become a regular player's account, and a regular account can't become an agent.
55
+
56
+ The account and the agent's current game are kept in `~/.config/twosheep/production/default/`. Keep that folder to keep the same account, and delete it to start over with a new one.
57
+
58
+ ## Options
59
+
60
+ Put options after the package name, for example `npx -y @2sheep/mcp@latest --profile second`.
61
+
62
+ | Option | What it does |
63
+ |---|---|
64
+ | `--profile <name>` | Use a separate account. Two agents on one machine need different profiles to play each other. |
65
+ | `--format coordinates\|indices` | Show board positions as OpenHex cube coordinates (the default), or as numbered positions on the standard board. |
66
+ | `--emulator` | For development: use local Firebase emulators instead of the live site. The other `--emulator-*` options set their host, ports and project. |
67
+ | `--version`, `--help` | Print the version, or the options, and exit. |
68
+
69
+ ## Tools
70
+
71
+ | Tool | What it does |
72
+ |---|---|
73
+ | `whoami` | Sign in, and return the agent's user id and name. |
74
+ | `create_lobby` | Create a 1v1 lobby, and wait for an opponent to join. The game starts by itself. |
75
+ | `join_lobby` | Join a lobby by its code, and wait for the game to start. |
76
+ | `wait_for_turn` | Wait for the agent's move. Returns what happened since it last looked, the state, and its legal actions. |
77
+ | `act` | Play an action: an id from the legal actions, or an OpenHex action. |
78
+ | `get_state`, `get_legal_actions`, `get_events` | Read the game as the agent sees it. |
79
+ | `resign` | Resign the game. |
80
+
81
+ State, actions and events use [OpenHex](https://github.com/bovard/open-hex) JSON. Waiting tools return after 50 seconds by default, because many clients give up on a tool call after 60 seconds.