@opengolfapi/mcp-server 2.2.0 → 2.2.2

package/README.md

@@ -61,6 +61,30 @@ Donor tiers raise the daily limit further (10k / 50k / 250k / 1M).
 - `get_climate(id)` — monthly climate normals for the course location
 - `get_nearby(id)` — nearby POIs (hotels, restaurants, airports)
 
+## 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.
+
+```json
+{
+  "mcpServers": {
+    "opengolfapi": {
+      "command": "npx",
+      "args": ["@opengolfapi/mcp-server"],
+      "env": {
+        "OPENGOLFAPI_KEY": "ogapi_yourkeyhere",
+        "SENTRY_DSN": "https://<key>@o<org>.ingest.sentry.io/<project>"
+      }
+    }
+  }
+}
+```
+
+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

@@ -11,11 +11,23 @@
  *
  * 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.
+import * as Sentry from '@sentry/node';
+if (process.env.SENTRY_DSN) {
+    Sentry.init({
+        dsn: process.env.SENTRY_DSN,
+        tracesSampleRate: 0.1,
+        release: `opengolfapi-mcp-server@${process.env.npm_package_version || 'unknown'}`,
+    });
+}
 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.0';
+const PKG_VERSION = '2.2.2';
 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,
@@ -76,61 +88,68 @@ server.tool('search_courses', 'Search golf courses by name, state, or location.
     state: z.string().optional().describe('2-letter US state code'),
     limit: z.number().optional().default(10).describe('Max results'),
 }, async ({ lat, lng, radius_mi, query: q, state, limit }) => {
-    const max = limit ?? 10;
-    const r = radius_mi ?? 25;
-    // Build a server-side query. The public search supports `q`, `state`,
-    // and `limit`. Geo (lat/lng/radius_mi) is filtered client-side after
-    // fetch — see https://github.com/opengolfapi/api/issues for tracking
-    // native geo search support.
-    const params = new URLSearchParams();
-    if (q)
-        params.set('q', q);
-    if (state)
-        params.set('state', state.toUpperCase());
-    let pool = [];
-    let geoFilterApplied = false;
-    if (lat !== undefined && lng !== undefined) {
-        // Geo filtering: pull a wider net so the local bbox filter has data
-        // to chew on. If a state is given, prefer the state listing
-        // (returns up to 100 per page) since it's higher recall than search.
-        params.set('limit', '100');
-        if (state && !q) {
-            const data = await apiGet(`/v1/courses/state/${state.toUpperCase()}`);
-            pool = data.courses ?? [];
+    try {
+        const max = limit ?? 10;
+        const r = radius_mi ?? 25;
+        // Build a server-side query. The public search supports `q`, `state`,
+        // and `limit`. Geo (lat/lng/radius_mi) is filtered client-side after
+        // fetch — see https://github.com/opengolfapi/api/issues for tracking
+        // native geo search support.
+        const params = new URLSearchParams();
+        if (q)
+            params.set('q', q);
+        if (state)
+            params.set('state', state.toUpperCase());
+        let pool = [];
+        let geoFilterApplied = false;
+        if (lat !== undefined && lng !== undefined) {
+            // Geo filtering: pull a wider net so the local bbox filter has data
+            // to chew on. If a state is given, prefer the state listing
+            // (returns up to 100 per page) since it's higher recall than search.
+            params.set('limit', '100');
+            if (state && !q) {
+                const data = await apiGet(`/v1/courses/state/${state.toUpperCase()}`);
+                pool = data.courses ?? [];
+            }
+            else {
+                const data = await apiGet(`/v1/courses/search?${params.toString()}`);
+                pool = data.courses ?? [];
+            }
+            const latDelta = r / 69.0;
+            const lngDelta = r / (69.0 * Math.cos(lat * Math.PI / 180));
+            pool = pool.filter(c => {
+                if (c.latitude == null || c.longitude == null)
+                    return false;
+                return c.latitude >= lat - latDelta
+                    && c.latitude <= lat + latDelta
+                    && c.longitude >= lng - lngDelta
+                    && c.longitude <= lng + lngDelta;
+            });
+            geoFilterApplied = true;
         }
         else {
+            params.set('limit', String(max));
             const data = await apiGet(`/v1/courses/search?${params.toString()}`);
             pool = data.courses ?? [];
         }
-        const latDelta = r / 69.0;
-        const lngDelta = r / (69.0 * Math.cos(lat * Math.PI / 180));
-        pool = pool.filter(c => {
-            if (c.latitude == null || c.longitude == null)
-                return false;
-            return c.latitude >= lat - latDelta
-                && c.latitude <= lat + latDelta
-                && c.longitude >= lng - lngDelta
-                && c.longitude <= lng + lngDelta;
-        });
-        geoFilterApplied = true;
+        const courses = pool.slice(0, max).map(summarizeCourse);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        courses,
+                        total: courses.length,
+                        ...(geoFilterApplied ? { geo_filter: { lat, lng, radius_mi: r } } : {}),
+                        source: SOURCE,
+                    }, null, 2),
+                }],
+        };
     }
-    else {
-        params.set('limit', String(max));
-        const data = await apiGet(`/v1/courses/search?${params.toString()}`);
-        pool = data.courses ?? [];
+    catch (err) {
+        Sentry.captureException(err, { tags: { tool: 'search_courses' } });
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
-    const courses = pool.slice(0, max).map(summarizeCourse);
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({
-                    courses,
-                    total: courses.length,
-                    ...(geoFilterApplied ? { geo_filter: { lat, lng, radius_mi: r } } : {}),
-                    source: SOURCE,
-                }, null, 2),
-            }],
-    };
 });
 // ── Tool: get_course ──
 server.tool('get_course', 'Get detailed golf course info including full scorecard with par and handicap index per hole. ODbL licensed.', {
@@ -144,7 +163,8 @@ server.tool('get_course', 'Get detailed golf course info including full scorecar
             apiGet(`/v1/courses/${course_id}/holes`),
         ]);
     }
-    catch {
+    catch (err) {
+        Sentry.captureException(err, { tags: { tool: 'get_course' } });
         return { content: [{ type: 'text', text: 'Course not found' }] };
     }
     const scorecard = (holes ?? [])
@@ -187,6 +207,7 @@ server.tool('get_tees', 'Get all tee sets for a course including ratings, slopes
         };
     }
     catch (err) {
+        Sentry.captureException(err, { tags: { tool: 'get_tees' } });
         const msg = err instanceof Error ? err.message : String(err);
         return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
@@ -205,6 +226,7 @@ server.tool('get_climate', 'Get monthly climate normals for a course (temperatur
         };
     }
     catch (err) {
+        Sentry.captureException(err, { tags: { tool: 'get_climate' } });
         const msg = err instanceof Error ? err.message : String(err);
         return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
@@ -228,13 +250,45 @@ server.tool('get_nearby', 'Get nearby points of interest for a course (hotels, r
         };
     }
     catch (err) {
+        Sentry.captureException(err, { tags: { tool: 'get_nearby' } });
         const msg = err instanceof Error ? err.message : String(err);
         return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
 });
+// ── Tool: about ──
+server.tool('about', 'Information about OpenGolfAPI: dataset size, license, how to contribute, how to contact the maintainers. Useful when an AI agent or user wants to know who built this and how to reach them.', {}, async () => {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    name: 'OpenGolfAPI',
+                    courses: 14708,
+                    license: 'ODbL-1.0',
+                    docs: 'https://opengolfapi.org',
+                    api_docs: 'https://api.opengolfapi.org',
+                    api_keys: 'https://courses.opengolfapi.org/api-keys',
+                    pricing: 'https://courses.opengolfapi.org/pricing',
+                    donate: 'https://opencollective.com/opengolfapi',
+                    github: 'https://github.com/opengolfapi',
+                    developers: {
+                        message: 'Building something on top of OpenGolfAPI? We want to know about it. Tell us what you\'re working on, what data you wish we had, and where the API or MCP server falls short.',
+                        contact: 'hello@opengolfapi.org',
+                    },
+                }, null, 2),
+            }],
+    };
+});
 // ── Start ──
 async function main() {
+    // Greet developers in stderr — visible in Claude Desktop / Cursor MCP logs.
+    // Helps anyone debugging or evaluating the server know how to reach us.
+    console.error('OpenGolfAPI MCP server — 14,708 US golf courses, ODbL.');
+    console.error('Building something? We want to hear about it: hello@opengolfapi.org');
+    console.error('Free key for higher rate limits: https://courses.opengolfapi.org/api-keys');
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch(console.error);
+main().catch((err) => {
+    Sentry.captureException(err);
+    console.error(err);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengolfapi/mcp-server",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Open MCP server for AI agents to query the OpenGolfAPI dataset (14,708 US golf courses, ODbL)",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
   "homepage": "https://opengolfapi.org",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "@sentry/node": "^10.51.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {