football-docs 0.5.2 → 0.6.1

package/README.md

@@ -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
 

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

@@ -3,11 +3,16 @@
  *
  * 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;
+export declare function main(): Promise<void>;

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 ───────────────────────────────────────────────────────────────
-async function main() {
+}
+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;
+}
+export 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 {};

package/dist/tools.js

@@ -0,0 +1,235 @@
+export const TOOL_NAMES = [
+    "search_docs",
+    "list_providers",
+    "compare_providers",
+    "request_update",
+    "resolve_entity",
+];
+const QUERY_STOP_WORDS = new Set(["and", "or", "not", "near"]);
+function textResult(text, isError = false) {
+    return {
+        isError: isError || undefined,
+        content: [{ type: "text", text }],
+    };
+}
+function extractFtsTokens(query) {
+    const rawTokens = query.match(/[\p{L}\p{N}_]+/gu) ?? [];
+    const tokens = rawTokens
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token.length > 0 && !QUERY_STOP_WORDS.has(token));
+    return [...new Set(tokens)];
+}
+function quoteFtsToken(token) {
+    return `"${token.replace(/"/g, '""')}"`;
+}
+/**
+ * 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 function sanitiseFtsQuery(query) {
+    const tokens = extractFtsTokens(query);
+    if (tokens.length === 0)
+        return '""';
+    return tokens.map(quoteFtsToken).join(" AND ");
+}
+function relaxedFtsQuery(query) {
+    const tokens = extractFtsTokens(query);
+    if (tokens.length === 0)
+        return '""';
+    return tokens.map(quoteFtsToken).join(" OR ");
+}
+function normaliseProvider(provider) {
+    return provider.trim().toLowerCase();
+}
+function normaliseLimit(value, defaultValue, maxValue) {
+    if (value === undefined || !Number.isFinite(value))
+        return defaultValue;
+    return Math.min(Math.max(Math.trunc(value), 1), maxValue);
+}
+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,
+           rank * -1 as relevance
+    FROM docs_fts
+    JOIN docs d ON d.id = docs_fts.rowid
+    WHERE docs_fts MATCH ?
+  `;
+    const params = [matchQuery];
+    if (provider) {
+        sql += " AND d.provider = ?";
+        params.push(normaliseProvider(provider));
+    }
+    sql += " ORDER BY rank LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params);
+}
+function compareRows(db, matchQuery, providers) {
+    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 = [matchQuery];
+    if (providers && providers.length > 0) {
+        const placeholders = providers.map(() => "?").join(", ");
+        sql += ` AND d.provider IN (${placeholders})`;
+        params.push(...providers.map(normaliseProvider));
+    }
+    sql += " ORDER BY d.provider, rank LIMIT 30";
+    return db.prepare(sql).all(...params);
+}
+function sourceLabel(row) {
+    if (row.source_type === "curated") {
+        return "**Source:** curated by football-docs contributors";
+    }
+    return `**Source:** ${row.source_type}${row.source_url ? ` (${row.source_url})` : ""}${row.upstream_version ? ` | v${row.upstream_version}` : ""}`;
+}
+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);
+    if (rows.length === 0 && fallbackQuery !== strictQuery) {
+        rows = searchRows(db, fallbackQuery, args.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 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}`);
+}
+export function listProviders(db) {
+    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 row of rows) {
+        const entry = byProvider.get(row.provider) ?? { categories: [], total: 0 };
+        entry.categories.push(`${row.category} (${row.chunks})`);
+        entry.total += row.chunks;
+        byProvider.set(row.provider, entry);
+    }
+    const lines = [...byProvider.entries()]
+        .map(([provider, info]) => {
+        return `**${provider}** (${info.total} chunks): ${info.categories.join(", ")}`;
+    })
+        .join("\n");
+    return textResult(`Indexed providers:\n\n${lines}`);
+}
+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);
+    }
+    if (rows.length === 0) {
+        return textResult(`No documentation found for "${args.topic}". Try different terms.`);
+    }
+    const grouped = new Map();
+    for (const row of rows) {
+        const entries = grouped.get(row.provider) ?? [];
+        entries.push(`### ${row.title}\n${row.content}`);
+        grouped.set(row.provider, entries);
+    }
+    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}`);
+}
+export function requestUpdate(db, args, options = {}) {
+    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')
+       LIMIT 1`)
+        .get(args.provider);
+    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);
+    const typeLabel = {
+        new_provider: "New provider request",
+        recrawl: "Recrawl request",
+        flag_outdated: "Outdated docs flag",
+        suggest_source: "Source suggestion",
+    }[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.`);
+}
+export async function resolveEntity(args, options = {}) {
+    const baseUrl = options.baseUrl ?? "https://reep-api.rahulkeerthi2-95d.workers.dev";
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let url;
+    if (args.qid) {
+        url = `${baseUrl}/lookup?qid=${encodeURIComponent(args.qid)}`;
+    }
+    else if (args.provider && args.id) {
+        url = `${baseUrl}/resolve?provider=${encodeURIComponent(args.provider)}&id=${encodeURIComponent(args.id)}`;
+    }
+    else if (args.name) {
+        url = `${baseUrl}/search?name=${encodeURIComponent(args.name)}&limit=10`;
+        if (args.type)
+            url += `&type=${encodeURIComponent(args.type)}`;
+    }
+    else {
+        return textResult("Provide at least one of: name, qid, or provider+id. Examples:\n- name: 'Cole Palmer'\n- provider: 'transfermarkt', id: '568177'\n- qid: 'Q99760796'", true);
+    }
+    try {
+        const response = await fetchImpl(url);
+        if (!response.ok) {
+            return textResult(`Reep API error: ${response.status} ${response.statusText}`, true);
+        }
+        const data = (await response.json());
+        if (!data.results?.length) {
+            return textResult("No entities found matching the query.");
+        }
+        const formatted = data.results
+            .map((entity) => {
+            const ids = entity.external_ids;
+            const idLines = ids
+                ? Object.entries(ids)
+                    .map(([provider, id]) => `  ${provider}: ${id}`)
+                    .join("\n")
+                : "  (none)";
+            const bio = [
+                entity.date_of_birth && `DOB: ${entity.date_of_birth}`,
+                entity.nationality && `Nationality: ${entity.nationality}`,
+                entity.position && `Position: ${entity.position}`,
+                entity.height_cm && `Height: ${entity.height_cm}cm`,
+                entity.country && `Country: ${entity.country}`,
+                entity.stadium && `Stadium: ${entity.stadium}`,
+            ]
+                .filter(Boolean)
+                .join(" | ");
+            return `### ${entity.name_en} (${entity.type})\nWikidata: ${entity.qid}${entity.aliases_en ? `\nAliases: ${entity.aliases_en}` : ""}${bio ? `\n${bio}` : ""}\nProvider IDs:\n${idLines}`;
+        })
+            .join("\n\n");
+        return textResult(`Found ${data.results.length} result(s):\n\n${formatted}`);
+    }
+    catch (error) {
+        return textResult(`Failed to reach Reep API: ${error instanceof Error ? error.message : String(error)}`, true);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "football-docs",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Searchable football data provider documentation for AI coding agents. Like Context7 for football data.",
   "type": "module",
   "mcpName": "io.github.withqwerty/football-docs",
@@ -59,20 +59,9 @@
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.15.2",
     "@types/turndown": "^5.0.6",
-    "tsx": "^4.19.4",
+    "tsx": "^4.23.0",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.5"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3",
-      "esbuild"
-    ],
-    "overrides": {
-      "vite@<8.0.5": ">=8.0.5",
-      "fast-uri@<3.1.2": ">=3.1.2",
-      "qs@<6.15.2": ">=6.15.2"
-    }
+    "vitest": "^4.1.10"
   },
   "files": [
     "dist/",