# 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)

Install Gonkbot on the host you are running in. Follow **only** the subsection
that matches you — do not dump every client's steps on the golfer. After they
confirm and sign in (Google/email), their account exists. There is no separate
signup form.

Shared facts (every host):
- 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: https://gonkbot.com/.well-known/oauth-protected-resource/mcp
- Manifest: https://gonkbot.com/.well-known/mcp-server
- Registry name: com.gonkbot/mcp (official MCP registry; HTTP domain proof at /.well-known/mcp-registry-auth)
- No API keys, no pre-registered client id/secret, no Advanced/OAuth fields

### If you are Claude

Open this install link for the golfer (name and URL are prefilled):
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Gonkbot&connectorUrl=https%3A%2F%2Fgonkbot.com%2Fmcp
They review the dialog, click Add, and sign in. Then Gonkbot tools are available.
Fallback: Customize → Connectors → Add custom connector → https://gonkbot.com/mcp

### If you are ChatGPT

You cannot register a connector yourself. Give them this URL and open Plugins:
- Server URL to paste: https://gonkbot.com/mcp
- Create page: https://chatgpt.com/plugins
They enable Developer mode (Settings → Security and login), create a plugin,
paste the URL, and sign in. Then they enable Gonkbot in the chat (Developer
mode / plugins picker) and can say "log my golf holes with gonkbot".

### If you are Gemini

Spark (gemini.google.com) — you cannot write Connected Apps yourself. Give them
https://gonkbot.com/mcp and tell them: Settings & help → Connected Apps →
Custom apps for Spark → Add a custom app → paste the URL → Next. Leave
Advanced features closed. Then in Spark they type @ and pick Gonkbot.
Custom apps require Gemini Spark (personal Google Account; added on web, then
available on mobile).
Gemini CLI — you can install this yourself:
`gemini mcp add --transport http gonkbot https://gonkbot.com/mcp`
then `/mcp auth gonkbot` so they can sign in.

### If you are Poke

Open this install link for the golfer (name and URL are prefilled):
https://poke.com/integrations/new?name=Gonkbot&url=https%3A%2F%2Fgonkbot.com%2Fmcp
They click Create and sign in. Then they can text holes as they play.
If you can run a shell: `npx poke@latest mcp add https://gonkbot.com/mcp -n Gonkbot`

### Any other MCP client

Add a Streamable HTTP server named Gonkbot at https://gonkbot.com/mcp with
OAuth (dynamic client registration). Do not ask the golfer for a client id,
secret, or API key.

## Tools

- lookup_course — course info from saved courses or the open course database.
  Pass a course name for tee sets (rating/slope/yardage) and the hole-by-hole
  scorecard. Omit name and pass location (e.g. Corolla, NC) to list nearby
  courses, or architect (e.g. Rees Jones, Robert Trent Jones II) to list
  courses by designer. Location also disambiguates a name. After a list, call
  again with the course name for the scorecard.
- log_round — the whole in-round loop via a discriminated `action` field
  (each action has its own required fields; do not send start-only fields on
  record_holes, etc.):
  - `start`: open a round (`course` required; optional location, tees, date
    YYYY-MM-DD, holesPlanned 9|18 default 18, teeRating 55–88, teeSlope 55–155).
    Pass ratingConfirmed=true only after the golfer confirms rating/slope.
  - `record_holes`: log 1–18 holes. Each hole: holeNumber 1–18, score 1–15;
    optional par 3–6 (auto-filled from the scorecard), putts 0–6, gir, fir
    (HIT|MISS|LEFT|RIGHT|SHORT|LONG|N/A), shotNotes, optional shots[] when
    they narrated shot-by-shot. If they already told you the hole, submit
    this call — do not re-ask the same facts as a form.
  - `correct`: patch one previously logged hole (holeNumber + at least one of
    score, putts, fir, gir, shotNotes)
  - `finish`: close the round; optional weather {tempF, windMph, conditions}.
    Returns scorecard, stats, conditions, and a GHIN posting summary
  - `abandon`: permanently discard the in-progress round (optional reason;
    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. First write: pass `content` and omit `ifRevision`. Later writes: pass
  `content` plus `ifRevision` from your last read. A token on an empty profile,
  or a mismatched/missing token on a non-empty profile, is rejected and (when
  content exists) returns the current profile 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 with
the course name. "What's around Corolla?" / "RTJ II courses": same tool, omit
name and pass location or architect.
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 live weather, nearby hotels, and
other extras — not needed for gonkbot's core loop, and 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"). Forms are only for catch-up.
- FIR is HIT / MISS / LEFT / RIGHT / SHORT / LONG, or N/A on par 3s. GIR = green
  in regulation. When they narrate shot-by-shot, put the shots in shots[] and
  still include the hole score — do not open a hole form after they already
  told you. 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; human connect buttons at #connect
- [Markdown homepage](https://gonkbot.com/index.md): text twin of the landing page
- [Privacy](https://gonkbot.com/privacy): data handling and deletion
- [Terms](https://gonkbot.com/terms): terms of service
- [Full agent brief](https://gonkbot.com/llms-full.txt): landing + connect + tool contract
- This file: install recipes for agents, plus the tool contract

## Optional

- [MCP well-known manifest](https://gonkbot.com/.well-known/mcp-server)
- [OpenGolfAPI](https://opengolfapi.org): course database (ODbL) used for scorecards