chipzen-mcp 0.1.0__tar.gz

chipzen_mcp-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.venv/
+venv/
+env/
+dist/
+build/
+
+# JavaScript / TypeScript
+node_modules/
+*.log
+.npm
+.pnpm-store/
+coverage/
+.next/
+.nuxt/
+.turbo/
+
+# Rust
+target/
+Cargo.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Local env
+.env
+.env.local
+.env.*.local
+.envrc
+
+# Credentials and secrets — defense in depth, the platform's threat
+# model assumes uploaded bot images carry no per-user secrets but a
+# leaked dotfile in a contributor's working tree is still bad.
+*.key
+*.pem
+*.cert
+*.crt
+secrets.*
+credentials.*
+.aws/credentials
+
+# Build artifacts
+*.tar.gz
+*.zip
+*.whl

chipzen_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: chipzen-mcp
+Version: 0.1.0
+Summary: Official Chipzen MCP server - let any MCP-capable agent play poker on chipzen.ai over the External-API remote-play track
+Project-URL: Homepage, https://chipzen.ai
+Project-URL: Repository, https://github.com/chipzen-ai/chipzen-sdk
+Project-URL: Issues, https://github.com/chipzen-ai/chipzen-sdk/issues
+Author-email: "Chipzen, Inc." <support@chipzen.ai>
+License-Expression: Apache-2.0
+Keywords: agent,ai,bot,chipzen,mcp,model-context-protocol,poker
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: chipzen-bot>=0.3.0
+Requires-Dist: mcp<2,>=1.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chipzen-mcp — the official Chipzen MCP server
+
+Let any MCP-capable agent (Claude, or anything else that speaks the
+[Model Context Protocol](https://modelcontextprotocol.io)) play poker on
+[chipzen.ai](https://chipzen.ai) with **zero protocol code**. The server
+wraps the Chipzen External-API remote-play track — the same
+`run_external_bot()` path the [`chipzen-bot` Python SDK](https://github.com/chipzen-ai/chipzen-sdk/tree/main/packages/python)
+packages — and exposes it as seven MCP tools.
+
+> **Status: pre-alpha.** Design tracked in chipzen-ai/Chipzen#3748;
+> runtime wiring (session lifecycle, lobby presence, agent-initiated
+> challenges) is complete. Not published to PyPI or any MCP directory yet.
+> `challenge_house_bot` speaks the **final** contract of the scoped server
+> endpoint (chipzen-ai/Chipzen#3750, implemented in chipzen-ai/Chipzen#3825),
+> which rolls out staging-first — on environments without it the tool
+> reports `endpoint_not_available` and points at the dashboard fallback.
+
+## How it works
+
+The External-API is a persistent WebSocket that *pushes* "your turn" frames;
+MCP is *pull*. The bridge in between:
+
+```
+ MCP agent ──tools──► FastMCP (stdio) ──► TurnRegistry (thread-safe)
+                                               ▲
+ chipzen.ai ◄──lobby + match WS──  SDK session thread (run_external_bot)
+                                   BridgeBot.decide() publishes each turn
+                                   and blocks until act() answers it
+```
+
+- The SDK session runs in a background thread: lobby presence, `matched`
+  dispatch, per-match gateway sockets, reconnect — all reused from
+  `chipzen-bot`, not reimplemented.
+- `wait_for_turn` long-polls the registry, so the agent's reasoning time
+  *is* the decision time. Up to 5 concurrent matches per token (platform
+  cap) are multiplexed through the same loop, most-urgent-deadline first.
+- Lifecycle: when the MCP transport closes, the session thread is stopped
+  cooperatively (sockets close cleanly, in-flight matches get a short drain
+  grace). Lobby presence and per-match reconnect state are derived from the
+  SDK's own log events — `get_status.lobby_connected` is truthful, not a
+  thread-liveness guess.
+
+## The tools
+
+| Tool | What it does |
+|---|---|
+| `get_status` | Truthful lobby presence (`connected` / `reconnecting` / `evicted`), active matches vs the 5-per-token cap |
+| `wait_for_turn` | **The main loop.** Blocks until a match needs your action |
+| `get_match_state` | Re-read one match's pending turn / results |
+| `act` | `fold` / `check` / `call` / `raise` (amount = TOTAL bet) / `all_in` |
+| `list_matches` | All in-flight and recent matches, incl. per-match gateway connection state |
+| `get_last_result` | Winners, payouts, showdown for the latest hand/match |
+| `challenge_house_bot` | Start an unrated, ~30s-clock practice match vs a house bot (server endpoint from chipzen-ai/Chipzen#3750; staging-first) |
+
+## Quickstart
+
+See [QUICKSTART.md](https://github.com/chipzen-ai/chipzen-sdk/blob/main/packages/mcp/QUICKSTART.md) — target is a seated agent in under
+10 minutes.
+
+## A word about the clock — read this
+
+Poker has a decision clock; LLM turns are slow. The v1 agent experience is
+**unrated/casual matches with a ~30 second clock** (chipzen-ai/Chipzen#3750).
+Rated ladder and tournament matches run a 2-second clock designed for
+compiled bots — an LLM reasoning per-turn **will time out there** and the
+server auto-plays check/fold. `wait_for_turn` returns `remaining_ms` so the
+agent can pace itself; the bridge falls back to check/fold just before the
+deadline rather than letting the server do it silently. We document this
+honestly instead of hiding it: don't take a per-turn-reasoning agent into a
+2-second division and expect anything but donated chips.
+
+## Development
+
+```bash
+cd packages/mcp
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && mypy src/
+pytest -q --cov=chipzen_mcp --cov-fail-under=85
+```
+
+Protocol references: [`docs/EXTERNAL-API-BOT-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/EXTERNAL-API-BOT-PROTOCOL.md),
+[`docs/protocol/POKER-GAME-STATE-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/protocol/POKER-GAME-STATE-PROTOCOL.md).

chipzen_mcp-0.1.0/QUICKSTART.md

@@ -0,0 +1,118 @@
+# Your agent, seated at a poker table in 10 minutes
+
+This is the drop-in path: you have an MCP-capable agent (Claude Desktop,
+Claude Code, anything that can mount an MCP server) and you want it playing
+poker on [chipzen.ai](https://chipzen.ai). No SDK, no protocol code, and the
+agent starts its own first match.
+
+> **Pre-release note:** install is from source until the first PyPI
+> release. Agent-initiated challenges (step 4) reach staging first
+> (server side of chipzen-ai/Chipzen#3750); the dashboard fallback at the
+> bottom covers environments that don't have them yet.
+
+## 0–2 min — create an External-API bot
+
+Sign in at [staging.chipzen.ai](https://staging.chipzen.ai), open
+**Bots → Create bot**, pick **External API** as the bot kind. Copy the
+**bot id** (a UUID) from the bot's detail page.
+
+## 2–4 min — issue a token
+
+On the same bot detail page: **API tokens → Create token**. Copy the
+`cz_extbot_...` value immediately — it is shown exactly once (lose it →
+just rotate).
+
+## 4–7 min — mount the MCP server
+
+Install (from source, pre-release):
+
+```bash
+git clone https://github.com/chipzen-ai/chipzen-sdk.git
+pip install ./chipzen-sdk/packages/mcp
+```
+
+Add the server to your agent's MCP config (Claude Desktop:
+`claude_desktop_config.json`; Claude Code: `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "chipzen": {
+      "command": "chipzen-mcp",
+      "env": {
+        "CHIPZEN_ENV": "staging",
+        "CHIPZEN_BOT_ID": "<your-bot-uuid>",
+        "CHIPZEN_EXTBOT_TOKEN": "cz_extbot_..."
+      }
+    }
+  }
+}
+```
+
+Restart the agent. The server connects your bot to the Chipzen lobby in the
+background — ask the agent to call `get_status` and you should see
+`lobby_connected: true`.
+
+## 7–8 min — the agent starts its own match
+
+Tell your agent:
+
+> Call `challenge_house_bot` to start an unrated practice match against a
+> house bot.
+
+That's it — the challenge is unrated (never touches ratings), runs on a
+relaxed **~30 second decision clock** built for reasoning agents, and is
+dispatched straight back to this session. No dashboard round-trip.
+
+## 8–10 min — the "your agent is seated" moment
+
+Follow up with something like:
+
+> You're seated. Loop on `wait_for_turn`; each time it returns a turn,
+> reason about the state and call `act`. Keep playing until the match ends,
+> then report the result.
+
+The agent sees its hole cards, the board, pot, stacks, and legal actions on
+every turn, and plays by calling `act(match_id, action, amount)`. When
+`get_last_result` shows the outcome — that's the moment.
+
+## Expectations, honestly
+
+- **Decision clock.** Agent challenges are unrated/casual with a ~30 s
+  clock. Rated ladder/tournament matches use a 2 s clock built for compiled
+  bots — a per-turn-reasoning LLM **will** time out there and
+  auto-check/fold. Watch `remaining_ms` in every turn.
+- **Concurrency.** One token can hold up to 5 simultaneous matches; the
+  `wait_for_turn` loop serves whichever seat is most urgent.
+- **Unrated vs rated.** House-bot practice matches never move your rating.
+  The competitive ladders remain the SDK bots' home turf — for now.
+
+## Fallback: starting a match from the dashboard
+
+Agent-initiated challenges roll out staging-first. If `challenge_house_bot`
+returns `endpoint_not_available` on your environment, start the first match
+from the dashboard instead: open **/challenges → New challenge**, pick your
+bot as the challenger and a house bot as the opponent, and choose an
+**unranked exhibition** match. Dispatch routes the match to your connected
+agent automatically; the `wait_for_turn` loop is identical from there.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `get_status` → `session_error` mentioning 4001 | Token/bot-id mismatch, or a revoked token — check both env vars |
+| `challenge_house_bot` → `unauthorized` | The token was rejected (invalid/revoked, or `CHIPZEN_BOT_ID` doesn't match it) — verify both env vars or rotate the token |
+| `challenge_house_bot` → `endpoint_not_available` | This environment doesn't have agent-initiated challenges yet — use the dashboard fallback above |
+| `challenge_house_bot` → `bot_offline` | Your session isn't connected to the lobby — check `get_status` (`lobby_connected` must be true), then retry |
+| `challenge_house_bot` → `concurrent_cap` | 5-match concurrency cap in use — finish or wait out a match (`list_matches`) |
+| `challenge_house_bot` → `free_tier_limit` | A free-tier account limit was hit — the `detail` field names the limit and when it resets |
+| `challenge_house_bot` → `house_bot_not_found` | The `bot_name` you passed isn't a house bot — use its exact name/UUID, or omit it for the default |
+| `challenge_house_bot` → `dispatch_failed` | Transient platform error launching the match — retry shortly |
+| `wait_for_turn` always `idle` | No match is running — start one (step 4 or the fallback) |
+| `act` → `no_pending_turn` | The decision clock expired (bridge already auto-played) or it isn't your turn |
+| `get_status` → `lobby_state: reconnecting` | Transient network drop — the SDK is re-establishing the lobby; matches in flight resume on their own sockets |
+
+Full protocol reference:
+[`docs/EXTERNAL-API-BOT-PROTOCOL.md`](../../docs/EXTERNAL-API-BOT-PROTOCOL.md).
+Something broken? [Open an issue](https://github.com/chipzen-ai/chipzen-sdk/issues)
+or find us on [Discord](https://discord.gg/U6SRwkpYXN).

chipzen_mcp-0.1.0/README.md

@@ -0,0 +1,82 @@
+# chipzen-mcp — the official Chipzen MCP server
+
+Let any MCP-capable agent (Claude, or anything else that speaks the
+[Model Context Protocol](https://modelcontextprotocol.io)) play poker on
+[chipzen.ai](https://chipzen.ai) with **zero protocol code**. The server
+wraps the Chipzen External-API remote-play track — the same
+`run_external_bot()` path the [`chipzen-bot` Python SDK](https://github.com/chipzen-ai/chipzen-sdk/tree/main/packages/python)
+packages — and exposes it as seven MCP tools.
+
+> **Status: pre-alpha.** Design tracked in chipzen-ai/Chipzen#3748;
+> runtime wiring (session lifecycle, lobby presence, agent-initiated
+> challenges) is complete. Not published to PyPI or any MCP directory yet.
+> `challenge_house_bot` speaks the **final** contract of the scoped server
+> endpoint (chipzen-ai/Chipzen#3750, implemented in chipzen-ai/Chipzen#3825),
+> which rolls out staging-first — on environments without it the tool
+> reports `endpoint_not_available` and points at the dashboard fallback.
+
+## How it works
+
+The External-API is a persistent WebSocket that *pushes* "your turn" frames;
+MCP is *pull*. The bridge in between:
+
+```
+ MCP agent ──tools──► FastMCP (stdio) ──► TurnRegistry (thread-safe)
+                                               ▲
+ chipzen.ai ◄──lobby + match WS──  SDK session thread (run_external_bot)
+                                   BridgeBot.decide() publishes each turn
+                                   and blocks until act() answers it
+```
+
+- The SDK session runs in a background thread: lobby presence, `matched`
+  dispatch, per-match gateway sockets, reconnect — all reused from
+  `chipzen-bot`, not reimplemented.
+- `wait_for_turn` long-polls the registry, so the agent's reasoning time
+  *is* the decision time. Up to 5 concurrent matches per token (platform
+  cap) are multiplexed through the same loop, most-urgent-deadline first.
+- Lifecycle: when the MCP transport closes, the session thread is stopped
+  cooperatively (sockets close cleanly, in-flight matches get a short drain
+  grace). Lobby presence and per-match reconnect state are derived from the
+  SDK's own log events — `get_status.lobby_connected` is truthful, not a
+  thread-liveness guess.
+
+## The tools
+
+| Tool | What it does |
+|---|---|
+| `get_status` | Truthful lobby presence (`connected` / `reconnecting` / `evicted`), active matches vs the 5-per-token cap |
+| `wait_for_turn` | **The main loop.** Blocks until a match needs your action |
+| `get_match_state` | Re-read one match's pending turn / results |
+| `act` | `fold` / `check` / `call` / `raise` (amount = TOTAL bet) / `all_in` |
+| `list_matches` | All in-flight and recent matches, incl. per-match gateway connection state |
+| `get_last_result` | Winners, payouts, showdown for the latest hand/match |
+| `challenge_house_bot` | Start an unrated, ~30s-clock practice match vs a house bot (server endpoint from chipzen-ai/Chipzen#3750; staging-first) |
+
+## Quickstart
+
+See [QUICKSTART.md](https://github.com/chipzen-ai/chipzen-sdk/blob/main/packages/mcp/QUICKSTART.md) — target is a seated agent in under
+10 minutes.
+
+## A word about the clock — read this
+
+Poker has a decision clock; LLM turns are slow. The v1 agent experience is
+**unrated/casual matches with a ~30 second clock** (chipzen-ai/Chipzen#3750).
+Rated ladder and tournament matches run a 2-second clock designed for
+compiled bots — an LLM reasoning per-turn **will time out there** and the
+server auto-plays check/fold. `wait_for_turn` returns `remaining_ms` so the
+agent can pace itself; the bridge falls back to check/fold just before the
+deadline rather than letting the server do it silently. We document this
+honestly instead of hiding it: don't take a per-turn-reasoning agent into a
+2-second division and expect anything but donated chips.
+
+## Development
+
+```bash
+cd packages/mcp
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && mypy src/
+pytest -q --cov=chipzen_mcp --cov-fail-under=85
+```
+
+Protocol references: [`docs/EXTERNAL-API-BOT-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/EXTERNAL-API-BOT-PROTOCOL.md),
+[`docs/protocol/POKER-GAME-STATE-PROTOCOL.md`](https://github.com/chipzen-ai/chipzen-sdk/blob/main/docs/protocol/POKER-GAME-STATE-PROTOCOL.md).

chipzen_mcp-0.1.0/RELEASING.md

@@ -0,0 +1,154 @@
+# Releasing `chipzen-mcp` to PyPI
+
+The release workflow lives at
+[`.github/workflows/release-mcp.yml`](../../.github/workflows/release-mcp.yml).
+It uses **PyPI Trusted Publishers (OIDC)** so there is no long-lived
+`PYPI_TOKEN` secret to manage.
+
+`chipzen-mcp` has **never been published** — the values below are the
+one-time handoff a maintainer enters on PyPI to enable the first publish.
+
+## PyPI "Add a pending publisher" form values — enter these EXACTLY
+
+Go to https://pypi.org/manage/account/publishing/ → **Add a new pending
+publisher** (GitHub), and enter:
+
+| Field | Value |
+|---|---|
+| **PyPI Project Name** | `chipzen-mcp` |
+| **Owner** | `chipzen-ai` |
+| **Repository name** | `chipzen-sdk` |
+| **Workflow name** | `release-mcp.yml` |
+| **Environment name** | `pypi` |
+
+For a TestPyPI dry run first, repeat the same form at
+https://test.pypi.org/manage/account/publishing/ with **Environment
+name** `testpypi` (everything else identical).
+
+Because the project does not exist yet, use PyPI's **pending publisher**
+form (not the per-project one) — Trusted Publishers will mint the
+`chipzen-mcp` project on the first successful publish. No placeholder
+upload and no API token are required.
+
+## One-time setup (before the first release)
+
+Done once per package + per index (PyPI and TestPyPI). Until the
+pending publisher exists, the publish job will fail with `Trusted
+Publisher not found`.
+
+### 1. Reserve the PyPI project name
+
+- Sign in at https://pypi.org/ as the maintainer account.
+- `chipzen-mcp` is currently unregistered (PyPI 404), so you do not need
+  to upload a placeholder — the pending Trusted Publisher configured
+  above mints the project on first publish. If you would rather be
+  explicit, upload an empty version manually with a one-time API token
+  (`python -m build && twine upload dist/*`), then revoke the token.
+- Repeat on https://test.pypi.org/ for TestPyPI if you want a dry run
+  there first.
+
+### 2. Configure the Trusted Publisher
+
+Per index (PyPI + TestPyPI), add the pending publisher using the exact
+values from the table at the top of this file:
+
+1. Open https://pypi.org/manage/account/publishing/ (or the TestPyPI
+   equivalent at https://test.pypi.org/manage/account/publishing/).
+2. **Add a new pending publisher** of type **GitHub**:
+   - **PyPI Project Name**: `chipzen-mcp`
+   - **Owner**: `chipzen-ai`
+   - **Repository name**: `chipzen-sdk`
+   - **Workflow name**: `release-mcp.yml`
+   - **Environment name**: `pypi` (or `testpypi` for the TestPyPI
+     entry — must match the `environment.name` in the workflow's
+     `publish` job)
+
+PyPI will accept publishes from this exact `(repo, workflow, environment)`
+triple via OIDC. No secret is stored on either side.
+
+### 3. (Optional) Add reviewers / wait timers to the GitHub environment
+
+In the chipzen-sdk repo on GitHub:
+
+- Settings → Environments → New environment → name `pypi`
+- Add `Required reviewers` (at least one maintainer, e.g. yourself)
+  — every publish then requires explicit approval before it runs.
+- Add `Wait timer` if you want a forced cooling-off window between
+  the trigger and the publish.
+
+Repeat for the `testpypi` environment if you want TestPyPI publishes
+to be gated similarly. (The `pypi` / `testpypi` environments are shared
+with the chipzen-bot `release-python.yml` workflow — if you already
+configured them for that package, no new environment is needed here.)
+
+## Cutting a release
+
+1. **Bump the version** in
+   [`packages/mcp/pyproject.toml`](pyproject.toml). Open a normal PR and
+   merge.
+2. **Verify locally**:
+   ```bash
+   cd packages/mcp
+   pip install --upgrade build
+   python -m build
+   ls dist/  # expect chipzen_mcp-X.Y.Z.tar.gz + .whl
+   ```
+3. **Tag the release** (after merging the version-bump PR to `main`):
+   ```bash
+   git checkout main
+   git pull
+   git tag mcp-v0.1.0   # match the pyproject version exactly
+   git push origin mcp-v0.1.0
+   ```
+   Pushing the tag triggers the workflow, which builds + publishes. The
+   `mcp-` prefix keeps this distinct from the chipzen-bot `python-v*`
+   tags in the same repo.
+4. **Approve** the publish (if reviewers were added in setup step 3).
+5. **Verify**: `pip install chipzen-mcp==0.1.0` in a clean venv, run
+   `chipzen-mcp --help` to confirm the console script resolves.
+
+## Cutting a TestPyPI release first
+
+Useful before a major bump to verify the wheel installs cleanly
+without polluting the real PyPI namespace.
+
+1. Actions → "Release MCP" → Run workflow.
+2. Set `target_index` to `testpypi`, leave `dry_run` unchecked.
+3. Approve the publish.
+4. Install from TestPyPI (the `--extra-index-url` lets pip resolve the
+   `chipzen-bot` runtime dependency from real PyPI):
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ \
+     --extra-index-url https://pypi.org/simple/ \
+     chipzen-mcp==0.1.0
+   ```
+5. Once happy, push the real tag (`mcp-v0.1.0`).
+
+## Dry-run a build without publishing
+
+For inspecting what the wheel + sdist actually contain before the
+first real release.
+
+1. Actions → "Release MCP" → Run workflow.
+2. Check `dry_run` (publish job will be skipped).
+3. Download the `chipzen-mcp-dist` artifact from the workflow run.
+4. Inspect:
+   ```bash
+   tar tzvf chipzen_mcp-0.1.0.tar.gz | head -30
+   unzip -l chipzen_mcp-0.1.0-py3-none-any.whl | head -30
+   ```
+
+## Yanking a bad release
+
+If you publish a release with a critical bug:
+
+1. Cut a fixed version (`0.1.1`) and publish it via the same flow.
+2. Yank the bad version on PyPI:
+   - https://pypi.org/manage/project/chipzen-mcp/releases/
+   - Open the bad release → Yank → confirm.
+3. Yanked releases stay installable for users who explicitly request
+   the version (so reproducibility holds), but pip will skip them by
+   default and emit a warning.
+
+Do **not** delete a published release unless you absolutely must —
+deletion blocks anyone reproducing an old build.

chipzen_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chipzen-mcp"
+version = "0.1.0"
+description = "Official Chipzen MCP server - let any MCP-capable agent play poker on chipzen.ai over the External-API remote-play track"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "Chipzen, Inc.", email = "support@chipzen.ai" },
+]
+keywords = ["poker", "bot", "ai", "agent", "mcp", "model-context-protocol", "chipzen"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    # The published Chipzen SDK carries the whole External-API remote-play
+    # path (lobby -> matched -> gateway -> game loop -> reconnect); this
+    # package only bridges it onto MCP.
+    "chipzen-bot>=0.3.0",
+    # Official MCP Python SDK (FastMCP server).
+    "mcp>=1.5,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.5.0",
+    "mypy>=1.0",
+]
+
+[project.urls]
+Homepage = "https://chipzen.ai"
+Repository = "https://github.com/chipzen-ai/chipzen-sdk"
+Issues = "https://github.com/chipzen-ai/chipzen-sdk/issues"
+
+[project.scripts]
+chipzen-mcp = "chipzen_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chipzen_mcp"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E741", "N806"]
+
+[tool.mypy]
+# The published chipzen-bot 0.3.0 wheel predates the py.typed marker this
+# repo now ships (the python-wheel-smoke CI job guards it going forward),
+# so mypy can't see the SDK's inline types when installed from PyPI.
+# Drop this override once the first post-0.3.0 SDK release is out.
+[[tool.mypy.overrides]]
+module = "chipzen.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

chipzen_mcp-0.1.0/src/chipzen_mcp/__init__.py

@@ -0,0 +1,41 @@
+"""Chipzen MCP server -- play poker on chipzen.ai from any MCP-capable agent.
+
+This package bridges the Chipzen External-API remote-play track (a persistent
+push-style WebSocket protocol, packaged by the ``chipzen-bot`` SDK) onto the
+Model Context Protocol's pull-style request/response tool model, so an agent
+can be seated at a table with zero protocol code.
+
+Status: **pre-alpha** (chipzen-ai/Chipzen#3748, runtime wiring complete).
+The push->pull bridge, session lifecycle (cooperative stop, lobby-presence
+surfacing), and the ``challenge_house_bot`` client are implemented; end-to-end
+staging verification against the server side of chipzen-ai/Chipzen#3750 is
+the remaining gate. Not published to any registry.
+"""
+
+__version__ = "0.1.0.dev0"
+
+from chipzen_mcp.bridge import BridgeBot, ExternalSession, TurnRegistry, TurnSnapshot
+from chipzen_mcp.config import (
+    ENV_BOT_ID,
+    ENV_ENV,
+    ENV_TOKEN,
+    McpConfig,
+    McpConfigError,
+    load_config,
+)
+
+__all__ = [
+    "__version__",
+    # Bridge (push->pull) primitives
+    "TurnRegistry",
+    "TurnSnapshot",
+    "BridgeBot",
+    "ExternalSession",
+    # Config
+    "McpConfig",
+    "McpConfigError",
+    "load_config",
+    "ENV_TOKEN",
+    "ENV_BOT_ID",
+    "ENV_ENV",
+]