# Gonkbot

> Gonkbot is a golf round-logging and coaching memory service for AI assistants,
> exposed as a remote MCP (Model Context Protocol) server. Golfers narrate holes
> conversationally during a round; Gonkbot stores structured hole-by-hole data,
> computes statistics, cross-round trends, and WHS handicap math, and powers a
> post-round coaching review with a persistent player profile.

## Connecting (for agents)

- MCP endpoint (Streamable HTTP): https://gonkbot.com/mcp
- The apex URL https://gonkbot.com also accepts MCP JSON-RPC POSTs directly.
- Auth: OAuth 2.1 with dynamic client registration (RFC 7591) and PKCE.
  Discovery starts at https://gonkbot.com/.well-known/oauth-protected-resource/mcp
  which points at the authorization server. No pre-registration or API keys needed.
- Accounts are provisioned automatically on first authenticated request —
  there is no separate signup step. The user signs in (Google/email) on the
  hosted consent page during the OAuth flow.

## Tools

- lookup_course — read-only course info: tee sets (rating/slope/yardage) and
  the hole-by-hole scorecard (par, stroke index, yardages). Checks the golfer's
  saved courses, then the open course database. Use it to answer course
  questions or to prep an accurate log_round start (pass a location to
  disambiguate).
- log_round — the whole in-round loop via a discriminated `action` field:
  - `start`: open a round (course, tees, date; optional teeRating/teeSlope — pass
    ratingConfirmed=true only after the golfer confirms them; enables handicap math)
  - `record_holes`: log one or more holes (number, par, score, fairway Y/N/NA,
    gir, putts, optional stroke index, notes, optional shot-by-shot array)
  - `correct`: amend previously logged holes
  - `finish`: close the round; returns scorecard, stats, day-of weather
    conditions (recorded for recap context), and a GHIN posting summary
  - `abandon`: permanently discard the in-progress round (confirm with the golfer first)
  - Pass a unique `idempotencyKey` per logical call; retries replay the original
    result instead of double-logging. Every response echoes canonical round state
    (round id, holes logged, running score) — use it to re-anchor after context loss.
  - Pass `roundId` (from the state echo) on record/correct/finish/abandon calls as
    a safety check; the call errors if it isn't the active round.
- get_rounds — list recent rounds, or fetch one round's full scorecard, stats,
  saved recap, and (with includeShots=true) shot-level detail.
- get_insights — cross-round trends: scoring averages, fairway/GIR/putting,
  par-3/4/5 performance, 3-putt rate, scrambling, and the internal WHS handicap
  index (unofficial; labeled unavailable until enough rated rounds exist).
- player_profile — persistent coach memory (tendencies, swing protocols, goals,
  recurring faults). Call with no args to read; the response includes a revision
  token. To update, pass full markdown `content` plus `ifRevision` from your
  read. Blind overwrites of a non-empty profile are rejected (optimistic
  concurrency) and return the current content to merge. Keep under ~2500 words.
- save_recap — persist the finished post-round review (markdown) for a round.

## Prompts

- review_round — a coaching-review playbook: pull the latest completed round +
  trends + profile, grill the golfer with specific hole-by-hole questions,
  produce a structured recap (went well / went poorly / technical analysis /
  next steps), save it via save_recap, and update player_profile.

## Course data (mostly automatic)

Gonkbot looks up new courses in the open course database (OpenGolfAPI,
opengolfapi.org — ODbL) automatically on log_round start: scorecard (par,
stroke index, yardages) and tee sets (rating/slope) are imported server-side.
That means:

- Include the course `location` ("Sterling, VA") on start — it disambiguates
  the lookup. If multiple candidates match, the response lists them with
  opengolfId values; call start again with the right one.
- Once imported, you can omit `par` when recording holes ("bogey on 3" is
  enough) and stroke indexes are applied automatically for exact net double
  bogey math.
- Imported rating/slope still need golfer confirmation: the start response
  states the values; confirm with the golfer and pass ratingConfirmed=true on
  a later call to enable handicap features.
- If the course isn't in the database (lookup fails soft), fall back to reading
  the course's scorecard yourself: BlueGolf course pages
  (course.bluegolf.com — needs browser-grade fetch, plain HTTP gets 405) or a
  web search, then supply teeRating/teeSlope/par/strokeIndex manually.

Course questions ("what's the slope from the blues?"): use lookup_course.
If you need data it doesn't return, OpenGolfAPI's keyless REST API is at
api.opengolfapi.org/v1 (attribution: OpenGolfAPI, opengolfapi.org, ODbL).

Optional companion server: OpenGolfAPI also runs its own MCP server
(github.com/opengolfapi/mcp-server) with course discovery, weather, and nearby
amenities — useful extras, but not needed for gonkbot's core loop, and note it
exposes ~50 tools (a large context footprint).

## Recommended agent behavior

- During a round, batch 1-3 holes per log_round call from natural speech; don't
  make the golfer recite a form. Confirm parsed values briefly ("logged: bogey
  on 8, missed green, 2 putts").
- Fairway is Y/N only for holes with a driver/tee shot landing zone; use NA on
  par 3s. GIR = green in regulation. Ask rather than guess when narration is
  ambiguous about score-affecting facts.
- After finish, offer the review. Compare against the golfer's own trends from
  get_insights, not tour statistics.
- Handicap figures are unofficial; the GHIN posting summary is for the golfer
  to enter into their official handicap app.

## Pages

- [Home](https://gonkbot.com/): what Gonkbot is, connect instructions
- [Privacy](https://gonkbot.com/privacy.html): data handling and deletion
- [Terms](https://gonkbot.com/terms.html): terms of service