@opengolfapi/mcp-server 2.2.2 → 2.3.0

package/README.md

@@ -63,9 +63,21 @@ Donor tiers raise the daily limit further (10k / 50k / 250k / 1M).
 
 ## Telemetry
 
-Optional: set `SENTRY_DSN` env var to send errors to your own Sentry instance.
-We do not collect telemetry from end users — this is opt-in for the operator
-running the server.
+This server reports unhandled errors to the OpenGolfAPI Sentry project by default so the maintainers can catch bugs that hit real users. **No request bodies, no API keys, no PII** — only stack traces of exceptions thrown inside the server process. Quotas and sampling live in the Sentry project config; the DSN is an ingest endpoint, not a secret.
+
+To opt out completely:
+
+```
+OPENGOLFAPI_DISABLE_TELEMETRY=1 npx @opengolfapi/mcp-server
+```
+
+To send to your own Sentry project instead (overrides the default DSN):
+
+```
+SENTRY_DSN=https://your-dsn@sentry.io/... npx @opengolfapi/mcp-server
+```
+
+Example MCP config:
 
 ```json
 {
@@ -74,17 +86,13 @@ running the server.
       "command": "npx",
       "args": ["@opengolfapi/mcp-server"],
       "env": {
-        "OPENGOLFAPI_KEY": "ogapi_yourkeyhere",
-        "SENTRY_DSN": "https://<key>@o<org>.ingest.sentry.io/<project>"
+        "OPENGOLFAPI_KEY": "ogapi_yourkeyhere"
       }
     }
   }
 }
 ```
 
-When `SENTRY_DSN` is unset the SDK is a complete no-op — nothing is initialized
-and no network calls are made.
-
 ## License
 
 MIT

package/dist/index.js

@@ -12,13 +12,20 @@
  * Install: npx @opengolfapi/mcp-server
  */
 // Sentry must initialize BEFORE any other imports that could throw, so any
-// load-time error in transitive deps still gets captured. The init is a no-op
-// when SENTRY_DSN is unset, so end users who run the server via npx never
-// send telemetry unless they set the env var themselves.
+// load-time error in transitive deps still gets captured.
+//
+// Default DSN ships baked-in so we get bug telemetry from every install — a
+// Sentry DSN is designed to be public (it's an ingest endpoint, not a secret).
+// Users can override with SENTRY_DSN, or opt out completely with
+// OPENGOLFAPI_DISABLE_TELEMETRY=1.
 import * as Sentry from '@sentry/node';
-if (process.env.SENTRY_DSN) {
+const DEFAULT_SENTRY_DSN = 'https://2cb261cd86bbfe9e105309d3c2edbced@o4511071885000704.ingest.us.sentry.io/4511345201315840';
+const SENTRY_DSN_ACTIVE = process.env.OPENGOLFAPI_DISABLE_TELEMETRY
+    ? ''
+    : (process.env.SENTRY_DSN || DEFAULT_SENTRY_DSN);
+if (SENTRY_DSN_ACTIVE) {
     Sentry.init({
-        dsn: process.env.SENTRY_DSN,
+        dsn: SENTRY_DSN_ACTIVE,
         tracesSampleRate: 0.1,
         release: `opengolfapi-mcp-server@${process.env.npm_package_version || 'unknown'}`,
     });
@@ -27,7 +34,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 // Package version — used in User-Agent so the API can identify MCP traffic.
-const PKG_VERSION = '2.2.2';
+const PKG_VERSION = '2.2.3';
 const API_BASE = process.env.OPENGOLFAPI_BASE ?? 'https://api.opengolfapi.org';
 // Optional API key for higher rate limits. Anonymous (no key) still works
 // at 1k req/day per IP. With a free key from courses.opengolfapi.org/api-keys,
@@ -55,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,
@@ -78,6 +98,13 @@ 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. 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.', {
@@ -278,6 +305,67 @@ 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(), launch_angle: z.number().optional(),
+    back_spin: z.number().optional(), side_spin: z.number().optional(), carry: z.number().optional(),
+    club: z.string().optional(), device_model: z.string().optional(),
+    course_id: z.string().optional(), hole: z.number().optional(), player_id: z.string().optional(),
+}, 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']),
+    lat: z.number().optional(), lng: z.number().optional(),
+    course_id: z.string().optional(), hole: z.number().optional(), player_id: z.string().optional(),
+    note: z.string().optional(),
+}, 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(), session_id: z.string().optional(), limit: z.number().optional() }, 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.2",
+  "version": "2.3.0",
   "description": "Open MCP server for AI agents to query the OpenGolfAPI dataset (14,708 US golf courses, ODbL)",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm test",
+    "test": "npm run build && vitest run"
   },
   "repository": {
     "type": "git",
@@ -38,6 +39,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.5"
   }
 }