@pipeworx/mcp-cricsheet 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojibake Inc.
+
+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.

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# @pipeworx/cricsheet
 
-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.
+Ball-by-ball cricket data collapsed to the questions people actually ask: a
+match's result and scorecard, a player's career batting/bowling aggregates,
+and a head-to-head record between two teams. Covers Test matches, One Day
+Internationals, T20 Internationals, and the Indian Premier League. Fleet
+#2975.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1856+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+
+## Tools
+
+- `cricsheet_match(match_id)` — one match's full result plus, for every
+  innings, the batting card (each batter's runs/balls/4s/6s/how out) and
+  bowling card (each bowler's overs/runs/wickets). Use
+  `cricsheet_find_matches` first to get a `match_id`.
+- `cricsheet_player_stats(player, format?)` — a cricketer's career batting
+  and bowling aggregates (matches, runs, average, strike rate, 100s/50s;
+  wickets, bowling average, economy). `player` is matched case-insensitively
+  as a substring against the short-form names this pack stores (e.g. "Kohli"
+  for "V Kohli"); an ambiguous query returns a candidate list instead of
+  guessing. Optionally scope to one `format`.
+- `cricsheet_head_to_head(team_a, team_b, format?, limit?, offset?)` — total
+  matches, each team's wins, ties/no-results, and the most recent matches
+  with their results. Team names must match Cricsheet's own strings (e.g.
+  `"India"`, `"Mumbai Indians"`).
+- `cricsheet_find_matches(team?, format?, season?, venue?, player?, limit?, offset?)`
+  — search the match index to discover `match_id`s. With no filters, returns
+  the most recent matches held across every format.
+- `cricsheet_chase_search(second_innings_result?, format?, min/max_wickets_remaining?, min/max_balls_remaining?, team?, gender?, season?, event?, date_from?, date_to?, limit?, offset?)`
+  — compound search on the chase (second innings) in ODI, T20I and IPL
+  matches: did the side batting second win, how many wickets in hand and
+  balls unused at the end, by date, season and tournament. `balls_remaining`
+  assumes the full scheduled overs (120 T20, 300 ODI) and is null for matches
+  decided by a rain method. Tests are excluded.
+
+`format` accepts `"Test"`, `"ODI"`, `"T20I"` (international T20), or `"IPL"`
+(case-insensitive); omit it to search across all four.
+
+**What this pack does not do:** it does not return individual deliveries
+(ball-by-ball). Every match file is parsed ball-by-ball once, at load time,
+and collapsed into match / innings / batting-card / bowling-card rows —
+storing every ball for ~11,000 matches would multiply the row count by
+roughly 150-200x for a question ("who scored what, who took which wickets")
+that the scorecard already answers.
+
+## Auth
+
+Keyless. The tools answer only through the Pipeworx gateway, which holds the
+data; a standalone `npm install` has no data to read, and every tool throws
+a clear "not bound in this runtime" error there instead of returning an
+empty list.
+
+## Data sources
+
+- Cricsheet — ball-by-ball match data for Test cricket, One Day
+  Internationals, T20 Internationals, and the Indian Premier League.
+  **Licence: ODC Attribution License (ODC-BY)** — free to share, adapt and
+  use (including commercially) with attribution to Cricsheet. Cricsheet
+  publishes bulk per-match files only (no live API), so this pack builds a
+  copy (`scripts/cricsheet/load-data.mjs`) into a D1 database rather than
+  proxying per request, per CLAUDE.md's "build the copy" rule for a
+  bulk-only source.
+
+### Known gaps — read before extending this pack
+
+**Only four of Cricsheet's ~60 competitions are loaded.** Cricsheet also
+publishes first-class, List A, and ~50 domestic T20 leagues (Big Bash, T20
+Blast, Pakistan Super League, Caribbean Premier League, The Hundred, and so
+on) as separate bulk files. This pack loads the four with the clearest
+cross-format demand (international Test/ODI/T20I plus the IPL, the league
+named explicitly in the originating demand signal). Adding another league is
+one more entry in `BULK_FILES` in the loader, using the same
+match-type-agnostic parser.
+
+**Women's matches are included wherever Cricsheet's own bulk file includes
+them**, distinguished by the `gender` field Cricsheet carries per match — not
+filtered out, not separately tooled.
+
+**Player identity is the raw name string Cricsheet uses** (e.g. "V Kohli",
+"SR Watson") — short forms, not full names, and this pack does not maintain
+its own name-to-person mapping beyond what `cricsheet_player_stats`'s
+substring match provides. Two different people sharing a short-form name
+(rare, but not impossible across ~8,400 distinct names) would merge under
+that string; nothing in Cricsheet's own files beyond the registry ID (not
+currently loaded) resolves that.
+
+**Super overs are stored as extra innings entries**, exactly as Cricsheet's
+own `innings` array represents them (a tied T20 can have 3 or 4 innings
+entries) — `cricsheet_match` returns whatever innings Cricsheet's file has,
+including super-over ones.
+
+### Refreshing or extending the data
+
+Re-run `node scripts/cricsheet/load-data.mjs` (needs `wrangler` logged in to
+the Pipeworx Cloudflare account, and `CLOUDFLARE_ACCOUNT_ID` set when more
+than one account is visible) — it re-fetches every format live and replaces
+every table (DROP + reload), because Cricsheet corrects historical files
+rather than versioning them. `--only <Test|ODI|T20I|IPL>` reloads a single
+format; `--dry-run` parses and prints counts without touching D1, useful
+after changing the parser. Cricsheet adds new matches continuously (for
+international and IPL cricket, typically within a day of the match); re-run
+the loader periodically to pick those up — `data_as_of` in every tool
+response names the load it is reading.
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "cricsheet": {
+      "url": "https://gateway.pipeworx.io/cricsheet/mcp"
+    }
+  }
+}
+```
+
+### What this endpoint actually serves
+
+`tools/list` at `https://gateway.pipeworx.io/cricsheet/mcp` returns the tools in the table
+above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
+`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
+gateway-wide set. So the tool count you see is larger than this table: a
+single-pack endpoint currently lists roughly 30 shared tools alongside the
+pack's own. The connection's `initialize` response states its exact scope, and
+is the authoritative answer for a given day.
+
+This is deliberate, not multiplexing by accident. The meta-tools are what let a
+scoped connection answer a question this pack does not cover — via
+`ask_pipeworx`, which routes across the whole catalog — without you adding a
+second MCP server. There is currently no way to mount a pack endpoint without
+them; if the extra schemas cost you more context than the routing is worth,
+connect to the full gateway once rather than to several pack endpoints.
+
+Or connect to the full Pipeworx gateway to get every pack's tools listed
+directly, instead of just this one's:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+Both URLs reach the same gateway and the same 1856+ data sources. The
+only difference is which pack's tools are listed **directly**; `ask_pipeworx`
+reaches all of them from either one.
+
+## No MCP client? Call it over HTTP
+
+```bash
+curl -X POST https://gateway.pipeworx.io/v1/tools/cricsheet_match \
+  -H 'Content-Type: application/json' \
+  -d '{"match_id":1082591}'
+```
+
+No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/cricsheet_match`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
+
+## Run it from npm
+
+`@pipeworx/mcp-cricsheet` is a local stdio bridge to the Pipeworx gateway: your MCP client
+starts it with `npx`, and it forwards every call to the same
+`https://gateway.pipeworx.io/cricsheet/mcp` endpoint shown above. It needs network access;
+there is no offline mode.
+
+```json
+{
+  "mcpServers": {
+    "cricsheet": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-cricsheet"]
+    }
+  }
+}
+```
+
+Without a key it calls anonymously, capped at 50 calls a day. A free account
+raises that to 200 a day: get a key at https://pipeworx.io/signup and add
+`"env": { "PIPEWORX_API_KEY": "<your key>" }` to the server entry.
+The key is sent as a Bearer token, the same way a hosted connection sends it,
+so calls are metered and billed exactly as they are there.
+
+It lists **only** this pack's tools by default. Set `PIPEWORX_META_TOOLS=1` to
+also list `ask_pipeworx` and the other gateway-wide tools.
+
+Behind an HTTPS proxy: Node's built-in `fetch` does not read `HTTPS_PROXY` by
+default. Newer Node releases honour it when `NODE_USE_ENV_PROXY=1` is set; check
+your Node version's documentation.
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English —
+this works on the pack endpoint above as well as on the full gateway:
+
+```
+ask_pipeworx({ question: "your question about Cricsheet data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [Docs and guides](https://pipeworx.io/docs)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Entry point for `npx @pipeworx/mcp-<slug>` in gateway mode (bin/cli.js).
+//
+// A stdio MCP server that relays every message to the Pipeworx gateway's
+// /<slug>/mcp endpoint -- fleet #3759, docs/standalone-via-gateway-plan.md.
+// It carries no pack code and has no local mode. The relay itself lives in
+// ../lib/index.js (copied from scripts/templates/standalone-gateway-lib.js);
+// this file only owns stdin/stdout.
+//
+// Copied VERBATIM into every gateway-mode package by scripts/publish-pack.sh.
+// Edit scripts/templates/standalone-gateway-cli.js in the monorepo, never a
+// per-pack copy. Zero dependencies, Node 18+.
+//
+// stdout carries newline-delimited JSON-RPC and nothing else; every diagnostic
+// goes to stderr, because a single stray line on stdout breaks the host's
+// parser.
+import { createInterface } from 'node:readline';
+import { relay, bridgeConfig } from '../lib/index.js';
+
+const cfg = bridgeConfig();
+const warn = (line) => process.stderr.write(`${line}\n`);
+const write = (msg) => { if (msg) process.stdout.write(`${JSON.stringify(msg)}\n`); };
+
+const pending = new Set();
+function track(p) {
+  pending.add(p);
+  p.finally(() => pending.delete(p));
+}
+
+async function handleLine(line) {
+  const text = line.trim();
+  if (!text) return;
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+    return;
+  }
+  // A JSON-RPC batch: relay each member, answer with the non-notification replies.
+  if (Array.isArray(message)) {
+    const replies = (await Promise.all(message.map((m) => relay(m, { cfg, warn })))).filter(Boolean);
+    if (replies.length) write(replies);
+    return;
+  }
+  write(await relay(message, { cfg, warn }));
+}
+
+// Requests are handled concurrently and answered as they finish: JSON-RPC ids
+// let the host match them, and a slow tool call must not hold up a ping.
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
+  track(handleLine(line).catch((err) => warn(`pipeworx-standalone: ${err && err.stack ? err.stack : err}`)));
+});
+rl.on('close', async () => {
+  // stdin closed: finish what is in flight, then exit.
+  while (pending.size) await Promise.allSettled([...pending]);
+  // Exit only once stdout has flushed: on a pipe that is not synchronous
+  // everywhere, and a bare exit can drop the last reply.
+  process.stdout.write('', () => process.exit(0));
+});

package/lib/index.js

@@ -0,0 +1,333 @@
+// @pipeworx/mcp-<slug> -- library half of the gateway bridge (lib/index.js).
+//
+// Copied VERBATIM into every gateway-mode pack package by scripts/publish-pack.sh
+// (fleet #3759, docs/standalone-via-gateway-plan.md section 1). There is no
+// per-pack templating: the slug and version are read from this package's own
+// package.json (`pipeworx.slug`, `version`) at load time, so the same bytes
+// ship in every package and the source hash can cover them once. Edit this
+// file in the monorepo (scripts/templates/standalone-gateway-lib.js), never a
+// per-pack copy.
+//
+// What it is: a relay. Every JSON-RPC message goes to
+// ${PIPEWORX_GATEWAY_URL:-https://gateway.pipeworx.io}/<slug>/mcp, the same
+// endpoint a hosted MCP client uses, so tiers, rate limits and credits apply
+// exactly as they do there. There is no local mode: the pack's code is not in
+// this package.
+//
+// Zero dependencies, plain ESM, Node 18+ (global fetch). Nothing here writes
+// to stdout -- bin/cli.js owns stdout and it carries JSON-RPC only.
+//
+// Environment:
+//   PIPEWORX_API_KEY      sent as `Authorization: Bearer <key>`. Never as
+//                         X-API-Key: the gateway reads a pwx_ key sent that way
+//                         as an unvalidated BYO string with no account.
+//   PIPEWORX_GATEWAY_URL  gateway base URL (no path), default the public gateway.
+//   PIPEWORX_META_TOOLS=1 list the gateway-wide tools (ask_pipeworx, ...) too.
+//   PIPEWORX_TIMEOUT_MS   per-request timeout, default 120000.
+
+import { readFileSync } from 'node:fs';
+
+const readJson = (rel) => JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+
+const PKG = readJson('../package.json');
+export const SLUG = PKG.pipeworx && PKG.pipeworx.slug;
+if (typeof SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries no valid pipeworx.slug -- this package was built wrong`);
+}
+/**
+ * The pack's slug on the GATEWAY: the /<slug>/mcp route and the `_meta.pack`
+ * every listed tool carries. Usually the same as `slug` (the npm/directory
+ * name), but 14 packs differ -- `hex-pm` is `hex_pm` on the gateway -- and
+ * filtering tools/list on the npm slug would match none of their tools
+ * (fleet #3761). publish-pack.sh stamps it from the gateway manifest.
+ */
+export const GATEWAY_SLUG = (PKG.pipeworx && PKG.pipeworx.gatewaySlug) || SLUG;
+if (typeof GATEWAY_SLUG !== 'string' || !/^[a-z0-9][a-z0-9_-]*$/.test(GATEWAY_SLUG)) {
+  throw new Error(`${PKG.name}: package.json carries an invalid pipeworx.gatewaySlug -- this package was built wrong`);
+}
+export const PACKAGE_NAME = PKG.name;
+export const VERSION = PKG.version;
+
+/** The pack's own tool definitions at publish time (the offline tools/list answer). */
+export const tools = readJson('../tools.json');
+
+const DEFAULT_GATEWAY = 'https://gateway.pipeworx.io';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGNUP_URL = 'https://pipeworx.io/signup';
+const VIA = '(via pipeworx-standalone)';
+
+/** Resolve the bridge's settings. Exported for the tests and for callTool. */
+export function bridgeConfig(env = process.env, overrides = {}) {
+  const base = String(overrides.gatewayUrl || env.PIPEWORX_GATEWAY_URL || DEFAULT_GATEWAY).trim().replace(/\/+$/, '');
+  const apiKey = String(overrides.apiKey ?? env.PIPEWORX_API_KEY ?? '').trim();
+  const t = Number(overrides.timeoutMs ?? env.PIPEWORX_TIMEOUT_MS);
+  return {
+    endpoint: `${base}/${GATEWAY_SLUG}/mcp`,
+    apiKey,
+    timeoutMs: Number.isFinite(t) && t > 0 ? t : DEFAULT_TIMEOUT_MS,
+    metaTools: (overrides.metaTools ?? env.PIPEWORX_META_TOOLS) === '1' || overrides.metaTools === true,
+  };
+}
+
+function requestHeaders(cfg) {
+  const h = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    // Stable per package version: the gateway remembers a client's name by
+    // identifier + User-Agent (workers/gateway/src/client-identity.ts).
+    'User-Agent': `pipeworx-standalone/${VERSION} (${PACKAGE_NAME})`,
+    // Analytics label only (blob11 = 'standalone'). It never changes tier,
+    // limits or price -- anyone can send it.
+    'X-Pipeworx-Surface': 'standalone',
+  };
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  return h;
+}
+
+/** Parse a gateway body: JSON, or the last JSON `data:` frame of an SSE stream. */
+function parseBody(text, contentType) {
+  if (/text\/event-stream/i.test(contentType || '')) {
+    let last = null;
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue;
+      try { last = JSON.parse(line.slice(5).trim()); } catch { /* keep-alive or partial frame */ }
+    }
+    return last;
+  }
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * POST one JSON-RPC message. Never throws: the outcome is one of
+ *   { kind: 'http', status, headers, body, text }   the gateway answered
+ *   { kind: 'network', detail }                      DNS, TLS, refused, reset
+ *   { kind: 'timeout' }                              no answer in cfg.timeoutMs
+ */
+export async function postToGateway(message, cfg) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), cfg.timeoutMs);
+  try {
+    const res = await fetch(cfg.endpoint, {
+      method: 'POST',
+      headers: requestHeaders(cfg),
+      body: JSON.stringify(message),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    return { kind: 'http', status: res.status, headers: res.headers, body: parseBody(text, res.headers.get('content-type')), text };
+  } catch (err) {
+    if (ac.signal.aborted || (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))) return { kind: 'timeout' };
+    const cause = err && err.cause;
+    const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
+    return { kind: 'network', detail };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── The key-not-accepted warning (one per process) ──────────────────
+
+let warnedKeyIgnored = false;
+const KEY_IGNORED = 'PIPEWORX_API_KEY was not accepted, calling anonymously.';
+
+/** True when a key was sent but the gateway still served the call as anonymous. */
+function keyIgnored(out, cfg) {
+  return !!cfg.apiKey && out.kind === 'http' && (out.headers.get('x-ratelimit-tier') || '').toLowerCase() === 'anonymous';
+}
+
+function noteTier(out, cfg, warn) {
+  if (!keyIgnored(out, cfg) || warnedKeyIgnored) return;
+  warnedKeyIgnored = true;
+  warn(`${PACKAGE_NAME}: ${KEY_IGNORED} Check the key at ${SIGNUP_URL}.`);
+}
+
+/** Test hook: forget that the warning was printed. */
+export function _resetWarnings() { warnedKeyIgnored = false; }
+
+// ── Results the host shows to the model ─────────────────────────────
+
+function errorResult(text, detail) {
+  const result = { content: [{ type: 'text', text }], isError: true };
+  if (detail) result._meta = { pipeworx_standalone: detail };
+  return result;
+}
+
+const rpcResult = (id, result) => ({ jsonrpc: '2.0', id, result });
+const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+function firstLine(text) {
+  const line = String(text || '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) || '(empty body)';
+  return line.length > 200 ? `${line.slice(0, 200)}...` : line;
+}
+
+function unreachableText(cfg, out) {
+  if (out.kind === 'timeout') {
+    return `The Pipeworx gateway at ${cfg.endpoint} did not answer within ${Math.round(cfg.timeoutMs / 1000)}s, so this call timed out. `
+      + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode. Try again; a call that keeps timing out is worth reporting.`;
+  }
+  return `Could not reach the Pipeworx gateway at ${cfg.endpoint} (${out.detail}). `
+    + `${PACKAGE_NAME} forwards every call to the Pipeworx gateway and has no local mode, so it needs network access.`;
+}
+
+function isAuthRequired(body) {
+  return !!body && (body.error_code === 'authentication_required'
+    || (body.error && body.error.data && body.error.data.reason === 'authentication_required'));
+}
+
+/** Map a tools/call outcome to the JSON-RPC response the host gets. */
+function toolsCallResponse(id, out, cfg) {
+  if (out.kind !== 'http') return rpcResult(id, errorResult(unreachableText(cfg, out), { reason: out.kind }));
+  const { status, body } = out;
+
+  // Anonymous daily cap: the gateway answers 401 with a JSON-RPC error whose
+  // message is the offer. Hosts often swallow protocol errors, so hand it over
+  // as a tool result the model actually reads.
+  if (status === 401 && isAuthRequired(body)) {
+    const data = (body.error && body.error.data) || {};
+    const parts = [body.error && body.error.message ? body.error.message : 'The anonymous daily allowance is used up.'];
+    if (data.resets_at) parts.push(`The anonymous allowance resets at ${data.resets_at}.`);
+    parts.push(cfg.apiKey
+      ? `${KEY_IGNORED} Check the key, or get a free one at ${SIGNUP_URL}.`
+      : `To keep going now, set PIPEWORX_API_KEY in this MCP server's environment; a free key is at ${SIGNUP_URL}.`);
+    return rpcResult(id, errorResult(parts.join('\n\n'), { status, reason: 'authentication_required', resets_at: data.resets_at ?? null }));
+  }
+
+  // A keyed tier over its cap: today the gateway answers 429 with a RESULT
+  // that has no isError, which reads as a success (fleet #3760). Mark it.
+  if (status === 429 && body && body.result && typeof body.result === 'object') {
+    const result = { ...body.result, isError: true };
+    if (cfg.apiKey && keyIgnored(out, cfg)) {
+      result.content = [...(Array.isArray(result.content) ? result.content : []), { type: 'text', text: KEY_IGNORED }];
+    }
+    return rpcResult(id, result);
+  }
+  if ((status === 401 || status === 429) && body && body.error) {
+    const extra = keyIgnored(out, cfg) ? ` ${KEY_IGNORED}` : '';
+    return rpcResult(id, errorResult(`${body.error.message || `HTTP ${status}`}${extra}`, { status }));
+  }
+
+  // A real JSON-RPC answer (result or protocol error): relay it verbatim,
+  // structuredContent and _meta (cost, tier, provenance) included.
+  if (body && body.jsonrpc === '2.0' && (body.result !== undefined || body.error !== undefined) && status < 500) {
+    return { ...body, id };
+  }
+
+  // 5xx, an HTML edge page, or anything else that is not JSON-RPC.
+  return rpcResult(id, errorResult(`The Pipeworx gateway returned HTTP ${status}: ${firstLine(out.text)}`, { status }));
+}
+
+function localInitialize(params) {
+  return {
+    protocolVersion: (params && params.protocolVersion) || '2025-06-18',
+    capabilities: { tools: {} },
+    serverInfo: { name: PACKAGE_NAME, version: VERSION },
+  };
+}
+
+const scopedInstructions = () =>
+  `${PACKAGE_NAME} forwards to the Pipeworx gateway and lists only the ${SLUG} pack's tools. `
+  + 'Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.';
+
+/** `<host name> (via pipeworx-standalone)`. The slug stays OUT of the name: the
+ *  gateway's scanner-name check substring-matches words like poll/watch/index. */
+export function bridgedClientName(name) {
+  const n = typeof name === 'string' && name.trim() ? name.trim() : 'unknown';
+  return n.includes(VIA) ? n : `${n} ${VIA}`;
+}
+
+/**
+ * Relay one JSON-RPC message to the gateway and return the response to write
+ * back, or null for a notification. Never throws.
+ *
+ * @param {object} message  a parsed JSON-RPC request or notification
+ * @param {{cfg?: object, warn?: (line: string) => void}} [opts]
+ */
+export async function relay(message, opts = {}) {
+  const cfg = opts.cfg || bridgeConfig();
+  const warn = opts.warn || ((line) => process.stderr.write(`${line}\n`));
+  if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+    const id = message && typeof message === 'object' && 'id' in message ? message.id : null;
+    return rpcError(id ?? null, -32600, 'Invalid Request');
+  }
+  const isNotification = !('id' in message) || message.id === undefined;
+  const id = message.id;
+
+  if (isNotification) {
+    const out = await postToGateway(message, cfg);
+    if (out.kind !== 'http') warn(`${PACKAGE_NAME}: notification ${message.method} not delivered: ${unreachableText(cfg, out)}`);
+    return null;
+  }
+
+  if (message.method === 'initialize') {
+    const params = { ...(message.params || {}) };
+    params.clientInfo = { ...(params.clientInfo || {}), name: bridgedClientName(params.clientInfo && params.clientInfo.name) };
+    if (!params.clientInfo.version) params.clientInfo.version = '0';
+    const out = await postToGateway({ ...message, params }, cfg);
+    noteTier(out, cfg, warn);
+    if (out.kind === 'http' && out.body && out.body.result && typeof out.body.result === 'object') {
+      const result = { ...out.body.result, serverInfo: { name: PACKAGE_NAME, version: VERSION } };
+      if (!cfg.metaTools) result.instructions = scopedInstructions();
+      return rpcResult(id, result);
+    }
+    // The host must still start: answer locally and let the calls report the
+    // gateway problem when they happen.
+    warn(`${PACKAGE_NAME}: initialize answered locally -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    return rpcResult(id, { ...localInitialize(message.params), instructions: scopedInstructions() });
+  }
+
+  if (message.method === 'tools/list') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    const listed = out.kind === 'http' && out.body && out.body.result && Array.isArray(out.body.result.tools)
+      ? out.body.result : null;
+    if (listed) {
+      if (cfg.metaTools) return rpcResult(id, listed);
+      const own = listed.tools.filter((t) => t && t._meta && (t._meta.pack === GATEWAY_SLUG || t._meta.pack === SLUG));
+      if (own.length > 0) return rpcResult(id, { ...listed, tools: own });
+      warn(`${PACKAGE_NAME}: the gateway listed no ${SLUG} tools; serving the tool list bundled with this package`);
+    } else {
+      warn(`${PACKAGE_NAME}: tools/list served from the snapshot bundled with this package -- ${out.kind === 'http' ? `gateway HTTP ${out.status}` : unreachableText(cfg, out)}`);
+    }
+    return rpcResult(id, { tools });
+  }
+
+  if (message.method === 'tools/call') {
+    const out = await postToGateway(message, cfg);
+    noteTier(out, cfg, warn);
+    return toolsCallResponse(id, out, cfg);
+  }
+
+  // Everything else (ping, resources/*, prompts/*, ...): relay as-is.
+  const out = await postToGateway(message, cfg);
+  noteTier(out, cfg, warn);
+  if (out.kind === 'http' && out.body && out.body.jsonrpc === '2.0') return { ...out.body, id };
+  if (message.method === 'ping') return rpcResult(id, {});
+  return rpcError(id, -32603, out.kind === 'http'
+    ? `The Pipeworx gateway returned HTTP ${out.status}: ${firstLine(out.text)}`
+    : unreachableText(cfg, out));
+}
+
+/**
+ * Call one of this pack's tools through the gateway -- the `{tools, callTool}`
+ * shape earlier versions of this package exported. Resolves with the tool's
+ * structured result; rejects with the gateway's message on any error.
+ *
+ * @param {string} name
+ * @param {Record<string, unknown>} [args]
+ * @param {{apiKey?: string, gatewayUrl?: string, timeoutMs?: number}} [opts]
+ *        apiKey defaults to process.env.PIPEWORX_API_KEY.
+ */
+export async function callTool(name, args = {}, opts = {}) {
+  const cfg = bridgeConfig(process.env, opts);
+  const res = await relay({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }, { cfg });
+  if (res.error) throw new Error(res.error.message);
+  const result = res.result || {};
+  const text = Array.isArray(result.content)
+    ? result.content.filter((c) => c && c.type === 'text').map((c) => c.text).join('\n')
+    : '';
+  if (result.isError) throw new Error(text || `${name} failed`);
+  if (result.structuredContent !== undefined) return result.structuredContent;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export default { tools, callTool };

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pipeworx/mcp-cricsheet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "cricsheet -- ball-by-ball cricket data collapsed to match / player / team questions (fleet #2975).",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./tools.json": "./tools.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "mcp-cricsheet": "bin/cli.js"
+  },
+  "files": ["bin/", "lib/", "tools.json", "server.json"],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "cricsheet"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-cricsheet.git"
+  },
+  "mcpName": "io.github.pipeworx-io/cricsheet",
+  "pipeworx": {
+    "mode": "gateway",
+    "slug": "cricsheet",
+    "gatewaySlug": "cricsheet",
+    "sourceHash": "v1-2548fdf5bbdcc80b9040c95bd186cf1bea0ef4bb2bfa1445a893196cef88e6b2",
+    "sourceCommit": "0b3faaa4d85299a961dd86dea75a0f0e1dad280c"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/cricsheet",
+  "title": "Cricsheet",
+  "description": "cricsheet -- ball-by-ball cricket data collapsed to match / player / team questions (fleet #2975).",
+  "version": "0.2.0",
+  "websiteUrl": "https://pipeworx.io/packs/cricsheet",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-cricsheet",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/cricsheet/mcp"
+    }
+  ]
+}

package/tools.json

@@ -0,0 +1,182 @@
+[
+  {
+    "name": "cricsheet_match",
+    "description": "Full result and scorecard for one cricket match: teams, venue, date, toss, result, and for every innings the batting card (each batter's runs/balls/4s/6s/how out) and bowling card (each bowler's overs/runs/wickets). Covers Test, ODI and T20 International cricket plus the IPL (Cricsheet, ODC-BY). Use cricsheet_find_matches first to get a match_id if you don't already have one.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "match_id": {
+          "type": "number",
+          "description": "Cricsheet match id, e.g. 1082591. Get one from cricsheet_find_matches."
+        }
+      },
+      "required": [
+        "match_id"
+      ]
+    }
+  },
+  {
+    "name": "cricsheet_player_stats",
+    "description": "A cricketer's career batting and bowling aggregates (matches, runs, average, strike rate, 100s/50s; wickets, bowling average, economy) from Cricsheet's Test/ODI/T20I/IPL match data. Pass a name or partial name (\"Kohli\", \"V Kohli\") -- Cricsheet stores short-form names, so this matches case-insensitively and returns a candidate list if the name is ambiguous. Optionally scope to one format with `format`. Covers only matches Cricsheet has scored ball-by-ball, not a player's entire career.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "player": {
+          "type": "string",
+          "description": "Player name or partial name, e.g. \"Kohli\" or \"V Kohli\"."
+        },
+        "format": {
+          "type": "string",
+          "description": "Match format: \"Test\", \"ODI\", \"T20I\" (international T20), or \"IPL\". Omit to search across every format this pack holds."
+        }
+      },
+      "required": [
+        "player"
+      ]
+    }
+  },
+  {
+    "name": "cricsheet_head_to_head",
+    "description": "Head-to-head record between two cricket teams from Cricsheet's Test/ODI/T20I/IPL match data: total matches, each team's wins, ties/no-results, and the most recent matches with their results. Pass team names as Cricsheet uses them, e.g. \"India\", \"Australia\", \"Mumbai Indians\" (IPL). Optionally scope to one format with `format`.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "team_a": {
+          "type": "string",
+          "description": "First team name, e.g. \"India\"."
+        },
+        "team_b": {
+          "type": "string",
+          "description": "Second team name, e.g. \"Australia\"."
+        },
+        "format": {
+          "type": "string",
+          "description": "Match format: \"Test\", \"ODI\", \"T20I\" (international T20), or \"IPL\". Omit to search across every format this pack holds."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max recent matches to list, 1-100. Default 10."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Pagination offset into the recent-matches list. Default 0."
+        }
+      },
+      "required": [
+        "team_a",
+        "team_b"
+      ]
+    }
+  },
+  {
+    "name": "cricsheet_find_matches",
+    "description": "Search Cricsheet's Test/ODI/T20I/IPL match index by team, format, season, venue and/or player, returning match_id plus date/teams/venue/result for each hit -- use this to discover match_ids for cricsheet_match. With no filters, returns the most recent matches across every format. Provide at least one filter to narrow a specific search.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "team": {
+          "type": "string",
+          "description": "Team name, e.g. \"England\" or \"Chennai Super Kings\" (IPL)."
+        },
+        "format": {
+          "type": "string",
+          "description": "Match format: \"Test\", \"ODI\", \"T20I\" (international T20), or \"IPL\". Omit to search across every format this pack holds."
+        },
+        "season": {
+          "type": "string",
+          "description": "Season label as Cricsheet records it, e.g. \"2023\" or \"2007/08\"."
+        },
+        "venue": {
+          "type": "string",
+          "description": "Venue name or partial venue name, e.g. \"Lord's\"."
+        },
+        "player": {
+          "type": "string",
+          "description": "Exact player name as Cricsheet stores it (see cricsheet_player_stats to resolve a partial name first)."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max matches to return, 1-200. Default 50."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Pagination offset. Default 0."
+        }
+      }
+    }
+  },
+  {
+    "name": "cricsheet_chase_search",
+    "description": "Compound cricket match search on the second innings (the chase): filter limited-overs matches (ODI, T20I, IPL) by whether the side batting second won or lost, wickets remaining and balls remaining at the end of the chase, date range, season, tournament/event, team, gender and format. Each hit returns target, chase score, wickets lost, balls used, wickets_remaining (10 minus wickets lost) and balls_remaining (scheduled overs minus legal balls bowled; null for rain-affected matches decided by a method such as DLS). Example: T20I chases won with 5+ wickets and 10+ balls to spare since 2024. Source: Cricsheet match data (ODC-BY). Tests are excluded.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "second_innings_result": {
+          "type": "string",
+          "enum": [
+            "won",
+            "lost",
+            "any"
+          ],
+          "description": "Did the side batting second win? Default \"won\" (a successful chase)."
+        },
+        "format": {
+          "type": "string",
+          "description": "Match format: \"ODI\", \"T20I\" or \"IPL\". Omit for all three."
+        },
+        "min_wickets_remaining": {
+          "type": "number",
+          "description": "Chasing side had at least this many wickets in hand at the end (0-10)."
+        },
+        "max_wickets_remaining": {
+          "type": "number",
+          "description": "Chasing side had at most this many wickets in hand at the end (0-10)."
+        },
+        "min_balls_remaining": {
+          "type": "number",
+          "description": "At least this many legal balls unused at the end of the chase (assumes full scheduled overs; 120 in T20, 300 in ODI)."
+        },
+        "max_balls_remaining": {
+          "type": "number",
+          "description": "At most this many legal balls unused (0 = chase went to the last ball)."
+        },
+        "team": {
+          "type": "string",
+          "description": "Chasing team name as Cricsheet uses it, e.g. \"India\"."
+        },
+        "gender": {
+          "type": "string",
+          "enum": [
+            "male",
+            "female"
+          ],
+          "description": "Men's or women's cricket."
+        },
+        "season": {
+          "type": "string",
+          "description": "Season label, e.g. \"2024\" or \"2023/24\"."
+        },
+        "event": {
+          "type": "string",
+          "description": "Tournament/event name or fragment, e.g. \"World Cup\" or \"Indian Premier League\"."
+        },
+        "date_from": {
+          "type": "string",
+          "description": "Earliest match date, YYYY-MM-DD."
+        },
+        "date_to": {
+          "type": "string",
+          "description": "Latest match date, YYYY-MM-DD."
+        },
+        "limit": {
+          "type": "number",
+          "description": "Max matches to return, 1-200. Default 25."
+        },
+        "offset": {
+          "type": "number",
+          "description": "Pagination offset. Default 0."
+        }
+      }
+    }
+  }
+]