@pipeworx/mcp-cricsheet 0.0.0-stage → 0.1.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,202 @@
-# 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 1784+ 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.
+
+`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 1784+ 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":"..."}`.
+
+## Standalone (no gateway account)
+
+This package also runs as a local stdio MCP server — no Pipeworx account, no
+gateway round-trip:
+
+```json
+{
+  "mcpServers": {
+    "cricsheet": {
+      "command": "npx",
+      "args": ["-y", "@pipeworx/mcp-cricsheet"]
+    }
+  }
+}
+```
+
+Or run it directly to confirm it starts:
+
+```bash
+npx -y @pipeworx/mcp-cricsheet
+```
+
+It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
+for **only** this pack's tools — none of the shared meta-tools the gateway
+connection above adds. Same source, same tools, no ask_pipeworx routing.
+
+## 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,17 @@
+#!/usr/bin/env node
+//
+// Entry point for `npx @pipeworx/mcp-<slug>`.
+//
+// Packs ship as raw TypeScript (no build step — see publish-pack.sh for why:
+// tsx sidesteps every extensionless-import / bare-JSON-import edge case a
+// per-pack tsc build would have to solve one pack at a time). This file
+// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
+// which wraps the pack's {tools, callTool} export in a stdio MCP server.
+//
+// Copied verbatim into every published pack repo by scripts/publish-pack.sh —
+// edit this file, not a per-pack copy.
+import { register } from 'tsx/esm/api';
+
+register();
+
+await import('../src/server.ts');

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@pipeworx/mcp-cricsheet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "cricsheet -- ball-by-ball cricket data collapsed to match / player / team questions (fleet #2975).",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "mcp-cricsheet": "bin/cli.js"
+  },
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "cricsheet"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pipeworx-io/mcp-cricsheet.git"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@cloudflare/workers-types": "^4.20260405.1"
+  },
+  "pipeworx": {
+    "sourceHash": "v1-a408bcb18921b17d5b636ede895773b52861f20e397029fca5407c02b9210876",
+    "sourceCommit": "3723e46c6d115bd4a1fd2175e6bf758555e7cb50"
+  }
+}

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.1.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/src/index.ts

@@ -0,0 +1,423 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  /** Human-facing one-liner (fleet #1967). Optional; consumers fall back to
+   *  description. Kept in step with shared/src/types.ts — scripts/lib/
+   *  check-inlined-types.mjs reports drift at publish time. */
+  summary?: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    anyOf?: Array<{ required: string[] }>;
+    oneOf?: Array<{ required: string[] }>;
+    allOf?: Array<{ required: string[] }>;
+  };
+  outputSchema?: Record<string, unknown>;
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * cricsheet -- ball-by-ball cricket data collapsed to match / player / team
+ * questions (fleet #2975).
+ *
+ * Data: Cricsheet (cricsheet.org) -- per-match JSON files for Test, One Day
+ * International and Twenty20 International cricket plus the Indian Premier
+ * League (ODC Attribution License, ODC-BY; attribution: Cricsheet). Cricsheet
+ * publishes bulk files only, so this pack builds a copy
+ * (scripts/cricsheet/load-data.mjs) into a D1 database the gateway hands it
+ * as `_d1` (pack-manifest "d1Binding": "CRICSHEET_DB"). Design note: this
+ * file + store.ts.
+ *
+ * Every match file is parsed ball-by-ball IN THE LOADER and collapsed to
+ * match, innings, and batting/bowling scorecard rows -- individual
+ * deliveries are not stored or served (CLAUDE.md "prefer the smallest store
+ * that answers the tool questions; do not store every ball if aggregates
+ * answer the questions").
+ *
+ * Every response carries `source`, `source_url`, `license` and `data_as_of`.
+ */
+import {
+  battingAggregate,
+  bowlingAggregate,
+  dataAsOf,
+  findMatches,
+  findMatchesCount,
+  getBattingCards,
+  getBowlingCards,
+  getInnings,
+  getMatch,
+  headToHeadCount,
+  headToHeadMatches,
+  requireDb,
+  resolveFormat,
+  resolvePlayer,
+  type D1Like,
+  type Format,
+} from './store.js';
+
+const SOURCE = 'Cricsheet, ball-by-ball cricket match data';
+const SOURCE_URL = 'https://cricsheet.org';
+const LICENSE = 'ODC-BY (Open Data Commons Attribution License); attribution: Cricsheet';
+
+const FORMAT_DESC = 'Match format: "Test", "ODI", "T20I" (international T20), or "IPL". Omit to search across every format this pack holds.';
+
+const tools: McpToolExport['tools'] = [
+  {
+    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.',
+    summary: "One match's full result and batting/bowling scorecards by match_id.",
+    inputSchema: {
+      type: 'object' as const,
+      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.',
+    summary: "A cricketer's batting/bowling career aggregates, optionally scoped to one format.",
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        player: { type: 'string', description: 'Player name or partial name, e.g. "Kohli" or "V Kohli".' },
+        format: { type: 'string', description: FORMAT_DESC },
+      },
+      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`.',
+    summary: 'Win/loss head-to-head record between two teams, optionally scoped to one format.',
+    inputSchema: {
+      type: 'object' as const,
+      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: FORMAT_DESC },
+        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.',
+    summary: 'Search matches by team/format/season/venue/player to get match_ids.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        team: { type: 'string', description: 'Team name, e.g. "England" or "Chennai Super Kings" (IPL).' },
+        format: { type: 'string', description: FORMAT_DESC },
+        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.' },
+      },
+    },
+  },
+];
+
+function clampInt(v: unknown, lo: number, hi: number, d: number): number {
+  const n = Math.floor(Number(v));
+  return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : d;
+}
+function str(v: unknown): string | null {
+  return v != null && v !== '' ? String(v).trim() : null;
+}
+
+function serializeMatch(m: {
+  match_id: number;
+  format: string;
+  gender: string;
+  team1: string;
+  team2: string;
+  match_date: string;
+  season: string | null;
+  venue: string | null;
+  city: string | null;
+  event_name: string | null;
+  toss_winner: string | null;
+  toss_decision: string | null;
+  outcome_winner: string | null;
+  outcome_by_runs: number | null;
+  outcome_by_wickets: number | null;
+  outcome_by_innings: number | null;
+  outcome_method: string | null;
+  result: string | null;
+  player_of_match: string | null;
+}) {
+  return {
+    match_id: m.match_id,
+    format: m.format,
+    gender: m.gender,
+    team1: m.team1,
+    team2: m.team2,
+    match_date: m.match_date,
+    season: m.season,
+    venue: m.venue,
+    city: m.city,
+    event: m.event_name,
+    toss: m.toss_winner ? { winner: m.toss_winner, decision: m.toss_decision } : null,
+    outcome: {
+      winner: m.outcome_winner,
+      by_runs: m.outcome_by_runs,
+      by_wickets: m.outcome_by_wickets,
+      by_innings: m.outcome_by_innings === 1,
+      method: m.outcome_method,
+      result: m.result,
+    },
+    player_of_match: m.player_of_match,
+  };
+}
+
+async function cricsheetMatchTool(db: D1Like, args: Record<string, unknown>) {
+  const asOf = await dataAsOf(db);
+  const matchId = Math.floor(Number(args.match_id));
+  if (!Number.isFinite(matchId)) {
+    return { found: false, reason: 'invalid_match_id', message: 'match_id must be a number.', data_as_of: asOf };
+  }
+  const match = await getMatch(db, matchId);
+  if (!match) {
+    return {
+      found: false,
+      reason: 'not_found',
+      match_id: matchId,
+      message: `No match held with match_id=${matchId}.`,
+      hint: 'Call cricsheet_find_matches to search by team/format/season/venue and get a valid match_id.',
+      data_as_of: asOf,
+    };
+  }
+  const [innings, batting, bowling] = await Promise.all([getInnings(db, matchId), getBattingCards(db, matchId), getBowlingCards(db, matchId)]);
+  const inningsOut = innings.map((inn) => ({
+    innings: inn.innings_num,
+    batting_team: inn.batting_team,
+    total_runs: inn.total_runs,
+    total_wickets: inn.total_wickets,
+    overs: `${Math.floor(inn.legal_balls / 6)}.${inn.legal_balls % 6}`,
+    batting_card: batting
+      .filter((b) => b.innings_num === inn.innings_num)
+      .map((b) => ({
+        position: b.position,
+        player: b.player,
+        runs: b.runs,
+        balls: b.balls,
+        fours: b.fours,
+        sixes: b.sixes,
+        not_out: b.not_out === 1,
+        dismissal: b.not_out === 1 ? 'not out' : b.dismissal_kind ? `${b.dismissal_kind}${b.dismissal_bowler ? ` b ${b.dismissal_bowler}` : ''}` : null,
+      })),
+    bowling_card: bowling
+      .filter((b) => b.innings_num === inn.innings_num)
+      .map((b) => ({
+        order: b.order_num,
+        player: b.player,
+        overs: `${Math.floor(b.balls / 6)}.${b.balls % 6}`,
+        runs_conceded: b.runs_conceded,
+        wickets: b.wickets,
+        economy: b.balls > 0 ? Math.round((b.runs_conceded / (b.balls / 6)) * 100) / 100 : null,
+      })),
+  }));
+  return {
+    found: true,
+    ...serializeMatch(match),
+    innings: inningsOut,
+    source: SOURCE,
+    source_url: SOURCE_URL,
+    license: LICENSE,
+    data_as_of: asOf,
+  };
+}
+
+async function cricsheetPlayerStatsTool(db: D1Like, args: Record<string, unknown>) {
+  const asOf = await dataAsOf(db);
+  const query = str(args.player);
+  if (!query) {
+    return { found: false, reason: 'missing_player', message: 'player is required.', data_as_of: asOf };
+  }
+  let format: Format | null = null;
+  if (args.format != null && args.format !== '') {
+    format = resolveFormat(args.format);
+    if (!format) {
+      return { found: false, reason: 'unknown_format', message: `${JSON.stringify(args.format)} is not a recognized format. Use "Test", "ODI", "T20I", or "IPL".`, data_as_of: asOf };
+    }
+  }
+  const { resolved, candidates } = await resolvePlayer(db, query);
+  if (!resolved) {
+    if (!candidates.length) {
+      return {
+        found: false,
+        reason: 'no_match',
+        message: `No player matching ${JSON.stringify(query)} held in this pack.`,
+        hint: 'Cricsheet uses short-form names (e.g. "V Kohli", "SR Watson") -- try a surname or a shorter fragment.',
+        data_as_of: asOf,
+      };
+    }
+    return {
+      found: false,
+      reason: 'ambiguous',
+      message: `${JSON.stringify(query)} matches ${candidates.length} players.`,
+      candidates: candidates.map((c) => ({ player: c.player, matches: c.matches })),
+      hint: 'Call again with the exact player string from candidates.',
+      data_as_of: asOf,
+    };
+  }
+  const [batting, bowling] = await Promise.all([battingAggregate(db, resolved, format), bowlingAggregate(db, resolved, format)]);
+  if (batting.innings === 0 && bowling.innings === 0) {
+    return {
+      found: false,
+      reason: 'no_data_for_format',
+      player: resolved,
+      format: format ?? 'all',
+      message: `${resolved} has no ${format ?? 'Cricsheet'} innings held in this pack.`,
+      hint: format ? 'Try again without format to search across every format.' : undefined,
+      data_as_of: asOf,
+    };
+  }
+  return {
+    found: true,
+    player: resolved,
+    format: format ?? 'all',
+    batting,
+    bowling,
+    source: SOURCE,
+    source_url: SOURCE_URL,
+    license: LICENSE,
+    data_as_of: asOf,
+  };
+}
+
+async function cricsheetHeadToHeadTool(db: D1Like, args: Record<string, unknown>) {
+  const asOf = await dataAsOf(db);
+  const teamA = str(args.team_a);
+  const teamB = str(args.team_b);
+  if (!teamA || !teamB) {
+    return { found: false, reason: 'missing_team', message: 'team_a and team_b are both required.', data_as_of: asOf };
+  }
+  let format: Format | null = null;
+  if (args.format != null && args.format !== '') {
+    format = resolveFormat(args.format);
+    if (!format) {
+      return { found: false, reason: 'unknown_format', message: `${JSON.stringify(args.format)} is not a recognized format. Use "Test", "ODI", "T20I", or "IPL".`, data_as_of: asOf };
+    }
+  }
+  const limit = clampInt(args.limit, 1, 100, 10);
+  const offset = Math.max(0, Math.floor(Number(args.offset) || 0));
+  const filter = { team_a: teamA, team_b: teamB, format, limit, offset };
+  const [rows, total] = await Promise.all([headToHeadMatches(db, filter), headToHeadCount(db, filter)]);
+  if (!total) {
+    return {
+      found: false,
+      reason: 'no_match',
+      team_a: teamA,
+      team_b: teamB,
+      format: format ?? 'all',
+      message: `No matches held between ${teamA} and ${teamB}${format ? ` in ${format}` : ''}.`,
+      hint: 'Check team spelling (Cricsheet uses full names, e.g. "India" not "IND") or call cricsheet_find_matches with team= to see what is held.',
+      data_as_of: asOf,
+    };
+  }
+  let winsA = 0, winsB = 0, ties = 0, noResult = 0;
+  for (const m of rows) {
+    if (m.result === 'tie') ties++;
+    else if (m.result) noResult++;
+    else if (m.outcome_winner && m.outcome_winner.toLowerCase() === teamA.toLowerCase()) winsA++;
+    else if (m.outcome_winner && m.outcome_winner.toLowerCase() === teamB.toLowerCase()) winsB++;
+  }
+  const truncated = rows.length < total;
+  return {
+    found: true,
+    team_a: teamA,
+    team_b: teamB,
+    format: format ?? 'all',
+    total_matching: total,
+    returned: rows.length,
+    truncated,
+    ...(truncated ? { hint: 'More matches exist than were returned (recent-matches list only). Page with limit/offset.' } : {}),
+    recent_matches_summary: { wins_in_returned_set: { [teamA]: winsA, [teamB]: winsB }, ties, no_result_or_draw: noResult },
+    recent_matches: rows.map(serializeMatch),
+    source: SOURCE,
+    source_url: SOURCE_URL,
+    license: LICENSE,
+    data_as_of: asOf,
+  };
+}
+
+async function cricsheetFindMatchesTool(db: D1Like, args: Record<string, unknown>) {
+  const asOf = await dataAsOf(db);
+  let format: Format | null = null;
+  if (args.format != null && args.format !== '') {
+    format = resolveFormat(args.format);
+    if (!format) {
+      return { found: false, reason: 'unknown_format', message: `${JSON.stringify(args.format)} is not a recognized format. Use "Test", "ODI", "T20I", or "IPL".`, data_as_of: asOf };
+    }
+  }
+  const limit = clampInt(args.limit, 1, 200, 50);
+  const offset = Math.max(0, Math.floor(Number(args.offset) || 0));
+  const filter = {
+    team: str(args.team) ?? undefined,
+    format,
+    season: str(args.season) ?? undefined,
+    venue: str(args.venue) ?? undefined,
+    player: str(args.player) ?? undefined,
+    limit,
+    offset,
+  };
+  const [rows, total] = await Promise.all([findMatches(db, filter), findMatchesCount(db, filter)]);
+  if (!total) {
+    return {
+      found: false,
+      reason: 'no_match',
+      message: 'No matches held matching those filters.',
+      hint: 'Loosen a filter -- venue is substring-matched, but team/season/player require the exact string Cricsheet uses.',
+      data_as_of: asOf,
+    };
+  }
+  const truncated = rows.length < total;
+  return {
+    found: true,
+    total_matching: total,
+    returned: rows.length,
+    truncated,
+    ...(truncated ? { hint: 'More matches exist than were returned. Narrow with team/format/season/venue/player, or page with limit/offset.' } : {}),
+    matches: rows.map(serializeMatch),
+    source: SOURCE,
+    source_url: SOURCE_URL,
+    license: LICENSE,
+    data_as_of: asOf,
+  };
+}
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const bound = requireDb(args._d1);
+  switch (name) {
+    case 'cricsheet_match':
+      return cricsheetMatchTool(bound, args);
+    case 'cricsheet_player_stats':
+      return cricsheetPlayerStatsTool(bound, args);
+    case 'cricsheet_head_to_head':
+      return cricsheetHeadToHeadTool(bound, args);
+    case 'cricsheet_find_matches':
+      return cricsheetFindMatchesTool(bound, args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/src/server.ts

@@ -0,0 +1,48 @@
+/**
+ * Stdio MCP server entry point for @pipeworx/mcp-cricsheet.
+ * Generated by scripts/publish-pack.sh — do not hand-edit in the pack repo;
+ * edit scripts/publish-pack.sh (the server.ts heredoc) and republish instead.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import pack from './index.js';
+
+
+const server = new Server(
+  { name: '@pipeworx/mcp-cricsheet', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: pack.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    const callArgs = { ...((args ?? {}) as Record<string, unknown>) };
+    
+    const result = await pack.callTool(name, callArgs);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal error running server:', err);
+  process.exit(1);
+});

package/src/store.ts

@@ -0,0 +1,372 @@
+/**
+ * Reads for cricsheet (fleet #2975).
+ *
+ * Data: Cricsheet (cricsheet.org) -- per-match ball-by-ball JSON files for
+ * Test, ODI and T20 International cricket plus the Indian Premier League
+ * (ODC Attribution License, ODC-BY). Cricsheet publishes bulk files only, so
+ * this pack builds a copy (scripts/cricsheet/load-data.mjs) into a D1
+ * database the gateway hands it as `_d1` (pack-manifest "d1Binding":
+ * "CRICSHEET_DB"). Each match file is parsed ball-by-ball IN THE LOADER and
+ * collapsed to match / innings / batting-card / bowling-card rows --
+ * individual deliveries are never stored, per CLAUDE.md "prefer the
+ * smallest store that answers the tool questions."
+ *
+ * Design note: this file + index.ts.
+ */
+
+/** The slice of Cloudflare's D1Database this pack uses, declared here so the
+ *  pack needs no workers-types and a test can pass a node:sqlite stub. */
+export interface D1Like {
+  prepare(sql: string): D1StmtLike;
+}
+export interface D1StmtLike {
+  bind(...values: unknown[]): D1StmtLike;
+  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+
+export class StoreUnavailableError extends Error {
+  constructor() {
+    super(
+      'cricsheet: the match store is not bound in this runtime (no _d1). These tools only answer through the Pipeworx gateway; a standalone install has no data to read.',
+    );
+    this.name = 'StoreUnavailableError';
+  }
+}
+export function requireDb(d1: unknown): D1Like {
+  if (!d1 || typeof (d1 as D1Like).prepare !== 'function') throw new StoreUnavailableError();
+  return d1 as D1Like;
+}
+
+export const FORMATS = ['Test', 'ODI', 'T20I', 'IPL'] as const;
+export type Format = (typeof FORMATS)[number];
+
+export function resolveFormat(input: unknown): Format | null {
+  if (input == null || input === '') return null;
+  const s = String(input).trim().toUpperCase();
+  const map: Record<string, Format> = {
+    TEST: 'Test', TESTS: 'Test',
+    ODI: 'ODI', ODIS: 'ODI', 'ONE DAY INTERNATIONAL': 'ODI', 'ONE-DAY INTERNATIONAL': 'ODI',
+    T20I: 'T20I', T20IS: 'T20I', T20: 'T20I', 'T20 INTERNATIONAL': 'T20I', 'T20 INTERNATIONALS': 'T20I',
+    IPL: 'IPL', 'INDIAN PREMIER LEAGUE': 'IPL',
+  };
+  return map[s] ?? null;
+}
+
+export async function dataAsOf(db: D1Like): Promise<string | null> {
+  const r = await db.prepare(`SELECT value FROM cricsheet_meta WHERE key = 'loaded_at'`).first<{ value: string }>();
+  return r?.value ?? null;
+}
+
+export interface MatchRow {
+  match_id: number;
+  format: string;
+  gender: string;
+  team1: string;
+  team2: string;
+  match_date: string;
+  season: string | null;
+  venue: string | null;
+  city: string | null;
+  event_name: string | null;
+  toss_winner: string | null;
+  toss_decision: string | null;
+  outcome_winner: string | null;
+  outcome_by_runs: number | null;
+  outcome_by_wickets: number | null;
+  outcome_by_innings: number | null;
+  outcome_method: string | null;
+  result: string | null;
+  player_of_match: string | null;
+}
+
+export async function getMatch(db: D1Like, matchId: number): Promise<MatchRow | null> {
+  return db
+    .prepare(
+      `SELECT match_id, format, gender, team1, team2, match_date, season, venue, city, event_name,
+              toss_winner, toss_decision, outcome_winner, outcome_by_runs, outcome_by_wickets,
+              outcome_by_innings, outcome_method, result, player_of_match
+       FROM matches WHERE match_id = ?`,
+    )
+    .bind(matchId)
+    .first<MatchRow>();
+}
+
+export interface InningsRow {
+  innings_num: number;
+  batting_team: string;
+  total_runs: number;
+  total_wickets: number;
+  legal_balls: number;
+}
+export async function getInnings(db: D1Like, matchId: number): Promise<InningsRow[]> {
+  const r = await db
+    .prepare(`SELECT innings_num, batting_team, total_runs, total_wickets, legal_balls FROM innings WHERE match_id = ? ORDER BY innings_num`)
+    .bind(matchId)
+    .all<InningsRow>();
+  return r.results;
+}
+
+export interface BattingCardRow {
+  innings_num: number;
+  position: number;
+  player: string;
+  runs: number;
+  balls: number;
+  fours: number;
+  sixes: number;
+  not_out: number;
+  dismissal_kind: string | null;
+  dismissal_bowler: string | null;
+}
+export async function getBattingCards(db: D1Like, matchId: number): Promise<BattingCardRow[]> {
+  const r = await db
+    .prepare(
+      `SELECT innings_num, position, player, runs, balls, fours, sixes, not_out, dismissal_kind, dismissal_bowler
+       FROM batting_cards WHERE match_id = ? ORDER BY innings_num, position`,
+    )
+    .bind(matchId)
+    .all<BattingCardRow>();
+  return r.results;
+}
+
+export interface BowlingCardRow {
+  innings_num: number;
+  order_num: number;
+  player: string;
+  balls: number;
+  runs_conceded: number;
+  wickets: number;
+}
+export async function getBowlingCards(db: D1Like, matchId: number): Promise<BowlingCardRow[]> {
+  const r = await db
+    .prepare(
+      `SELECT innings_num, order_num, player, balls, runs_conceded, wickets
+       FROM bowling_cards WHERE match_id = ? ORDER BY innings_num, order_num`,
+    )
+    .bind(matchId)
+    .all<BowlingCardRow>();
+  return r.results;
+}
+
+/** Resolve a free-text player query against the small `players` table
+ *  (one row per distinct name string Cricsheet uses). Cricsheet names are
+ *  short forms ("V Kohli", "SR Watson") -- matching is case-insensitive
+ *  substring, ranked by how many matches that name appears in, so a common
+ *  surname like "Kohli" resolves unambiguously while a genuinely ambiguous
+ *  query (e.g. a shared surname) comes back as a candidate list rather than
+ *  picking one silently. */
+export interface PlayerCandidate {
+  player: string;
+  matches: number;
+}
+export async function resolvePlayer(db: D1Like, query: string): Promise<{ resolved: string | null; candidates: PlayerCandidate[] }> {
+  const exact = await db
+    .prepare(`SELECT player, matches FROM players WHERE player = ? COLLATE NOCASE`)
+    .bind(query)
+    .first<PlayerCandidate>();
+  if (exact) return { resolved: exact.player, candidates: [exact] };
+
+  const r = await db
+    .prepare(`SELECT player, matches FROM players WHERE player LIKE ? COLLATE NOCASE ORDER BY matches DESC LIMIT 20`)
+    .bind(`%${query}%`)
+    .all<PlayerCandidate>();
+  if (r.results.length === 1) return { resolved: r.results[0].player, candidates: r.results };
+  return { resolved: null, candidates: r.results };
+}
+
+export interface BattingAgg {
+  innings: number;
+  runs: number;
+  balls: number;
+  outs: number;
+  not_outs: number;
+  fours: number;
+  sixes: number;
+  high_score: number | null;
+  hundreds: number;
+  fifties: number;
+  average: number | null;
+  strike_rate: number | null;
+}
+export interface BowlingAgg {
+  innings: number;
+  balls: number;
+  runs_conceded: number;
+  wickets: number;
+  best_wickets: number | null;
+  average: number | null;
+  economy: number | null;
+}
+
+export async function battingAggregate(db: D1Like, player: string, format: Format | null): Promise<BattingAgg> {
+  const where = format ? 'player = ? AND format = ?' : 'player = ?';
+  const params = format ? [player, format] : [player];
+  const row = await db
+    .prepare(
+      `SELECT COUNT(*) AS innings, COALESCE(SUM(runs),0) AS runs, COALESCE(SUM(balls),0) AS balls,
+              COALESCE(SUM(CASE WHEN not_out = 0 THEN 1 ELSE 0 END),0) AS outs,
+              COALESCE(SUM(CASE WHEN not_out = 1 THEN 1 ELSE 0 END),0) AS not_outs,
+              COALESCE(SUM(fours),0) AS fours, COALESCE(SUM(sixes),0) AS sixes,
+              MAX(runs) AS high_score,
+              COALESCE(SUM(CASE WHEN runs >= 100 THEN 1 ELSE 0 END),0) AS hundreds,
+              COALESCE(SUM(CASE WHEN runs >= 50 AND runs < 100 THEN 1 ELSE 0 END),0) AS fifties
+       FROM batting_cards WHERE ${where}`,
+    )
+    .bind(...params)
+    .first<{ innings: number; runs: number; balls: number; outs: number; not_outs: number; fours: number; sixes: number; high_score: number | null; hundreds: number; fifties: number }>();
+  const innings = row?.innings ?? 0;
+  const runs = row?.runs ?? 0;
+  const balls = row?.balls ?? 0;
+  const outs = row?.outs ?? 0;
+  return {
+    innings,
+    runs,
+    balls,
+    outs,
+    not_outs: row?.not_outs ?? 0,
+    fours: row?.fours ?? 0,
+    sixes: row?.sixes ?? 0,
+    high_score: row?.high_score ?? null,
+    hundreds: row?.hundreds ?? 0,
+    fifties: row?.fifties ?? 0,
+    average: outs > 0 ? round2(runs / outs) : null,
+    strike_rate: balls > 0 ? round2((runs / balls) * 100) : null,
+  };
+}
+
+export async function bowlingAggregate(db: D1Like, player: string, format: Format | null): Promise<BowlingAgg> {
+  const where = format ? 'player = ? AND format = ?' : 'player = ?';
+  const params = format ? [player, format] : [player];
+  const row = await db
+    .prepare(
+      `SELECT COUNT(*) AS innings, COALESCE(SUM(balls),0) AS balls, COALESCE(SUM(runs_conceded),0) AS runs_conceded,
+              COALESCE(SUM(wickets),0) AS wickets, MAX(wickets) AS best_wickets
+       FROM bowling_cards WHERE ${where}`,
+    )
+    .bind(...params)
+    .first<{ innings: number; balls: number; runs_conceded: number; wickets: number; best_wickets: number | null }>();
+  const innings = row?.innings ?? 0;
+  const balls = row?.balls ?? 0;
+  const runs_conceded = row?.runs_conceded ?? 0;
+  const wickets = row?.wickets ?? 0;
+  return {
+    innings,
+    balls,
+    runs_conceded,
+    wickets,
+    best_wickets: row?.best_wickets ?? null,
+    average: wickets > 0 ? round2(runs_conceded / wickets) : null,
+    economy: balls > 0 ? round2(runs_conceded / (balls / 6)) : null,
+  };
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+export interface HeadToHeadFilter {
+  team_a: string;
+  team_b: string;
+  format: Format | null;
+  limit: number;
+  offset: number;
+}
+export async function headToHeadMatches(db: D1Like, f: HeadToHeadFilter): Promise<MatchRow[]> {
+  const where = ['((team1 = ? COLLATE NOCASE AND team2 = ? COLLATE NOCASE) OR (team1 = ? COLLATE NOCASE AND team2 = ? COLLATE NOCASE))'];
+  const params: unknown[] = [f.team_a, f.team_b, f.team_b, f.team_a];
+  if (f.format) {
+    where.push('format = ?');
+    params.push(f.format);
+  }
+  const sql = `SELECT match_id, format, gender, team1, team2, match_date, season, venue, city, event_name,
+                      toss_winner, toss_decision, outcome_winner, outcome_by_runs, outcome_by_wickets,
+                      outcome_by_innings, outcome_method, result, player_of_match
+               FROM matches WHERE ${where.join(' AND ')} ORDER BY match_date DESC LIMIT ? OFFSET ?`;
+  params.push(f.limit, f.offset);
+  const r = await db.prepare(sql).bind(...params).all<MatchRow>();
+  return r.results;
+}
+export async function headToHeadCount(db: D1Like, f: Omit<HeadToHeadFilter, 'limit' | 'offset'>): Promise<number> {
+  const where = ['((team1 = ? COLLATE NOCASE AND team2 = ? COLLATE NOCASE) OR (team1 = ? COLLATE NOCASE AND team2 = ? COLLATE NOCASE))'];
+  const params: unknown[] = [f.team_a, f.team_b, f.team_b, f.team_a];
+  if (f.format) {
+    where.push('format = ?');
+    params.push(f.format);
+  }
+  const r = await db.prepare(`SELECT COUNT(*) AS n FROM matches WHERE ${where.join(' AND ')}`).bind(...params).first<{ n: number }>();
+  return r?.n ?? 0;
+}
+
+export interface FindMatchesFilter {
+  team?: string;
+  format?: Format | null;
+  season?: string;
+  venue?: string;
+  player?: string;
+  limit: number;
+  offset: number;
+}
+export async function findMatches(db: D1Like, f: FindMatchesFilter): Promise<MatchRow[]> {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  if (f.team) {
+    where.push('(team1 = ? COLLATE NOCASE OR team2 = ? COLLATE NOCASE)');
+    params.push(f.team, f.team);
+  }
+  if (f.format) {
+    where.push('format = ?');
+    params.push(f.format);
+  }
+  if (f.season) {
+    where.push('season = ? COLLATE NOCASE');
+    params.push(f.season);
+  }
+  if (f.venue) {
+    where.push('venue LIKE ? COLLATE NOCASE');
+    params.push(`%${f.venue}%`);
+  }
+  if (f.player) {
+    where.push(
+      'match_id IN (SELECT match_id FROM batting_cards WHERE player = ? COLLATE NOCASE UNION SELECT match_id FROM bowling_cards WHERE player = ? COLLATE NOCASE)',
+    );
+    params.push(f.player, f.player);
+  }
+  const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+  const sql = `SELECT match_id, format, gender, team1, team2, match_date, season, venue, city, event_name,
+                      toss_winner, toss_decision, outcome_winner, outcome_by_runs, outcome_by_wickets,
+                      outcome_by_innings, outcome_method, result, player_of_match
+               FROM matches ${whereSql} ORDER BY match_date DESC LIMIT ? OFFSET ?`;
+  params.push(f.limit, f.offset);
+  const r = await db.prepare(sql).bind(...params).all<MatchRow>();
+  return r.results;
+}
+export async function findMatchesCount(db: D1Like, f: Omit<FindMatchesFilter, 'limit' | 'offset'>): Promise<number> {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  if (f.team) {
+    where.push('(team1 = ? COLLATE NOCASE OR team2 = ? COLLATE NOCASE)');
+    params.push(f.team, f.team);
+  }
+  if (f.format) {
+    where.push('format = ?');
+    params.push(f.format);
+  }
+  if (f.season) {
+    where.push('season = ? COLLATE NOCASE');
+    params.push(f.season);
+  }
+  if (f.venue) {
+    where.push('venue LIKE ? COLLATE NOCASE');
+    params.push(`%${f.venue}%`);
+  }
+  if (f.player) {
+    where.push(
+      'match_id IN (SELECT match_id FROM batting_cards WHERE player = ? COLLATE NOCASE UNION SELECT match_id FROM bowling_cards WHERE player = ? COLLATE NOCASE)',
+    );
+    params.push(f.player, f.player);
+  }
+  const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+  const r = await db.prepare(`SELECT COUNT(*) AS n FROM matches ${whereSql}`).bind(...params).first<{ n: number }>();
+  return r?.n ?? 0;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["src/server.ts"]
+}