@opengolfapi/mcp-server 2.1.0 → 2.2.1

package/README.md

@@ -1,6 +1,8 @@
 # @opengolfapi/mcp-server
 
-Open MCP server for AI agents to query the OpenGolfAPI dataset (16,908 US golf courses). All data is ODbL licensed and open.
+Open MCP server for AI agents to query the OpenGolfAPI dataset (14,708 US golf courses). All data is ODbL licensed and open.
+
+All requests go through the public API at https://api.opengolfapi.org. With an optional `OPENGOLFAPI_KEY`, requests authenticate as your tier and unlock higher rate limits.
 
 ## Install
 
@@ -22,6 +24,35 @@ Add to your MCP client config:
 }
 ```
 
+## API keys (optional)
+
+### Optional: higher rate limits with a free key
+
+Without a key, the MCP server uses anonymous access (1,000 requests/day per IP).
+
+Get a free key at https://courses.opengolfapi.org/api-keys (~30 seconds, no card),
+then set:
+
+```bash
+export OPENGOLFAPI_KEY=ogapi_yourkeyhere
+```
+
+In Claude Desktop's MCP config, add the env var to the server entry:
+
+```json
+{
+  "mcpServers": {
+    "opengolfapi": {
+      "command": "npx",
+      "args": ["@opengolfapi/mcp-server"],
+      "env": { "OPENGOLFAPI_KEY": "ogapi_yourkeyhere" }
+    }
+  }
+}
+```
+
+Donor tiers raise the daily limit further (10k / 50k / 250k / 1M).
+
 ## Tools
 
 - `search_courses(query, state?, lat?, lng?, radius_mi?)` — find courses by name, state, or location

package/dist/index.d.ts

@@ -5,6 +5,10 @@
  * Tools: search_courses, get_course, get_tees, get_climate, get_nearby
  * All data is open — ODbL licensed.
  *
+ * All tools call the public REST API at https://api.opengolfapi.org.
+ * No direct database access. With an optional OPENGOLFAPI_KEY env var,
+ * requests authenticate as your tier and unlock higher rate limits.
+ *
  * Install: npx @opengolfapi/mcp-server
  */
 export {};

package/dist/index.js

@@ -5,23 +5,67 @@
  * Tools: search_courses, get_course, get_tees, get_climate, get_nearby
  * All data is open — ODbL licensed.
  *
+ * All tools call the public REST API at https://api.opengolfapi.org.
+ * No direct database access. With an optional OPENGOLFAPI_KEY env var,
+ * requests authenticate as your tier and unlock higher rate limits.
+ *
  * Install: npx @opengolfapi/mcp-server
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { createClient } from '@supabase/supabase-js';
-const SUPABASE_URL = process.env.SUPABASE_URL ?? 'https://zeskurqlsgvmahzmmsmd.supabase.co';
-const SUPABASE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY ?? '';
-if (!SUPABASE_KEY) {
-    console.error('SUPABASE_SERVICE_ROLE_KEY required');
-    process.exit(1);
+// Package version — used in User-Agent so the API can identify MCP traffic.
+const PKG_VERSION = '2.2.0';
+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,
+// the limit jumps to 10k+/day depending on donor tier.
+const OPENGOLFAPI_KEY = process.env.OPENGOLFAPI_KEY;
+const userAgent = `opengolfapi-mcp-server/${PKG_VERSION}`;
+const SOURCE = 'OpenGolfAPI (opengolfapi.org) — ODbL licensed';
+// Wrap fetch so every outbound request carries our User-Agent and, when
+// OPENGOLFAPI_KEY is set, an Authorization: Bearer header so the API can
+// apply the donor-tier rate limit.
+const customFetch = (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set('User-Agent', userAgent);
+    headers.set('Accept', 'application/json');
+    if (OPENGOLFAPI_KEY) {
+        headers.set('Authorization', `Bearer ${OPENGOLFAPI_KEY}`);
+    }
+    return fetch(input, { ...init, headers });
+};
+async function apiGet(path) {
+    const url = `${API_BASE}${path}`;
+    const res = await customFetch(url);
+    if (!res.ok) {
+        throw new Error(`API ${res.status} ${res.statusText} for ${path}`);
+    }
+    return res.json();
+}
+function summarizeCourse(c) {
+    return {
+        id: c.id,
+        name: c.course_name,
+        city: c.city,
+        state: c.state,
+        lat: c.latitude,
+        lng: c.longitude,
+        type: c.course_type,
+        par: c.par_total,
+        total_yardage: c.total_yardage,
+        phone: c.phone,
+        website: c.website,
+        architect: c.architect,
+        year_built: c.year_built,
+        address: c.address,
+        postal_code: c.postal_code,
+    };
 }
-const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
 const server = new McpServer({
     name: 'opengolfapi',
-    version: '2.0.0',
-    description: 'Open database of 17,000+ US golf courses. ODbL licensed. opengolfapi.org',
+    version: PKG_VERSION,
+    description: 'Open database of US golf courses. ODbL licensed. opengolfapi.org',
 });
 // ── Tool: search_courses ──
 server.tool('search_courses', 'Search golf courses by name, state, or location. Returns full course info. ODbL licensed data from OpenGolfAPI.', {
@@ -32,44 +76,58 @@ 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 }) => {
-    let query = supabase.from('golf_courses').select('*');
+    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)
-        query = query.ilike('course_name', `%${q}%`);
+        params.set('q', q);
     if (state)
-        query = query.eq('state', state.toUpperCase());
+        params.set('state', state.toUpperCase());
+    let pool = [];
+    let geoFilterApplied = false;
     if (lat !== undefined && lng !== undefined) {
-        const r = radius_mi ?? 25;
+        // 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));
-        query = query
-            .gte('latitude', lat - latDelta).lte('latitude', lat + latDelta)
-            .gte('longitude', lng - lngDelta).lte('longitude', lng + lngDelta);
+        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 { data } = await query.limit(limit ?? 10);
-    const courses = (data ?? []).map((c) => ({
-        id: c.id,
-        name: c.course_name,
-        city: c.city,
-        state: c.state,
-        lat: c.latitude,
-        lng: c.longitude,
-        type: c.course_type,
-        par: c.par_total,
-        total_yardage: c.total_yardage,
-        phone: c.phone,
-        website: c.website,
-        architect: c.architect,
-        year_built: c.year_built,
-        address: c.address,
-        postal_code: c.postal_code,
-    }));
+    else {
+        params.set('limit', String(max));
+        const data = await apiGet(`/v1/courses/search?${params.toString()}`);
+        pool = data.courses ?? [];
+    }
+    const courses = pool.slice(0, max).map(summarizeCourse);
     return {
         content: [{
                 type: 'text',
                 text: JSON.stringify({
                     courses,
                     total: courses.length,
-                    source: 'OpenGolfAPI (opengolfapi.org) — ODbL licensed',
+                    ...(geoFilterApplied ? { geo_filter: { lat, lng, radius_mi: r } } : {}),
+                    source: SOURCE,
                 }, null, 2),
             }],
     };
@@ -78,15 +136,21 @@ server.tool('search_courses', 'Search golf courses by name, state, or location.
 server.tool('get_course', 'Get detailed golf course info including full scorecard with par and handicap index per hole. ODbL licensed.', {
     course_id: z.string().describe('Course UUID from search results'),
 }, async ({ course_id }) => {
-    const [courseRes, holesRes] = await Promise.all([
-        supabase.from('golf_courses').select('*').eq('id', course_id).single(),
-        supabase.from('golf_course_holes').select('hole_number, par, handicap_index').eq('course_id', course_id).not('par', 'is', null).order('hole_number'),
-    ]);
-    if (courseRes.error || !courseRes.data) {
+    let c;
+    let holes;
+    try {
+        [c, { holes }] = await Promise.all([
+            apiGet(`/v1/courses/${course_id}`),
+            apiGet(`/v1/courses/${course_id}/holes`),
+        ]);
+    }
+    catch {
         return { content: [{ type: 'text', text: 'Course not found' }] };
     }
-    const c = courseRes.data;
-    const scorecard = (holesRes.data ?? []).map(h => ({
+    const scorecard = (holes ?? [])
+        .filter(h => h.par != null)
+        .sort((a, b) => a.hole_number - b.hole_number)
+        .map(h => ({
         hole: h.hole_number,
         par: h.par,
         handicap_index: h.handicap_index,
@@ -95,24 +159,10 @@ server.tool('get_course', 'Get detailed golf course info including full scorecar
         content: [{
                 type: 'text',
                 text: JSON.stringify({
-                    id: c.id,
-                    name: c.course_name,
-                    city: c.city,
-                    state: c.state,
-                    lat: c.latitude,
-                    lng: c.longitude,
-                    type: c.course_type,
-                    par: c.par_total,
-                    total_yardage: c.total_yardage,
-                    holes: scorecard.length,
-                    phone: c.phone,
-                    website: c.website,
-                    architect: c.architect,
-                    year_built: c.year_built,
-                    address: c.address,
-                    postal_code: c.postal_code,
+                    ...summarizeCourse(c),
+                    holes: scorecard.length || c.holes_count,
                     scorecard,
-                    source: 'OpenGolfAPI (opengolfapi.org) — ODbL licensed',
+                    source: SOURCE,
                 }, null, 2),
             }],
     };
@@ -121,62 +171,97 @@ server.tool('get_course', 'Get detailed golf course info including full scorecar
 server.tool('get_tees', 'Get all tee sets for a course including ratings, slopes, and yardages per tee. ODbL licensed.', {
     course_id: z.string().describe('Course UUID'),
 }, async ({ course_id }) => {
-    const { data, error } = await supabase
-        .from('golf_course_tees')
-        .select('*')
-        .eq('course_id', course_id)
-        .order('total_yardage', { ascending: false });
-    if (error) {
-        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    try {
+        const { tees } = await apiGet(`/v1/courses/${course_id}/tees`);
+        // Sort longest-yardage first to match prior behavior.
+        const sorted = [...(tees ?? [])].sort((a, b) => {
+            const ay = a.total_yardage ?? -1;
+            const by = b.total_yardage ?? -1;
+            return by - ay;
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ tees: sorted, source: SOURCE }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({ tees: data ?? [], source: 'OpenGolfAPI (opengolfapi.org) — ODbL licensed' }, null, 2),
-            }],
-    };
 });
 // ── Tool: get_climate ──
 server.tool('get_climate', 'Get monthly climate normals for a course (temperature, precipitation, playability). ODbL licensed.', {
     course_id: z.string().describe('Course UUID'),
 }, async ({ course_id }) => {
-    const { data, error } = await supabase
-        .from('golf_course_climate')
-        .select('*')
-        .eq('course_id', course_id)
-        .maybeSingle();
-    if (error) {
-        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    try {
+        const climate = await apiGet(`/v1/courses/${course_id}/climate`);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ climate, source: SOURCE }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: 'text', text: `Error: ${msg}` }] };
     }
-    return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({ climate: data, source: 'OpenGolfAPI (opengolfapi.org) — ODbL licensed' }, null, 2),
-            }],
-    };
 });
 // ── Tool: get_nearby ──
 server.tool('get_nearby', 'Get nearby points of interest for a course (hotels, restaurants, airports) within ~20 miles. ODbL licensed.', {
     course_id: z.string().describe('Course UUID'),
 }, async ({ course_id }) => {
-    const { data, error } = await supabase
-        .from('golf_course_nearby')
-        .select('*')
-        .eq('course_id', course_id)
-        .order('distance_miles')
-        .limit(20);
-    if (error) {
-        return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
+    try {
+        const { nearby } = await apiGet(`/v1/courses/${course_id}/nearby`);
+        const sorted = [...(nearby ?? [])].sort((a, b) => {
+            const ad = a.distance_miles ?? Number.POSITIVE_INFINITY;
+            const bd = b.distance_miles ?? Number.POSITIVE_INFINITY;
+            return ad - bd;
+        }).slice(0, 20);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ nearby: sorted, source: SOURCE }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        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({ nearby: data ?? [], source: 'OpenGolfAPI (opengolfapi.org) — ODbL licensed' }, null, 2),
+                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);
 }

package/package.json

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