footballbin-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FootballBin
+
+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,278 @@
+# FootballBin MCP Server
+
+A Model Context Protocol (MCP) server that provides AI agents with access to football match predictions for the Premier League and Champions League.
+
+## What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that enables AI agents to securely access external tools and data sources. This server implements MCP to expose football match predictions to any MCP-compatible AI client.
+
+## Features
+
+- **AI Match Predictions**: Get predictions for upcoming matches including:
+  - Half-time score
+  - Full-time score
+  - Next goal scorer
+  - Corner count predictions
+
+- **Supported Leagues**:
+  - Premier League (EPL)
+  - UEFA Champions League (UCL)
+
+- **Key Players**: Each match includes key player insights with reasoning
+
+## Live Endpoint
+
+The FootballBin MCP server is publicly available:
+
+```
+https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp
+```
+
+No API key required.
+
+## Usage
+
+### Connect via Claude Desktop
+
+Add this to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "footballbin": {
+      "url": "https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp"
+    }
+  }
+}
+```
+
+### Connect via Claude.ai
+
+1. Go to **Settings > Connectors**
+2. Click **Add custom connector**
+3. Enter the endpoint URL
+4. Start asking about football predictions!
+
+### Direct API Usage
+
+#### List Available Tools
+
+```bash
+curl -X POST https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/list",
+    "id": 1
+  }'
+```
+
+#### Get Premier League Predictions
+
+```bash
+curl -X POST https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "get_match_predictions",
+      "arguments": {
+        "league": "premier_league"
+      }
+    },
+    "id": 1
+  }'
+```
+
+#### Get Champions League Predictions
+
+```bash
+curl -X POST https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "get_match_predictions",
+      "arguments": {
+        "league": "ucl"
+      }
+    },
+    "id": 1
+  }'
+```
+
+#### Filter by Team
+
+```bash
+curl -X POST https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "tools/call",
+    "params": {
+      "name": "get_match_predictions",
+      "arguments": {
+        "league": "epl",
+        "home_team": "liverpool"
+      }
+    },
+    "id": 1
+  }'
+```
+
+## Tool: get_match_predictions
+
+### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `league` | string | Yes | League identifier. Accepts: `premier_league`, `epl`, `pl`, `champions_league`, `ucl`, `cl` |
+| `matchweek` | number | No | Matchweek number (defaults to current matchweek) |
+| `home_team` | string | No | Filter by home team (e.g., `chelsea`, `arsenal`, `man_utd`) |
+| `away_team` | string | No | Filter by away team (e.g., `liverpool`, `wolves`) |
+
+### Team Aliases
+
+The API supports common team aliases:
+
+| Alias | Maps To |
+|-------|---------|
+| `united`, `mufc` | `man_utd` |
+| `city`, `mcfc` | `man_city` |
+| `spurs` | `tottenham` |
+| `villa` | `aston_villa` |
+| `forest` | `nottm_forest` |
+| `palace` | `crystal_palace` |
+| `gunners` | `arsenal` |
+| `reds` | `liverpool` |
+| `blues` | `chelsea` |
+| `barca` | `barcelona` |
+| `real` | `real_madrid` |
+| `bayern_munich` | `bayern` |
+
+### Response Format
+
+```json
+{
+  "league": "premier_league",
+  "matchweek": 22,
+  "count": 10,
+  "app_link": "https://apps.apple.com/app/footballbin/id6757111871",
+  "note": "Download FootballBin for live match tracking, player valuations, and detailed predictions.",
+  "matches": [
+    {
+      "match_id": "epl_mw22_liv_bur",
+      "home_team": "Liverpool",
+      "away_team": "Burnley",
+      "kickoff_time": "2026-01-17T15:00:00Z",
+      "kickoff_formatted": "Sat 17 Jan 15:00",
+      "countdown": "7d 3h",
+      "status": "scheduled",
+      "predictions": [
+        { "type": "Half Time Result", "value": "2:0", "confidence": 75 },
+        { "type": "Full Time Result", "value": "4:0", "confidence": 75 },
+        { "type": "Next Goal", "value": "Home,Wirtz", "confidence": 75 },
+        { "type": "Corner Count", "value": "9:3", "confidence": 75 }
+      ],
+      "key_players": [
+        {
+          "player_id": "florian_wirtz",
+          "player_name": "Florian Wirtz",
+          "reason": "12 goals, 14 assists. Liverpool's creative hub with 89 form rating."
+        },
+        {
+          "player_id": "zian_flemming",
+          "player_name": "Zian Flemming",
+          "reason": "6 goals, 3 assists. Burnley's top scorer and set-piece specialist."
+        }
+      ]
+    }
+  ]
+}
+```
+
+## FootballBin App
+
+Get the full experience with the FootballBin iOS app:
+
+[![Download on App Store](https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg)](https://apps.apple.com/app/footballbin/id6757111871)
+
+Features:
+- Live match tracking
+- AI player valuations
+- Detailed match predictions
+- Player news and discussions
+- Squad browsers for all major leagues
+
+## Technical Details
+
+### Protocol
+
+- **Protocol**: JSON-RPC 2.0
+- **Transport**: HTTPS POST
+- **Content-Type**: application/json
+
+### Infrastructure
+
+- **Runtime**: AWS Lambda (Node.js 20.x)
+- **Database**: Amazon DynamoDB
+- **API Gateway**: AWS API Gateway
+- **Region**: eu-central-1 (Frankfurt)
+
+### Error Codes
+
+| Code | Meaning |
+|------|---------|
+| -32700 | Parse error (invalid JSON) |
+| -32600 | Invalid request |
+| -32601 | Method not found |
+| -32602 | Invalid params |
+| -32603 | Internal error |
+
+## Self-Hosting
+
+If you want to deploy your own instance:
+
+### Prerequisites
+
+- Node.js 20+
+- AWS Account with DynamoDB access
+- AWS SAM CLI
+
+### Deploy
+
+```bash
+# Clone the repository
+git clone https://github.com/billychl1/footballbin-mcp-server.git
+cd footballbin-mcp-server
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Deploy with SAM
+sam deploy --guided
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MATCHES_TABLE` | DynamoDB table for matches | `footballbin-matches-prod` |
+| `MATCHWEEKS_TABLE` | DynamoDB table for matchweeks | `footballbin-matchweeks-prod` |
+| `DEFAULT_REGION` | AWS region | `eu-central-1` |
+| `APP_STORE_LINK` | App Store URL | `https://apps.apple.com/app/footballbin/id6757111871` |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Links
+
+- [FootballBin App](https://apps.apple.com/app/footballbin/id6757111871)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [MCP Specification](https://spec.modelcontextprotocol.io)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * FootballBin MCP Server (npm package)
+ *
+ * A thin wrapper that provides MCP stdio transport
+ * and calls the FootballBin remote API for predictions.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * FootballBin MCP Server (npm package)
+ *
+ * A thin wrapper that provides MCP stdio transport
+ * and calls the FootballBin remote API for predictions.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Remote API endpoint
+const API_ENDPOINT = "https://ru7m5svay1.execute-api.eu-central-1.amazonaws.com/prod/mcp";
+/**
+ * Call the remote FootballBin API
+ */
+async function callRemoteAPI(args) {
+    const response = await fetch(API_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "tools/call",
+            params: {
+                name: "get_match_predictions",
+                arguments: args
+            },
+            id: Date.now()
+        })
+    });
+    if (!response.ok) {
+        throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (data.error) {
+        throw new Error(data.error.message || "API error");
+    }
+    // Extract the structured content from the response
+    if (data.result?.structuredContent) {
+        return data.result.structuredContent;
+    }
+    // Fallback to parsing the text content
+    if (data.result?.content?.[0]?.text) {
+        return JSON.parse(data.result.content[0].text);
+    }
+    return data.result;
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    // Create the MCP server
+    const server = new McpServer({
+        name: "footballbin-mcp-server",
+        version: "1.0.0"
+    });
+    // Register the get_match_predictions tool using shape syntax
+    server.tool("get_match_predictions", "Get AI-powered predictions for Premier League and Champions League matches including half-time score, full-time score, next goal scorer, and corner predictions.", {
+        league: z.string().describe('League to get predictions for. Accepts: "premier_league", "epl", "pl", "champions_league", "ucl", "cl"'),
+        matchweek: z.number().optional().describe("Matchweek number (optional, defaults to current matchweek)"),
+        home_team: z.string().optional().describe('Filter by home team name (optional, e.g., "chelsea", "arsenal", "man_utd")'),
+        away_team: z.string().optional().describe('Filter by away team name (optional, e.g., "liverpool", "wolves")')
+    }, async (args) => {
+        try {
+            const result = await callRemoteAPI(args);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+                    }
+                ],
+                isError: true
+            };
+        }
+    });
+    // Create stdio transport and connect
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is used for MCP protocol)
+    console.error("FootballBin MCP Server running on stdio");
+}
+// Run the server
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "footballbin-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for FootballBin football match predictions - Premier League & Champions League",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "footballbin-mcp": "./dist/index.js"
+  },
+  "mcpName": "io.github.billychl1/footballbin-mcp-server",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "football",
+    "soccer",
+    "premier-league",
+    "champions-league",
+    "predictions",
+    "ai",
+    "claude",
+    "anthropic"
+  ],
+  "author": "billychl1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/billychl1/footballbin-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/billychl1/footballbin-mcp-server/issues"
+  },
+  "homepage": "https://github.com/billychl1/footballbin-mcp-server#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}