{
  "markdown": "# SoaringSpot MCP Server (Python / FastMCP)\n\nAn MCP server wrapping the [SoaringSpot public API](http://download.naviter.com/soaringspot/api/index.html) — the gliding competition platform by Naviter — built with **FastMCP** and supporting HTTP, SSE, and stdio transports.\n\n## Requirements\n\n- Python 3.11+\n- `fastmcp >= 3.0`, `httpx`\n\n## Install\n\n```bash\npip install fastmcp httpx\n```\n\n## Credentials\n\nIn your SoaringSpot competition admin panel go to **Edit Competition → API Keys** to generate a **Client ID** and **Secret**.\n\n```bash\nexport SOARINGSPOT_CLIENT_ID=\"your-client-id\"\nexport SOARINGSPOT_SECRET=\"your-secret\"\n\n```\nThe credentials for an specific competitions are under the directory SoaringSpot \nand within that directory on a subdirectory that matches the name with the \ncompetition name, for example:\nSoaringSpot/wgc2026/clientid or\nSoaringSpot/wgc2026/secretkey\n\nOptionally override the base URL (e.g. for the test environment):\n```bash\nexport SOARINGSPOT_BASE_URL=\"https://api.test.soaringspot.com/v1\"\n```\n\n---\n\n## Running\n\n### HTTP (default — streamable-http, port 8000)\n\n```bash\npython ss_server.py\n# → http://127.0.0.1:8000/mcp\n```\n\n### Custom host / port / path\n\n```bash\npython ss_server.py --host 0.0.0.0 --port 9000 --path /soaringspot\n```\n\n### SSE transport\n\n```bash\npython ss_server.py --transport sse --port 8000\n```\n\n### stdio (Claude Desktop)\n\n```bash\npython ss_server.py --transport stdio\n```\n\n---\n\n## Claude Desktop config (stdio)\n\n```json\n{\n  \"mcpServers\": {\n    \"soaringspot\": {\n      \"command\": \"python\",\n      \"args\": [\"/absolute/path/to/soaringspot_mcp/ss_server.py\", \"--transport\", \"stdio\"],\n      \"env\": {\n        \"SOARINGSPOT_CLIENT_ID\": \"<your-client-id>\",\n        \"SOARINGSPOT_SECRET\": \"<your-secret>\"\n      }\n    }\n  }\n}\n```\n\n## Claude Desktop config (HTTP)\n\nStart the server first, then point Claude at it:\n\n```json\n{\n  \"mcpServers\": {\n    \"soaringspot\": {\n      \"url\": \"http://127.0.0.1:8000/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_contests` | Search competitions by name, country, date range, category; supports paging |\n| `get_contest` | Full details of one competition |\n| `get_contest_classes` | All glider classes in a competition |\n| `get_contest_downloads` | Airspace & waypoint file links |\n| `get_contest_winners` | Overall winners |\n| `get_class` | Class details (type, category) |\n| `get_class_contestants` | Pilots registered in a class |\n| `get_class_results` | Cumulative standings for a class |\n| `get_class_tasks` | All scored days for a class |\n| `get_contestant` | Individual pilot details |\n| `get_tasks` | Today's tasks (or filter by date / pilot email) |\n| `get_task` | Task details (type, status, distances) |\n| `get_task_download_xml` | Task XML for nav devices (Oudie, XCSoar, LX9000…) |\n| `get_task_images` | Task map images |\n| `get_task_points` | Turnpoints with observation zones |\n| `get_task_results` | Daily results per pilot |\n| `get_flight` | IGC flight metadata for a result |\n| `get_location` | Competition airfield location |\n| `get_image` | Image metadata |\n| `get_server_time` | Server UTC time (for clock-sync / auth debugging) |\n\n---\n\n## Authentication details\n\nEvery request is signed with **HMAC-SHA256**:\n\n```\nAuthorization: http://api.soaringspot.com/v1/hmac/v1\n  ClientID=\"<id>\", Signature=\"<sig>\", Nonce=\"<nonce>\", Created=\"<ISO-UTC>\"\n\nSignature = base64(HMAC-SHA256(nonce + created + clientId, secret))\n```\n\nThe nonce is generated fresh per request using `secrets`; the timestamp must be within ±5 minutes of the server. Use `get_server_time` to diagnose drift.\n\n---\n\n## Notes\n\n- The API uses **HAL+JSON** (`application/hal+json`). Responses include `_links` you should follow rather than hard-coding URIs.\n- `get_task_download_xml` returns raw XML intended for glider navigation devices.\n- Flight upload (`POST /contests/{id}/flights`) is intentionally omitted — it requires `multipart/form-data` and is normally handled by scoring software like SeeYou Competition.\n",
  "bytes": 4018,
  "sha": "1a25c776c58187276167f99ff94d9017f4866d5301b7c690566aa0af5659c629",
  "repo_slug": "acasadoalonso/soaringspot.ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_acasadoalonso_soaringspot_ai_okf_index_m_f2158c69/readme"
}