内容
# @opengolfapi/mcp-server
**高尔夫球，为人工智能代理而设计 — 高尔夫球开放数据层。** 给你的助手提供所有美国高尔夫球场（16,845个），免费，并让它能够贡献回馈，签署玩家，举办锦标赛。仅需一个提示就能构建一个完整的高尔夫球应用程序。
[OpenGolfAPI](https://opengolfapi.org) 是一个社区拥有的公共资源。一个免费的密钥，你的代理就可以读取全球高尔夫球数据并写入四个开放标准。
---
## 标准（整个故事）
OpenGolfAPI 建立在开放、可组合的协议上 — 实现一个或全部：
| 标准 | 什么是它 | 你用它来… |
|---|---|---|
| **OpenShot** | 一个 CC0 形状，用于发射监视器射击 — 一个模式，每个设备都映射到（Trackman，GSPro，Garmin，…）。 | 吸收来自任何监视器/模拟器的射击 → `log_shot`。 |
| **Moments** | 通用的事件吸收 — *任何*传感器信号（GPS 导航点，挥杆，推杆，俱乐部，分数，球洞，条件，存在）作为一个灵活的事件。 | 发送你拥有的任何信号 → `submit_moment`。 |
| **OpenJoin** | 签名，范围限定，**过期** 的加入令牌。一个 QR/链接 → 所有兑换它的人都加入同一个轮次/锦标赛 = 群组，链接。 | 通过一个点击加入一组或整个锦标赛 → `create_tournament_invite` / `join_tournament`。 |
| **OpenGolf ID** | 便携的高尔夫球身份 — *"用 OpenGolf 登录。"* 一个伪匿名 `player_id` 跨所有应用程序；差点 + 历史记录在每个应用程序中（引擎按 `player_id` 折叠，因此声明的身份的跨应用程序记录存在）。 | 给玩家一个身份，整个生态系统都共享 → `sign_in_with_opengolf`。 |
**大想法：** 每一次击球、时刻和轮次的贡献都使共享的公共资源对每个人更好 — 一个真正的双向数据层。读取是免费的；贡献是你在这个标准中获得地位的方式。
---
## 你的代理能得到什么
- **读取（免费，无密钥）：** 搜索和比较球场 · 完整的记分卡（标准杆 / 差点 / 洞距） · 障碍 · 实时天气和气候 · 附近地点 · 球台建议。
- **贡献（免费密钥）：** `log_shot`，`submit_moment` → 将数据写入开放标准 · `get_my_shots` → 读取您自己的数据。
- **身份和锦标赛（免费密钥）：** `sign_in_with_opengolf`（便携式 ID）· `create_tournament_invite` + `join_tournament`（运行活动 — **差点可选**，总杆或净杆）。
一个优秀的高尔夫球应用程序只需一个下午，不需要一年。
## 安装（MCP 客户端配置）
```json
{
"mcpServers": {
"opengolfapi": {
"command": "npx",
"args": ["-y", "@opengolfapi/mcp-server"],
"env": {
"OPENGOLFAPI_KEY": "<免费，可选 — 启用贡献，身份和锦标赛>"
}
}
}
}
```
在 https://courses.opengolfapi.org/api-keys 获取免费的 `OPENGOLFAPI_KEY`。读取工具无需密钥即可工作。
> **Claude Desktop：** 配置文件是 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）。 **Claude 代码：** `claude mcp add opengolfapi -- npx -y @opengolfapi/mcp-server`。 **无需密钥？** 删除整个 `env` 块 — 所有读取工具无需密钥即可工作（不要将占位符作为密钥粘贴）。
**第一个提示：** *"查找芝加哥附近的高尔夫球场，并向我展示最难的一个。"*
**哪个评分工具：** 随意一杆评分 → `score_round` · 联赛/锦标赛（分数随时间推移，排名很重要）→ `create_competition` → `record_attempt` → `finalize_competition` · 流媒体设备/实时应用程序 → `submit_moment`。规范域模型：https://api.opengolfapi.org/api/v1/model
## 工具
<!-- TOOLS:START (auto-generated from src by gen-manifest.mjs — do not edit by hand) -->
_56 工具：
- `search_courses` — 按名称、美国州或位置（纬度/经度 + 半径）搜索美国高尔夫球场。返回匹配的球场，包含位置、类型、标准杆。免费，ODbL 数据。
- `get_course` — 通过 ID 获取一个球场的完整详细信息：记分卡（每洞标准杆 + 差点）、球台、位置、联系方式、附近信息。免费。
- `get_tees` — 获取一个球场的所有球台，包含评级、坡度、距离。免费。
- `get_weather` — 获取一个球场位置的实时天气预报（Weather.gov）。免费。
- `get_climate` — 获取一个球场的每月气候正常值 + 最佳游玩月份。免费。
- `get_nearby` — 获取附近的酒店、餐厅和其他球场。免费。
- `log_shot` — 将高尔夫球击球贡献到开放的 OpenShot 标准（任何发射监视器）。需要密钥。单位：速度英里/小时，角度度，旋转速度转/分钟，距离码。
- `submit_moment` — 从任何传感器/可穿戴设备/手机贡献一个 Open Connect 事件。整个传感器频谱通过此处 — 类型特定数据放入 `payload`。需要密钥。
- `get_my_shots` — 读取您自己贡献的击球，按玩家或会话。需要密钥。
- `get_my_moments` — 读取您自己贡献的时刻（导航点、挥杆、推杆、条件...）按玩家、会话或类型。需要密钥。
- `propose_correction` — 提出对球场事实字段的修复（电话、网站、地址、建筑师、建成年份、球场名称、城市、邮政编码、球场类型）。我们的 AI 审查它（批准/拒绝/需要信息）。需要密钥。几何形状无法在此处纠正。
- `respond_to_review` — 对一个需要信息的纠正做出回应 — 添加来源或解释并重新打开它进行审查。需要密钥。
- `get_correction` — 检查您提出的纠正状态/裁决（已批准 | 已拒绝 | 需要信息 | 已应用）。需要密钥。
- `how_to_build` — 在 OpenGolfAPI 上构建和贡献数据的稳妥指南。在贡献之前调用此工具一次。
- `get_passport` — 免费（公共，无密钥）。任何高尔夫球手的共享记录 — 显示名称、OpenGolf 会员编号、已游玩球场、轮次、奖杯、推荐人。在您的应用程序中显示玩家的高尔夫球履历。
- `record_referral` — 记录一个用户推荐了另一个用户（推荐边）— 在共享图谱中构建您自己的应用程序邀请循环，命名空间到您的应用程序。需要密钥。
- `get_referrals` — 一个用户推荐了多少高尔夫球手（+ 列表）— 您的应用程序的病毒循环指标。需要密钥。
- `about` — 关于 OpenGolfAPI 以及如何使用此 MCP 服务器的信息。
- `request_sign_in_code` — 为一个人启动 "用 OpenGolf 登录"：向他们发送一个 6 位数字代码。无需 API 密钥。他们读取代码，然后调用 `complete_sign_in`。
- `complete_sign_in` — 完成登录：用 6 位数字代码交换他们的 OpenGolf ID + 访问令牌（用作 X-OpenGolf-Token 来扮演他们）。传递 ref=<邀请者玩家 ID>，当另一个玩家的邀请将他们带到这里时 — 它会记下推荐。
- `create_dev_key` — 创建一个与 OpenGolf ID 绑定的开发者 API 密钥（首先通过 `request_sign_in_code` → `complete_sign_in` 登录）。一次性返回密钥。第一方通道：无 OpenGolf ID，无密钥。
- `sign_in_with_opengolf` — 从他们的电子邮件中确定用户的 OpenGolf ID（sub = ogid_ + sha256(lower(trim(email)))[:16]）— 一行代码，无重定向。对于已验证的会话令牌，请使用 `request_sign_in_code` → `complete_sign_in`。
- `register_webhook` — 为您的域名事件注册一个 https URL（HMAC 签名交付，范围限定）。需要您的密钥（Authorization: Bearer ogapi_...）。
- `create_tournament_invite` — 创建一个可分享的邀请（QR/链接）；所有兑换它的人加入同一个活动/轮次。max_uses 限制大小（四人组=4）。需要密钥。
- `join_tournament` — 兑换邀请令牌 — 玩家加入群组/活动。需要密钥。
- `list_game_formats` — 每个 OpenMatch 评分格式。GROSS 评分免费且无密钥。
- `score_round` — 以任何格式评分一轮 — GROSS，免费，无密钥。players:[{player_id,holes:{"1":4}}] 或 entries:[{player_id,hole,value}]；holes:[{hole,par,stroke_index?}]。
- `plays_like` — 有效距离 — 规范的"plays like"数字（风/海拔/温度/海拔），因素逐一列出。免费，无密钥。与 `get_conditions` 搭配使用实时风。
- `get_conditions` — 球场的实时天气（温度/风/降水，预测模型，15 分钟缓存）。免费。 feeds `plays_like`。
- `link_dev_key` — 在现有的密钥上确认您的 OpenGolf ID。先登录；传递访问令牌 + 密钥。
- `list_dev_keys` — 列出您的 OpenGolf ID 拥有的密钥（仅前缀）。需要来自 `complete_sign_in` 的访问令牌。
- `get_profile` — 玩家的公共 OpenGolf ID 卡 — 名称、头像、链接、首选项。免费。
- `update_profile` — 编辑玩家自我声明的配置文件字段（派生事实无法设置）。需要密钥（声明的玩家需要他们的授权）。
- `get_awards` — 玩家的 OpenAwards — 派生奖杯 + 球场护照。需要密钥。
- `set_beacon` — 广播一个有同意的、过期的存在/可用性信号（存在|可用|开放）。需要密钥。
- `find_beacons` — 发现活跃的公共信号（查找我的群组/匹配）。需要密钥。
- `record_consent` — 记录玩家的同意授权（可审计，可撤销）。需要密钥。
- `create_competition` — 创建一个竞争（任何 OpenMatch 格式）。需要密钥。
- `list_competitions` — 列出竞争（免费）。过滤组织/球场/状态。
- `get_competition` — 一个竞争 + 实时总杆排名（免费）。
- `record_attempt` — 记录一个尝试（分数或边游戏价值）。幂等。需要密钥。
- `finalize_competition` — 完成 — 运行内核，存储总杆结果。需要密钥。
- `broadcast_feed` — OpenBroadcast P1 — 一个会话的 typed 馈送：广播值得广播的项目（分数/边游戏/金钱/奖项/条件）按升序（recorded_at, seq），每个都有模板叙述（headline<=60/ticker<=80）。仅在结算记录中出现金钱。需要密钥 + 会话访问（参与者或计算）。
- `get_handicap` — OpenIndex（测试版）— 从真实的、经公证的轮次计算出的玩家估计差点（每个分数在发生时盖章；任何人都可以验证）。不是官方的 — 可证明。读取您自己的免费，您的密钥；player_id 必须是 ogid_... 形式。
- `get_showcase` — 玩家的公共展示 — 他们的 OpenGolf ID 上的收藏品/记录（og.* 命名空间 + course.*）。免费，无密钥：传递他们的 ogid_。 Tombstoned（撤销/过期）记录隐藏。 可证明的奖杯墙。
- `verify_record` — 验证 OpenGolf 链上的记录/收藏品（签名、哈希链接、比特币锚定的透明度日志）。返回哈希 + 是否匹配 + 客户端计算公式（记录的 SHA256）+ 锚点。然后，您可以进一步操作，所有操作都无需密钥：拉取默克尔包含证明（GET /chain/anchors/:id/inclusion?hash=），验证检查点的 RS256 签名与 /.well-known/jwks.json，并解析比特币（OpenTimestamps）锚点。免费。信任没有人 — 重新计算哈希，检查包含，解析比特币。
- `list_webhooks` — 列出您的活动 webhook 订阅。需要密钥。
- `remove_webhook` — 通过 ID 停用您的 webhook 订阅之一（审计行保留）。需要密钥。
- `list_orgs` — 公共的已验证组织目录（免费）。
- `mint_asset` — 将资产（奖杯/徽章/印章/优惠券/会员资格）铸造到所有者的奖杯盒 + 链中。需要密钥。
- `file_claim` — 在信任账本中提交声明（所有权/证明/身份/记录/纠正）。需要密钥。
- `list_claims` — 列出声明（免费）。过滤申报者/主题/状态。
- `post_beta` — 在球洞上发布本地球场知识（“beta”）— AI 球童的燃料。需要密钥。
- `get_beta` — 读取球场/球洞的本地球场知识（免费）。
- `get_my_chain` — 导出您自己的防篡改 OpenGolf 链 + 检查点。需要密钥（自己的读取免费）。
- `verify_chain` — 验证链导出或遍历公共透明度日志（GET /chain/log?subject=），公共 + 无密钥 — 重新计算哈希链接，验证每个 RS256 检查点签名与 JWKS，并解析比特币锚点；报告篡改和位置。整个历史（注册表，按球场，主机）是独立可审计的 — 信任没有人。
<!-- TOOLS:END -->
## 更大的生态系统 — 两个前门
代理通过此 MCP 进入；**传感器/设备** 通过 **OpenGolf Connect** 进入（一个开放的连接器，从任何发射监视器流式传输击球到 `POST /v1/shots`）。两者都写入同一个开放的公共资源。 → https://opengolfapi.org/connect
## 了解更多
- **完整的 AI 编码器指南：** https://api.opengolfapi.org/llms-full.txt
- 机器规格（OpenAPI 3.1）：https://api.opengolfapi.org/openapi.json
- OpenShot 字段目录：https://api.opengolfapi.org/api/v1/openshot/fields
- Moments 字段目录：https://api.opengolfapi.org/api/v1/moments/fields
MIT 许可。球场数据 ODbL。击球 CC0。
