football-docs 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,11 @@
 
 Searchable football data provider documentation for AI coding agents. Like [Context7](https://context7.com) for football data.
 
-An MCP server that gives your AI agent instant access to documentation for Opta, StatsBomb, Wyscout, SportMonks, socceraction, kloppy, soccerdata, mplsoccer, databallpy, and free sources (FBref, Understat, ClubElo). Search event types, qualifier IDs, coordinate systems, API endpoints, and cross-provider mappings.
+**Who it's for:** Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot, Windsurf) 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 16 football data providers — event types, qualifier IDs, coordinate systems, API endpoints, data models, and cross-provider comparisons. 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.
 
 MCP ([Model Context Protocol](https://modelcontextprotocol.io)) is a standard for connecting AI coding tools to external data sources.
 

package/dist/index.js

@@ -79,7 +79,7 @@ server.tool("search_docs", "Search football data provider documentation. Use for
         .optional()
         .default(10)
         .describe("Maximum number of results to return (default 10)"),
-}, async ({ query, provider, max_results }) => {
+}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ query, provider, max_results }) => {
     const db = openDb();
     try {
         const safeQuery = sanitiseFtsQuery(query);
@@ -131,7 +131,7 @@ server.tool("search_docs", "Search football data provider documentation. Use for
     }
 });
 // 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.", {}, async () => {
+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 () => {
     const db = openDb();
     try {
         const rows = db
@@ -167,7 +167,7 @@ server.tool("list_providers", "List all indexed football data providers, their d
 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."),
-}, async ({ topic, providers }) => {
+}, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ topic, providers }) => {
     const db = openDb();
     try {
         const safeTopic = sanitiseFtsQuery(topic);
@@ -225,7 +225,7 @@ server.tool("request_update", "Request that a provider's documentation be added,
     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.)"),
-}, async ({ type, provider, reason, suggested_urls }) => {
+}, { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ type, provider, reason, suggested_urls }) => {
     const qdb = openQueueDb();
     try {
         // Hard cap on queue size
@@ -279,6 +279,79 @@ server.tool("request_update", "Request that a provider's documentation be added,
         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() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "football-docs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Searchable football data provider documentation for AI coding agents. Like Context7 for football data.",
   "type": "module",
+  "mcpName": "io.github.withqwerty/football-docs",
   "bin": {
     "football-docs": "bin/serve.js"
   },