@cyanheads/openstreetmap-mcp-server 0.2.0

package/dist/mcp-server/tools/definitions/openstreetmap-query-bbox.tool.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Overpass bounding box query tool — finds OSM features within a bbox.
+ * @module mcp-server/tools/definitions/openstreetmap-query-bbox.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getOverpassService } from '../../../services/overpass/overpass-service.js';
+import { resolveTagInput } from './openstreetmap-tag-input.js';
+const ATTRIBUTION = 'Data © OpenStreetMap contributors, ODbL 1.0';
+export const openstreetmapQueryBbox = tool('openstreetmap_query_bbox', {
+    title: 'Find OSM features within a bounding box',
+    description: 'Find OSM features within a rectangular geographic area (bounding box) via the Overpass API. ' +
+        'Useful for area surveys where you want everything in a region, not proximity searches. ' +
+        'Use amenity for common POI types (hospital, pharmacy, cafe, school, etc.) ' +
+        'or tag_key + tag_value for other OSM categories (leisure=park, shop=supermarket, natural=peak). ' +
+        'Exactly one of amenity or tag_key/tag_value must be provided. ' +
+        'For proximity searches centered on a point, use openstreetmap_query_nearby instead.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        south: z.number().min(-90).max(90).describe('Southern boundary latitude (minimum latitude).'),
+        west: z.number().min(-180).max(180).describe('Western boundary longitude (minimum longitude).'),
+        north: z.number().min(-90).max(90).describe('Northern boundary latitude (maximum latitude).'),
+        east: z.number().min(-180).max(180).describe('Eastern boundary longitude (maximum longitude).'),
+        amenity: z
+            .string()
+            .optional()
+            .describe('OSM amenity tag value shortcut (e.g., "cafe", "bench", "hospital"). Cannot be combined with tag_key/tag_value.'),
+        tag_key: z
+            .string()
+            .optional()
+            .describe('OSM tag key for non-amenity queries (e.g., "leisure", "shop", "natural"). Use with tag_value. Cannot be combined with amenity.'),
+        tag_value: z
+            .string()
+            .optional()
+            .describe('OSM tag value paired with tag_key (e.g., "park", "supermarket", "peak").'),
+        element_types: z
+            .array(z.enum(['node', 'way', 'relation']))
+            .default(['node', 'way'])
+            .describe('OSM element types to search. Ways cover most buildings and areas; nodes cover most standalone POIs. Add "relation" for complex structures.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(20)
+            .describe('Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated.'),
+        timeout_seconds: z
+            .number()
+            .int()
+            .min(5)
+            .max(60)
+            .default(25)
+            .describe('Overpass query timeout in seconds. Increase for large bounding boxes or dense areas.'),
+    }),
+    output: z.object({
+        elements: z
+            .array(z
+            .object({
+            osm_type: z.enum(['node', 'way', 'relation']).describe('OSM element type.'),
+            osm_id: z
+                .number()
+                .describe('OSM element ID. Use with osm_type for openstreetmap_lookup.'),
+            lat: z
+                .number()
+                .optional()
+                .describe('Latitude (present for nodes and ways/relations with computed center).'),
+            lon: z
+                .number()
+                .optional()
+                .describe('Longitude (present for nodes and ways/relations with computed center).'),
+            name: z.string().optional().describe('Feature name from OSM tags.'),
+            tags: z
+                .record(z.string(), z.string())
+                .describe('All OSM tags for this feature. Values are always strings.'),
+        })
+            .describe('A single matching OSM feature.'))
+            .describe('Matching OSM features within the bounding box, up to the limit.'),
+        total_found: z
+            .number()
+            .describe('Total features returned by Overpass before limit truncation.'),
+        truncated: z
+            .boolean()
+            .describe('True if results were cut at the limit. Reduce bbox area or add more specific tags to narrow the result set.'),
+        data_timestamp: z.string().describe('OSM data freshness timestamp from the Overpass response.'),
+        attribution: z
+            .string()
+            .describe('Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0.'),
+    }),
+    errors: [
+        {
+            reason: 'invalid_tag',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Both amenity and tag_key/tag_value are provided, or neither is provided.',
+            recovery: 'Provide either amenity (e.g., "hospital") or tag_key + tag_value (e.g., tag_key="leisure", tag_value="park"), but not both and not neither.',
+        },
+        {
+            reason: 'query_timeout',
+            code: JsonRpcErrorCode.Timeout,
+            when: 'The Overpass query exceeded the timeout.',
+            retryable: true,
+            recovery: 'Reduce the bounding box area, add more specific tag filters, or increase timeout_seconds and retry.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Overpass returned HTTP 429 — all 4 concurrent query slots are occupied.',
+            retryable: true,
+            recovery: 'Wait a few seconds and retry. Reduce concurrent calls or switch to a private Overpass instance via OSM_OVERPASS_BASE_URL.',
+        },
+    ],
+    async handler(input, ctx) {
+        const resolved = resolveTagInput(input);
+        if ('error' in resolved) {
+            throw ctx.fail('invalid_tag', resolved.error === 'both'
+                ? 'Cannot combine amenity with tag_key/tag_value.'
+                : 'Provide either amenity or tag_key + tag_value.', { ...ctx.recoveryFor('invalid_tag') });
+        }
+        const { tagKey, tagValue } = resolved;
+        const service = getOverpassService();
+        const ql = service.buildBboxQuery({
+            south: input.south,
+            west: input.west,
+            north: input.north,
+            east: input.east,
+            tagKey,
+            tagValue,
+            elementTypes: input.element_types,
+            timeoutSeconds: input.timeout_seconds,
+        });
+        const response = await service.query(ql, ctx);
+        const allPois = service.normalizeElements(response.elements);
+        const limited = allPois.slice(0, input.limit);
+        const dataTimestamp = response.osm3s?.timestamp_osm_base ?? new Date().toISOString();
+        ctx.log.info('Overpass bbox results', {
+            total: allPois.length,
+            returned: limited.length,
+        });
+        return {
+            elements: limited,
+            total_found: allPois.length,
+            truncated: allPois.length > input.limit,
+            data_timestamp: dataTimestamp,
+            attribution: ATTRIBUTION,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.total_found} feature${result.total_found === 1 ? '' : 's'} found**${result.truncated ? ` (showing first ${result.elements.length} — results truncated)` : ''}`,
+            `**Data as of:** ${result.data_timestamp}`,
+            '',
+        ];
+        for (const el of result.elements) {
+            const nameStr = el.name ?? 'Unnamed';
+            lines.push(`## ${nameStr}`);
+            lines.push(`**OSM:** ${el.osm_type.charAt(0).toUpperCase()}${el.osm_id}`);
+            if (el.lat !== undefined && el.lon !== undefined) {
+                lines.push(`**Coordinates:** ${el.lat}, ${el.lon}`);
+            }
+            const tagEntries = Object.entries(el.tags)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (tagEntries)
+                lines.push(`**Tags:** ${tagEntries}`);
+            lines.push('');
+        }
+        lines.push(`*${result.attribution}*`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=openstreetmap-query-bbox.tool.js.map

package/dist/mcp-server/tools/definitions/openstreetmap-query-bbox.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-query-bbox.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-query-bbox.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Overpass nearby query tool — finds OSM features within a radius.
+ * @module mcp-server/tools/definitions/openstreetmap-query-nearby.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const openstreetmapQueryNearby: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    radius_meters: z.ZodDefault<z.ZodNumber>;
+    amenity: z.ZodOptional<z.ZodString>;
+    tag_key: z.ZodOptional<z.ZodString>;
+    tag_value: z.ZodOptional<z.ZodString>;
+    element_types: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        node: "node";
+        way: "way";
+        relation: "relation";
+    }>>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    timeout_seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    elements: z.ZodArray<z.ZodObject<{
+        osm_type: z.ZodEnum<{
+            node: "node";
+            way: "way";
+            relation: "relation";
+        }>;
+        osm_id: z.ZodNumber;
+        lat: z.ZodOptional<z.ZodNumber>;
+        lon: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodOptional<z.ZodString>;
+        tags: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    total_found: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    data_timestamp: z.ZodString;
+    attribution: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_tag";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Both amenity and tag_key/tag_value are provided, or neither is provided.";
+    readonly recovery: "Provide either amenity (e.g., \"hospital\") or tag_key + tag_value (e.g., tag_key=\"leisure\", tag_value=\"park\"), but not both and not neither.";
+}, {
+    readonly reason: "query_timeout";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "The Overpass query exceeded the timeout.";
+    readonly retryable: true;
+    readonly recovery: "Reduce radius_meters, add more specific tag filters, or increase timeout_seconds and retry.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Overpass returned HTTP 429 — all 4 concurrent query slots are occupied.";
+    readonly retryable: true;
+    readonly recovery: "Wait a few seconds and retry. Reduce concurrent calls or switch to a private Overpass instance via OSM_OVERPASS_BASE_URL.";
+}]>;
+//# sourceMappingURL=openstreetmap-query-nearby.tool.d.ts.map

package/dist/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-query-nearby.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAMjE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoMnC,CAAC"}

package/dist/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.js

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Overpass nearby query tool — finds OSM features within a radius.
+ * @module mcp-server/tools/definitions/openstreetmap-query-nearby.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getOverpassService } from '../../../services/overpass/overpass-service.js';
+import { resolveTagInput } from './openstreetmap-tag-input.js';
+const ATTRIBUTION = 'Data © OpenStreetMap contributors, ODbL 1.0';
+export const openstreetmapQueryNearby = tool('openstreetmap_query_nearby', {
+    title: 'Find OSM features near a point',
+    description: 'Find OSM features within a radius around a geographic point via the Overpass API. ' +
+        'The primary tool for "what\'s near X?" spatial queries. ' +
+        'Use amenity for common POI types (hospital, pharmacy, restaurant, cafe, school, atm, etc.) ' +
+        'or tag_key + tag_value for other OSM categories (leisure=park, shop=supermarket, natural=peak). ' +
+        'Exactly one of amenity or tag_key/tag_value must be provided. ' +
+        'Results include all element types specified (nodes cover standalone POIs, ways cover buildings and areas). ' +
+        'Note: results are not sorted by distance — the Overpass API returns them in OSM element ID order.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        lat: z.number().min(-90).max(90).describe('Center latitude in WGS84 decimal degrees.'),
+        lon: z.number().min(-180).max(180).describe('Center longitude in WGS84 decimal degrees.'),
+        radius_meters: z
+            .number()
+            .positive()
+            .max(50000)
+            .default(1000)
+            .describe('Search radius in meters. Max 50,000m (50km). Keep under 5,000m for dense urban POI queries to avoid slow responses.'),
+        amenity: z
+            .string()
+            .optional()
+            .describe('OSM amenity tag value (e.g., "hospital", "pharmacy", "restaurant", "school", "atm"). Shortcut for tag_key="amenity". Cannot be combined with tag_key/tag_value.'),
+        tag_key: z
+            .string()
+            .optional()
+            .describe('OSM tag key for non-amenity queries (e.g., "leisure", "shop", "highway", "natural"). Use with tag_value. Cannot be combined with amenity.'),
+        tag_value: z
+            .string()
+            .optional()
+            .describe('OSM tag value paired with tag_key (e.g., "park", "supermarket", "primary", "peak").'),
+        element_types: z
+            .array(z.enum(['node', 'way', 'relation']))
+            .default(['node', 'way'])
+            .describe('OSM element types to search. Ways cover most buildings and areas; nodes cover most standalone POIs. Add "relation" for complex structures like large campuses.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .default(20)
+            .describe('Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated.'),
+        timeout_seconds: z
+            .number()
+            .int()
+            .min(5)
+            .max(60)
+            .default(25)
+            .describe('Overpass query timeout in seconds. Increase for large radius or dense areas.'),
+    }),
+    output: z.object({
+        elements: z
+            .array(z
+            .object({
+            osm_type: z.enum(['node', 'way', 'relation']).describe('OSM element type.'),
+            osm_id: z
+                .number()
+                .describe('OSM element ID. Use with osm_type for openstreetmap_lookup.'),
+            lat: z
+                .number()
+                .optional()
+                .describe('Latitude (present for nodes and ways/relations with computed center).'),
+            lon: z
+                .number()
+                .optional()
+                .describe('Longitude (present for nodes and ways/relations with computed center).'),
+            name: z.string().optional().describe('Feature name from OSM tags.'),
+            tags: z
+                .record(z.string(), z.string())
+                .describe('All OSM tags for this feature. Values are always strings.'),
+        })
+            .describe('A single matching OSM feature.'))
+            .describe('Matching OSM features, up to the limit.'),
+        total_found: z
+            .number()
+            .describe('Total features returned by Overpass before limit truncation.'),
+        truncated: z
+            .boolean()
+            .describe('True if results were cut at the limit. Reduce radius or add more specific tags to narrow the result set.'),
+        data_timestamp: z.string().describe('OSM data freshness timestamp from the Overpass response.'),
+        attribution: z
+            .string()
+            .describe('Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0.'),
+    }),
+    errors: [
+        {
+            reason: 'invalid_tag',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Both amenity and tag_key/tag_value are provided, or neither is provided.',
+            recovery: 'Provide either amenity (e.g., "hospital") or tag_key + tag_value (e.g., tag_key="leisure", tag_value="park"), but not both and not neither.',
+        },
+        {
+            reason: 'query_timeout',
+            code: JsonRpcErrorCode.Timeout,
+            when: 'The Overpass query exceeded the timeout.',
+            retryable: true,
+            recovery: 'Reduce radius_meters, add more specific tag filters, or increase timeout_seconds and retry.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Overpass returned HTTP 429 — all 4 concurrent query slots are occupied.',
+            retryable: true,
+            recovery: 'Wait a few seconds and retry. Reduce concurrent calls or switch to a private Overpass instance via OSM_OVERPASS_BASE_URL.',
+        },
+    ],
+    async handler(input, ctx) {
+        const resolved = resolveTagInput(input);
+        if ('error' in resolved) {
+            throw ctx.fail('invalid_tag', resolved.error === 'both'
+                ? 'Cannot combine amenity with tag_key/tag_value.'
+                : 'Provide either amenity or tag_key + tag_value.', { ...ctx.recoveryFor('invalid_tag') });
+        }
+        const { tagKey, tagValue } = resolved;
+        const service = getOverpassService();
+        const ql = service.buildAroundQuery({
+            lat: input.lat,
+            lon: input.lon,
+            radiusMeters: input.radius_meters,
+            tagKey,
+            tagValue,
+            elementTypes: input.element_types,
+            timeoutSeconds: input.timeout_seconds,
+        });
+        const response = await service.query(ql, ctx);
+        const allPois = service.normalizeElements(response.elements);
+        const limited = allPois.slice(0, input.limit);
+        const dataTimestamp = response.osm3s?.timestamp_osm_base ?? new Date().toISOString();
+        ctx.log.info('Overpass nearby results', {
+            total: allPois.length,
+            returned: limited.length,
+        });
+        return {
+            elements: limited,
+            total_found: allPois.length,
+            truncated: allPois.length > input.limit,
+            data_timestamp: dataTimestamp,
+            attribution: ATTRIBUTION,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.total_found} feature${result.total_found === 1 ? '' : 's'} found**${result.truncated ? ` (showing first ${result.elements.length} — results truncated)` : ''}`,
+            `**Data as of:** ${result.data_timestamp}`,
+            '',
+        ];
+        for (const el of result.elements) {
+            const nameStr = el.name ?? 'Unnamed';
+            lines.push(`## ${nameStr}`);
+            lines.push(`**OSM:** ${el.osm_type.charAt(0).toUpperCase()}${el.osm_id}`);
+            if (el.lat !== undefined && el.lon !== undefined) {
+                lines.push(`**Coordinates:** ${el.lat}, ${el.lon}`);
+            }
+            const tagEntries = Object.entries(el.tags)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (tagEntries)
+                lines.push(`**Tags:** ${tagEntries}`);
+            lines.push('');
+        }
+        lines.push(`*${result.attribution}*`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=openstreetmap-query-nearby.tool.js.map

package/dist/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-query-nearby.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-query-nearby.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,MAAM,WAAW,GAAG,6CAA6C,CAAC;AAElE,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC,4BAA4B,EAAE;IACzE,KAAK,EAAE,gCAAgC;IACvC,WAAW,EACT,oFAAoF;QACpF,0DAA0D;QAC1D,6FAA6F;QAC7F,kGAAkG;QAClG,gEAAgE;QAChE,6GAA6G;QAC7G,mGAAmG;IACrG,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAE9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,2CAA2C,CAAC;QACtF,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACzF,aAAa,EAAE,CAAC;aACb,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,GAAG,CAAC,KAAK,CAAC;aACV,OAAO,CAAC,IAAI,CAAC;aACb,QAAQ,CACP,qHAAqH,CACtH;QACH,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,iKAAiK,CAClK;QACH,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,2IAA2I,CAC5I;QACH,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,qFAAqF,CACtF;QACH,aAAa,EAAE,CAAC;aACb,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;aAC1C,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;aACxB,QAAQ,CACP,gKAAgK,CACjK;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CACP,kHAAkH,CACnH;QACH,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,8EAA8E,CAAC;KAC5F,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC;aACR,KAAK,CACJ,CAAC;aACE,MAAM,CAAC;YACN,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;YAC3E,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CAAC,6DAA6D,CAAC;YAC1E,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,uEAAuE,CAAC;YACpF,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,wEAAwE,CAAC;YACrF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;YACnE,IAAI,EAAE,CAAC;iBACJ,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;iBAC9B,QAAQ,CAAC,2DAA2D,CAAC;SACzE,CAAC;aACD,QAAQ,CAAC,gCAAgC,CAAC,CAC9C;aACA,QAAQ,CAAC,yCAAyC,CAAC;QACtD,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CAAC,8DAA8D,CAAC;QAC3E,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,CACP,0GAA0G,CAC3G;QACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;QAC/F,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,CAAC,yEAAyE,CAAC;KACvF,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,aAAa;YACrB,IAAI,EAAE,gBAAgB,CAAC,eAAe;YACtC,IAAI,EAAE,0EAA0E;YAChF,QAAQ,EACN,6IAA6I;SAChJ;QACD;YACE,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,gBAAgB,CAAC,OAAO;YAC9B,IAAI,EAAE,0CAA0C;YAChD,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,6FAA6F;SAChG;QACD;YACE,MAAM,EAAE,cAAc;YACtB,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,yEAAyE;YAC/E,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,2HAA2H;SAC9H;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YACxB,MAAM,GAAG,CAAC,IAAI,CACZ,aAAa,EACb,QAAQ,CAAC,KAAK,KAAK,MAAM;gBACvB,CAAC,CAAC,gDAAgD;gBAClD,CAAC,CAAC,gDAAgD,EACpD,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,CACtC,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC;QAEtC,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAClC,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,YAAY,EAAE,KAAK,CAAC,aAAa;YACjC,MAAM;YACN,QAAQ;YACR,YAAY,EAAE,KAAK,CAAC,aAAa;YACjC,cAAc,EAAE,KAAK,CAAC,eAAe;SACtC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC7D,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAE9C,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,EAAE,kBAAkB,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAErF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,EAAE;YACtC,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,QAAQ,EAAE,OAAO,CAAC,MAAM;SACzB,CAAC,CAAC;QAEH,OAAO;YACL,QAAQ,EAAE,OAAO;YACjB,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK;YACvC,cAAc,EAAE,aAAa;YAC7B,WAAW,EAAE,WAAW;SACzB,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa;YACtB,KAAK,MAAM,CAAC,WAAW,WAAW,MAAM,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,WAAW,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,MAAM,CAAC,QAAQ,CAAC,MAAM,uBAAuB,CAAC,CAAC,CAAC,EAAE,EAAE;YAC1K,mBAAmB,MAAM,CAAC,cAAc,EAAE;YAC1C,EAAE;SACH,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,OAAO,GAAG,EAAE,CAAC,IAAI,IAAI,SAAS,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1E,IAAI,EAAE,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBACjD,KAAK,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;YACtD,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC;iBACvC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;iBAC5B,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,IAAI,UAAU;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,UAAU,EAAE,CAAC,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC;QACtC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/openstreetmap-query-raw.tool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Raw Overpass QL query tool — escape hatch for advanced spatial queries.
+ * @module mcp-server/tools/definitions/openstreetmap-query-raw.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const openstreetmapQueryRaw: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    timeout_seconds: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    elements: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    total_elements: z.ZodNumber;
+    data_timestamp: z.ZodOptional<z.ZodString>;
+    attribution: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "query_error";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Overpass returned a 400 error — malformed query syntax.";
+    readonly recovery: "Check Overpass QL syntax. Validate the query at overpass-turbo.eu before using this tool.";
+}, {
+    readonly reason: "query_timeout";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "The query exceeded its timeout (Overpass runtime error in response body).";
+    readonly retryable: true;
+    readonly recovery: "Add [timeout:N] to the query string with a higher value, or simplify the query (smaller bbox, fewer element types, more specific tags).";
+}, {
+    readonly reason: "result_too_large";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Overpass runtime error: query ran out of memory — result set exceeds the server memory limit.";
+    readonly recovery: "Narrow the query scope: reduce the bbox or around radius, add more tag filters, limit element types, or add [maxsize:N] to the query.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Overpass returned HTTP 429 — all 4 concurrent query slots are occupied.";
+    readonly retryable: true;
+    readonly recovery: "Wait a few seconds and retry. Switch to a private Overpass instance via OSM_OVERPASS_BASE_URL for higher concurrency.";
+}]>;
+//# sourceMappingURL=openstreetmap-query-raw.tool.d.ts.map

package/dist/mcp-server/tools/definitions/openstreetmap-query-raw.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-query-raw.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-query-raw.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAKjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8IhC,CAAC"}

package/dist/mcp-server/tools/definitions/openstreetmap-query-raw.tool.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Raw Overpass QL query tool — escape hatch for advanced spatial queries.
+ * @module mcp-server/tools/definitions/openstreetmap-query-raw.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getOverpassService } from '../../../services/overpass/overpass-service.js';
+const ATTRIBUTION = 'Data © OpenStreetMap contributors, ODbL 1.0';
+export const openstreetmapQueryRaw = tool('openstreetmap_query_raw', {
+    title: 'Execute a raw Overpass QL query',
+    description: 'Execute a raw Overpass QL query for advanced spatial queries that the convenience tools do not cover. ' +
+        'Use for multi-type queries, union queries, relation membership, historical queries, or any operation ' +
+        'requiring full Overpass QL expressiveness. ' +
+        'The query must include [out:json]. ' +
+        'Example: "[out:json][timeout:15];node[\\"natural\\"=\\"peak\\"](47.5,-122.5,47.7,-122.2);out body;" ' +
+        'Validate complex queries at overpass-turbo.eu before use. ' +
+        'For simple "what\'s near X?" or "what\'s in this area?" queries, use openstreetmap_query_nearby or openstreetmap_query_bbox instead.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        query: z
+            .string()
+            .describe('Overpass QL query string. Must include [out:json]. The server sets the endpoint and User-Agent; do not include those. Example: "[out:json][timeout:15];node[\\"natural\\"=\\"peak\\"](47.5,-122.5,47.7,-122.2);out body;"'),
+        timeout_seconds: z
+            .number()
+            .int()
+            .min(5)
+            .max(180)
+            .default(30)
+            .describe('Query timeout in seconds. The [timeout:N] directive in the query string takes precedence if present. Max 180s.'),
+    }),
+    output: z.object({
+        elements: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Raw Overpass API response elements. Structure varies by query type — nodes have lat/lon, ways have nodes[], relations have members[].'),
+        total_elements: z.number().describe('Number of elements returned.'),
+        data_timestamp: z
+            .string()
+            .optional()
+            .describe('OSM data freshness timestamp from the Overpass response. Absent if not included in the response.'),
+        attribution: z
+            .string()
+            .describe('Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0.'),
+    }),
+    errors: [
+        {
+            reason: 'query_error',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'Overpass returned a 400 error — malformed query syntax.',
+            recovery: 'Check Overpass QL syntax. Validate the query at overpass-turbo.eu before using this tool.',
+        },
+        {
+            reason: 'query_timeout',
+            code: JsonRpcErrorCode.Timeout,
+            when: 'The query exceeded its timeout (Overpass runtime error in response body).',
+            retryable: true,
+            recovery: 'Add [timeout:N] to the query string with a higher value, or simplify the query (smaller bbox, fewer element types, more specific tags).',
+        },
+        {
+            reason: 'result_too_large',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Overpass runtime error: query ran out of memory — result set exceeds the server memory limit.',
+            recovery: 'Narrow the query scope: reduce the bbox or around radius, add more tag filters, limit element types, or add [maxsize:N] to the query.',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Overpass returned HTTP 429 — all 4 concurrent query slots are occupied.',
+            retryable: true,
+            recovery: 'Wait a few seconds and retry. Switch to a private Overpass instance via OSM_OVERPASS_BASE_URL for higher concurrency.',
+        },
+    ],
+    async handler(input, ctx) {
+        let ql = input.query.trim();
+        // Preflight: require [out:json] before calling the service.
+        // Without it Overpass returns XML, JSON.parse throws, and the error surfaces as InternalError.
+        if (!ql.includes('[out:json]')) {
+            throw ctx.fail('query_error', 'Query is missing [out:json]. Add [out:json] at the start of the settings block (e.g. "[out:json][timeout:30];...").');
+        }
+        // Inject timeout if the query doesn't already include one
+        if (!ql.includes('[timeout:')) {
+            ql = ql.replace('[out:json]', `[out:json][timeout:${input.timeout_seconds}]`);
+        }
+        ctx.log.info('Overpass raw query', { queryLength: ql.length });
+        const service = getOverpassService();
+        const response = await service.query(ql, ctx);
+        const dataTimestamp = response.osm3s?.timestamp_osm_base;
+        ctx.log.info('Overpass raw results', { count: response.elements.length });
+        return {
+            elements: response.elements,
+            total_elements: response.elements.length,
+            ...(dataTimestamp ? { data_timestamp: dataTimestamp } : {}),
+            attribution: ATTRIBUTION,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.total_elements} element${result.total_elements === 1 ? '' : 's'} returned**`,
+        ];
+        if (result.data_timestamp) {
+            lines.push(`**Data as of:** ${result.data_timestamp}`);
+        }
+        lines.push('');
+        for (const el of result.elements.slice(0, 50)) {
+            const type = String(el.type ?? 'unknown');
+            const id = String(el.id ?? '?');
+            const tags = el.tags;
+            const name = tags?.name;
+            lines.push(`**${type}** ${id}${name ? ` — ${name}` : ''}`);
+            if (tags && Object.keys(tags).length > 0) {
+                const tagStr = Object.entries(tags)
+                    .map(([k, v]) => `${k}=${v}`)
+                    .join(', ');
+                lines.push(`  Tags: ${tagStr}`);
+            }
+        }
+        if (result.elements.length > 50) {
+            lines.push(`... and ${result.elements.length - 50} more elements`);
+        }
+        lines.push('');
+        lines.push(`*${result.attribution}*`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=openstreetmap-query-raw.tool.js.map

package/dist/mcp-server/tools/definitions/openstreetmap-query-raw.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-query-raw.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-query-raw.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/openstreetmap-reverse.tool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Reverse geocoding tool — converts coordinates to nearest address or place.
+ * @module mcp-server/tools/definitions/openstreetmap-reverse.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const openstreetmapReverse: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    lat: z.ZodNumber;
+    lon: z.ZodNumber;
+    zoom: z.ZodDefault<z.ZodNumber>;
+    layer: z.ZodOptional<z.ZodString>;
+    extratags: z.ZodDefault<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    result: z.ZodObject<{
+        place_id: z.ZodNumber;
+        osm_type: z.ZodOptional<z.ZodEnum<{
+            node: "node";
+            way: "way";
+            relation: "relation";
+        }>>;
+        osm_id: z.ZodOptional<z.ZodNumber>;
+        lat: z.ZodString;
+        lon: z.ZodString;
+        display_name: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        boundingbox: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString, z.ZodString], null>>;
+        extratags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>;
+    attribution: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_coverage";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Nominatim returns an error indicating no OSM data at the given coordinates (e.g., open ocean or unmapped territory).";
+    readonly recovery: "Verify the coordinates are correct. Try a lower zoom value to match at a coarser level (e.g., zoom=10 for city-level).";
+}]>;
+//# sourceMappingURL=openstreetmap-reverse.tool.d.ts.map