football-docs 0.6.1 → 0.6.3

package/README.md

@@ -4,19 +4,26 @@ Searchable football data provider and tooling documentation for AI coding agents
 
 **Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.
 
-**What it does:** Gives your AI agent a searchable index of documentation for 17 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, FMDB Pro, TransferRoom, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, and more). Your agent looks up the real docs instead of guessing from training data.
+**What it does:** Gives your AI agent a searchable index of documentation for 20 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, and more). Your agent looks up the real docs instead of guessing from training data.
 
 **Why not just let the AI figure it out?** LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
 
+## Strategy
+
+football-docs is intended to be a community-owned, source-transparent Context7
+for football data. The public operating contract is in
+[STRATEGY.md](STRATEGY.md): what belongs here, what must stay out, how we handle
+public-safe provider facts, and how contributors should prove retrieval quality.
+
 ## Provider identity facts
 
 football-docs is the public source for provider identity-surface facts: access
 shape, ID schemes, matching fields, provider quirks, and provenance rules.
-Curated Reep-derived notes belong here when they can be stated without private
-register state. They should say whether a fact comes from public docs, public
-page evidence, licensed feed shape, or a reviewed public-safe observation, and
-must not include private paths, credentials, scraper state, action ledgers, mint
-salts, or raw restricted payloads.
+Curated provider identity notes belong here when they can be stated without
+private register state. They should say whether a fact comes from public docs,
+public page evidence, licensed feed shape, or a reviewed public-safe
+observation, and must not include private paths, credentials, scraper state,
+action ledgers, mint salts, or raw restricted payloads.
 
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
 
@@ -78,11 +85,15 @@ Add to `claude_desktop_config.json`:
 | Tool | Description |
 |------|-------------|
 | `search_docs` | Full-text search across all provider docs. Filter by provider. Results include provenance (source URL, version). |
+| `resolve_provider_id` | Resolve provider names and aliases to canonical indexed provider keys before searching. |
+| `get_provider_docs` | Retrieve docs for a resolved provider, optionally filtered by topic or category. |
 | `list_providers` | List all indexed providers and their doc coverage. |
 | `compare_providers` | Compare how different providers handle the same concept. |
-| `request_update` | Request a new provider, flag outdated docs, or suggest a better doc source. Queued for maintainer review. |
+| `request_update` | Request a new provider, flag outdated docs, or suggest a better doc source. Queues locally and points to the matching public GitHub issue template. |
 | `resolve_entity` | Resolve players, teams, or coaches to cross-provider IDs via the Reep API. |
 
+Provider filters use the indexed provider keys shown by `list_providers`, but common aliases are accepted. Examples: `fbref`, `understat`, `ClubElo`, `football-data.co.uk`, and `engsoccerdata` search `free-sources`; `Sofascore` and `ESPN` search `soccerdata`; `FMDB` searches `fmdb-pro`; `Transfer Room` searches `transferroom`; `Hudl Wyscout` searches `wyscout`; `Stats Perform` / `Opta F24` / `WhoScored` search `opta`; `Metrica`, `Sportec` / `DFL`, and `TRACAB` search `databallpy`; `Second Spectrum` searches `kloppy`; `SportRadar API` / `Soccer Extended` search `sportradar`; `The Sports DB` / `TSDB` search `thesportsdb`; `StatsBomb Open Data` searches `statsbomb`.
+
 ## Example queries
 
 - "What is Opta qualifier 76?" (big chance)
@@ -97,32 +108,35 @@ Add to `claude_desktop_config.json`:
 
 | Provider | Chunks | Categories |
 |----------|--------|------------|
-| StatsBomb | 231 | event-types, data-model, coordinate-system, api-access, api-endpoints, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces |
-| Wyscout | 157 | event-types, data-model, coordinate-system, api-access, api-endpoints, glossary, identity-surfaces |
-| kloppy | 100 | data-model, usage, provider-mapping |
-| SportMonks | 78 | event-types, data-model, api-access, identity-surfaces |
+| StatsBomb | 237 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-lineups, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces |
+| Wyscout | 164 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-analysis-metrics, glossary, identity-surfaces |
+| kloppy | 126 | data-model, usage, provider-mapping, tracking-rendering, event-derived-metrics |
+| floodlight | 145 | core data objects, io parsers (Tracab, DFL, Kinexon, Opta, SkillCorner, StatsBomb, StatsPerform, Second Spectrum), transforms, metrics, models, visualisation, guides |
+| SportMonks | 85 | event-types, data-model, api-access, charting-season-stories, identity-surfaces |
 | databallpy | 63 | data-model, overview, usage |
-| mplsoccer | 62 | overview, pitch-types, visualizations |
+| mplsoccer | 64 | overview, pitch-types, visualizations |
 | Impect | 58 | api-access, api-endpoints, data-model, event-types, coordinate-system, concepts, identity-surfaces |
-| SkillCorner | 51 | api-access, api-endpoints, data-model, physical-data, coordinate-system, concepts, identity-surfaces |
-| Free sources | 45 | overview, fbref, understat |
-| soccerdata | 40 | overview, data-sources, usage |
-| TransferRoom | 38 | api-access, api-endpoints, data-model, identity-surfaces |
-| Opta | 36 | event-types, qualifiers, coordinate-system, api-access, identity-surfaces |
+| SkillCorner | 52 | api-access, api-endpoints, data-model, physical-data, coordinate-system, concepts, identity-surfaces |
+| Free sources | 62 | overview, fbref, understat, contextual-story-joins, xg-timelines |
+| soccerdata | 41 | overview, data-sources, usage |
+| TransferRoom | 43 | api-access, api-endpoints, charting-availability, data-model, identity-surfaces |
+| Opta | 74 | event-types, qualifiers, coordinate-system, api-access, charting-game-state, charting-lineups, charting-passmaps, charting-set-pieces, charting-shot-placement, identity-surfaces |
 | FMDB Pro | 36 | api-access, api-endpoints, data-model, identity-surfaces |
-| socceraction | 26 | SPADL format, VAEP, Expected Threat |
+| Sportradar | 29 | api-access, api-endpoints, data-model, charting-and-stories, integration-notes |
+| socceraction | 27 | SPADL format, VAEP, Expected Threat |
+| TheSportsDB | 18 | api-access, api-endpoints, livescore, identity-surfaces |
 | FotMob | 7 | identity-surfaces |
 | Soccerdonna | 7 | identity-surfaces |
-| Transfermarkt | 7 | identity-surfaces |
+| Transfermarkt | 8 | identity-surfaces |
 
-**1,042 searchable chunks** across 17 providers and tools.
+**1,346 searchable chunks** across 20 providers and tools.
 
 ## Contributing
 
 Contributions are welcome from everyone. There are three ways to help:
 
 1. **Open an issue** — [request a new provider](https://github.com/withqwerty/football-docs/issues/new/choose), [flag outdated docs](https://github.com/withqwerty/football-docs/issues/new/choose), or [suggest a better doc source](https://github.com/withqwerty/football-docs/issues/new/choose)
-2. **Use the `request_update` tool** — AI agents can flag outdated or missing docs directly via the MCP server, which queues requests for maintainer review
+2. **Use the `request_update` tool** — AI agents can flag outdated or missing docs directly via the MCP server, which queues requests locally and points to the matching public GitHub issue template
 3. **Open a PR** — fix errors, add new providers, or improve existing docs
 
 **You don't need to be an expert.** See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.

package/dist/crawl.js

@@ -30,6 +30,58 @@ const turndown = new TurndownService({
     codeBlockStyle: "fenced",
     bulletListMarker: "-",
 });
+// Sphinx (and other Pygments-based renderers) mark up code blocks as bare
+// <pre> containing syntax-highlighting <span>s, not <pre><code>. Turndown's
+// built-in fenced-code rule only matches <pre><code>, so these fall through
+// to plain-text handling where markdown-escaping mangles identifiers (e.g.
+// `read_position_data_json` becomes `read\_position\_data\_json`). Read
+// textContent directly to bypass that escaping.
+turndown.addRule("preBlock", {
+    filter: "pre",
+    replacement: (_content, node) => {
+        const code = node.textContent?.replace(/\n+$/, "") ?? "";
+        if (!code.trim())
+            return "";
+        const parentClass = node.parentElement?.getAttribute?.("class") ?? "";
+        const langMatch = parentClass.match(/highlight-(\w+)/);
+        const lang = langMatch && langMatch[1] !== "default" ? langMatch[1] : "";
+        return `\n\n\`\`\`${lang}\n${code}\n\`\`\`\n\n`;
+    },
+});
+// Sphinx marks up identifiers/parameter names/default values in signatures
+// with <span class="pre"> (a "don't word-wrap" hint, not semantic <code>).
+// Same escaping problem as above — render as inline code instead.
+turndown.addRule("sphinxPreSpan", {
+    filter: (node) => node.nodeName === "SPAN" &&
+        (node.getAttribute?.("class") ?? "")
+            .split(/\s+/)
+            .includes("pre"),
+    replacement: (_content, node) => `\`${node.textContent ?? ""}\``,
+});
+// Turndown escapes every underscore in plain text nodes by default (guarding
+// against accidental markdown emphasis), including identifiers that carry no
+// code markup at all — e.g. Sphinx renders parameter/return names in
+// "Variables:" lists as plain `<strong>essential_missing</strong>`, no <code>
+// or .pre span in sight. Since this corpus exists for full-text search rather
+// than pixel-perfect rendering, an escaped underscore that breaks substring
+// matches on the real identifier is worse than the rare accidental italics.
+const defaultEscape = turndown.escape.bind(turndown);
+turndown.escape = (text) => defaultEscape(text).replace(/\\_/g, "_");
+// Turndown's built-in image rule escapes alt text via a private module-level
+// helper, not the overridable `escape` method above, so alt text (often just
+// the image's own filename, e.g. "pitch_positive.png") still comes out with
+// escaped underscores. Same fix, applied to this one rule directly.
+turndown.addRule("unescapedImageAlt", {
+    filter: "img",
+    replacement: (_content, node) => {
+        const el = node;
+        const alt = el.getAttribute?.("alt") ?? "";
+        const src = el.getAttribute?.("src") ?? "";
+        const title = el.getAttribute?.("title");
+        const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : "";
+        return src ? `![${alt}](${src}${titlePart})` : "";
+    },
+});
 // ── HTML → Markdown ──────────────────────────────────────────────────
 /**
  * Extract main content from an HTML page and convert to markdown.
@@ -43,7 +95,13 @@ export function htmlToMarkdown(html, url) {
         ? html
         : html.replace(/(<head[^>]*>)/i, `$1<base href="${url}">`);
     const { document } = parseHTML(htmlWithBase);
-    const reader = new Readability(document, { charThreshold: 100 });
+    // classesToPreserve keeps class="pre" (Sphinx's no-wrap marker for inline
+    // literals) alive through Readability's cleanup, so the sphinxPreSpan
+    // Turndown rule above can still detect and unescape it.
+    const reader = new Readability(document, {
+        charThreshold: 100,
+        classesToPreserve: ["pre"],
+    });
     const article = reader.parse();
     if (!article?.content)
         return null;

package/dist/index.js

@@ -17,7 +17,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import Database from "better-sqlite3";
 import { z } from "zod";
-import { compareProviders, listProviders, requestUpdate, resolveEntity, searchDocs, } from "./tools.js";
+import { compareProviders, getProviderDocs, listProviders, requestUpdate, resolveEntity, resolveProviderId, searchDocs, } from "./tools.js";
 export { sanitiseFtsQuery } from "./tools.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DB_PATH = resolve(__dirname, "..", "data", "docs.db");
@@ -78,24 +78,44 @@ export function createFootballDocsServer() {
         version: PKG_VERSION,
     });
     server.tool("search_docs", "Search football data provider documentation. Use for finding event types, qualifier IDs, API endpoints, coordinate systems, data models, and cross-provider mappings. Returns the most relevant documentation chunks.", {
-        query: z.string().describe("Search query. Examples: 'Opta goal qualifier', 'StatsBomb shot event type', 'coordinate system differences', 'xG qualifier ID', 'SportMonks fixture endpoint'"),
+        query: z.string().describe("Search query. Examples: 'Opta goal qualifier', 'StatsBomb shot event type', 'coordinate system differences', 'xG qualifier ID', 'SportMonks fixture endpoint', 'FMDB Pro players endpoint'"),
         provider: z
             .string()
             .optional()
-            .describe("Filter to a specific provider: opta, statsbomb, wyscout, sportmonks, fbref, understat, kloppy, or leave empty for all"),
+            .describe("Optional provider filter. Use list_providers for indexed provider keys. Common aliases such as fbref, understat, ClubElo, football-data.co.uk, engsoccerdata, Sofascore, ESPN, FMDB, TransferRoom, Hudl Wyscout, Stats Perform, Opta F24, WhoScored, Metrica, Sportec/DFL, TRACAB, Second Spectrum, SportRadar API, Soccer Extended, TheSportsDB, and TSDB are accepted."),
         max_results: z
             .number()
             .optional()
             .default(10)
             .describe("Maximum number of results to return (default 10)"),
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args) => withDocsDb((db) => searchDocs(db, args)));
+    server.tool("resolve_provider_id", "Resolve a football data provider name or alias to the canonical football-docs provider key before searching. Use when users mention brands, vendors, products, or aliases such as Stats Perform, Opta F24, Hudl Wyscout, Second Spectrum, FMDB, Transfer Room, FBref, Sofascore, or TheSportsDB.", {
+        query: z
+            .string()
+            .describe("Provider name, brand, product, or alias to resolve to a canonical provider key."),
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args) => withDocsDb((db) => resolveProviderId(db, args)));
+    server.tool("get_provider_docs", "Retrieve documentation for a resolved provider, optionally filtered by topic or indexed category. Use after resolve_provider_id when you know which provider to inspect and want provenance-bearing docs.", {
+        provider: z
+            .string()
+            .describe("Provider key or alias. Use resolve_provider_id first when the provider name is ambiguous."),
+        topic: z.string().optional().describe("Optional topic to search within this provider's docs."),
+        category: z
+            .string()
+            .optional()
+            .describe("Optional indexed category to restrict results, such as api-endpoints, qualifiers, identity-surfaces, or tracking-rendering."),
+        max_results: z
+            .number()
+            .optional()
+            .default(10)
+            .describe("Maximum number of provider docs to return (default 10)."),
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args) => withDocsDb((db) => getProviderDocs(db, args)));
     server.tool("list_providers", "List all indexed football data providers, their document count, and coverage categories. Use to understand what documentation is available. Call this first to see what providers are indexed before searching.", {}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async () => withDocsDb((db) => listProviders(db)));
     server.tool("compare_providers", "Compare what two or more providers offer for a specific data type or concept. For example: 'How do Opta and StatsBomb represent shot events differently?'", {
         topic: z.string().describe("The concept to compare across providers. Examples: 'shot events', 'coordinate systems', 'xG', 'pass types'"),
         providers: z
             .array(z.string())
             .optional()
-            .describe("Providers to compare. If omitted, compares all indexed providers."),
+            .describe("Providers to compare. If omitted, compares all indexed providers. Use list_providers for indexed keys; common aliases such as ClubElo, football-data.co.uk, engsoccerdata, Sofascore, ESPN, StatsBomb Open Data, Opta F24, WhoScored, SkillCorner, Metrica, Sportec/DFL, TRACAB, Second Spectrum, SportRadar API, Soccer Extended, TheSportsDB, and TSDB are accepted."),
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (args) => withDocsDb((db) => compareProviders(db, args)));
     server.tool("request_update", "Request that a provider's documentation be added, updated, or recrawled. Use when you notice docs are outdated, a provider is missing, or you know of a better documentation source. Requests are queued for review.", {
         type: z.enum(["new_provider", "recrawl", "flag_outdated", "suggest_source"]).describe("Type of request: new_provider (add a new tool/library), recrawl (refresh existing docs), flag_outdated (mark docs as stale), suggest_source (recommend a better doc source like llms.txt)"),

package/dist/tools.d.ts

@@ -1,5 +1,5 @@
 import type Database from "better-sqlite3";
-export declare const TOOL_NAMES: readonly ["search_docs", "list_providers", "compare_providers", "request_update", "resolve_entity"];
+export declare const TOOL_NAMES: readonly ["search_docs", "resolve_provider_id", "get_provider_docs", "list_providers", "compare_providers", "request_update", "resolve_entity"];
 type TextContent = {
     type: "text";
     text: string;
@@ -13,6 +13,15 @@ export type SearchDocsArgs = {
     provider?: string;
     max_results?: number;
 };
+export type ResolveProviderIdArgs = {
+    query: string;
+};
+export type GetProviderDocsArgs = {
+    provider: string;
+    topic?: string;
+    category?: string;
+    max_results?: number;
+};
 export type CompareProvidersArgs = {
     topic: string;
     providers?: string[];
@@ -38,6 +47,8 @@ export type ResolveEntityArgs = {
  * like "Opta qualifier 76" to match docs that contain those tokens separately.
  */
 export declare function sanitiseFtsQuery(query: string): string;
+export declare function resolveProviderId(db: Database.Database, args: ResolveProviderIdArgs): ToolResponse;
+export declare function getProviderDocs(db: Database.Database, args: GetProviderDocsArgs): ToolResponse;
 export declare function searchDocs(db: Database.Database, args: SearchDocsArgs): ToolResponse;
 export declare function listProviders(db: Database.Database): ToolResponse;
 export declare function compareProviders(db: Database.Database, args: CompareProvidersArgs): ToolResponse;