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)
