pokerdata-mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 HFT Studio LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This licence covers the code in this repository. The sample data in
+samples/ is solver output from pokerdata.io, provided for evaluation under the
+terms at https://pokerdata.io/terms.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# PokerData MCP: GTO poker solver data for AI agents
 
-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.
+[PokerData](https://pokerdata.io) serves GTO solver strategy for no-limit
+hold'em and pot-limit Omaha as JSON, over an MCP server and a REST API.
+Point Claude, Cursor or any MCP client at it and ask "what does UTG open at
+100bb?" or "how does the BB defend vs a BTN open?" and the agent gets the
+solver's real frequencies and EVs, not a guess.
+
+- **Endpoint:** `https://pokerdata.io/api/mcp` (Streamable HTTP, stateless)
+- **Free without a key:** the tool list and every 6-max NL cash preflop tool,
+  all 8 stack depths
+- **Everything else:** a `pdk_` key from [pokerdata.io/app/api](https://pokerdata.io/app/api).
+  A free trial key (100 calls, no card) unlocks every data tool.
+
+This repository holds setup instructions, a small stdio bridge for clients
+that only speak stdio, examples and sample data. The data and the server are
+hosted at pokerdata.io.
+
+## What's covered
+
+| Game | Format | Stacks | Data |
+|---|---|---|---|
+| No-limit hold'em 6-max (`nl`) | Cash, 5% rake, 0.5bb cap | 20, 30, 40, 50, 70, 100, 150, 200bb | Every preflop decision node, frequency and EV per hand class (169) |
+| NLHE tournament 8-max (`nlmtt8`) | Chip EV, 1bb BB ante | 10 to 300bb | Preflop |
+| NLHE tournament 8-max, classic ante (`nlh8-hydra`) | Chip EV, 0.1bb ante | 10, 20, 30, 60bb | Preflop |
+| Pot-limit Omaha 6-max (`plo`) | Cash | 12 to 200bb | Preflop, suit-grouped classes |
+| PLO 9-max (`plo9`) | Cash | 60, 100bb | Preflop |
+| PLO5 6-max (`plo5`) | Cash, 1.2bb ante | 100bb | Preflop and postflop |
+| NLHE heads-up postflop | Single-raised, 3-bet and 4-bet pots | 100bb | Solved flops with turns and rivers, per-combo strategy and EV, two bet-size trees |
+
+`list_games` and `list_postflop_packs` return the live coverage, so an agent
+never has to trust this table. Not covered: ICM, PKO, multiway postflop,
+tournament postflop. Those requests come back as explicit "unsupported"
+rather than a cash-game stand-in.
+
+## Set it up
+
+### Claude Code
+
+```sh
+# No key: 6-max NL cash preflop
+claude mcp add --transport http pokerdata https://pokerdata.io/api/mcp
+
+# With a key: every game and postflop
+claude mcp add --transport http pokerdata https://pokerdata.io/api/mcp \
+  --header "Authorization: Bearer pdk_YOUR_KEY"
+```
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "pokerdata": {
+      "url": "https://pokerdata.io/api/mcp",
+      "headers": { "Authorization": "Bearer pdk_YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Claude Desktop and other stdio clients
+
+```json
+{
+  "mcpServers": {
+    "pokerdata": {
+      "command": "npx",
+      "args": ["-y", "pokerdata-mcp"],
+      "env": { "POKERDATA_API_KEY": "pdk_YOUR_KEY" }
+    }
+  }
+}
+```
+
+Leave out `env` to use the free tools only. The bridge in
+[`bin/pokerdata-mcp.js`](bin/pokerdata-mcp.js) has no dependencies and only
+forwards JSON-RPC to the hosted endpoint. Claude Desktop can also add
+`https://pokerdata.io/api/mcp` directly as a custom connector.
+
+### Plain HTTP
+
+```sh
+curl -s https://pokerdata.io/api/mcp -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_node","arguments":{"game":"nl","stack":100,"history":"UTG"}}}'
+```
+
+More in [`examples/`](examples/): curl, Python, and the REST API.
+
+## Tools
+
+| Group | Tools | Key |
+|---|---|---|
+| Coverage and docs | `list_games`, `list_postflop_packs`, `list_datasets`, `get_tree_docs`, `get_exploitability` | Not needed |
+| Preflop | `get_range`, `get_node`, `list_spots`, `get_config`, `get_range_metadata` | Not needed for `game: "nl"`; needed for every other game |
+| Postflop | `get_postflop_node`, `get_postflop_range` | Needed |
+| Coaching | `explain_combo`, `get_board_report`, `compare_strategies` | Needed |
+| Your hands | hand, session and opponent tools, hand upload | Any key, free trial included; never counts against your allowance |
+| Solve queue | `enqueue_solve`, `get_queued_solve`, `list_queued_solves`, `list_library_solutions` | Needed |
+
+Preflop spots are action paths such as `UTG_60%_HJ_Call` (NLHE) or
+`UTG_Open_HJ_3B` (PLO). EVs are in small blinds. Responses are compact by
+default; pass `detail: "full"` for complete maps. Full contract:
+[docs.pokerdata.io/ranges](https://docs.pokerdata.io/ranges).
+
+## Plans
+
+| Plan | Price | What you get |
+|---|---|---|
+| No key | Free | Tool list, coverage tools, 6-max NL cash preflop at every stack. 200 tool calls a day per IP |
+| Starter | Free key, no card | Every data tool, 100 calls (or 50 MB) lifetime. Personal use |
+| Pro | $100/month | Every game and all postflop, 250,000 calls or 5 GB a month. Personal use |
+| Enterprise | $250/month | Everything in Pro, **commercial use allowed**, 5 million calls or 100 GB a month, higher rate limit |
+| Custom | [Contact us](https://pokerdata.io/support) | Redistribution, bulk export, licences for model training, SLAs |
+
+REST and MCP share one meter. Keys and plans: [pokerdata.io/app/api](https://pokerdata.io/app/api).
+
+## Sample data
+
+[`samples/`](samples/) has two real responses, so you can check the format
+before connecting anything:
+
+- `nl-6max-100bb-utg-first-in.json`: UTG's first decision at 100bb, every
+  action with per-hand frequency and EV.
+- `nl-6max-100bb-utg-open-range.json`: UTG's opening range at 100bb.
+
+## How the solves were made
+
+Preflop cash trees are MonkerSolver solutions. The tournament and postflop
+solves come from our own engine, validated against MonkerSolver as described
+at [pokerdata.io/methodology](https://pokerdata.io/methodology). Postflop
+exploitability is published per board (`list_postflop_packs` with a `pack`).
+
+## Related
+
+- [pokerdata.io](https://pokerdata.io): download the raw solver packs, browse ranges free
+- [Poker Study AI](https://www.pokerstudy.ai): an AI coach that reviews your hands against the same solves
+
+Code in this repository is MIT licensed. Sample data is provided for
+evaluation under the [pokerdata.io terms](https://pokerdata.io/terms).

package/bin/pokerdata-mcp.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// stdio bridge to the hosted PokerData MCP server.
+//
+// Reads newline-delimited JSON-RPC from stdin, POSTs each message to
+// https://pokerdata.io/api/mcp and writes the reply to stdout. The server
+// does all the work; this file only exists for MCP clients that speak stdio.
+//
+// POKERDATA_API_KEY  optional pdk_ key. Without it, the tool list and the
+//                    free 6-max NL cash preflop tools still work.
+// POKERDATA_MCP_URL  optional override of the endpoint.
+
+"use strict";
+
+const readline = require("node:readline");
+
+const URL_ = process.env.POKERDATA_MCP_URL || "https://pokerdata.io/api/mcp";
+const KEY = (process.env.POKERDATA_API_KEY || "").trim();
+const VERSION = require("../package.json").version;
+
+const headers = {
+  "Content-Type": "application/json",
+  Accept: "application/json, text/event-stream",
+  "User-Agent": `pokerdata-mcp/${VERSION}`,
+};
+if (KEY) headers.Authorization = `Bearer ${KEY}`;
+
+function write(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+function errorReply(msg, code, message) {
+  if (!msg || msg.id === undefined || msg.id === null) return;
+  write({ jsonrpc: "2.0", id: msg.id, error: { code, message } });
+}
+
+async function forward(line) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+    return;
+  }
+  let res;
+  try {
+    res = await fetch(URL_, { method: "POST", headers, body: line });
+  } catch (err) {
+    errorReply(msg, -32000, `Could not reach ${URL_}: ${err.message}`);
+    return;
+  }
+  if (res.status === 202) return; // notifications get no reply
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    errorReply(msg, -32000, `Unexpected ${res.status} response from ${URL_}`);
+    return;
+  }
+  // Errors raised before the server read the message carry id null; give
+  // them back the caller's id so the client can match the reply.
+  if (!Array.isArray(body) && body && body.id === null && msg.id !== undefined) {
+    body.id = msg.id;
+  }
+  write(body);
+}
+
+const rl = readline.createInterface({ input: process.stdin });
+let queue = Promise.resolve();
+rl.on("line", (line) => {
+  if (!line.trim()) return;
+  queue = queue.then(() => forward(line));
+});
+rl.on("close", () => {
+  queue.then(() => process.exit(0));
+});

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "pokerdata-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "MCP server for GTO poker solver data: preflop ranges and postflop strategy for no-limit hold'em and pot-limit Omaha, from pokerdata.io.",
+  "mcpName": "io.github.hft-studio/pokerdata",
+  "bin": {
+    "pokerdata-mcp": "bin/pokerdata-mcp.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "poker",
+    "gto",
+    "solver",
+    "poker-ranges",
+    "preflop",
+    "postflop",
+    "nlhe",
+    "plo",
+    "poker-api"
+  ],
+  "homepage": "https://pokerdata.io/api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hft-studio/pokerdata-mcp.git"
+  },
+  "license": "MIT",
+  "author": "HFT Studio LLC"
+}