google-tools-mcp 1.2.11 → 2.0.0

package/dist/tools/maps/directions.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { UserError } from 'fastmcp';
+import { getMapsApiKey, mapsFetch } from './mapsClient.js';
+
+const waypoint = z.union([
+    z.string().min(1).describe('An address or place name'),
+    z.object({
+        latitude: z.number().min(-90).max(90).describe('Latitude in degrees'),
+        longitude: z.number().min(-180).max(180).describe('Longitude in degrees'),
+    }).describe('Explicit coordinates'),
+]);
+const FIELD_MASK = 'routes.distanceMeters,routes.duration,routes.description,routes.legs.steps.distanceMeters,routes.legs.steps.staticDuration,routes.legs.steps.navigationInstruction.instructions,routes.legs.steps.transitDetails';
+
+// The Routes API documents WALK and BICYCLE as beta travel modes and requires displaying
+// this warning to the user for any walking/bicycling route shown:
+// https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteTravelMode
+const BETA_TRAVEL_MODES = new Set(['WALK', 'BICYCLE']);
+const BETA_TRAVEL_MODE_WARNING = 'WALK and BICYCLE routes are in beta: pedestrian and cycling paths may be incomplete or imprecise in some areas.';
+
+function formatWaypoint(value) {
+    return typeof value === 'string' ? { address: value } : { location: { latLng: value } };
+}
+
+function formatTransitDetails(details) {
+    if (!details) return undefined;
+    const line = details.transitLine;
+    return {
+        line: line?.nameShort || line?.name || null,
+        vehicle: line?.vehicle?.type || null,
+        headsign: details.headsign || null,
+        departureStop: details.stopDetails?.departureStop?.name || null,
+        departureTime: details.stopDetails?.departureTime || null,
+        arrivalStop: details.stopDetails?.arrivalStop?.name || null,
+        arrivalTime: details.stopDetails?.arrivalTime || null,
+        stopCount: details.stopCount ?? null,
+    };
+}
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsDirections',
+        description: 'Get a route summary and turn-by-turn instructions between addresses or coordinates.',
+        parameters: z.object({
+            origin: waypoint.describe('Route start: address string or {latitude, longitude}'),
+            destination: waypoint.describe('Route end: address string or {latitude, longitude}'),
+            travelMode: z.enum(['DRIVE', 'WALK', 'BICYCLE', 'TRANSIT']).describe('Travel mode for the route'),
+            departureTime: z.string().datetime({ offset: true }).optional().describe('RFC 3339 departure time. Omit to depart now. Must be in the future unless travelMode is TRANSIT (the Routes API rejects past times for other modes).'),
+        }),
+        execute: async (args) => {
+            if (args.departureTime && args.travelMode !== 'TRANSIT' && new Date(args.departureTime).getTime() < Date.now()) {
+                throw new UserError('departureTime must be in the future for DRIVE/WALK/BICYCLE routes (the Routes API only accepts past departure times for TRANSIT). Omit departureTime to depart now.');
+            }
+            const body = { origin: formatWaypoint(args.origin), destination: formatWaypoint(args.destination), travelMode: args.travelMode };
+            if (args.departureTime) body.departureTime = args.departureTime;
+            const data = await mapsFetch('https://routes.googleapis.com/directions/v2:computeRoutes', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Goog-Api-Key': getMapsApiKey(), 'X-Goog-FieldMask': FIELD_MASK }, body: JSON.stringify(body) });
+            const route = data.routes?.[0];
+            if (!route) return JSON.stringify(null);
+            return JSON.stringify({
+                description: route.description || null,
+                distanceMeters: route.distanceMeters ?? null,
+                duration: route.duration || null,
+                ...(BETA_TRAVEL_MODES.has(args.travelMode) ? { warning: BETA_TRAVEL_MODE_WARNING } : {}),
+                steps: (route.legs || []).flatMap((leg) => (leg.steps || []).map((step) => ({
+                    instructions: step.navigationInstruction?.instructions || null,
+                    distanceMeters: step.distanceMeters ?? null,
+                    duration: step.staticDuration || null,
+                    ...(step.transitDetails ? { transit: formatTransitDetails(step.transitDetails) } : {}),
+                }))),
+            });
+        },
+    });
+}

package/dist/tools/maps/geocode.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { getMapsApiKey, mapsFetch } from './mapsClient.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsGeocode',
+        description: 'Convert an address to coordinates, a formatted address, and a Google place ID.',
+        parameters: z.object({ address: z.string().min(1).describe('The street address or place name to geocode') }),
+        execute: async ({ address }) => {
+            const params = new URLSearchParams({ address, key: getMapsApiKey() });
+            const data = await mapsFetch(`https://maps.googleapis.com/maps/api/geocode/json?${params}`);
+            const result = data.results?.[0];
+            return JSON.stringify(result ? { location: result.geometry?.location || null, formattedAddress: result.formatted_address || null, placeId: result.place_id || null } : null);
+        },
+    });
+}

package/dist/tools/maps/index.js

@@ -0,0 +1,15 @@
+import { register as geocode } from './geocode.js';
+import { register as reverseGeocode } from './reverseGeocode.js';
+import { register as searchNearby } from './searchNearby.js';
+import { register as searchPlaces } from './searchPlaces.js';
+import { register as placeDetails } from './placeDetails.js';
+import { register as directions } from './directions.js';
+
+export function registerMapsTools(server) {
+    geocode(server);
+    reverseGeocode(server);
+    searchNearby(server);
+    searchPlaces(server);
+    placeDetails(server);
+    directions(server);
+}

package/dist/tools/maps/mapsClient.js

@@ -0,0 +1,83 @@
+import { UserError } from 'fastmcp';
+
+export function getMapsApiKey() {
+    const apiKey = process.env.GOOGLE_MAPS_API_KEY;
+    if (!apiKey) throw new UserError('Set GOOGLE_MAPS_API_KEY to use Maps tools. This must be a Google Maps Platform API key, separate from Google OAuth.');
+    return apiKey;
+}
+
+// Generic query-string secret patterns (key=, api_key=, apikey=, access_token=, token=),
+// so future call sites that embed a credential in a URL are covered even if the exact
+// param name changes.
+const SECRET_QUERY_PARAM_PATTERN = /([?&](?:key|api[_-]?key|access_token|token)=)[^&\s'"]+/gi;
+
+// Scrubs the live GOOGLE_MAPS_API_KEY value (if set) plus any key-shaped query-string
+// parameter out of a string before it can reach a caller-visible UserError. This is the
+// single boundary every mapsFetch error path routes through, so no code path (geocoding's
+// URL-embedded key, a future endpoint, a raw network error whose message happens to quote
+// the failed URL) can leak the credential to the MCP caller or its logs.
+export function redactSecrets(text) {
+    if (typeof text !== 'string') return text;
+    let redacted = text;
+    const apiKey = process.env.GOOGLE_MAPS_API_KEY;
+    if (apiKey) redacted = redacted.split(apiKey).join('[REDACTED]');
+    return redacted.replace(SECRET_QUERY_PARAM_PATTERN, '$1[REDACTED]');
+}
+
+export async function mapsFetch(url, options = {}) {
+    let response;
+    try { response = await fetch(url, options); }
+    catch (error) { throw new UserError(redactSecrets(`Google Maps request failed: ${error.message || error}`)); }
+    let data;
+    try { data = await response.json(); } catch { data = null; }
+    if (data === null && response.ok) {
+        throw new UserError(`Google Maps API returned an unparsable response (HTTP ${response.status}).`);
+    }
+    const apiStatusError = data?.status && !['OK', 'ZERO_RESULTS'].includes(data.status);
+    if (!response.ok || apiStatusError) {
+        const status = data?.error?.status || data?.status || response.status;
+        const message = data?.error?.message || data?.error_message || response.statusText || 'Unknown error';
+        throw new UserError(redactSecrets(`Google Maps API error (${status}): ${message}`));
+    }
+    return data;
+}
+
+export async function placesRequest(url, { method = 'GET', body, fieldMask }) {
+    const headers = { 'X-Goog-Api-Key': getMapsApiKey(), 'X-Goog-FieldMask': fieldMask };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    return mapsFetch(url, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+}
+
+export function formatPlace(place) {
+    return { placeId: place.id, name: place.displayName?.text || null, address: place.formattedAddress || null, location: place.location || null, types: place.types || [], rating: place.rating ?? null, userRatingCount: place.userRatingCount ?? null, priceLevel: place.priceLevel || null, googleMapsUri: place.googleMapsUri || null };
+}
+
+export function haversineMeters(a, b) {
+    const R = 6371000;
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(b.latitude - a.latitude);
+    const dLng = toRad(b.longitude - a.longitude);
+    const lat1 = toRad(a.latitude);
+    const lat2 = toRad(b.latitude);
+    const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+    return 2 * R * Math.asin(Math.sqrt(h));
+}
+
+export function withinRadius(places, center, radiusMeters) {
+    return places.filter((place) => {
+        const loc = place.location;
+        if (!loc || typeof loc.latitude !== 'number' || typeof loc.longitude !== 'number') return false;
+        return haversineMeters(center, loc) <= radiusMeters;
+    });
+}
+
+export function dedupePlaces(places, maxResults) {
+    const seen = new Set();
+    return places.filter((place) => {
+        if (!place.placeId || seen.has(place.placeId)) return false;
+        seen.add(place.placeId);
+        return true;
+    }).slice(0, maxResults);
+}
+
+export const SEARCH_FIELD_MASK = 'places.id,places.displayName,places.formattedAddress,places.location,places.types,places.rating,places.userRatingCount,places.priceLevel,places.googleMapsUri';

package/dist/tools/maps/placeDetails.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import { placesRequest } from './mapsClient.js';
+
+const FIELD_MASK = 'id,displayName,formattedAddress,nationalPhoneNumber,websiteUri,regularOpeningHours.weekdayDescriptions,rating,userRatingCount,priceLevel,types,googleMapsUri,location';
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsPlaceDetails',
+        description: 'Get contact, hours, rating, price, type, map link, and location details for a place ID.',
+        parameters: z.object({ placeId: z.string().min(1).describe('Google place ID (from mapsGeocode or the search tools)') }),
+        execute: async ({ placeId }) => {
+            const place = await placesRequest(`https://places.googleapis.com/v1/places/${encodeURIComponent(placeId)}`, { fieldMask: FIELD_MASK });
+            return JSON.stringify({ placeId: place.id || placeId, name: place.displayName?.text || null, address: place.formattedAddress || null, phone: place.nationalPhoneNumber || null, website: place.websiteUri || null, hours: place.regularOpeningHours?.weekdayDescriptions || [], rating: place.rating ?? null, userRatingCount: place.userRatingCount ?? null, priceLevel: place.priceLevel || null, types: place.types || [], googleMapsUri: place.googleMapsUri || null, location: place.location || null });
+        },
+    });
+}

package/dist/tools/maps/reverseGeocode.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { getMapsApiKey, mapsFetch } from './mapsClient.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsReverseGeocode',
+        description: 'Convert coordinates to the nearest formatted street address.',
+        parameters: z.object({
+            latitude: z.number().min(-90).max(90).describe('Latitude in degrees'),
+            longitude: z.number().min(-180).max(180).describe('Longitude in degrees'),
+        }),
+        execute: async ({ latitude, longitude }) => {
+            const params = new URLSearchParams({ latlng: `${latitude},${longitude}`, key: getMapsApiKey() });
+            const data = await mapsFetch(`https://maps.googleapis.com/maps/api/geocode/json?${params}`);
+            const result = data.results?.[0];
+            return JSON.stringify(result ? { formattedAddress: result.formatted_address || null, placeId: result.place_id || null, location: result.geometry?.location || { lat: latitude, lng: longitude } } : null);
+        },
+    });
+}

package/dist/tools/maps/searchNearby.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { dedupePlaces, formatPlace, placesRequest, SEARCH_FIELD_MASK, withinRadius } from './mapsClient.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsSearchNearby',
+        description: 'Find places near coordinates, optionally filtering by place types or a keyword.',
+        parameters: z.object({
+            latitude: z.number().min(-90).max(90).describe('Center latitude in degrees'),
+            longitude: z.number().min(-180).max(180).describe('Center longitude in degrees'),
+            radiusMeters: z.number().positive().max(50000).describe('Search radius in meters (max 50000)'),
+            includedTypes: z.array(z.string()).max(50).optional().describe('Place types to include, e.g. ["restaurant", "gym"]'),
+            keyword: z.string().min(1).optional().describe('Free-text query ranked server-side by Text Search, biased to the radius'),
+            maxResults: z.number().int().min(1).max(20).optional().default(10).describe('Maximum places to return (default 10, max 20)'),
+        }),
+        execute: async (args) => {
+            const center = { latitude: args.latitude, longitude: args.longitude };
+            let places;
+            if (args.keyword) {
+                // Nearby Search (New) has no keyword field, and filtering an unfiltered
+                // nearby page locally drops semantically-relevant hits (e.g. a Starbucks
+                // that lacks the literal word "coffee"). Send the keyword to Text Search,
+                // which ranks relevance server-side, bias it to the circle, then enforce
+                // the radius locally so the result still honors radiusMeters.
+                //
+                // Text Search's includedType is a ranking bias, not a filter, unless
+                // strictTypeFiltering is set (Google docs:
+                // https://developers.google.com/maps/documentation/places/web-service/text-search#includedtype).
+                // This tool promises type filtering, and Text Search only accepts a single
+                // includedType per request, so for multiple requested types we run one
+                // strict Text Search per type and merge, instead of asking for one type and
+                // locally filtering an unfiltered (and therefore incomplete, capped-at-20)
+                // page of results by the rest.
+                const types = args.includedTypes?.length ? args.includedTypes : [undefined];
+                const resultSets = await Promise.all(types.map(async (type) => {
+                    const body = { textQuery: args.keyword, maxResultCount: 20, locationBias: { circle: { center, radius: args.radiusMeters } } };
+                    if (type) {
+                        body.includedType = type;
+                        body.strictTypeFiltering = true;
+                    }
+                    const data = await placesRequest('https://places.googleapis.com/v1/places:searchText', { method: 'POST', body, fieldMask: SEARCH_FIELD_MASK });
+                    return (data.places || []).map(formatPlace);
+                }));
+                places = withinRadius(resultSets.flat(), center, args.radiusMeters);
+            } else {
+                const body = { locationRestriction: { circle: { center, radius: args.radiusMeters } }, maxResultCount: args.maxResults };
+                if (args.includedTypes?.length) body.includedTypes = args.includedTypes;
+                const data = await placesRequest('https://places.googleapis.com/v1/places:searchNearby', { method: 'POST', body, fieldMask: SEARCH_FIELD_MASK });
+                places = (data.places || []).map(formatPlace);
+            }
+            return JSON.stringify(dedupePlaces(places, args.maxResults));
+        },
+    });
+}

package/dist/tools/maps/searchPlaces.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { dedupePlaces, formatPlace, placesRequest, SEARCH_FIELD_MASK } from './mapsClient.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'mapsSearchPlaces',
+        description: 'Search Google Places with free text and an optional circular location bias.',
+        parameters: z.object({
+            query: z.string().min(1).describe('Free-text place search, e.g. "vegan restaurants in Lafayette IN"'),
+            locationBias: z.object({
+                latitude: z.number().min(-90).max(90).describe('Bias center latitude'),
+                longitude: z.number().min(-180).max(180).describe('Bias center longitude'),
+                radiusMeters: z.number().positive().max(50000).describe('Bias radius in meters (max 50000)'),
+            }).optional().describe('Optional circular area to bias results toward'),
+            maxResults: z.number().int().min(1).max(20).optional().default(10).describe('Maximum places to return (default 10, max 20)'),
+        }),
+        execute: async (args) => {
+            const body = { textQuery: args.query, maxResultCount: args.maxResults };
+            if (args.locationBias) body.locationBias = { circle: { center: { latitude: args.locationBias.latitude, longitude: args.locationBias.longitude }, radius: args.locationBias.radiusMeters } };
+            const data = await placesRequest('https://places.googleapis.com/v1/places:searchText', { method: 'POST', body, fieldMask: SEARCH_FIELD_MASK });
+            return JSON.stringify(dedupePlaces((data.places || []).map(formatPlace), args.maxResults));
+        },
+    });
+}