内容
<!-- mcp-name: io.github.bjornj12/golf-coach -->
# 高尔夫教练
**一个纯粹根据您的统计数据训练您的高尔夫教练 — 场次接着场次，更加接近标准杆。**
高尔夫教练登录到 **Trackman Golf** 使用您自己的账户，并将您的统计数据 — 场次回合、练习会话、击球级别的发射监视器数据、俱乐部间距和残障 — 转化为找出您丢失 strokes 的位置的诊断，然后为您提供一个具体的练习计划，包括练习和 YouTube 链接，适用于您的下一个会话，并随着时间的推移评估您的进步。它作为一个 MCP 服务器（数据工具）加上 Claude **技能**（教练大脑）一起提供。
## 您将获得
您不需要阅读图表 — 您将获得一个教练。将它指向您的 Trackman 数据，它：
- **找出您实际丢失 strokes 的位置** — 不是“改进您的铁杆”，而是 *"您的发球杆有一个双向偏差，分布在约 115 米的走廊中 — 速度是真实的，球面还不够。"*
- **为您提供一个特定的会话** — 俱乐部、距离、重复次数、Trackman 目标和一个带有真实 YouTube 链接的练习。如果您呆在室内，它还提供一个在家中无需球的常规。
- **评估您的进步** — 它保存计划并检查您的下一个会话是否成功，这样您就可以真正了解它是否有效。
- **为您展示图片** — 一个动画的球飞行视图、偏差后的摆动路径，以及您距离每个目标的接近程度。
*一个真实的会话诊断：问题是什么，为什么，与目标的接近程度以及接下来要练习的内容。*
> **名称说明。** “高尔夫教练” 是产品名称。技术 ID 保持为 `golf-coach`（MCP 服务器/插件）和 `golf-coach`（已发布的软件包），以便现有安装继续有效。
> [!IMPORTANT]
> **非官方。** 本项目与 Trackman 无关，也不得到 Trackman 的认可。它使用从您自己的身份验证会话中获取的令牌与 Trackman 的 **私有** 网络 API 进行通信，并代表您自动进行浏览器登录。这可能会与 Trackman 的服务条款相冲突 — 请在您自己的账户上使用，并自担风险。永远不要使用它来访问其他人的数据。
## 设计边界
- **MCP 服务器** = 原始数据获取 + 身份验证。无任何意见。
- **技能** = 所有教练（分析、计划、练习）。
有关完整的架构和身份验证/秘密规则，请参见 [`CLAUDE.md`](./CLAUDE.md)。
## 安装
选择您使用 Claude 的方式。每个方式大约需要两分钟，然后执行一次 [身份验证](#authentication-one-time) 步骤。
### 🖥️ Claude Desktop — 一键安装（推荐，无终端）
1. **下载 [`golf-coach.mcpb`](https://github.com/bjornj12/golf-coach/releases/latest/download/golf-coach.mcpb)** （从 [最新版本](https://github.com/bjornj12/golf-coach/releases/latest)）。
2. 打开 **Claude Desktop → 设置 → 扩展**，拖入该文件（或双击它），然后点击 **安装**。请将令牌字段留空。
3. 在聊天中，说 **"登录到 Trackman"** → **浏览器窗口打开** → 使用您的 Trackman 电子邮件和密码登录一次（也支持 Apple / Google 登录）。窗口 **保持打开，直到您完成** — 请慢慢来，它不会自行关闭。完成后，请告诉 Claude，它会确认您已登录。
4. 询问 Claude： *"我的 Trackman 残障是多少？"*
无需安装和编辑任何配置 — Claude Desktop 运行所有内容，并为您打开登录浏览器。（第一次登录可能需要一些时间，如果它需要获取浏览器。您也可能会看到一个“未签名的扩展”提示 — 对于从文件安装的扩展，这是预期的。）
**平台：** macOS、Linux 和 **Windows** — Claude Desktop 在所有三个平台上通过 `uv` 运行服务器，浏览器登录使用 Playwright（跨平台）。在 Windows 上有一个注意事项：本地令牌/数据文件由您的 Windows 用户配置文件（ACL）保护，而不是 POSIX `0600` 模式。可选的 cron/launchd 自动刷新脚本仅适用于 macOS/Linux — 在 Windows 上使用任务计划程序，或只需重新运行应用程序中的“登录到 Trackman”，当大约 7 天的令牌过期时。
### ⌨️ Claude Code — 插件（服务器 **和** 教练技能）
```text
/plugin marketplace add bjornj12/golf-coach
/plugin install golf-coach@golf-coach
```
安装 MCP 服务器（通过 `uvx` 运行）和所有七个教练技能。
### 🔌 其他 MCP 客户端（或无扩展的 Claude Desktop）
需要 [uv](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh`）。将以下内容添加到您的客户端的 MCP 配置中：
```json
{
"mcpServers": {
"golf-coach": { "command": "uvx", "args": ["golf-coach"] }
}
}
```
> 对于 **Claude Desktop 的手动配置**（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上），请使用 `uvx` 的 **绝对路径** — 例如 `/opt/homebrew/bin/uvx` — 因为应用程序不会继承您的 shell `PATH`。上述 `.mcpb` 安装完全避免了这个问题。
## 身份验证（一次性）
服务器需要登录到 **您自己的** Trackman 账户。Trackman 没有公开的登录 API，因此它从一个真实的已登录浏览器会话中捕获一个令牌；它然后缓存在本地并自行刷新。您的密码永远不会被该工具看到或存储，并且没有任何数据离开您的机器。
### 最简单 — 只需让 Claude 登录（Claude Desktop / Claude Code）
说 **"登录到 Trackman"**。浏览器窗口打开（一个隔离的配置文件，而不是您的普通 Chrome）；登录一次，您自己的节奏 — 窗口由后台任务驱动，因此它 **保持打开，直到您完成**，并且不会在您完成之前关闭（即使是慢速 Apple/Google 2FA 也没问题）。完成后，请告诉 Claude，它会确认。令牌缓存在 `~/.golf-coach/token.json`（模式 `0600`）中，MCP 从那时起自动使用它。无需终端，无需复制令牌 — 扩展程序如果您没有浏览器，则会自行获取一个。
### 终端替代（CLI 用户）
```bash
uv tool install "golf-coach[login]"
golf-coach login # 打开浏览器；登录一次
golf-coach login --headless # 静默刷新稍后（令牌有效期约为 7 天）
scripts/install-refresh-schedule.sh # 可选：每两周自动刷新一次
```
### 高级 — 粘贴令牌
`portal.trackmangolf.com` → 开发工具 → **网络** → 一个 `graphql` 请求 → 复制 `Authorization: Bearer …` 值 → 粘贴到扩展的 **Trackman 令牌** 字段（或设置 `TRACKMAN_TOKEN`）。令牌在大约 7 天后过期，因此上面的登录流程更简单。
### 验证它是否有效
询问 Claude *"我是否已登录到 Trackman?"* — 它运行 `auth(action="status")` 并用您的名字回复（永远不会是令牌）。
## MCP 工具
所有工具仅返回 **原始数据**；技能解释它。
**8 个工具。** `trackman` 和 `gamebook` 每个都采用一个 `action`（因此代理选择一个带有模式的工具，而不是许多几乎相同的工具）。
**设置：** `setup` — 一个调用返回一个始终在线的教练 **系统** （对于一个项目），**技能** 作为可上传的文件，以及每个客户端的步骤。匹配的拾取器中有一个 `setup` 提示。
**身份验证：** `auth(action: status | login, source?)`
**Trackman 数据（只读）：** `trackman(action: profile | handicap | sessions | session | rounds | clubs | summary)` — 配置文件+残障，残障历史，活动列表，一个活动完整信息（包括击球级别的指标），场次回合，俱乐部间距，活动计数。
**Gamebook 回合（本地，确定性）：** `gamebook(action: save | list | get | compare)` — 从 Golf GameBook 截图中提取的场次回合，滚动最后 5 个，覆盖范围感知（仅信任每洞得分）。
**跨源综合（本地，确定性）：** `synthesize()` — 对齐 Trackman 和 GameBook 的每个源的发现，按技能领域（无判决；参见 `CLAUDE.md` 的“源和规范化”）。
**会话分析（本地，确定性）：** `session_analysis(action: analyze | get | list)`
**训练计划内存：** `training_plan(action: save | next | list | done | verify)`
**可视化：** `build_visualization` （自包含的动画 HTML 工件）
有关完整的表格和支持的 GraphQL，请参见 [`CLAUDE.md`](./CLAUDE.md)。
## 技能（教练大脑）
`skills/` 下的技能以两种方式提供：
- **Claude Code:** 插件自动安装。
- **任何 MCP 客户端（包括 Claude Desktop）：** 服务器 **提供它们作为 MCP 提示**，因此它们出现在您的客户端的提示选择器中 — 无需单独安装。
| 技能 | 它做什么 |
|-------|--------------|
| `trackman-stats-analysis` | 从数据中诊断弱点 |
| `golf-coaching` | 将诊断转化为可行的练习计划（视觉优先；自动评估进度） |
| `drill-library` | 精选的练习 + 验证的链接 — 包括 **在家/无球** 练习 — 以及实时搜索 |
| `golf-practice-at-home` | 为诊断的故障构建每日 **无球** 例行程序，按练习动画 |
| `trackman-session-analyzer` | 摄入 + 规范化最近的会话 |
| `gamebook-screenshot-analysis` | 摄入 GameBook 回合截图到覆盖范围感知的回合记录；记分驱动的进度，供给教练 |
| `trackman-visualizer` | 动画诊断（或单个练习的机制）为 HTML 工件 |
（`trackman-api-discovery` 是一个项目/开发技能，不作为提示提供。）
## 开发
```bash
uv venv && uv pip install -e '.[login,dev]' # [login] = Playwright，[dev] = 测试/检查工具
golf-coach # 运行 MCP 服务器（stdio）
uv run python scripts/validate.py # 用您的令牌检查统计数据的覆盖范围
uv run pytest # 测试
uv run ruff check # 检查代码风格
uv run mypy # 类型检查
```
发布（PyPI + MCP 注册表 + Desktop `.mcpb`）是一个命令 — `scripts/release.sh patch` — 请参见 [`PUBLISHING.md`](./PUBLISHING.md)。
## 许可证
[MIT](./LICENSE)
