Repository avatar
AI Tools
v0.1.0
active

spinspots

io.github.CloudCorpRecords/spinspots

Outdoor table-tennis spots near a coordinate, spot details, and playing conditions.

Documentation

spinspots

Outdoor table tennis lives or dies by the weather and by knowing where the tables are. spinspots is a small local bridge to the League of Spin directory: it answers three questions — which outdoor spots sit near a coordinate, what does one particular spot look like (with its neighbours), and is it actually playable outside right now, given the wind, temperature and rain?

The package holds no spot data itself. It is a forwarding client for the hosted League of Spin MCP server. The tool list is served locally from a verbatim capture of the upstream surface; every tool call is then forwarded upstream over a streamable-HTTP JSON-RPC session and the upstream result is handed back exactly as received.

Install and run

npx -y @reneturcios/spinspots mcp        # stdio MCP server
npx -y @reneturcios/spinspots --version  # 0.1.0

One bin serves both the MCP server and a small CLI:

spinspots find-spots '{"lat": 37.7749, "lng": -122.4194, "radiusKm": 10}'
spinspots get-spot '{"slugOrId": "some-spot-slug"}'
spinspots playing-conditions '{"lat": 37.7749, "lng": -122.4194}'
spinspots mcp          # run the stdio MCP server
spinspots --version

Exit codes for tool subcommands: 0 on success, 1 when the forwarded result is an error result, 2 on a usage error.

MCP client configuration

{
  "mcpServers": {
    "spinspots": {
      "command": "npx",
      "args": ["-y", "@reneturcios/spinspots", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/spinspots          # stdio MCP server (default command: mcp)
docker run --rm ghcr.io/cloudcorprecords/spinspots --version

Tools

ToolArgumentsWhat it returns
find-spotslat, lng (required); optional radiusKm, limitThe nearest outdoor spots to the coordinate, each with its distance and a citable url.
get-spotslugOrId (required)One spot's details plus nearby spots, addressed by the slug from a leagueofspin.com/spots/{slug} url (preferred) or by raw id.
playing-conditionslat, lng (required)Current wind, temperature and precipitation for the location. Wind is the decisive signal for outdoor table tennis.

The upstream tool names carry hyphens and are served verbatim.

How forwarding works

  • Upstream endpoint: https://leagueofspin.com/api/mcp. It can be replaced with the LEAGUEOFSPIN_MCP_URL environment variable (a labelled reconstruction of this rebuild).
  • Each call opens (once, lazily) a streamable-HTTP JSON-RPC session: initialize, then notifications/initialized, then tools/call. When the upstream issues an Mcp-Session-Id, later requests carry it. Plain-JSON and SSE-framed replies are both understood.
  • The upstream registry record declares no headers, so no Authorization header (or any API-key header) is ever sent, under any environment.
  • Upstream results pass through untouched, isError flag included. When the upstream itself fails — a JSON-RPC error, a non-2xx status, an unparseable body, a thrown or timed-out fetch — the result is an error result whose text begins with spinspots error:.

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (stubbed upstream, no network)
npm run dev     # run the CLI from source

License

MIT — see LICENSE. Copyright (c) 2026 Rene Turcios.

NPM
@reneturcios/spinspots
Install Command
npm install @reneturcios/spinspots
Runtime: npx
OCI
ghcr.io/cloudcorprecords/spinspots:0.1.0
Install Command
docker pull ghcr.io/cloudcorprecords/spinspots:0.1.0:undefined
Runtime: docker