football-docs 0.5.1 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ 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 15 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, 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 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.
 
 **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.
 
@@ -81,6 +81,7 @@ Add to `claude_desktop_config.json`:
 | `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. |
+| `resolve_entity` | Resolve players, teams, or coaches to cross-provider IDs via the Reep API. |
 
 ## Example queries
 
@@ -106,13 +107,15 @@ Add to `claude_desktop_config.json`:
 | 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 |
+| FMDB Pro | 36 | api-access, api-endpoints, data-model, identity-surfaces |
 | socceraction | 26 | SPADL format, VAEP, Expected Threat |
 | FotMob | 7 | identity-surfaces |
 | Soccerdonna | 7 | identity-surfaces |
 | Transfermarkt | 7 | identity-surfaces |
 
-**968 searchable chunks** across 15 providers and tools.
+**1,042 searchable chunks** across 17 providers and tools.
 
 ## Contributing
 

package/dist/index.d.ts

@@ -3,11 +3,15 @@
  *
  * A Context7-style searchable index of football data provider documentation.
  * Exposes tools for searching docs, listing providers, comparing providers,
- * and requesting documentation updates.
+ * requesting documentation updates, and resolving football entities.
  *
- * Data is stored in a SQLite FTS5 index for fast offline search.
- * Update requests are stored in a separate writable SQLite DB in a
- * user-writable location (XDG_DATA_HOME or ~/.local/share).
+ * Data is stored in a SQLite FTS5 index for fast offline search. Update
+ * requests are stored in a separate writable SQLite DB in a user-writable
+ * location (XDG_DATA_HOME or ~/.local/share).
  */
-/** Sanitise a query string for FTS5 MATCH by wrapping in double quotes (phrase search). */
-export declare function sanitiseFtsQuery(query: string): string;
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import Database from "better-sqlite3";
+export { sanitiseFtsQuery } from "./tools.js";
+export declare function openDb(): Database.Database;
+export declare function openQueueDb(): Database.Database;
+export declare function createFootballDocsServer(): McpServer;

package/dist/index.js

@@ -3,11 +3,11 @@
  *
  * A Context7-style searchable index of football data provider documentation.
  * Exposes tools for searching docs, listing providers, comparing providers,
- * and requesting documentation updates.
+ * requesting documentation updates, and resolving football entities.
  *
- * Data is stored in a SQLite FTS5 index for fast offline search.
- * Update requests are stored in a separate writable SQLite DB in a
- * user-writable location (XDG_DATA_HOME or ~/.local/share).
+ * Data is stored in a SQLite FTS5 index for fast offline search. Update
+ * requests are stored in a separate writable SQLite DB in a user-writable
+ * location (XDG_DATA_HOME or ~/.local/share).
  */
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -17,28 +17,27 @@ 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";
+export { sanitiseFtsQuery } from "./tools.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DB_PATH = resolve(__dirname, "..", "data", "docs.db");
 const PKG_VERSION = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf-8")).version;
-// Request queue DB goes in a user-writable location, not inside the npm package
 const QUEUE_DB_DIR = resolve(process.env.XDG_DATA_HOME ?? resolve(homedir(), ".local", "share"), "football-docs");
 const QUEUE_DB_PATH = resolve(QUEUE_DB_DIR, "requests.db");
-// ── Database ────────────────────────────────────────────────────────────
-function openDb() {
+export function openDb() {
     if (!existsSync(DB_PATH)) {
         throw new Error(`Docs database not found at ${DB_PATH}. Run 'npm run ingest' first to build the index.`);
     }
     const db = new Database(DB_PATH, { readonly: true });
-    // Check schema version — source_type column was added in v0.2.0
     const columns = db.pragma("table_info(docs)");
-    const hasProvenance = columns.some((c) => c.name === "source_type");
+    const hasProvenance = columns.some((column) => column.name === "source_type");
     if (!hasProvenance) {
         db.close();
-        throw new Error(`Docs database is outdated (missing provenance columns). Run 'npm run ingest' to rebuild.`);
+        throw new Error("Docs database is outdated (missing provenance columns). Run 'npm run ingest' to rebuild.");
     }
     return db;
 }
-function openQueueDb() {
+export function openQueueDb() {
     mkdirSync(QUEUE_DB_DIR, { recursive: true });
     const db = new Database(QUEUE_DB_PATH);
     db.pragma("journal_mode = WAL");
@@ -55,309 +54,90 @@ function openQueueDb() {
   `);
     return db;
 }
-/** Sanitise a query string for FTS5 MATCH by wrapping in double quotes (phrase search). */
-export function sanitiseFtsQuery(query) {
-    // FTS5 special syntax (AND, OR, NOT, NEAR, column:, *, ^) can cause errors.
-    // Wrap the user query in double quotes to treat it as a phrase search,
-    // escaping any embedded double quotes first.
-    return `"${query.replace(/"/g, '""')}"`;
-}
-// ── Server ──────────────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "nutmeg-football-docs",
-    version: PKG_VERSION,
-});
-// Tool: search_docs
-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'"),
-    provider: z
-        .string()
-        .optional()
-        .describe("Filter to a specific provider: opta, statsbomb, wyscout, sportmonks, fbref, understat, kloppy, or leave empty for all"),
-    max_results: z
-        .number()
-        .optional()
-        .default(10)
-        .describe("Maximum number of results to return (default 10)"),
-}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ query, provider, max_results }) => {
-    const db = openDb();
-    try {
-        const safeQuery = sanitiseFtsQuery(query);
-        let sql = `
-        SELECT d.provider, d.category, d.title, d.content,
-               d.source_type, d.source_url, d.upstream_version,
-               rank * -1 as relevance
-        FROM docs_fts
-        JOIN docs d ON d.id = docs_fts.rowid
-        WHERE docs_fts MATCH ?
-      `;
-        const params = [safeQuery];
-        if (provider) {
-            sql += ` AND d.provider = ?`;
-            params.push(provider.toLowerCase());
-        }
-        sql += ` ORDER BY rank LIMIT ?`;
-        params.push(max_results);
-        const rows = db.prepare(sql).all(...params);
-        if (rows.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No results found for "${query}"${provider ? ` in ${provider}` : ""}. Try broader terms or remove the provider filter.`,
-                    },
-                ],
-            };
-        }
-        const results = rows
-            .map((r, i) => {
-            const source = r.source_type === "curated"
-                ? "**Source:** curated by football-docs contributors"
-                : `**Source:** ${r.source_type}${r.source_url ? ` (${r.source_url})` : ""}${r.upstream_version ? ` | v${r.upstream_version}` : ""}`;
-            return `## [${i + 1}] ${r.title}\n**Provider:** ${r.provider} | **Category:** ${r.category} | ${source}\n\n${r.content}`;
-        })
-            .join("\n\n---\n\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Found ${rows.length} result(s) for "${query}"${provider ? ` in ${provider}` : ""}:\n\n${results}`,
-                },
-            ],
-        };
-    }
-    finally {
-        db.close();
-    }
-});
-// Tool: list_providers
-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 () => {
+function withDocsDb(handler) {
     const db = openDb();
     try {
-        const rows = db
-            .prepare(`SELECT provider, category, COUNT(*) as chunks
-           FROM docs
-           GROUP BY provider, category
-           ORDER BY provider, category`)
-            .all();
-        const byProvider = new Map();
-        for (const r of rows) {
-            const entry = byProvider.get(r.provider) ?? { categories: [], total: 0 };
-            entry.categories.push(`${r.category} (${r.chunks})`);
-            entry.total += r.chunks;
-            byProvider.set(r.provider, entry);
-        }
-        const lines = [...byProvider.entries()]
-            .map(([p, info]) => `**${p}** (${info.total} chunks): ${info.categories.join(", ")}`)
-            .join("\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Indexed providers:\n\n${lines}`,
-                },
-            ],
-        };
+        return handler(db);
     }
     finally {
         db.close();
     }
-});
-// Tool: compare_providers
-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."),
-}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ topic, providers }) => {
-    const db = openDb();
+}
+function withQueueDb(handler) {
+    const db = openQueueDb();
     try {
-        const safeTopic = sanitiseFtsQuery(topic);
-        let sql = `
-        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 ?
-      `;
-        const params = [safeTopic];
-        if (providers && providers.length > 0) {
-            const placeholders = providers.map(() => "?").join(", ");
-            sql += ` AND d.provider IN (${placeholders})`;
-            params.push(...providers.map((p) => p.toLowerCase()));
-        }
-        sql += ` ORDER BY d.provider, rank LIMIT 30`;
-        const rows = db.prepare(sql).all(...params);
-        if (rows.length === 0) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No documentation found for "${topic}". Try different terms.`,
-                    },
-                ],
-            };
-        }
-        // Group by provider
-        const grouped = new Map();
-        for (const r of rows) {
-            const entries = grouped.get(r.provider) ?? [];
-            entries.push(`### ${r.title}\n${r.content}`);
-            grouped.set(r.provider, entries);
-        }
-        const sections = [...grouped.entries()]
-            .map(([p, chunks]) => `## ${p}\n\n${chunks.slice(0, 3).join("\n\n")}`)
-            .join("\n\n---\n\n");
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Comparison for "${topic}" across ${grouped.size} provider(s):\n\n${sections}`,
-                },
-            ],
-        };
+        return handler(db);
     }
     finally {
         db.close();
     }
-});
-// Tool: request_update
-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)"),
-    provider: z.string().max(100).describe("Provider name (existing or proposed). Examples: 'statsbomb', 'mplsoccer', 'floodlight'"),
-    reason: z.string().max(2000).describe("Why this update is needed. Be specific: version bump, missing event types, new API endpoints, etc."),
-    suggested_urls: z.array(z.string().url().max(500)).max(10).optional().describe("URLs for documentation sources (readthedocs, GitHub, llms.txt, etc.)"),
-}, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ type, provider, reason, suggested_urls }) => {
-    const qdb = openQueueDb();
-    try {
-        // Hard cap on queue size
-        const countRow = qdb.prepare("SELECT COUNT(*) as cnt FROM requests").get();
-        if (countRow.cnt >= 500) {
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: `Request queue is full (${countRow.cnt} entries). Please file an issue at https://github.com/withqwerty/football-docs/issues instead.`,
-                    },
-                ],
-            };
-        }
-        // Cooldown: reject if same provider was requested in last 7 days
-        const recentRequest = qdb.prepare(`SELECT id, requested_at FROM requests
-         WHERE lower(provider) = lower(?) AND status = 'pending'
-           AND datetime(requested_at) > datetime('now', '-7 days')
-         LIMIT 1`).get(provider);
-        if (recentRequest) {
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: `A pending request for "${provider}" already exists (from ${recentRequest.requested_at}). Requests have a 7-day cooldown to prevent duplicate work. Request ID: ${recentRequest.id}`,
-                    },
-                ],
-            };
-        }
-        const id = `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-        qdb.prepare(`INSERT INTO requests (id, type, provider, reason, suggested_urls, requested_at, status)
-         VALUES (?, ?, ?, ?, ?, ?, 'pending')`).run(id, type, provider.toLowerCase(), reason, suggested_urls ? JSON.stringify(suggested_urls) : null, new Date().toISOString());
-        const typeLabel = {
-            new_provider: "New provider request",
-            recrawl: "Recrawl request",
-            flag_outdated: "Outdated docs flag",
-            suggest_source: "Source suggestion",
-        }[type];
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `${typeLabel} queued for "${provider}" (ID: ${id}).\n\nReason: ${reason}${suggested_urls?.length ? `\nSuggested URLs:\n${suggested_urls.map((u) => `  - ${u}`).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.`,
-                },
-            ],
-        };
-    }
-    finally {
-        qdb.close();
-    }
-});
-// Tool: resolve_entity
-const REEP_API = "https://reep-api.rahulkeerthi2-95d.workers.dev";
-server.tool("resolve_entity", "Resolve a football entity (player, team, or coach) to get cross-provider IDs. Use when you need to map between Transfermarkt, FBref, Sofascore, Opta, and other provider IDs, or when you need to look up a player/team/coach by name.", {
-    name: z.string().optional().describe("Entity name to search for (e.g. 'Cole Palmer', 'Arsenal'). Fuzzy match on name and aliases."),
-    provider: z.string().optional().describe("Source provider for ID resolution (e.g. 'transfermarkt', 'fbref', 'sofascore', 'opta', 'soccerway')"),
-    id: z.string().optional().describe("ID from the source provider to resolve to all other IDs"),
-    qid: z.string().optional().describe("Wikidata QID for direct lookup (e.g. 'Q99760796')"),
-    type: z.enum(["player", "team", "coach"]).optional().describe("Filter results by entity type"),
-}, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ name, provider, id, qid, type }) => {
-    let url;
-    if (qid) {
-        url = `${REEP_API}/lookup?qid=${encodeURIComponent(qid)}`;
-    }
-    else if (provider && id) {
-        url = `${REEP_API}/resolve?provider=${encodeURIComponent(provider)}&id=${encodeURIComponent(id)}`;
-    }
-    else if (name) {
-        url = `${REEP_API}/search?name=${encodeURIComponent(name)}&limit=10`;
-        if (type)
-            url += `&type=${encodeURIComponent(type)}`;
-    }
-    else {
-        return {
-            isError: true,
-            content: [{
-                    type: "text",
-                    text: "Provide at least one of: name, qid, or provider+id. Examples:\n- name: 'Cole Palmer'\n- provider: 'transfermarkt', id: '568177'\n- qid: 'Q99760796'",
-                }],
-        };
-    }
-    try {
-        const resp = await fetch(url);
-        if (!resp.ok) {
-            return {
-                isError: true,
-                content: [{ type: "text", text: `Reep API error: ${resp.status} ${resp.statusText}` }],
-            };
-        }
-        const data = await resp.json();
-        if (!data.results?.length) {
-            return {
-                content: [{ type: "text", text: "No entities found matching the query." }],
-            };
-        }
-        const formatted = data.results.map((e) => {
-            const ids = e.external_ids;
-            const idLines = ids
-                ? Object.entries(ids).map(([k, v]) => `  ${k}: ${v}`).join("\n")
-                : "  (none)";
-            const bio = [
-                e.date_of_birth && `DOB: ${e.date_of_birth}`,
-                e.nationality && `Nationality: ${e.nationality}`,
-                e.position && `Position: ${e.position}`,
-                e.height_cm && `Height: ${e.height_cm}cm`,
-                e.country && `Country: ${e.country}`,
-                e.stadium && `Stadium: ${e.stadium}`,
-            ].filter(Boolean).join(" | ");
-            return `### ${e.name_en} (${e.type})\nWikidata: ${e.qid}${e.aliases_en ? `\nAliases: ${e.aliases_en}` : ""}${bio ? `\n${bio}` : ""}\nProvider IDs:\n${idLines}`;
-        }).join("\n\n");
-        return {
-            content: [{
-                    type: "text",
-                    text: `Found ${data.results.length} result(s):\n\n${formatted}`,
-                }],
-        };
-    }
-    catch (err) {
-        return {
-            isError: true,
-            content: [{ type: "text", text: `Failed to reach Reep API: ${err instanceof Error ? err.message : String(err)}` }],
-        };
-    }
-});
-// ── Start ───────────────────────────────────────────────────────────────
+}
+export function createFootballDocsServer() {
+    const server = new McpServer({
+        name: "nutmeg-football-docs",
+        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'"),
+        provider: z
+            .string()
+            .optional()
+            .describe("Filter to a specific provider: opta, statsbomb, wyscout, sportmonks, fbref, understat, kloppy, or leave empty for all"),
+        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("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."),
+    }, { 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)"),
+        provider: z
+            .string()
+            .max(100)
+            .describe("Provider name (existing or proposed). Examples: 'statsbomb', 'mplsoccer', 'floodlight'"),
+        reason: z
+            .string()
+            .max(2000)
+            .describe("Why this update is needed. Be specific: version bump, missing event types, new API endpoints, etc."),
+        suggested_urls: z
+            .array(z.string().url().max(500))
+            .max(10)
+            .optional()
+            .describe("URLs for documentation sources (readthedocs, GitHub, llms.txt, etc.)"),
+    }, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async (args) => withQueueDb((db) => requestUpdate(db, args)));
+    server.tool("resolve_entity", "Resolve a football entity (player, team, or coach) to get cross-provider IDs. Use when you need to map between Transfermarkt, FBref, Sofascore, Opta, and other provider IDs, or when you need to look up a player/team/coach by name.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Entity name to search for (e.g. 'Cole Palmer', 'Arsenal'). Fuzzy match on name and aliases."),
+        provider: z
+            .string()
+            .optional()
+            .describe("Source provider for ID resolution (e.g. 'transfermarkt', 'fbref', 'sofascore', 'opta', 'soccerway')"),
+        id: z.string().optional().describe("ID from the source provider to resolve to all other IDs"),
+        qid: z.string().optional().describe("Wikidata QID for direct lookup (e.g. 'Q99760796')"),
+        type: z.enum(["player", "team", "coach"]).optional().describe("Filter results by entity type"),
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async (args) => resolveEntity(args));
+    return server;
+}
 async function main() {
     const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await createFootballDocsServer().connect(transport);
+}
+const isDirectRun = process.argv[1]
+    ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+    : false;
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error("Failed to start nutmeg docs server:", error);
+        process.exit(1);
+    });
 }
-main().catch((err) => {
-    console.error("Failed to start nutmeg docs server:", err);
-    process.exit(1);
-});

package/dist/tools.d.ts

@@ -0,0 +1,52 @@
+import type Database from "better-sqlite3";
+export declare const TOOL_NAMES: readonly ["search_docs", "list_providers", "compare_providers", "request_update", "resolve_entity"];
+type TextContent = {
+    type: "text";
+    text: string;
+};
+export type ToolResponse = {
+    isError?: boolean;
+    content: TextContent[];
+};
+export type SearchDocsArgs = {
+    query: string;
+    provider?: string;
+    max_results?: number;
+};
+export type CompareProvidersArgs = {
+    topic: string;
+    providers?: string[];
+};
+export type RequestUpdateArgs = {
+    type: "new_provider" | "recrawl" | "flag_outdated" | "suggest_source";
+    provider: string;
+    reason: string;
+    suggested_urls?: string[];
+};
+export type ResolveEntityArgs = {
+    name?: string;
+    provider?: string;
+    id?: string;
+    qid?: string;
+    type?: "player" | "team" | "coach";
+};
+/**
+ * Build a safe FTS5 MATCH query from user text.
+ *
+ * User questions are usually natural language, not exact doc phrases. Joining
+ * searchable tokens with AND keeps results precise while still allowing queries
+ * like "Opta qualifier 76" to match docs that contain those tokens separately.
+ */
+export declare function sanitiseFtsQuery(query: string): string;
+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;
+export declare function requestUpdate(db: Database.Database, args: RequestUpdateArgs, options?: {
+    now?: Date;
+    requestId?: string;
+}): ToolResponse;
+export declare function resolveEntity(args: ResolveEntityArgs, options?: {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<ToolResponse>;
+export {};