Golf Reports

A self-contained golf-data skill: pulls your own data from Arccos (shot-level

• strokes-gained), GHIN (official handicap + scores), and 18Birdies (export import), then renders any round to an HTML report (satellite shot map + stats) and a shot-map PDF. Login-based — no browser DevTools. Runs locally, so it works inside the Claude Desktop app (Chat / Cowork / Code) via a local MCP server.

Why local: the Cowork cloud sandbox can't reach the golf APIs or your files. The engine runs on your machine and exposes tools to Claude. (Architecture vetted with Codex.)

What's inside

ingest/    pull_arccos.py · pull_ghin.py · pull_18birdies.py   (login-based, no DevTools)
render/    gen_combined · gen_stats · gen_satellite · gen_gps_pdf · build_round_pages
           trends.py      (MCP tool: unified Arccos+GHIN+18Birdies history, WHS index + trajectory)
           dispersion.py  (MCP tool: per-club distance/lateral model → <store>/dispersion.json)
mcp/       server.py        (MCP tools: list_rounds, round_stats, render_round, sync_*, …
                             trends, compare_rounds, export_dispersion)
skills/    golf-reports/SKILL.md
setup.py   one-time login wizard
manifest.json / .claude-plugin/plugin.json   packaging

export_dispersion writes <store>/dispersion.json — an empirical-Bayes per-club total-distance and lateral-dispersion model (schema v1.0) used as the golfsmart bridge artifact.

Related MCP server: macrofactor-mcp

1. One-time setup (no DevTools)

pip install -r requirements.txt
python3 setup.py          # prompts for Arccos + GHIN email/password, optional 18Birdies export

Credentials are stored only on your machine (~/.arccos_creds.json, ~/.ghin_creds.json, chmod 600) and never uploaded. Arccos stores a long-lived accessKey (password discarded); GHIN password goes to the OS keychain when available (plaintext file only with explicit consent — it's needed each sync, 12h tokens).

2. Use it in the Claude Desktop app

Cowork / Chat (recommended for non-devs): install as a one-click Desktop Extension (the local MCP server) — Customize → Browse plugins/extensions → add this package. Then ask: "sync my golf data", "how was my last round?", "render my latest round as a PDF I can send."

Manual MCP config (alternative): add to claude_desktop_config.json:

{ "mcpServers": { "golf-reports": {
  "command": "python3", "args": ["/ABSOLUTE/PATH/golf-reports/mcp/server.py"],
  "env": { "GOLF_STORE": "/ABSOLUTE/PATH/golf-data",
           "GOLF_INGEST": "/ABSOLUTE/PATH/golf-reports/ingest",
           "GOLF_REPORTS": "/ABSOLUTE/PATH/golf-data/reports",
           "PYTHONPATH": "/ABSOLUTE/PATH/golf-reports/render" } } } }

Claude Code (Code tab / CLI): /plugin marketplace add <your-gh>/golf-reports then /plugin install golf-reports, or copy skills/golf-reports into ~/.claude/skills/.

3. CLI (works anywhere, no Claude)

cd render
python3 build_round_pages.py <store-dir-or-git-url> ./out --all --split
# -> <course>_<date>_report.html + _shotmaps.pdf (+ _stats.html + _map.html)

GPS columns in the store are opt-in when pulling: pass --include-gps to pull_arccos.py (or set GOLF_INCLUDE_GPS=1) if you want shot maps with real coordinates in a store you keep private.

Notes & provenance

• Strokes gained (by category / 15-yd band / hole) is measured (Arccos, vs scratch). Putting make % and approach proximity are derived heuristics. Peer carry is vs a modeled ~12-HCP table — edit render/peer_config.json.

• Satellite tiles (Esri) load only when the HTML is opened in a browser; the PDF is the reliable offline/shareable artifact. GPS is optional at every layer (map omitted / PDF falls back to a distance schematic).

• Privacy: credentials, raw data, and reports stay local. Nothing is published.

First-run checklist

1. Install the extension and confirm a tool (e.g. list_rounds) appears + runs from the Cowork tab.

2. Ask Claude to sync_arccos / sync_ghin and confirm files appear in your store (~/golf-data by default).

3. Ask Claude to render_round and open the HTML in a browser — satellite tiles should load.