Football Domain Context Protocol Server Implementation

This Python service leverages the Model Context Protocol (MCP) specification to expose detailed soccer statistics and live contest feeds sourced from the API-Football backend system.

Synopsis

This server acts as an abstraction layer, facilitating application access to a rich repository of soccer intelligence derived from the API-Football REST interface. It furnishes both temporal contest records and static attributes pertaining to organized competitions, participating squads, and individual athletes across the globe.

Key Functionalities

• Competition oversight (tables, scheduled matchups, season planners)
• Squad/Club profiles and associated game schedules
• Individual athlete statistical dossiers and biographical summaries
• Real-time contest feeds (incident logs, metrics, chronological event streams)
• Contest performance analysis (metrics breakdown, event logging)

Setup Prerequisites

Operation mandates a valid subscription key from RapidAPI for leveraging the API-Football service:

1. Establish an account at RapidAPI
2. Subscribe to the designated API-Football API endpoint
3. Configure the system environment variable as follows:

RAPID_API_KEY_FOOTBALL=your_api_key_here

Available Toolset

Competition Data Access

• query_league_identifier_by_moniker
• Fetches the numerical ID corresponding to a specified league designation.

• Example: query_league_identifier_by_moniker(league_name="English Premier League")

• fetch_all_competition_identifiers

• Returns a complete enumeration of all recognized soccer competitions and their associated identifiers.
• Optional country filtering available.

• Example: fetch_all_competition_identifiers(country=["UK", "Germany"])

• retrieve_current_standings

• Retrieves positional data for multiple leagues across defined seasons.
• Supports filtering by a specific participating entity.

• Example: retrieve_current_standings(league_id=[202, 135], season=[2021, 2022])

• obtain_league_overview

• Fetches descriptive particulars for a designated soccer tournament.

• Example: obtain_league_overview(league_name="UEFA Champions League")

• get_tournament_schedule

• Retrieves the full slate of scheduled fixtures for a league and season.

• Example: get_tournament_schedule(league_id=202, season=2023)

• lookup_competition_agenda_by_date

• Retrieves the organized schedule for a competition across specified calendar dates.
• Example: lookup_competition_agenda_by_date(league_name="Bundesliga", date=["2024-04-12", "2024-04-13"], season="2023")

Athlete Information Retrieval

• locate_player_identifier
• Acquires unique identifiers and supplementary data for athletes matching a supplied name.

• Example: locate_player_identifier(player_name="Ronaldo")

• fetch_athlete_biography

• Retrieves the detailed profile record for an athlete based on their surname.

• Example: fetch_athlete_biography(player_name="Ronaldo")

• get_player_performance_metrics_by_name

• Retrieves granular performance statistics for an athlete segmented by season and league designation.

• Example: get_player_performance_metrics_by_name(player_id=999, seasons=[2021, 2022], league_name="Serie A")

• get_player_performance_metrics_by_id

• Retrieves granular performance statistics for an athlete segmented by season and league identifier.
• Example: get_player_performance_metrics_by_id(player_id=999, seasons=[2021, 2022], league_id=135)

Squad/Club Data Access

• fetch_club_match_log
• Returns sequential records of past or future contests for a specified club.

• Example: fetch_club_match_log(team_name="FC Barcelona", type="future", count=5)

• retrieve_club_log_within_period

• Fetches club fixtures bounded by a specific temporal interval.

• Example: retrieve_club_log_within_period(team_name="Bayern Munich", start_date="2023-08-01", end_date="2023-08-31", year="2023")

• get_club_summary

• Retrieves fundamental descriptive metadata pertaining to an associated club entity.
• Example: get_club_summary(team_name="Manchester City")

Contest/Fixture Data Interfaces

• extract_fixture_metrics
• Retrieves comprehensive performance statistics for an individual contest.

• Example: extract_fixture_metrics(fixture_id=10001)

• fetch_fixture_occurrence_log

• Retrieves all logged in-game occurrences (goals, disciplinary actions, substitutions) for a contest.

• Example: fetch_fixture_occurrence_log(fixture_id=10001)

• bulk_retrieve_contest_statistics

• Retrieves performance data for several contests concurrently.
• Example: bulk_retrieve_contest_statistics(fixture_ids=[10001, 10002, 10003])

Real-Time Contest Monitoring

• check_for_active_team_contest
• Determines if an entity is presently engaged in a live match.

• Example: check_for_active_team_contest(team_name="Arsenal FC")

• get_in_progress_team_metrics

• Retrieves live operational statistics for a team currently participating in a match.

• Example: get_in_progress_team_metrics(team_name="PSG")

• obtain_live_event_chronology

• Retrieves the streaming sequence of events for a team's active contest.
• Example: obtain_live_event_chronology(team_name="Inter Milan")

Deployment Guide

The service infrastructure is constructed utilizing the Fast MCP library and operates as a self-contained daemon.

python

Initiate the server process

python server_application.py

Alternatively, using the MCP utility

mcp initiate soccer-daemon.py

Operational Parameters

• The server is configured with a 30-second response timeout to ensure operational stability.
• Graceful termination routines (handling Ctrl+C) are integrated.

Integration with Localized Desktop Client

Method 1: Containerization (Recommended Approach)

1. Obtain the repository source code:

git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server

1. Install necessary software packages:

pip install -r requirements.txt

1. Construct the Docker image:

docker build -t soccer_data_agent .

1. Execute the Docker instance (ensure the key environment variable is injected):

docker run -d -p 5000:5000 -e RAPID_API_KEY_FOOTBALL=your_api_key_here --name soccer_agent soccer_data_agent

1. Augment your client_config.json file with the following mapping:

{ "mcpServices": { "soccer_data_agent": { "launch_mode": "docker", "execution_params": [ "execute", "-t", "soccer_agent", "python", "server_application.py" ], "environment_vars": { "RAPID_API_KEY_FOOTBALL": "your_api_key_here" } } } }

Method 2: Direct Python Execution

1. Clone the repository structure

git clone https://github.com/obinopaul/soccer-mcp-server.git cd soccer-mcp-server

1. Install dependencies

pip install -r requirements.txt

1. Establish the required API credential environment variable

export RAPID_API_KEY_FOOTBALL="your_api_key_here"

1. Update your client_config.json, customizing the file paths as appropriate:

{ "mcpServices": { "soccer_data_agent": { "launch_mode": "direct_python", "command_path": "/usr/bin/python3", "script_location": "/path/to/soccer_data_agent.py", "environment_vars": { "RAPID_API_KEY_FOOTBALL": "your_api_key_here" } } } }

Upon configuration update, reload the desktop client to enable access to the complete suite of football data functionalities within conversational interactions.

Implementation Foundation

The backend architecture relies upon: - API-Football, accessed through RapidAPI infrastructure - MCP for standardized service interfacing - Pydantic for robust input schema verification - Requests library for HTTP data transport

Licensing

This MCP data provision service is distributed under the permissive MIT License.

WIKIPEDIA: Asynchronous JavaScript and XML (AJAX) is a set of techniques used in web development to create asynchronous web applications. With AJAX, web applications can send and receive data from a server asynchronously (in the background) without interfering with the display and behavior of the existing page. Although the term AJAX is most commonly associated with JavaScript, the underlying concepts can be implemented using any technology capable of making HTTP requests, such as XMLHttpRequest (XHR) or the newer Fetch API. AJAX applications behave more responsively because part of a web page can be updated without reloading the entire page.

== Genesis == XMLHttpRequest (XHR) was first introduced by Microsoft in Internet Explorer 5 (1999) for use in Microsoft Outlook Web Access. The core functionality was later adopted and standardized across other major browser engines, leading to its eventual formalization.

=== Standardization Evolution === The W3C took the lead in formalizing the interface. Early drafts focused on functional specification. Later iterations, particularly those related to XHR Level 2, introduced critical features such as support for monitoring data transfer progress, enabling cross-origin resource sharing (CORS), and handling binary data streams. Development shifted to WHATWG, which maintains the specification as a living document using Web IDL.

== Operational Flow == Typical invocation of an XHR request involves several sequential programming steps:

1. Instantiation: Create an instance of the XHR object.
2. Configuration: Invoke the open() method to define the request method (GET, POST, etc.), the target URL, and the necessity for asynchronous processing.
3. Event Handling: For asynchronous operations, define a callback function that processes state transitions upon response reception.
4. Dispatch: Execute the send() method to transmit the request payload to the server.
5. State Monitoring: The listener function reacts to changes in the object's state. State 4 signifies completion ("done"). Retrieved data is usually accessible via the responseText or response attributes.

Beyond these fundamentals, the interface permits advanced control, including setting custom request headers, uploading substantial binary or textual payloads via send(), automatic parsing of JSON responses into native objects, and implementing request cancellation or timeout mechanisms.