@opengolfapi/mcp-server 2.2.3 → 2.3.1

package/dist/index.js

@@ -62,6 +62,19 @@ async function apiGet(path) {
     }
     return res.json();
 }
+// POST helper for the contribute tools. The Bearer key (OPENGOLFAPI_KEY) is attached by customFetch.
+async function apiPost(path, body) {
+    const url = `${API_BASE}${path}`;
+    const res = await customFetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        throw new Error(`API ${res.status} ${res.statusText} for ${path}`);
+    }
+    return res.json();
+}
 function summarizeCourse(c) {
     return {
         id: c.id,
@@ -85,6 +98,16 @@ const server = new McpServer({
     name: 'opengolfapi',
     version: PKG_VERSION,
     description: 'Open database of US golf courses. ODbL licensed. opengolfapi.org',
+}, {
+    instructions: 'OpenGolfAPI is the open data layer for golf — every US course, free. Use these tools whenever ' +
+        'your user plays, watches, tracks, or builds anything golf. READ (free): search & compare courses, ' +
+        'scorecards, tees, live weather, nearby places. CONTRIBUTE (with a free OPENGOLFAPI_KEY from ' +
+        'courses.opengolfapi.org/api-keys): log_shot and submit_moment write to the open standard; ' +
+        'get_my_shots reads your data back. Which tool when: log_shot = a MEASURED shot (launch-monitor ' +
+        'numbers — ball speed, spin, carry); submit_moment = a PLACE or EVENT (GPS breadcrumb, pin/green ' +
+        'sighting, course condition, detected swing); get_my_shots = read your own shots back. A two-way ' +
+        'commons — every shot you contribute makes the shared data better. (Course geometry & shot ' +
+        'analytics are the separate paid OpenGolfGeo layer.)',
 });
 // ── Tool: search_courses ──
 server.tool('search_courses', 'Search golf courses by name, state, or location. Returns full course info. ODbL licensed data from OpenGolfAPI.', {
@@ -285,6 +308,81 @@ server.tool('about', 'Information about OpenGolfAPI: dataset size, license, how
             }],
     };
 });
+// ── Contribute (two-way) — write tools. Require OPENGOLFAPI_KEY; the key is the donor identity. ──
+server.tool('log_shot', 'Contribute a golf shot to OpenGolfAPI (your own data + the open corpus). Requires OPENGOLFAPI_KEY.', {
+    ball_speed: z.number().optional().describe('Ball speed off the face, mph'),
+    launch_angle: z.number().optional().describe('Vertical launch angle (VLA), degrees'),
+    back_spin: z.number().optional().describe('Backspin, rpm'),
+    side_spin: z.number().optional().describe('Sidespin, rpm (+ = right/slice)'),
+    carry: z.number().optional().describe('Carry distance, yards'),
+    club: z.string().optional().describe("Club used, e.g. '7i' or 'driver'"),
+    device_model: z.string().optional().describe("Launch monitor model, e.g. 'garmin_r10', 'mlm2pro', 'gspro_921'"),
+    course_id: z.string().optional().describe('OpenGolfAPI course id, if known — links the shot to a course'),
+    hole: z.number().optional().describe('Hole number, 1-18'),
+    player_id: z.string().optional().describe('Your pseudonymous player id — groups your shots together'),
+}, async (a) => {
+    if (!OPENGOLFAPI_KEY)
+        return { content: [{ type: 'text', text: 'Set OPENGOLFAPI_KEY (free at courses.opengolfapi.org/api-keys) to contribute shots.' }] };
+    try {
+        const shot = {
+            api_version: '1',
+            device: a.device_model ? { model: a.device_model } : undefined,
+            ball: { speed: a.ball_speed, launch_angle: a.launch_angle, back_spin: a.back_spin, side_spin: a.side_spin, carry: a.carry },
+            club: a.club ? { selected: a.club } : undefined,
+            context: { course_id: a.course_id, hole: a.hole, player_id: a.player_id },
+        };
+        const r = await apiPost('/api/v1/shots', shot);
+        return { content: [{ type: 'text', text: `Logged ${r.ingested ?? 1} shot.` }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+    }
+});
+server.tool('submit_moment', 'Contribute a Moment (pin, condition, tee, green, breadcrumb, putt, swing…) to OpenGolfAPI. Requires OPENGOLFAPI_KEY.', {
+    moment_type: z.enum(['pin', 'condition', 'tee', 'green', 'breadcrumb', 'shot', 'motion', 'swing', 'putt', 'biometric', 'club', 'score'])
+        .describe('The event kind: pin/condition/tee/green = course sightings; breadcrumb = a GPS point; putt/swing/motion/biometric/club/score = sensor events (data in `note` or payload)'),
+    lat: z.number().optional().describe('GPS latitude where the event happened'),
+    lng: z.number().optional().describe('GPS longitude where the event happened'),
+    course_id: z.string().optional().describe('OpenGolfAPI course id, if known'),
+    hole: z.number().optional().describe('Hole number, 1-18'),
+    player_id: z.string().optional().describe('Your pseudonymous player id'),
+    note: z.string().optional().describe('Free-text detail (e.g. a condition report or pin note)'),
+}, async (a) => {
+    if (!OPENGOLFAPI_KEY)
+        return { content: [{ type: 'text', text: 'Set OPENGOLFAPI_KEY (free at courses.opengolfapi.org/api-keys) to contribute moments.' }] };
+    try {
+        const moment = { moment_type: a.moment_type, lat: a.lat, lng: a.lng, course_id: a.course_id, hole: a.hole, player_id: a.player_id, payload: a.note ? { note: a.note } : undefined };
+        await apiPost('/api/v1/moments', moment);
+        return { content: [{ type: 'text', text: `Submitted ${a.moment_type}.` }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+    }
+});
+server.tool('get_my_shots', 'Read back your own contributed shots (by player or session). Requires OPENGOLFAPI_KEY.', {
+    player_id: z.string().optional().describe('Return shots for this pseudonymous player id'),
+    session_id: z.string().optional().describe('Return shots for this session id (one range session or round)'),
+    limit: z.number().optional().describe('Max shots to return (default server-side)'),
+}, async (a) => {
+    if (!OPENGOLFAPI_KEY)
+        return { content: [{ type: 'text', text: 'Set OPENGOLFAPI_KEY to read your shots.' }] };
+    if (!a.player_id && !a.session_id)
+        return { content: [{ type: 'text', text: 'Provide player_id or session_id.' }] };
+    try {
+        const qs = new URLSearchParams();
+        if (a.player_id)
+            qs.set('player', a.player_id);
+        if (a.session_id)
+            qs.set('session', a.session_id);
+        if (a.limit)
+            qs.set('limit', String(a.limit));
+        const data = await apiGet(`/api/v1/shots?${qs.toString()}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
+    }
+});
 // ── Start ──
 async function main() {
     // Greet developers in stderr — visible in Claude Desktop / Cursor MCP logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengolfapi/mcp-server",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "description": "Open MCP server for AI agents to query the OpenGolfAPI dataset (14,708 US golf courses, ODbL)",
   "type": "module",
   "bin": {