# Crewboard

> Crewboard is the booking board of Cambridge college boat clubs (first: Lucy Cavendish College Boat Club, LCCBC, at https://lccbc.camsocs.uk). Captains plan outings (on the water) and land / erg sessions; rowers see their seat and reply YES or NO. People's AI agents can do the same through an MCP server and a REST API, acting as the person who created the token.

## Connect

- MCP server (Streamable HTTP, protocol 2025-06-18, stateless JSON): https://trustworthy-moose-24.convex.site/mcp
- REST API base: https://trustworthy-moose-24.convex.site/api/v1 (JSON)
- OpenAPI 3.1: https://trustworthy-moose-24.convex.site/api/v1/openapi.json
- Human guide: https://lccbc.camsocs.uk/docs/agents
- Auth: a personal API token, created by the person in Settings → AI agents & API. Send `Authorization: Bearer cb_…`. Read-only tokens can only read (GET / read tools). Tokens expire and can be revoked. There is no OAuth flow; ask the person for a token.
- Calendar: people can subscribe to a private iCal feed of their own seats (Settings → Calendar feed).

## Key concepts

- Club: one college boat club, identified by its slug (e.g. "lccbc"). `whoami` lists the person's clubs.
- Squad: a group within a club with captains, coaches and members, e.g. NW (Novice Women), NO (Novice Open).
- Session: an outing (kind "outing") or a land / erg session (kind "land") on a London day (YYYY-MM-DD). Status: draft (captains and coaches only), published, cancelled. startAt / endAt are UTC epoch milliseconds; null means the time is TBC.
- Seat: a place in a session: crew (Stroke, 7 … 2, Bow), cox, land (erg 1 … 8), sub (substitutes) or dropout (people who dropped out, kept visible).
- Reply: the person in a seat answers pending → yes | no. A NO alerts the captains and asks the squad for a sub.
- Availability: per day, morning and afternoon each available | maybe | unavailable; captains use it to build crews.

## Rules for agents

- Act only on what the person asked. Confirm before any write: replying, signing up, withdrawing, changing availability, and (captains) publishing, cancelling, assigning seats or deciding join requests.
- Never reply YES or NO for the person without asking them first.
- Never take a person's name out of a crew or cox seat. To drop out, reply NO; a captain moves them to the drop-out row. Only sub and erg slots can be withdrawn from.
- Dates are Europe/London days; show times to people in 24-hour London time.
- Errors are {"error": {"code", "message"}} (REST) or tool results with isError (MCP); the message is written for people and can be shown as is.
- Be gentle with the API: about 120 requests a minute per token.

## Tools (MCP tool = REST endpoint)

### Everyone
- whoami (GET /api/v1/me): Returns the signed-in person (the owner of this API token): name, email and every club membership with its status, display name, admin flag and squads (id, code, name, role).
- list_sessions (GET /api/v1/clubs/{club}/sessions): Lists outings (on the water) and land / erg sessions in a club between two days (inclusive, at most 62 days).
- my_upcoming_sessions (GET /api/v1/clubs/{club}/me/upcoming): The caller's own seats in published or cancelled sessions from today for the next `days` days (default 14, at most 62), soonest first.
- get_session (GET /api/v1/sessions/{sessionId}): One session in full: everything from list_sessions plus every seat in order (id, kind crew | cox | land | sub | dropout, label, who is in it, their reply and note, `isMe`), notes, revision, cancel reason and what the caller may do (`permissions`).
- reply_to_seat (POST /api/v1/seats/{seatId}/reply): Replies YES (I'll be there) or NO (I can't make it) for one of the caller's own seats in a published session.
- sign_up_for_session (POST /api/v1/sessions/{sessionId}/sign-up): Puts the caller into the first free sub slot of a published outing, or the first free erg slot of a land session (then a sub slot), and marks them YES.
- withdraw_from_seat (POST /api/v1/seats/{seatId}/withdraw): Takes the caller out of a sub slot or an erg slot they hold.
- list_open_slots (GET /api/v1/clubs/{club}/open-slots): Published sessions from today on (between `from` and `to`, at most 62 days) that the caller could still sign up for, with the number of free sub and erg slots.
- get_availability (GET /api/v1/clubs/{club}/availability): The caller's own availability per day between two days (at most 62): morning and afternoon each available | maybe | unavailable, with an optional note, or null when not set.
- set_availability (PUT /api/v1/clubs/{club}/availability): Saves the caller's availability for up to 62 days (today up to 120 days ahead).
- list_key_dates (GET /api/v1/clubs/{club}/key-dates): The club's key dates: races, Head-to-Heads, socials and deadlines, with date (or the original free-text date), entry deadline, location, organiser, course, link and the squads concerned.
- list_squads (GET /api/v1/clubs/{club}/squads): The club's squads (id, code, name, boat size, coxed, sub / erg slot counts, auto-publish rule) and the caller's role in each.
- river_conditions (GET /api/v1/conditions): Current CUCBC flag on the Cam (with what it means for boating), the river level at the club's gauge, and today's and tomorrow's lighting-down / lighting-up times and weather.

### Captains, coaches and club admins
- create_session (POST /api/v1/squads/{squadId}/sessions): Creates a DRAFT outing or land session for a squad, with the squad's default empty seats.
- update_session (PATCH /api/v1/sessions/{sessionId}): Changes a session's details.
- cancel_session (POST /api/v1/sessions/{sessionId}/cancel): Cancels a session (it stays visible, struck out) and tells everyone in it.
- assign_seat (POST /api/v1/seats/{seatId}/assign): Puts a member (membershipId, from list_members or squad_planner) or an unclaimed name from the old sheet (placeholderId) into a seat.
- publish_week (POST /api/v1/squads/{squadId}/publish): Publishes every draft of a squad between `from` and `to` (default: the Monday–Sunday week containing `from`, or this week) and emails the crews.
- squad_planner (GET /api/v1/squads/{squadId}/planner): The planning grid for one squad and one week (Monday–Sunday): the week's sessions, and every squad member with their availability per day (morning / afternoon) and the seats they already hold that day in any squad.
- list_members (GET /api/v1/clubs/{club}/members): Active members of the club (or of one squad): membership id, display name, side, can cox / row, admin flag, committee titles and squads with roles.
- list_join_requests (GET /api/v1/clubs/{club}/join-requests): Open requests to join the club that the caller may decide: name, email, requested squad, side, can cox, message and when they asked.
- approve_member (POST /api/v1/memberships/{membershipId}/approve): Lets a person into the club, into their requested squad (or `squadId`) with `role` (default member).
- reject_member (POST /api/v1/memberships/{membershipId}/reject): Declines an open join request.