trackman-mcp 0.1.0__tar.gz

trackman_mcp-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "trackman-golf",
+  "owner": { "name": "Bjorn Jonsson", "email": "bjorn@avo.sh" },
+  "metadata": {
+    "description": "Single-plugin marketplace for the Trackman Golf MCP + coaching skills.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "trackman-golf",
+      "source": "./",
+      "description": "Trackman Golf MCP server (stats as MCP tools) plus the coaching skills."
+    }
+  ]
+}

trackman_mcp-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "trackman-golf",
+  "description": "Connect to Trackman Golf with your own login, expose your stats as MCP tools, and coach from them with bundled skills.",
+  "version": "0.1.0",
+  "author": { "name": "Bjorn Jonsson", "email": "bjorn@avo.sh" },
+  "homepage": "https://github.com/bjornj12/trackman-mcp-client",
+  "repository": "https://github.com/bjornj12/trackman-mcp-client",
+  "license": "MIT",
+  "keywords": ["golf", "trackman", "coaching", "mcp"]
+}

trackman_mcp-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# Trackman Golf MCP — environment
+
+# REQUIRED: a Bearer access token captured from an authenticated portal session.
+# How to get it:
+#   1. Log in at https://portal.trackmangolf.com
+#   2. Open DevTools -> Network, filter for "graphql"
+#   3. Click a request to api.trackmangolf.com/graphql
+#   4. Copy the Authorization header value (the part after "Bearer ")
+# Paste it here (with or without the leading "Bearer ").
+# Tokens last ~7 days — re-capture when tools return a 401.
+TRACKMAN_TOKEN=
+
+# OPTIONAL: override the GraphQL endpoint (defaults to the production API).
+# TRACKMAN_GRAPHQL_ENDPOINT=https://api.trackmangolf.com/graphql
+
+# OPTIONAL: request timeout in seconds (default 30).
+# TRACKMAN_TIMEOUT_SECONDS=30

trackman_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check src tests
+
+      - name: Type-check (mypy)
+        run: uv run mypy
+
+      - name: Test (pytest)
+        run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build

trackman_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+# Publishes to PyPI on a version tag (e.g. `v0.1.0`) using PyPI Trusted
+# Publishing (OIDC) — no API token is stored anywhere. See PUBLISHING.md for the
+# one-time PyPI-side setup that authorizes this exact workflow.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify the tag matches the package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$TAG  pyproject=$VER"
+          test "$TAG" = "$VER" || { echo "::error::tag v$TAG does not match pyproject version $VER"; exit 1; }
+
+      - name: Lint, type-check, test (gate the release)
+        run: |
+          uv sync --extra dev
+          uv run ruff check src tests
+          uv run mypy
+          uv run pytest -q
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

trackman_mcp-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Secrets & credentials — NEVER commit
+.env
+.env.*
+!.env.example
+*.token
+*token*.json
+*credentials*.json
+
+# Local session/auth cache
+.cache/
+.sessions/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Tooling
+.uv/
+dist/
+build/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# uv.lock IS committed for reproducible installs (do not ignore).
+
+# Generated visualizations (contain personal data)
+viz/
+*-viz.html
+*.viz.html

trackman_mcp-0.1.0/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "trackman-golf": {
+      "command": "uvx",
+      "args": ["--from", "${CLAUDE_PLUGIN_ROOT}", "trackman-mcp"],
+      "env": { "TRACKMAN_TOKEN": "${TRACKMAN_TOKEN}" }
+    }
+  }
+}

trackman_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,249 @@
+# Trackman Golf MCP
+
+## Project Overview
+
+**Name**: Trackman Golf MCP (working name)
+
+**Purpose**: A Model Context Protocol (MCP) server that connects to Trackman's
+golf platform using the user's own login, fetches their stats (course rounds,
+practice sessions, shot-level launch-monitor data, club gapping, handicap), and
+exposes them as MCP tools. On top of that data, a set of Claude **skills** act
+as the user's golf coach — diagnosing weaknesses and giving actionable,
+specific practice plans with example drills and YouTube links to follow.
+
+**Who it's for**: The individual golfer who already practices on Trackman bays /
+ranges or plays Trackman-enabled courses, and wants their data turned into a
+concrete "what should I work on next" plan.
+
+---
+
+## The Core Boundary (read this first)
+
+There is a **hard separation of concerns**. Respect it in every change:
+
+- **The MCP server only fetches and returns raw data.** Authentication,
+  HTTP calls to Trackman, and shaping responses into clean JSON. It contains
+  **no coaching opinions, no drill recommendations, no analysis verdicts.**
+- **The Claude skills do all the thinking.** They call the MCP tools to get
+  data, then diagnose, plan, and coach in prompt/markdown.
+
+Why: coaching logic should be tunable by editing markdown, not redeploying a
+server. Keep judgment out of the server and data out of the skills.
+
+If you find yourself adding "recommend a drill" logic to the MCP, stop — that
+belongs in a skill. If you find yourself hardcoding shot data in a skill, stop —
+that belongs behind an MCP tool.
+
+---
+
+## Status & Phases
+
+This repo currently contains **documentation and skills only** — no server code
+yet. Build in this order:
+
+- **Phase 0 — API discovery (do this first).** Trackman has no public golf API.
+  Before writing a single tool, discover the real endpoints and auth flow the
+  web portal uses, and write them down. Use the `trackman-api-discovery` skill.
+  Output: `docs/trackman-api.md` filled in.
+- **Phase 1 — MCP server.** Implement the tools below against the discovered
+  API. Python + FastMCP.
+- **Phase 2 — Coaching skills.** Wire `trackman-stats-analysis` and
+  `golf-coaching` to real tool output; grow the `drill-library`.
+
+Do not skip Phase 0. Tool names and shapes below are **provisional** and will be
+corrected by what discovery finds.
+
+---
+
+## Technology Stack
+
+- **Runtime**: Python 3.12+
+- **MCP framework**: [FastMCP](https://github.com/jlowin/fastmcp) / the official
+  `mcp` Python SDK
+- **HTTP client**: `httpx` (async)
+- **Auth/session**: `httpx` cookie/token session; tokens stored locally only
+- **Data shaping**: plain dicts / `pydantic` models; `pandas` is allowed in
+  *skills'* helper scripts for analysis, not required in the server
+- **Package/deps**: `uv` (preferred) or `pip` + `pyproject.toml`
+- **Tests**: `pytest`; record real API responses as fixtures (with secrets
+  scrubbed) and test tools against those.
+
+---
+
+## MCP Tools (confirmed against the real API — see `docs/trackman-api.md`)
+
+All tools return **raw, structured data only**. No prose, no advice. Every tool
+calls the single GraphQL endpoint `POST https://api.trackmangolf.com/graphql`
+under the signed-in user's `me` root.
+
+| Tool | Backing (under `me`) | Returns |
+|------|----------------------|---------|
+| `authenticate` | OIDC token capture | Validates the current token; reports who you're signed in as (or that the session expired). Never echoes the token. |
+| `login` | Browser capture | (Re)authenticate. Tries a silent refresh first; if the saved session expired, opens a browser window to sign in. The friendly recovery path when tools report an expired session. |
+| `get_profile` | `profile` + `hcp` | Identity + current **handicap** (`hcp.currentHcp`). |
+| `get_handicap` | `hcp.playerHistory` | Handicap record history (differentials, trend). |
+| `list_sessions` | `activities(kinds,timeFrom,timeTo,skip,take)` | Practice + course activities (id, time, kind, summary). |
+| `get_session` | `node(id)` / `activities` | One activity in full: range strokes or round detail. |
+| `get_course_rounds` | `scorecards(skip,take,completed)` | Scorecards: per-hole scores, FIR/GIR, putts, `stat`. |
+| `get_club_stats` | `equipment.clubs.findMyDistance` | Per-club **gapping**: carry/total, std-dev, dispersion. |
+| `get_shot_data` | `*.measurement` (`Measurement`) | Shot launch metrics: ball/club speed, smash, launch, spin, carry, side, curve, landing angle (~80 fields). |
+| `get_activity_summary` | `activitySummary(timeFrom,timeTo)` | Counts per activity kind over a window. |
+
+### Session-analysis tools (local store, deterministic analytics)
+
+These persist and serve a per-session *analysis*. The analytics are
+**deterministic** (in `analysis.py`) — classification and measurement, not
+coaching. Coaching narrative still lives in the skills. The store is JSON at
+`~/.trackman-mcp/session-analyses.json`, capped at the **last 30**, latest first.
+
+| Tool | Does |
+|------|------|
+| `analyze_and_store_session(activity_id)` | Fetch a session, classify (warm-up vs serious practice vs game), compute metrics + course difficulty, normalize vs previously stored sessions, flag used-vs-available clubs, store, return the record. |
+| `list_session_analyses()` | Index of stored analyses (id, time, kind, category, seriousness, summary), latest first. |
+| `get_session_analysis(activity_id)` | One full stored analysis record. |
+
+Classification (see `analysis.py`): a session is a **warm-up** (not an
+improvement attempt) if under ~8 strokes or ~5 minutes — even for an otherwise
+"serious" kind; **serious practice** if it has real volume/duration/club variety
+or is a focused kind (shot analysis, find-my-distance, sim/virtual-range, etc.);
+**game** for played rounds. Normalization is always against sessions
+*chronologically before* the one analyzed. Units are metric (m/s, meters).
+
+### Training-plan tools (the coach's memory)
+
+The coach saves prescribed practice sessions so they can be recalled later
+("what's today's training?"). Store is JSON at `~/.trackman-mcp/training-plans.json`
+(`training_store.py`), an ordered queue capped at the most recent 50.
+
+| Tool | Does |
+|------|------|
+| `save_training_plan(plan)` | Persist a prescribed plan (title, focus, diagnosis, blocks, targets) to the pending queue. |
+| `get_next_training()` | Return the next pending plan — the answer to "what's today's training?". |
+| `list_training_plans(status?)` | List plans (oldest→newest), optional `pending`/`done` filter. |
+| `mark_training_done(plan_id, result_session_id?)` | Complete a plan; the next pending one becomes current. |
+| `verify_training_progress(plan_id, activity_id?)` | Grade a recent session's real shot metrics against the plan's structured `target_specs` (e.g. driver `clubPath` between -1 and +2). Returns per-target session-mean vs target, `all_met`, and a recommendation. |
+
+Plans carry **`target_specs`** — machine-readable targets (`{metric, club?, op,
+value|low/high}`, ops `< <= > >= between abs< abs<=`) graded deterministically by
+`analysis.verify_targets` against a session's `Measurement` fields (queried via
+`SESSION_MEASUREMENTS`, which includes face/path/spin).
+
+`golf-coaching` writes here (Prescribe → `save_training_plan` with `target_specs`)
+and reads here (Recall → `get_next_training` → `verify_training_progress`, then
+`mark_training_done` once every target is met).
+
+**Auth reality**: the web portal uses a *confidential* OIDC client (backend-for-
+frontend), so the MCP cannot run the OAuth exchange itself. It authenticates with
+a **Bearer access token captured from an authenticated portal session**, attached
+as `Authorization: Bearer …`. Tokens last ~7 days (observed `iat`→`exp` =
+604800s); on `401` the tool returns a clear "re-capture token" error.
+
+**Recovery when expired**: data tools auto-retry once after a silent headless
+refresh (`_try_silent_refresh`), so a stale 7-day token renews invisibly while the
+browser session is still valid. When the browser session itself expires, tools
+return a clear "session expired — use the `login` tool" message, and the `login`
+tool opens a sign-in window (falling back from a fast silent attempt).
+
+**Getting the token** — two paths (`Config.from_env`: `TRACKMAN_TOKEN` env wins,
+else the cached token):
+- **Browser login (recommended)**: `trackman-mcp login` opens an isolated
+  Playwright browser; the user signs in once; the token is captured from the
+  GraphQL traffic and cached at `~/.trackman-mcp/token.json` (mode `0600`). The
+  browser profile persists the session, so `trackman-mcp login --headless`
+  refreshes silently with no re-login (cron-friendly). Code: `login.py`,
+  `token_store.py`. Playwright is the optional `[login]` extra.
+- **Manual**: set `TRACKMAN_TOKEN` from a captured portal session (`.env.example`).
+
+Full detail and example GraphQL queries live in `docs/trackman-api.md`.
+
+---
+
+## Authentication & Secrets — Rules
+
+Treat the user's Trackman login as sensitive. **Non-negotiable:**
+
+- **Never commit credentials, tokens, cookies, or session dumps.** They go in
+  `.env` (gitignored) or the OS keychain — never in source or fixtures.
+- The MCP reads credentials from environment variables only
+  (`TRACKMAN_USERNAME`, `TRACKMAN_PASSWORD`, or a captured `TRACKMAN_TOKEN`).
+  See `.env.example` once Phase 1 starts.
+- **Do not return raw auth material to the model.** Tools may say "authenticated
+  as <name>" but must not echo passwords or bearer tokens.
+- **Scrub fixtures.** Any recorded API response saved for tests must have
+  tokens, cookies, emails, and player IDs redacted or faked.
+- Cache sessions locally under a gitignored path (e.g. `.cache/`), not in the
+  repo tree.
+- This MCP is for a user accessing **their own** Trackman account. Don't build
+  anything that scrapes or accesses other users' data.
+
+---
+
+## Project Structure (target, once Phase 1 begins)
+
+```
+trackman-mcp-client/
+├── CLAUDE.md                      # this file
+├── README.md
+├── pyproject.toml
+├── .env.example
+├── .gitignore
+├── docs/
+│   └── trackman-api.md            # discovered endpoints (Phase 0 output)
+├── src/
+│   └── trackman_mcp/
+│       ├── __init__.py
+│       ├── server.py              # FastMCP app + tool registration
+│       ├── client.py              # Trackman HTTP client + auth/session
+│       ├── tools/                 # one module per tool group
+│       └── models.py              # pydantic response models
+├── tests/
+│   ├── fixtures/                  # scrubbed recorded responses
+│   └── test_tools.py
+├── .claude-plugin/               # Claude Code plugin + marketplace manifests
+├── .mcp.json                     # MCP server declaration (for the plugin)
+├── server.json                   # MCP Registry manifest
+└── skills/                       # coaching brain (see below); plugin-root layout
+```
+
+---
+
+## Skills (the coaching brain)
+
+Skills live in `skills/` (the Claude Code plugin-root layout, so they ship with
+the plugin). Each has a `SKILL.md`.
+
+- **`trackman-api-discovery`** — Phase 0. Reverse-engineer the portal's auth +
+  data endpoints via the browser network panel; write them into
+  `docs/trackman-api.md`.
+- **`trackman-stats-analysis`** — Pull stats through the MCP and diagnose weak
+  areas (dispersion, gapping, scoring trends, handicap movement). Analysis only.
+- **`golf-coaching`** — Turn the diagnosis into specific, actionable practice:
+  an example session, drills, and YouTube links. The coach persona.
+- **`drill-library`** — Curated drills + vetted YouTube links, plus the
+  procedure for live web-searching fresh videos matched to a weakness.
+- **`trackman-session-analyzer`** — Ingests recent sessions, stores a per-session
+  analysis (last 30) via the MCP, and returns a normalized summary of the latest
+  session. **Context-forked / data-collection skill: must run in a subagent,
+  never on the main thread.**
+
+Typical flow: `authenticate` → `trackman-stats-analysis` (diagnose) →
+`golf-coaching` (prescribe, pulling from `drill-library`). For per-session
+ingest + a normalized latest-session report, dispatch `trackman-session-analyzer`
+as a subagent.
+
+---
+
+## Conventions
+
+- Keep tools small and single-purpose; one concern per module.
+- Tools fail loudly with clear errors (auth expired, endpoint changed) rather
+  than returning empty success.
+- Prefer async `httpx`; don't block the event loop.
+- When the API shape is uncertain, write a fixture-backed test from a real
+  (scrubbed) response so regressions are caught when Trackman changes things.
+- Coaching is **specific**: "10 balls, 7-iron, alternate target 140/160y, log
+  carry dispersion" — never "practice your irons."
+
+---
+
+*Last updated: 2026-06-27 · Version 0.1.0 (scaffolding)*

trackman_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjorn Jonsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trackman_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: trackman-mcp
+Version: 0.1.0
+Summary: MCP server that fetches a user's Trackman Golf stats (handicap, rounds, practice, shots, club gapping).
+Project-URL: Homepage, https://github.com/bjornj12/trackman-mcp-client
+Project-URL: Repository, https://github.com/bjornj12/trackman-mcp-client
+Project-URL: Issues, https://github.com/bjornj12/trackman-mcp-client/issues
+Author-email: Bjorn Jonsson <bjorn@avo.sh>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,golf,llm,mcp,model-context-protocol,trackman
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: login
+Requires-Dist: playwright>=1.40; extra == 'login'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.bjornj12/trackman-mcp -->
+
+# trackman-mcp
+
+An MCP server that logs into **Trackman Golf** with your own account and exposes
+your stats — course rounds, practice sessions, shot-level launch-monitor data,
+club gapping, and handicap — as MCP tools. On top of that, a set of Claude
+**skills** act as your golf coach: they diagnose your weaknesses and hand you a
+specific practice plan with drills and YouTube links for your next session.
+
+> [!IMPORTANT]
+> **Unofficial.** This project is not affiliated with or endorsed by Trackman.
+> It talks to Trackman's **private** web API using a token from *your own*
+> authenticated session, and automates a browser login on your behalf. This may
+> conflict with Trackman's Terms of Service — use it on your own account, at your
+> own risk. Never use it to access anyone else's data.
+
+## Design boundary
+
+- **MCP server** = raw data fetch + auth only. No opinions.
+- **Skills** = all the coaching (analysis, plans, drills).
+
+See [`CLAUDE.md`](./CLAUDE.md) for the full architecture and auth/secret rules.
+
+## Install
+
+### Option A — Claude Code plugin (server + skills together)
+
+```text
+/plugin marketplace add bjornj12/trackman-mcp-client
+/plugin install trackman-golf@trackman-golf
+```
+
+This installs the MCP server (run via `uvx`) **and** the six coaching skills.
+Then sign in once (see [Authentication](#authentication)).
+
+### Option B — any MCP client (Claude Desktop, etc.)
+
+Once published to PyPI, add this to your client's MCP config (Claude Desktop:
+`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "trackman-golf": {
+      "command": "uvx",
+      "args": ["trackman-mcp"]
+    }
+  }
+}
+```
+
+No `env` is required: after you run `trackman-mcp login` the server loads the
+cached token from `~/.trackman-mcp/token.json` automatically. (You can instead
+set `TRACKMAN_TOKEN` to override it — see `.env.example`.)
+
+To run it straight from a local checkout before publishing, use
+`"command": "uvx", "args": ["--from", "/abs/path/to/trackman-mcp-client", "trackman-mcp"]`.
+
+### Option C — from source (development)
+
+```bash
+uv venv && uv pip install -e '.[login,dev]'   # [login] adds Playwright, [dev] adds test/lint tools
+```
+
+## Authentication
+
+### Browser login (recommended)
+
+```bash
+trackman-mcp login            # opens a browser; sign in once with email+password
+```
+
+A browser window opens (an **isolated** profile, not your normal Chrome). Sign
+in once; the MCP captures the access token and caches it at
+`~/.trackman-mcp/token.json` (mode `0600`). The session persists, so to refresh
+later (tokens last ~7 days) just run:
+
+```bash
+trackman-mcp login --headless   # silent refresh, no window
+```
+
+If you don't have Google Chrome installed, the browser flow falls back to
+Playwright's bundled Chromium — install it once with `playwright install chromium`.
+
+### Keep it fresh automatically (optional)
+
+Schedule the headless refresh so you never think about tokens (twice weekly,
+margin on the ~7-day token). Portable — paths are derived at install time:
+
+```bash
+scripts/install-refresh-schedule.sh dry-run    # preview what gets installed
+scripts/install-refresh-schedule.sh            # install (macOS launchd / Linux cron)
+scripts/install-refresh-schedule.sh uninstall  # remove
+```
+
+Run a headed `trackman-mcp login` **once** first to establish the browser
+session; the schedule then refreshes it silently. Windows: schedule
+`scripts/refresh-token.sh` via Task Scheduler.
+
+### Alternative: paste a token manually
+
+Set `TRACKMAN_TOKEN` (it overrides the cache). Get it from
+portal.trackmangolf.com → DevTools → Network → a `graphql` request → the
+`Authorization` header value. See `.env.example`.
+
+## Run
+
+```bash
+trackman-mcp                              # start the MCP (stdio)
+uv run python scripts/validate.py         # validate stats coverage (uses cached token)
+```
+
+## MCP tools
+
+All tools return **raw data only**; the skills interpret it.
+
+**Data (read-only):** `authenticate` · `get_profile` · `get_handicap` ·
+`list_sessions` · `get_session` · `get_course_rounds` · `get_club_stats` ·
+`get_shot_data` · `get_activity_summary`
+
+**Auth:** `login`
+
+**Session analysis (local store, deterministic):** `analyze_and_store_session` ·
+`list_session_analyses` · `get_session_analysis`
+
+**Training-plan memory:** `save_training_plan` · `get_next_training` ·
+`list_training_plans` · `mark_training_done` · `verify_training_progress`
+
+**Visualization:** `build_visualization` (self-contained animated HTML artifact)
+
+See [`CLAUDE.md`](./CLAUDE.md) for the full table and backing GraphQL.
+
+## Skills
+
+Bundled under [`skills/`](./skills) (installed automatically with the plugin):
+
+- `trackman-api-discovery` — reverse-engineer the portal's API (Phase 0)
+- `trackman-stats-analysis` — diagnose weaknesses from the data
+- `golf-coaching` — turn the diagnosis into an actionable practice plan
+- `drill-library` — curated drills + vetted YouTube links, plus live search
+- `trackman-session-analyzer` — ingest + normalize recent sessions (runs forked)
+- `trackman-visualizer` — animate a diagnosis as an HTML artifact
+
+## Development
+
+```bash
+uv run pytest        # tests
+uv run ruff check    # lint
+uv run mypy          # type-check
+```
+
+## License
+
+[MIT](./LICENSE)