football-docs 0.6.0 → 0.6.2

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 19 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, 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,34 @@ 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 |
+| 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,201 searchable chunks** across 19 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/bin/serve.js

@@ -3,4 +3,9 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-await import(pathToFileURL(resolve(__dirname, "..", "dist", "index.js")).href);
+const { main } = await import(pathToFileURL(resolve(__dirname, "..", "dist", "index.js")).href);
+
+main().catch((error) => {
+  console.error("Failed to start football-docs MCP server:", error);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export { sanitiseFtsQuery } from "./tools.js";
 export declare function openDb(): Database.Database;
 export declare function openQueueDb(): Database.Database;
 export declare function createFootballDocsServer(): McpServer;
+export declare function main(): Promise<void>;

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)"),
@@ -128,7 +148,7 @@ export function createFootballDocsServer() {
     }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async (args) => resolveEntity(args));
     return server;
 }
-async function main() {
+export async function main() {
     const transport = new StdioServerTransport();
     await createFootballDocsServer().connect(transport);
 }

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;

package/dist/tools.js

@@ -1,11 +1,47 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 export const TOOL_NAMES = [
     "search_docs",
+    "resolve_provider_id",
+    "get_provider_docs",
     "list_providers",
     "compare_providers",
     "request_update",
     "resolve_entity",
 ];
 const QUERY_STOP_WORDS = new Set(["and", "or", "not", "near"]);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROVIDERS_PATH = resolve(__dirname, "..", "providers.json");
+const PROVIDER_REGISTRY = JSON.parse(readFileSync(PROVIDERS_PATH, "utf-8"));
+function slugProvider(provider) {
+    return provider
+        .trim()
+        .toLowerCase()
+        .replace(/&/g, " and ")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+function buildProviderAliases() {
+    const aliases = {};
+    for (const [provider, metadata] of Object.entries(PROVIDER_REGISTRY.providers)) {
+        aliases[slugProvider(provider)] = provider;
+        aliases[slugProvider(metadata.display_name)] = provider;
+        for (const alias of metadata.aliases) {
+            aliases[slugProvider(alias)] = provider;
+        }
+    }
+    return aliases;
+}
+const PROVIDER_ALIASES = buildProviderAliases();
+const DISPLAY_PROVIDER_ALIASES = Object.entries(PROVIDER_ALIASES).reduce((aliasesByProvider, [alias, provider]) => {
+    if (alias === provider)
+        return aliasesByProvider;
+    const aliases = aliasesByProvider[provider] ?? [];
+    aliases.push(alias);
+    aliasesByProvider[provider] = aliases;
+    return aliasesByProvider;
+}, {});
 function textResult(text, isError = false) {
     return {
         isError: isError || undefined,
@@ -42,7 +78,83 @@ function relaxedFtsQuery(query) {
     return tokens.map(quoteFtsToken).join(" OR ");
 }
 function normaliseProvider(provider) {
-    return provider.trim().toLowerCase();
+    const slug = slugProvider(provider);
+    return PROVIDER_ALIASES[slug] ?? slug;
+}
+function providerFilterLabel(original, normalised) {
+    if (!original || !normalised)
+        return "";
+    const trimmed = original.trim();
+    return trimmed === normalised ? normalised : `${trimmed} (${normalised})`;
+}
+function indexedProviders(db) {
+    const rows = db.prepare("SELECT DISTINCT provider FROM docs ORDER BY provider").all();
+    return new Set(rows.map((row) => row.provider));
+}
+function editDistance(a, b) {
+    const previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    const current = Array.from({ length: b.length + 1 }, () => 0);
+    for (let i = 1; i <= a.length; i += 1) {
+        current[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
+        }
+        previous.splice(0, previous.length, ...current);
+    }
+    return previous[b.length];
+}
+function providerSuggestions(provider, providerSet) {
+    const candidates = new Map();
+    for (const indexedProvider of providerSet) {
+        candidates.set(indexedProvider, indexedProvider);
+    }
+    for (const [alias, indexedProvider] of Object.entries(PROVIDER_ALIASES)) {
+        if (providerSet.has(indexedProvider)) {
+            candidates.set(alias, indexedProvider);
+        }
+    }
+    const threshold = Math.max(2, Math.ceil(provider.length * 0.3));
+    return [...candidates.entries()]
+        .map(([candidate, indexedProvider]) => ({
+        candidate,
+        indexedProvider,
+        distance: editDistance(provider, candidate),
+    }))
+        .filter((suggestion) => suggestion.distance <= threshold)
+        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate))
+        .map((suggestion) => suggestion.indexedProvider)
+        .filter((providerName, index, suggestions) => suggestions.indexOf(providerName) === index)
+        .slice(0, 3);
+}
+function unknownProviderMessage(original, provider, providerSet) {
+    const suggestions = providerSuggestions(provider, providerSet);
+    const suggestionText = suggestions.length ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+    return `Provider "${providerFilterLabel(original, provider)}" is not indexed.${suggestionText} Call list_providers for available provider keys, or use request_update to suggest adding it.`;
+}
+function requestProviderKey(provider) {
+    return slugProvider(provider).replace(/-/g, "");
+}
+function requestIssueTemplate(type) {
+    return {
+        new_provider: "new-provider.md",
+        recrawl: "flag-outdated.md",
+        flag_outdated: "flag-outdated.md",
+        suggest_source: "suggest-source.md",
+    }[type];
+}
+function requestIssueUrl(args) {
+    const titlePrefix = {
+        new_provider: "New provider",
+        recrawl: "Recrawl",
+        flag_outdated: "Outdated",
+        suggest_source: "Better source",
+    }[args.type];
+    const params = new URLSearchParams({
+        template: requestIssueTemplate(args.type),
+        title: `${titlePrefix}: ${args.provider}`,
+    });
+    return `https://github.com/withqwerty/football-docs/issues/new?${params.toString()}`;
 }
 function normaliseLimit(value, defaultValue, maxValue) {
     if (value === undefined || !Number.isFinite(value))
@@ -53,6 +165,7 @@ function searchRows(db, matchQuery, provider, limit) {
     let sql = `
     SELECT d.provider, d.category, d.title, d.content,
            d.source_type, d.source_url, d.upstream_version,
+           d.crawled_at,
            rank * -1 as relevance
     FROM docs_fts
     JOIN docs d ON d.id = docs_fts.rowid
@@ -84,29 +197,162 @@ function compareRows(db, matchQuery, providers) {
     sql += " ORDER BY d.provider, rank LIMIT 30";
     return db.prepare(sql).all(...params);
 }
+function compareRowsForProvider(db, matchQuery, provider, limit) {
+    return db
+        .prepare(`SELECT d.provider, d.category, d.title, d.content,
+              rank * -1 as relevance
+       FROM docs_fts
+       JOIN docs d ON d.id = docs_fts.rowid
+       WHERE docs_fts MATCH ? AND d.provider = ?
+       ORDER BY rank
+       LIMIT ?`)
+        .all(matchQuery, normaliseProvider(provider), limit);
+}
 function sourceLabel(row) {
+    const crawledAt = row.crawled_at ? ` | crawled ${row.crawled_at}` : "";
     if (row.source_type === "curated") {
-        return "**Source:** curated by football-docs contributors";
+        return `**Source:** curated by football-docs contributors${crawledAt}`;
     }
-    return `**Source:** ${row.source_type}${row.source_url ? ` (${row.source_url})` : ""}${row.upstream_version ? ` | v${row.upstream_version}` : ""}`;
+    return `**Source:** ${row.source_type}${row.source_url ? ` (${row.source_url})` : ""}${row.upstream_version ? ` | v${row.upstream_version}` : ""}${crawledAt}`;
+}
+function providerMetadata(provider) {
+    return PROVIDER_REGISTRY.providers[provider];
+}
+function providerCoverage(db, provider) {
+    const rows = db
+        .prepare(`SELECT category, COUNT(*) as chunks
+       FROM docs
+       WHERE provider = ?
+       GROUP BY category
+       ORDER BY category`)
+        .all(provider);
+    return {
+        indexed: rows.length > 0,
+        total: rows.reduce((sum, row) => sum + row.chunks, 0),
+        categories: rows.map((row) => `${row.category} (${row.chunks})`),
+    };
+}
+function formatProviderResolution(db, provider, originalQuery) {
+    const metadata = providerMetadata(provider);
+    const coverage = providerCoverage(db, provider);
+    const aliasText = metadata?.aliases.length ? metadata.aliases.join(", ") : "none";
+    const sourceText = metadata?.sources
+        .map((source) => `${source.type}${source.url ? `: ${source.url}` : ""}`)
+        .join("; ") || "none registered";
+    return [
+        `Resolved "${originalQuery}" to provider ID: **${provider}**`,
+        `**Display name:** ${metadata?.display_name ?? provider}`,
+        `**Indexed:** ${coverage.indexed ? `yes (${coverage.total} chunks)` : "no"}`,
+        `**Categories:** ${coverage.categories.length ? coverage.categories.join(", ") : "none indexed"}`,
+        `**Aliases:** ${aliasText}`,
+        `**Access level:** ${metadata?.access_level ?? "unknown"}`,
+        `**Licence/status:** ${metadata?.licence_status ?? "unknown"}`,
+        `**Public-safety notes:** ${metadata?.public_safety_notes ?? "none registered"}`,
+        `**Version:** ${metadata?.version ?? "unversioned"}`,
+        `**Last crawled:** ${metadata?.last_crawled ?? "not crawled"}`,
+        `**Registered sources:** ${sourceText}`,
+    ].join("\n");
+}
+function providerDocsRows(db, provider, matchQuery, category, limit) {
+    const params = [];
+    let sql;
+    if (matchQuery) {
+        sql = `
+      SELECT d.provider, d.category, d.title, d.content,
+             d.source_type, d.source_url, d.upstream_version,
+             d.crawled_at,
+             rank * -1 as relevance
+      FROM docs_fts
+      JOIN docs d ON d.id = docs_fts.rowid
+      WHERE docs_fts MATCH ? AND d.provider = ?
+    `;
+        params.push(matchQuery, provider);
+    }
+    else {
+        sql = `
+      SELECT d.provider, d.category, d.title, d.content,
+             d.source_type, d.source_url, d.upstream_version,
+             d.crawled_at,
+             0 as relevance
+      FROM docs d
+      WHERE d.provider = ?
+    `;
+        params.push(provider);
+    }
+    if (category) {
+        sql += " AND d.category = ?";
+        params.push(category);
+    }
+    sql += matchQuery ? " ORDER BY rank LIMIT ?" : " ORDER BY d.category, d.id LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params);
+}
+export function resolveProviderId(db, args) {
+    const provider = normaliseProvider(args.query);
+    const registryProviders = new Set(Object.keys(PROVIDER_REGISTRY.providers));
+    const indexedProviderSet = indexedProviders(db);
+    if (registryProviders.has(provider)) {
+        return textResult(formatProviderResolution(db, provider, args.query));
+    }
+    const suggestions = providerSuggestions(provider, new Set([...registryProviders, ...indexedProviderSet]));
+    const suggestionText = suggestions.length ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+    return textResult(`Provider "${args.query}" is not registered.${suggestionText} Use request_update to suggest adding it, or open a GitHub issue with the new-provider template.`, true);
+}
+export function getProviderDocs(db, args) {
+    const provider = normaliseProvider(args.provider);
+    const providerSet = indexedProviders(db);
+    if (!providerSet.has(provider)) {
+        const registryProviders = new Set(Object.keys(PROVIDER_REGISTRY.providers));
+        if (registryProviders.has(provider)) {
+            return textResult(`Provider "${providerFilterLabel(args.provider, provider)}" is registered but has no indexed docs yet. Use request_update to ask maintainers to crawl or curate it.`, true);
+        }
+        return textResult(unknownProviderMessage(args.provider, provider, providerSet), true);
+    }
+    const limit = normaliseLimit(args.max_results, 10, 50);
+    const category = args.category ? slugProvider(args.category) : undefined;
+    const strictQuery = args.topic ? sanitiseFtsQuery(args.topic) : undefined;
+    const fallbackQuery = args.topic ? relaxedFtsQuery(args.topic) : undefined;
+    let rows = providerDocsRows(db, provider, strictQuery, category, limit);
+    if (rows.length === 0 && fallbackQuery && fallbackQuery !== strictQuery) {
+        rows = providerDocsRows(db, provider, fallbackQuery, category, limit);
+    }
+    if (rows.length === 0) {
+        return textResult(`No provider docs found for "${providerFilterLabel(args.provider, provider)}"${category ? ` in category "${category}"` : ""}${args.topic ? ` matching "${args.topic}"` : ""}. Call resolve_provider_id or list_providers to inspect available coverage.`);
+    }
+    const metadata = providerMetadata(provider);
+    const docs = rows
+        .map((row, index) => {
+        return `## [${index + 1}] ${row.title}\n**Provider:** ${row.provider} | **Category:** ${row.category} | ${sourceLabel(row)}\n\n${row.content}`;
+    })
+        .join("\n\n---\n\n");
+    return textResult(`Provider docs for **${provider}** (${metadata?.display_name ?? provider})${args.topic ? ` matching "${args.topic}"` : ""}${category ? ` in category "${category}"` : ""}:\n\n${docs}`);
 }
 export function searchDocs(db, args) {
     const limit = normaliseLimit(args.max_results, 10, 50);
     const strictQuery = sanitiseFtsQuery(args.query);
     const fallbackQuery = relaxedFtsQuery(args.query);
-    let rows = searchRows(db, strictQuery, args.provider, limit);
+    const provider = args.provider ? normaliseProvider(args.provider) : undefined;
+    if (args.provider && provider) {
+        const providerSet = indexedProviders(db);
+        if (!providerSet.has(provider)) {
+            return textResult(unknownProviderMessage(args.provider, provider, providerSet), true);
+        }
+    }
+    let rows = searchRows(db, strictQuery, provider, limit);
     if (rows.length === 0 && fallbackQuery !== strictQuery) {
-        rows = searchRows(db, fallbackQuery, args.provider, limit);
+        rows = searchRows(db, fallbackQuery, provider, limit);
     }
     if (rows.length === 0) {
-        return textResult(`No results found for "${args.query}"${args.provider ? ` in ${args.provider}` : ""}. Try broader terms or remove the provider filter.`);
+        const providerLabel = providerFilterLabel(args.provider, provider);
+        return textResult(`No results found for "${args.query}"${providerLabel ? ` in ${providerLabel}` : ""}. Try broader football-data terms, remove the provider filter, or call list_providers to inspect coverage.`);
     }
     const results = rows
         .map((row, index) => {
         return `## [${index + 1}] ${row.title}\n**Provider:** ${row.provider} | **Category:** ${row.category} | ${sourceLabel(row)}\n\n${row.content}`;
     })
         .join("\n\n---\n\n");
-    return textResult(`Found ${rows.length} result(s) for "${args.query}"${args.provider ? ` in ${args.provider}` : ""}:\n\n${results}`);
+    const providerLabel = providerFilterLabel(args.provider, provider);
+    return textResult(`Found ${rows.length} result(s) for "${args.query}"${providerLabel ? ` in ${providerLabel}` : ""}:\n\n${results}`);
 }
 export function listProviders(db) {
     const rows = db
@@ -124,7 +370,9 @@ export function listProviders(db) {
     }
     const lines = [...byProvider.entries()]
         .map(([provider, info]) => {
-        return `**${provider}** (${info.total} chunks): ${info.categories.join(", ")}`;
+        const aliases = DISPLAY_PROVIDER_ALIASES[provider];
+        const aliasText = aliases?.length ? ` | aliases: ${aliases.join(", ")}` : "";
+        return `**${provider}** (${info.total} chunks): ${info.categories.join(", ")}${aliasText}`;
     })
         .join("\n");
     return textResult(`Indexed providers:\n\n${lines}`);
@@ -132,11 +380,39 @@ export function listProviders(db) {
 export function compareProviders(db, args) {
     const strictQuery = sanitiseFtsQuery(args.topic);
     const fallbackQuery = relaxedFtsQuery(args.topic);
-    let rows = compareRows(db, strictQuery, args.providers);
-    if (rows.length === 0 && fallbackQuery !== strictQuery) {
-        rows = compareRows(db, fallbackQuery, args.providers);
+    let rows;
+    let requestedProviders = [];
+    const providerSet = indexedProviders(db);
+    if (args.providers?.length) {
+        requestedProviders = [...new Set(args.providers.map(normaliseProvider))];
+        rows = requestedProviders.flatMap((provider) => {
+            if (!providerSet.has(provider))
+                return [];
+            const strictRows = compareRowsForProvider(db, strictQuery, provider, 3);
+            if (strictRows.length > 0 || fallbackQuery === strictQuery)
+                return strictRows;
+            return compareRowsForProvider(db, fallbackQuery, provider, 3);
+        });
+    }
+    else {
+        rows = compareRows(db, strictQuery, args.providers);
+        if (rows.length === 0 && fallbackQuery !== strictQuery) {
+            rows = compareRows(db, fallbackQuery, args.providers);
+        }
     }
     if (rows.length === 0) {
+        if (requestedProviders.length > 0) {
+            const missingProviders = requestedProviders.filter((provider) => !providerSet.has(provider));
+            const providerNote = missingProviders.length
+                ? ` Requested provider(s) not indexed: ${missingProviders.join(", ")}.${missingProviders
+                    .map((provider) => {
+                    const suggestions = providerSuggestions(provider, providerSet);
+                    return suggestions.length ? ` ${provider}: did you mean ${suggestions.join(", ")}?` : "";
+                })
+                    .join("")}`
+                : "";
+            return textResult(`No matching docs found for "${args.topic}" across requested provider(s): ${requestedProviders.join(", ")}.${providerNote} Call list_providers to inspect coverage, or use request_update to suggest missing provider docs.`);
+        }
         return textResult(`No documentation found for "${args.topic}". Try different terms.`);
     }
     const grouped = new Map();
@@ -148,27 +424,39 @@ export function compareProviders(db, args) {
     const sections = [...grouped.entries()]
         .map(([provider, chunks]) => `## ${provider}\n\n${chunks.slice(0, 3).join("\n\n")}`)
         .join("\n\n---\n\n");
-    return textResult(`Comparison for "${args.topic}" across ${grouped.size} provider(s):\n\n${sections}`);
+    const missingProviders = requestedProviders.filter((provider) => !grouped.has(provider));
+    const missingNote = missingProviders.length
+        ? `\n\nNo matching docs found for requested provider(s): ${missingProviders.join(", ")}.${missingProviders
+            .map((provider) => {
+            if (providerSet.has(provider))
+                return "";
+            const suggestions = providerSuggestions(provider, providerSet);
+            return suggestions.length ? ` ${provider}: did you mean ${suggestions.join(", ")}?` : "";
+        })
+            .join("")}`
+        : "";
+    return textResult(`Comparison for "${args.topic}" across ${grouped.size} provider(s):\n\n${sections}${missingNote}`);
 }
 export function requestUpdate(db, args, options = {}) {
+    const requestedAt = (options.now ?? new Date()).toISOString();
+    const providerKey = requestProviderKey(args.provider);
     const countRow = db.prepare("SELECT COUNT(*) as cnt FROM requests").get();
     if (countRow.cnt >= 500) {
         return textResult(`Request queue is full (${countRow.cnt} entries). Please file an issue at https://github.com/withqwerty/football-docs/issues instead.`, true);
     }
     const recentRequest = db
         .prepare(`SELECT id, requested_at FROM requests
-       WHERE lower(provider) = lower(?) AND status = 'pending'
-         AND datetime(requested_at) > datetime('now', '-7 days')
+       WHERE provider = ? AND status = 'pending'
+         AND datetime(requested_at) > datetime(?, '-7 days')
        LIMIT 1`)
-        .get(args.provider);
+        .get(providerKey, requestedAt);
     if (recentRequest) {
         return textResult(`A pending request for "${args.provider}" already exists (from ${recentRequest.requested_at}). Requests have a 7-day cooldown to prevent duplicate work. Request ID: ${recentRequest.id}`, true);
     }
     const id = options.requestId ??
         `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-    const requestedAt = (options.now ?? new Date()).toISOString();
     db.prepare(`INSERT INTO requests (id, type, provider, reason, suggested_urls, requested_at, status)
-     VALUES (?, ?, ?, ?, ?, ?, 'pending')`).run(id, args.type, args.provider.toLowerCase(), args.reason, args.suggested_urls ? JSON.stringify(args.suggested_urls) : null, requestedAt);
+     VALUES (?, ?, ?, ?, ?, ?, 'pending')`).run(id, args.type, providerKey, args.reason, args.suggested_urls ? JSON.stringify(args.suggested_urls) : null, requestedAt);
     const typeLabel = {
         new_provider: "New provider request",
         recrawl: "Recrawl request",
@@ -177,7 +465,7 @@ export function requestUpdate(db, args, options = {}) {
     }[args.type];
     return textResult(`${typeLabel} queued for "${args.provider}" (ID: ${id}).\n\nReason: ${args.reason}${args.suggested_urls?.length
         ? `\nSuggested URLs:\n${args.suggested_urls.map((url) => `  - ${url}`).join("\n")}`
-        : ""}\n\nThis request will be reviewed by maintainers. You can also file an issue at https://github.com/withqwerty/football-docs/issues for community visibility.`);
+        : ""}\n\nThis local request will be reviewed by maintainers. For community visibility, also open the matching GitHub issue: ${requestIssueUrl(args)}`);
 }
 export async function resolveEntity(args, options = {}) {
     const baseUrl = options.baseUrl ?? "https://reep-api.rahulkeerthi2-95d.workers.dev";
@@ -200,6 +488,9 @@ export async function resolveEntity(args, options = {}) {
     try {
         const response = await fetchImpl(url);
         if (!response.ok) {
+            if (response.status === 401 || response.status === 403) {
+                return textResult(`Reep API authentication failed (${response.status} ${response.statusText}). Entity resolution is optional and needs a Reep API credential/configured endpoint before provider ID lookup can work. Docs search tools still work without Reep access.`, true);
+            }
             return textResult(`Reep API error: ${response.status} ${response.statusText}`, true);
         }
         const data = (await response.json());