plavecka-akademia-mcp

A remote MCP (Model Context Protocol) server that turns plaveckaakademia.sk's children's swimming course listings into structured tools an LLM can call, so prompts like "Žralok on Friday in Devínska" or "a date and place where I can book Žralok + Delfín + Korytnačka at the same location" are answerable in one or two tool calls instead of manually paging through the site.

The site itself has no API: it's a Drupal 7 Views exposed-filter form supporting only a centre and a sub-level filter, no day/time filter and no way to ask a cross-category question. This server fetches and parses the site's own HTML and layers the richer filtering on top, server-side.

It runs as an Azure Function App and is meant to be added to Claude as a custom connector — see Add it to Claude below.

Tools

list_categories

No arguments. Lists the four course categories (Morský koník, Korytnačka, Delfín, Žralok) with their slug, age range, whether they offer */** sub-levels, and the centres each is offered at.

list_courses

{
  category: string,        // slug or display name, diacritic/case-insensitive, e.g. "zralok" or "Žralok"
  location?: string,       // centre name, diacritic/case-insensitive, e.g. "devinska" -> "Devínska"
  level?: "*" | "**" | "any",
  day?: string,            // Slovak or English weekday, e.g. "piatok" or "friday"
  timeFrom?: string,       // "HH:MM"
  timeTo?: string,         // "HH:MM"
  startAfter?: string,     // ISO date
  startBefore?: string,    // ISO date
  maxPrice?: number,
  limit?: number,
  offset?: number,
}

Returns { total, returned, offset, courses[] }. An unknown location, day or category is rejected with an error message listing the valid values — it never silently falls through to an empty result.

get_course

{ courseId?: string } | { url?: string }

Fetches the live detail page for one course (by numeric id, or by its full URL) and returns address, date range, day/time, price, lesson counts, age range, availability, booking URL and the per-session calendar.

find_common_slots

{
  categories: { category: string, level?: "*" | "**" | "any" }[],
  location?: string,
  day?: string,
  limit?: number,
  offset?: number,
}

Returns only the centre/day combinations where every requested { category, level } has at least one matching course, with the concrete courses per requirement attached (groups[] on each match). This is what answers "book Žralok** + Delfín* at the same place" in one call — the same category can be requested twice at different levels (e.g. one child ready for Žralok**, a sibling still on Žralok*). Omit level (or pass "any") for no level restriction.

Returns { total, returned, offset, matches[] }, where total counts every match and matches is the requested slice — a broad request (one category, no location) matches most centre/day pairs, so pass limit unless you really want all of them.

Add it to Claude

The endpoint is https://<your-function-app-name>.azurewebsites.net/api/mcp?code=<key> — gated by an Azure Functions key rather than a login, since this is a read-only proxy over public listings with no per-user data (see Security & trust model).

If you're pointing this at an already-deployed instance, ask whoever deployed it for the URL (including the ?code= part) and skip to step 2. If you're deploying your own copy, see ARCHITECTURE.md first, then come back here.

1. Get a function key, if you don't already have one. Create a dedicated named key rather than reusing the default/host master key, so it can be revoked independently later:

   az functionapp function keys set \
     --name <your-function-app-name> \
     --resource-group <your-resource-group> \
     --function-name mcp \
     --key-name claude-connector \
     --key-value "$(openssl rand -base64 32)"
   

   Or via the Portal: Function App → Functions → mcp → Function Keys → + New function key.

2. In Claude, go to Settings → Connectors → Add custom connector, and point it at the full URL above, including the ?code= query parameter.

3. Try a prompt like "What Žralok courses are available on Friday in Devínska?" to confirm it's wired up.

Rotating or deleting the key immediately invalidates any URL using it — update the connector's URL in Claude after rotating.

Security & trust model

This server is a read-only proxy over public course listings, so there's nothing to protect behind a login — but that's not the same as nothing to think about:

• A function key, not user authentication, gates the endpoint. It's a shared-secret gate against casual/automated abuse, not per-caller accounting or rate limiting. Anyone with the key can drive unlimited requests at plaveckaakademia.sk from the server's IP.
• get_course's url input is validated, not just fetched — only an exactly-matching allowlisted host, https, and a course-detail-shaped path are accepted, so it can't be used as an open proxy for arbitrary URLs.
• Upstream text is untrusted input to the calling model. Fields like address and venueName are scraped verbatim from the site and flow into the LLM's context — treat tool output as data, not instructions.

See ARCHITECTURE.md's Security & trust model for the full reasoning, including known limitations.

Contributing

See CONTRIBUTING.md for the development workflow, coding conventions, how to re-record fixtures when the site changes, and what a pull request is expected to include.

For how the server is built, how the site is scraped, and how it's deployed, see ARCHITECTURE.md. If you're working on this repo with Claude Code, CLAUDE.md carries the project context and the non-obvious site-scraping gotchas that are easy to reintroduce.

License

GNU General Public License v3.0 — see LICENSE.