openfoot-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Dumitriu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# openfoot-mcp
+
+MCP server for the [OpenFootAPI](https://openfootapi.com/) football intelligence API. Gives an LLM client real football data — fixtures, standings, lineups, live events, **shot-level xG with pitch coordinates**, and model-derived fair odds — instead of a hallucinated scoreline.
+
+12 tools, 1 prompt. Node ≥ 20, no build step.
+
+## Install
+
+```bash
+npx openfoot-mcp
+```
+
+Set your API key in the environment. Free tier: 5,000 requests/month. Get a key at [openfootapi.com/pricing](https://openfootapi.com/pricing).
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "openfoot": {
+      "command": "npx",
+      "args": ["-y", "openfoot-mcp"],
+      "env": { "OPENFOOT_API_KEY": "of_live_..." }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf / any stdio MCP client
+
+Same block, in that client's MCP config file.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `openfoot_competitions` | Supported competitions, season metadata, data source and licence per competition |
+| `openfoot_search` | Free-text team/competition name → stable IDs |
+| `openfoot_matches` | Fixtures and results, filtered by date / competition / team / status / season / round, cursor-paginated |
+| `openfoot_standings` | Standings table for a competition and season |
+| `openfoot_match_lineups` | Starting XI, bench, formation |
+| `openfoot_match_events` | Goals, cards, substitutions, commentary timeline |
+| `openfoot_match_xg` | One entry per shot: pitch coordinates + xG value |
+| `openfoot_match_context` | Derived context — form, head-to-head, pre-computed signals |
+| `openfoot_league_xg` | League xG table: xG for, xG against, over/under-performance vs actual goals |
+| `openfoot_odds` | Bookmaker benchmark + implied fair probabilities. Informational, not betting advice |
+| `openfoot_quota` | Remaining monthly quota — this call does not consume quota |
+| `openfoot_health` | Reachability check. Works without an API key |
+
+Prompt: `scout_team_form` — resolve a team, pull its last 5 matches, read the xG behind the results.
+
+**Start with `openfoot_search`** to resolve IDs. Guessing IDs wastes quota: 404s and empty results are metered like any other request.
+
+## Coverage, stated honestly
+
+The catalogue lists 75 competitions. **Depth is not uniform, and the catalogue is wider than the deep coverage.**
+
+- **Deepest:** Bundesliga, 2. Bundesliga, DFB Pokal, Superliga României
+- **Expanded European:** Eredivisie, Primeira Liga, Süper Lig, Pro League, Scottish Premiership
+- **Historical / analytics only:** Premier League, La Liga, Serie A, Ligue 1 (xG is Understat-derived)
+
+Call `openfoot_competitions` and check your league before you build on it.
+
+## Quota behaviour
+
+- Free: 5,000 requests/month, 15 req/min. Developer $14/month: 250,000 requests/month, 100 req/min, includes xG, shot maps, lineups, live events and fair odds. Pro $39/month: 2,000,000/month, 250 req/min.
+- **No overage billing.** When the quota is spent the API returns 429; this server surfaces that as a `quota_or_rate_limit` error rather than an empty result.
+- Quota resets on the 1st of the month, UTC.
+- Every request is metered, including 404s and empty results.
+
+## When this is the wrong tool
+
+- **High-frequency live polling across many competitions.** A monthly quota is the wrong shape for it — a per-day or per-second plan elsewhere will cost you less.
+- **Leagues outside the deep-coverage list above.**
+- **You need a contractual SLA, uptime credits or a named support contact.** Not offered at these prices.
+
+## Development
+
+```bash
+npm install
+npm run smoke   # boots the server over stdio, lists tools, calls health
+```
+
+`npm run smoke` works without an API key: `openfoot_health` returns live status, and a key-gated tool returns a readable `missing_api_key` error so you can tell "not configured" from "broken".
+
+MIT.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "openfoot-mcp",
+  "version": "0.1.0",
+  "description": "Native Model Context Protocol (MCP) server for OpenFootAPI — football fixtures, standings, lineups, events timeline, shot-level xG and match context.",
+  "license": "MIT",
+  "homepage": "https://openfootapi.com",
+  "type": "module",
+  "bin": {
+    "openfoot-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "scripts/smoke.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "football",
+    "soccer",
+    "xg",
+    "expected-goals",
+    "football-api",
+    "sports-data",
+    "openfoot"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "smoke": "node scripts/smoke.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  }
+}

package/scripts/smoke.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Smoke test: boots the server over stdio, lists tools and prompts, and calls
+ * openfoot_health (the only tool that works without an API key).
+ * Run with: npm run smoke
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import assert from "node:assert/strict";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = resolve(here, "../src/index.js");
+
+const transport = new StdioClientTransport({ command: process.execPath, args: [entry] });
+const client = new Client({ name: "smoke", version: "0.0.0" });
+await client.connect(transport);
+
+const { tools } = await client.listTools();
+console.log(`tools (${tools.length}):`);
+for (const t of tools) console.log(`  - ${t.name}`);
+assert.equal(tools.length, 12, "Expected exactly 12 tools registered");
+
+const { prompts } = await client.listPrompts();
+console.log(`prompts (${prompts.length}): ${prompts.map((p) => p.name).join(", ")}`);
+assert.equal(prompts.length, 1, "Expected exactly 1 prompt registered");
+assert.equal(prompts[0].name, "scout_team_form");
+
+const health = await client.callTool({ name: "openfoot_health", arguments: {} });
+console.log("health ->", health.content?.[0]?.text?.slice(0, 300));
+assert.equal(health.isError, undefined, "Health check should not be an error");
+const healthData = JSON.parse(health.content[0].text);
+assert.equal(healthData.data?.status, "operational", "Health status must be operational");
+
+const gated = await client.callTool({ name: "openfoot_competitions", arguments: {} });
+console.log("competitions ->", gated.content?.[0]?.text?.slice(0, 300));
+assert.equal(gated.isError, true, "Gated call without key must return isError: true");
+const gatedData = JSON.parse(gated.content[0].text);
+assert.equal(gatedData.error, "missing_api_key");
+
+await client.close();
+console.log("\n✅ Smoke test passed all strict assertions.");

package/src/index.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * OpenFootAPI MCP server.
+ *
+ * Exposes the OpenFootAPI football intelligence API (fixtures, standings, lineups,
+ * live events, shot-level xG, fair odds) as MCP tools so an LLM client can
+ * query real football data instead of hallucinating.
+ *
+ * Auth: set OPENFOOT_API_KEY (keys use the of_live_ prefix).
+ * Free tier: 5,000 requests/month.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const BASE_URL = process.env.OPENFOOT_BASE_URL ?? "https://openfootapi.com";
+const API_KEY = process.env.OPENFOOT_API_KEY ?? "";
+const VERSION = "0.1.0";
+
+/** Endpoints that never need a key, so the server is useful before signup. */
+const PUBLIC_PATHS = new Set(["/v1/health"]);
+
+async function call(path, query = {}) {
+  const url = new URL(path, BASE_URL);
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  }
+
+  if (!API_KEY && !PUBLIC_PATHS.has(path)) {
+    return {
+      error: "missing_api_key",
+      message:
+        "OPENFOOT_API_KEY is not set. Create a free key (5,000 requests/month) at https://openfootapi.com/pricing and put it in the server's env.",
+    };
+  }
+
+  const headers = { Accept: "application/json", "User-Agent": `openfoot-mcp/${VERSION}` };
+  if (API_KEY) headers.Authorization = `Bearer ${API_KEY}`;
+
+  let res;
+  try {
+    res = await fetch(url, { headers, signal: AbortSignal.timeout(20_000) });
+  } catch (err) {
+    return { error: "network_error", message: String(err?.message ?? err), url: url.toString() };
+  }
+
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = { raw: text.slice(0, 2000) };
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    return { error: "unauthorized", status: res.status, message: "API key missing, invalid or revoked.", body };
+  }
+  if (res.status === 429) {
+    return {
+      error: "quota_or_rate_limit",
+      status: 429,
+      message:
+        "Rate limit or monthly quota hit. There is no overage billing — the quota resets on the 1st of the month UTC. Check remaining quota with openfoot_quota.",
+      body,
+    };
+  }
+  if (!res.ok) return { error: "http_error", status: res.status, body };
+
+  return body;
+}
+
+function jsonResult(data) {
+  const isErr = Boolean(data && typeof data === "object" && (data.error || data.status >= 400));
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    ...(isErr ? { isError: true } : {}),
+  };
+}
+
+/** Wrap a handler so a thrown error becomes a readable tool result, not a crash. */
+function tool(fn) {
+  return async (args) => {
+    try {
+      return jsonResult(await fn(args ?? {}));
+    } catch (err) {
+      return { content: [{ type: "text", text: `Tool failed: ${String(err?.message ?? err)}` }], isError: true };
+    }
+  };
+}
+
+const server = new McpServer({ name: "openfoot", version: VERSION });
+
+/* ---------------------------------------------------------------- discovery */
+
+server.registerTool(
+  "openfoot_competitions",
+  {
+    title: "List competitions",
+    description:
+      "List the competitions OpenFootAPI supports, with IDs, country codes, tiers and provider coverage. Use this first when you need a valid competition ID.",
+    inputSchema: {},
+  },
+  tool(() => call("/v1/competitions")),
+);
+
+server.registerTool(
+  "openfoot_search",
+  {
+    title: "Search teams and competitions",
+    description: "Search for teams or competitions by fuzzy name to find their canonical OpenFootAPI IDs.",
+    inputSchema: {
+      q: z.string().min(1).describe("Search query, e.g. 'Arsenal', 'Real Madrid', 'Bundesliga'"),
+      type: z.enum(["team", "competition"]).optional().describe("Optional filter by entity type"),
+    },
+  },
+  tool(({ q, type }) => call("/v1/search", { q, type })),
+);
+
+/* ------------------------------------------------------------------ matches */
+
+server.registerTool(
+  "openfoot_matches",
+  {
+    title: "List matches",
+    description:
+      "List fixtures and results with scores, kickoff times, status and teams. Filter by competition, team, status, date or season.",
+    inputSchema: {
+      competition: z.string().optional().describe("Competition ID, e.g. 'comp_premier_league_eng', 'comp_bundesliga_de'"),
+      team: z.string().optional().describe("Team ID or fuzzy name"),
+      status: z.enum(["SCHEDULED", "LIVE", "IN_PLAY", "PAUSED", "FINISHED", "POSTPONED", "CANCELLED"]).optional(),
+      from: z.string().optional().describe("Start date in YYYY-MM-DD format"),
+      to: z.string().optional().describe("End date in YYYY-MM-DD format"),
+      season: z.string().optional().describe("Season in YYYY/YY format (e.g. '2025/26')"),
+      limit: z.number().int().min(1).max(100).optional().describe("Max matches to return (default 50, max 100)"),
+    },
+  },
+  tool(({ competition, team, status, from, to, season, limit }) =>
+    call("/v1/matches", { competition, team, status, from, to, season, limit }),
+  ),
+);
+
+server.registerTool(
+  "openfoot_standings",
+  {
+    title: "Get standings",
+    description: "Get the league table for a competition — rank, points, played, won, drawn, lost, goals for/against, goal difference and recent form.",
+    inputSchema: {
+      competition: z.string().describe("Competition ID, e.g. 'comp_premier_league_eng', 'comp_bundesliga_de'"),
+      season: z.string().optional().describe("Season in YYYY/YY format (e.g. '2025/26')"),
+    },
+  },
+  tool(({ competition, season }) => call("/v1/standings", { competition, season })),
+);
+
+/* ----------------------------------------------------------- match deep dives */
+
+server.registerTool(
+  "openfoot_match_lineups",
+  {
+    title: "Get match lineups",
+    description: "Confirmed starting XI, benches and formations for a match.",
+    inputSchema: {
+      matchId: z.string().describe("Match ID returned by openfoot_matches"),
+    },
+  },
+  tool(({ matchId }) => call(`/v1/matches/${encodeURIComponent(matchId)}/lineups`)),
+);
+
+server.registerTool(
+  "openfoot_match_events",
+  {
+    title: "Get match events",
+    description: "Timeline of events in a match: goals, assists, yellow/red cards, substitutions, VAR checks, plus live minute-by-minute text commentary.",
+    inputSchema: {
+      matchId: z.string().describe("Match ID returned by openfoot_matches"),
+    },
+  },
+  tool(({ matchId }) => call(`/v1/matches/${encodeURIComponent(matchId)}/events`)),
+);
+
+server.registerTool(
+  "openfoot_match_xg",
+  {
+    title: "Get match shot map & xG",
+    description: "Shot-level Expected Goals data with coordinates on the pitch, shot type, situation (open play, penalty, corner), outcome and cumulative xG.",
+    inputSchema: {
+      matchId: z.string().describe("Match ID returned by openfoot_matches"),
+    },
+  },
+  tool(({ matchId }) => call(`/v1/matches/${encodeURIComponent(matchId)}/xg`)),
+);
+
+server.registerTool(
+  "openfoot_match_context",
+  {
+    title: "Get match context dossier",
+    description:
+      "A complete pre-match or post-match dossier assembled for analysis: recent form, Elo delta, rest days, head-to-head record and model-derived fair match probabilities.",
+    inputSchema: {
+      matchId: z.string().describe("Match ID returned by openfoot_matches"),
+    },
+  },
+  tool(({ matchId }) => call(`/v1/matches/${encodeURIComponent(matchId)}/context`)),
+);
+
+/* ---------------------------------------------------------------- analytics */
+
+server.registerTool(
+  "openfoot_league_xg",
+  {
+    title: "Get league xG analytics",
+    description:
+      "Season-level Expected Goals analytics for a league — teams ranked by xG generated, xG conceded, over/underperformance vs real goals, and shot efficiency.",
+    inputSchema: {
+      league: z.string().describe("League code, e.g. 'epl', 'la-liga', 'bundesliga', 'serie-a', 'ligue-1'"),
+      season: z.string().optional().describe("Season year (e.g. '2025' for 2025/26)"),
+    },
+  },
+  tool(({ league, season }) => call("/v1/analytics/xg", { league, season })),
+);
+
+server.registerTool(
+  "openfoot_odds",
+  {
+    title: "Get match odds",
+    description: "Fair 1X2 and over/under 2.5 probabilities derived from underlying team form, Elo delta and xG performance.",
+    inputSchema: {
+      matchId: z.string().optional().describe("Specific match ID"),
+      competition: z.string().optional().describe("Competition ID to list odds for"),
+      date: z.string().optional().describe("Date in YYYY-MM-DD format"),
+    },
+  },
+  tool(({ matchId, competition, date }) => call("/v1/odds", { matchId, competition, date })),
+);
+
+/* ----------------------------------------------------------------- account */
+
+server.registerTool(
+  "openfoot_quota",
+  {
+    title: "Check API quota",
+    description: "Check your API key's tier, monthly request allowance, requests used this month and reset date.",
+    inputSchema: {},
+  },
+  tool(() => call("/v1/account/quota")),
+);
+
+server.registerTool(
+  "openfoot_health",
+  {
+    title: "Check upstream health",
+    description: "Check the operational status of OpenFootAPI without authentication.",
+    inputSchema: {},
+  },
+  tool(() => call("/v1/health")),
+);
+
+/* ------------------------------------------------------------------ prompt */
+
+server.registerPrompt(
+  "scout_team_form",
+  {
+    title: "Scout a team's recent form",
+    description: "Build a dossier on a team: recent results, xG trend, upcoming fixtures and key strengths.",
+    arguments: [
+      {
+        name: "team",
+        description: "Team name, e.g. 'Arsenal' or 'Bayern Munich'",
+        required: true,
+      },
+    ],
+  },
+  (args) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: `Please scout ${args.team}. First use openfoot_search to find their team ID, then fetch their last 5 matches using openfoot_matches (with status=FINISHED) and their next fixture (with status=SCHEDULED). If xG is available, summarize their attacking efficiency and defensive stability.`,
+        },
+      },
+    ],
+  }),
+);
+
+/* ----------------------------------------------------------------- startup */
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[openfoot-mcp v${VERSION}] connected to stdio`);
+}
+
+main().catch((err) => {
+  console.error("Fatal error in openfoot-mcp:", err);
+  process.exit(1);
+});