@cyanheads/geonames-mcp-server 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/AGENTS.md +438 -0
  2. package/CLAUDE.md +438 -0
  3. package/Dockerfile +177 -0
  4. package/LICENSE +201 -0
  5. package/README.md +316 -2
  6. package/changelog/0.1.x/0.1.0.md +9 -0
  7. package/changelog/0.1.x/0.1.1.md +22 -0
  8. package/changelog/template.md +151 -0
  9. package/dist/config/server-config.d.ts +13 -0
  10. package/dist/config/server-config.d.ts.map +1 -0
  11. package/dist/config/server-config.js +21 -0
  12. package/dist/config/server-config.js.map +1 -0
  13. package/dist/index.d.ts +8 -0
  14. package/dist/index.d.ts.map +1 -0
  15. package/dist/index.js +30 -0
  16. package/dist/index.js.map +1 -0
  17. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts +90 -0
  18. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -0
  19. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +262 -0
  20. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -0
  21. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +88 -0
  22. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -0
  23. package/dist/mcp-server/tools/definitions/get-children.tool.js +248 -0
  24. package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -0
  25. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +90 -0
  26. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -0
  27. package/dist/mcp-server/tools/definitions/get-countries.tool.js +217 -0
  28. package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -0
  29. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.d.ts +64 -0
  30. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.d.ts.map +1 -0
  31. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js +168 -0
  32. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js.map +1 -0
  33. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +108 -0
  34. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -0
  35. package/dist/mcp-server/tools/definitions/get-place.tool.js +300 -0
  36. package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -0
  37. package/dist/mcp-server/tools/definitions/index.d.ts +735 -0
  38. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
  39. package/dist/mcp-server/tools/definitions/index.js +23 -0
  40. package/dist/mcp-server/tools/definitions/index.js.map +1 -0
  41. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +103 -0
  42. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -0
  43. package/dist/mcp-server/tools/definitions/list-reference.tool.js +233 -0
  44. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -0
  45. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts +134 -0
  46. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -0
  47. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +381 -0
  48. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -0
  49. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +133 -0
  50. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -0
  51. package/dist/mcp-server/tools/definitions/search-places.tool.js +348 -0
  52. package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -0
  53. package/dist/mcp-server/tools/shared-inputs.d.ts +97 -0
  54. package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -0
  55. package/dist/mcp-server/tools/shared-inputs.js +156 -0
  56. package/dist/mcp-server/tools/shared-inputs.js.map +1 -0
  57. package/dist/services/geonames/feature-codes.d.ts +27 -0
  58. package/dist/services/geonames/feature-codes.d.ts.map +1 -0
  59. package/dist/services/geonames/feature-codes.js +723 -0
  60. package/dist/services/geonames/feature-codes.js.map +1 -0
  61. package/dist/services/geonames/geonames-service.d.ts +98 -0
  62. package/dist/services/geonames/geonames-service.d.ts.map +1 -0
  63. package/dist/services/geonames/geonames-service.js +555 -0
  64. package/dist/services/geonames/geonames-service.js.map +1 -0
  65. package/dist/services/geonames/response-cache.d.ts +24 -0
  66. package/dist/services/geonames/response-cache.d.ts.map +1 -0
  67. package/dist/services/geonames/response-cache.js +44 -0
  68. package/dist/services/geonames/response-cache.js.map +1 -0
  69. package/dist/services/geonames/response-parsers.d.ts +34 -0
  70. package/dist/services/geonames/response-parsers.d.ts.map +1 -0
  71. package/dist/services/geonames/response-parsers.js +350 -0
  72. package/dist/services/geonames/response-parsers.js.map +1 -0
  73. package/dist/services/geonames/types.d.ts +218 -0
  74. package/dist/services/geonames/types.d.ts.map +1 -0
  75. package/dist/services/geonames/types.js +10 -0
  76. package/dist/services/geonames/types.js.map +1 -0
  77. package/dist/services/geonames/upstream-errors.d.ts +54 -0
  78. package/dist/services/geonames/upstream-errors.d.ts.map +1 -0
  79. package/dist/services/geonames/upstream-errors.js +187 -0
  80. package/dist/services/geonames/upstream-errors.js.map +1 -0
  81. package/dist/utils/inline-text.d.ts +25 -0
  82. package/dist/utils/inline-text.d.ts.map +1 -0
  83. package/dist/utils/inline-text.js +60 -0
  84. package/dist/utils/inline-text.js.map +1 -0
  85. package/package.json +108 -4
  86. package/server.json +114 -0
@@ -0,0 +1,381 @@
1
+ /**
2
+ * @fileoverview geonames_reverse_geocode — a coordinate's country and admin subdivisions
3
+ * (`countrySubdivisionJSON`), the ocean when no country contains it (`oceanJSON`), the
4
+ * nearest populated places or features (`findNearbyPlaceNameJSON` / `findNearbyJSON`),
5
+ * and optionally its timezone (`timezoneJSON`). The legs run in parallel inside a 30 s
6
+ * budget and fail together.
7
+ * @module mcp-server/tools/definitions/reverse-geocode.tool
8
+ */
9
+ import { tool, z } from '@cyanheads/mcp-ts-core';
10
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
11
+ import { blankAsUnset, citiesInput, featureClassesInput, featureCodesInput, geonamesUsernameInput, latInput, lngInput, USERNAME_ALIASES, } from '../shared-inputs.js';
12
+ import { getFeatureCode } from '../../../services/geonames/feature-codes.js';
13
+ import { getGeoNamesService } from '../../../services/geonames/geonames-service.js';
14
+ import { inlineText, tableCell } from '../../../utils/inline-text.js';
15
+ /** Wall-clock budget for the whole call, inside a 60 s client timeout. */
16
+ const TOOL_BUDGET_MS = 30_000;
17
+ /** Ceiling on the ocean follow-up's ladder; it also gets no more than what the budget has left. */
18
+ const OCEAN_BUDGET_MS = 10_000;
19
+ /** The most nearby rows one call returns. */
20
+ const MAX_NEARBY = 50;
21
+ /** GeoNames' free-tier ceiling on the nearby radius (status 24 beyond). */
22
+ const MAX_RADIUS_KM = 300;
23
+ const NEARBY_KINDS = ['populated_places', 'features', 'none'];
24
+ const NEARBY_TITLES = {
25
+ populated_places: 'Nearest populated places',
26
+ features: 'Nearest features',
27
+ none: 'Nearby lookup skipped (nearbyLimit 0)',
28
+ };
29
+ /** A nearby row as this tool returns it: no country label or id, no first-level code. */
30
+ const toNearby = ({ adminCode1: _adminCode, countryGeonameId: _countryId, countryName: _countryName, featureClassName: _className, iso3166_2: _iso, ...row }) => row;
31
+ /** The timezone block without its country name (the containment already names the country). */
32
+ const toTimezone = ({ countryName: _countryName, ...timezone }) => timezone;
33
+ const orNotAvailable = (value) => value === undefined ? 'Not available' : tableCell(String(value));
34
+ export const reverseGeocodeTool = tool('geonames_reverse_geocode', {
35
+ title: 'Reverse geocode with GeoNames',
36
+ description: "Resolve a latitude/longitude to the country and admin subdivisions that contain it (down to ADM5, each with its geonameId and ISO 3166-2 code where one exists), or the ocean or sea when the point is offshore, plus the nearest populated places with distances; these include neighborhood sections (PPLX) and historical places (PPLH), marked by featureCode. Set featureClasses or featureCodes to list the nearest features of that type instead (peaks, lakes, airports), cities to keep only places above a population tier, and includeTimezone for the IANA timezone with local time, sunrise, and sunset (offshore points get only GeoNames' UTC-offset estimate). Costs 1 GeoNames credit for containment, plus 3 for nearest populated places or 4 for nearest features (nearbyLimit 0 skips them), 1 for the ocean when no country contains the point, and 1 for the timezone.",
37
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
38
+ input: z.object({
39
+ lat: latInput,
40
+ lng: lngInput,
41
+ nearbyLimit: blankAsUnset(z.number().int().min(0).max(MAX_NEARBY).default(5)).describe('How many nearest places or features to list, 0 to 50. Default 5. 0 skips the nearby lookup and its 3 or 4 credits.'),
42
+ radiusKm: blankAsUnset(z.number().positive().max(MAX_RADIUS_KM).default(20)).describe("Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20."),
43
+ cities: citiesInput.describe("Keep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes."),
44
+ featureClasses: featureClassesInput.describe('List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. A list or a comma-separated string; case-insensitive. Not combinable with cities.'),
45
+ featureCodes: featureCodesInput.describe('List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (T.MT) is dropped. geonames_list_reference topic feature_codes lists every code. Not combinable with cities.'),
46
+ includeTimezone: blankAsUnset(z.boolean().default(false)).describe('Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false.'),
47
+ geonamesUsername: geonamesUsernameInput,
48
+ }),
49
+ inputAliases: USERNAME_ALIASES,
50
+ output: z.object({
51
+ lat: z.number().describe('The latitude that was looked up.'),
52
+ lng: z.number().describe('The longitude that was looked up.'),
53
+ country: z
54
+ .object({
55
+ countryCode: z.string().describe('ISO 3166-1 alpha-2 country code.'),
56
+ countryName: z
57
+ .string()
58
+ .optional()
59
+ .describe('Country name. Absent when GeoNames sent none.'),
60
+ })
61
+ .optional()
62
+ .describe('The country containing the point; absent offshore and in unmapped areas.'),
63
+ adminLevels: z
64
+ .array(z
65
+ .object({
66
+ level: z.number().describe('Admin level: 1 for the first-order division, up to 5.'),
67
+ code: z.string().optional().describe('Admin code at this level.'),
68
+ name: z.string().optional().describe('Name of the division.'),
69
+ geonameId: z
70
+ .number()
71
+ .optional()
72
+ .describe('GeoNames feature id of the division: pass it to geonames_get_place.'),
73
+ isoCode: z
74
+ .string()
75
+ .optional()
76
+ .describe('ISO 3166-2 code of the division, subdivision part only (IDF, not FR-IDF), where one exists.'),
77
+ })
78
+ .describe('One admin division containing the point.'))
79
+ .describe('Admin divisions containing the point, first level first; empty offshore, and where GeoNames records no subdivision of the country.'),
80
+ ocean: z
81
+ .object({
82
+ name: z.string().describe('Name of the ocean or sea.'),
83
+ geonameId: z
84
+ .number()
85
+ .optional()
86
+ .describe('GeoNames feature id of the water body. Absent when GeoNames has none.'),
87
+ })
88
+ .optional()
89
+ .describe('The ocean or sea at the point; present only when no country contains it.'),
90
+ nearbyKind: z
91
+ .enum(NEARBY_KINDS)
92
+ .describe('What nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0).'),
93
+ nearby: z
94
+ .array(z
95
+ .object({
96
+ geonameId: z
97
+ .number()
98
+ .describe('GeoNames feature id: pass it to geonames_get_place or geonames_get_hierarchy.'),
99
+ name: z.string().describe('Name of the place or feature, as GeoNames displays it.'),
100
+ toponymName: z
101
+ .string()
102
+ .describe("GeoNames' main name for the feature, often the local-language form."),
103
+ featureClass: z
104
+ .string()
105
+ .optional()
106
+ .describe('One-letter feature class (P populated place, T terrain, H water, …).'),
107
+ featureCode: z
108
+ .string()
109
+ .optional()
110
+ .describe('Feature code, such as PPL (populated place), PPLX (section), PPLH (historical place), or MT (mountain).'),
111
+ featureName: z.string().optional().describe("GeoNames' name for the feature code."),
112
+ countryCode: z
113
+ .string()
114
+ .optional()
115
+ .describe('ISO 3166-1 alpha-2 code of the containing country.'),
116
+ adminName1: z
117
+ .string()
118
+ .optional()
119
+ .describe('Name of the first-order admin division containing it.'),
120
+ lat: z
121
+ .number()
122
+ .optional()
123
+ .describe('Latitude in decimal degrees. Absent when GeoNames sent none.'),
124
+ lng: z
125
+ .number()
126
+ .optional()
127
+ .describe('Longitude in decimal degrees. Absent when GeoNames sent none.'),
128
+ distanceInKm: z
129
+ .number()
130
+ .optional()
131
+ .describe('Distance from the point in kilometres. Absent when GeoNames sent no usable value.'),
132
+ population: z
133
+ .number()
134
+ .optional()
135
+ .describe('Population. Absent when GeoNames records none.'),
136
+ })
137
+ .describe('One nearby place or feature.'))
138
+ .describe('Nearest places or features, nearest first; empty when nearbyKind is none.'),
139
+ timezone: z
140
+ .object({
141
+ timezoneId: z
142
+ .string()
143
+ .optional()
144
+ .describe('IANA timezone id, such as Europe/Paris. Absent offshore.'),
145
+ countryCode: z
146
+ .string()
147
+ .optional()
148
+ .describe('ISO 3166-1 alpha-2 code of the timezone country. Absent offshore.'),
149
+ rawOffsetInHours: z.number().describe('Standard UTC offset in hours, without DST.'),
150
+ gmtOffsetInHours: z.number().describe('UTC offset in hours on 1 January.'),
151
+ dstOffsetInHours: z.number().describe('UTC offset in hours on 1 July.'),
152
+ localTime: z
153
+ .string()
154
+ .optional()
155
+ .describe('Current local time, YYYY-MM-DD HH:mm. Absent offshore.'),
156
+ sunrise: z
157
+ .string()
158
+ .optional()
159
+ .describe("Today's local sunrise, YYYY-MM-DD HH:mm. Absent offshore."),
160
+ sunset: z
161
+ .string()
162
+ .optional()
163
+ .describe("Today's local sunset, YYYY-MM-DD HH:mm. Absent offshore."),
164
+ })
165
+ .optional()
166
+ .describe('The timezone at the point; present only with includeTimezone.'),
167
+ }),
168
+ enrichment: {
169
+ truncated: z
170
+ .boolean()
171
+ .describe('True when nearby is full at nearbyLimit, so more may lie within the radius.'),
172
+ shown: z.number().describe('Nearby places or features returned.'),
173
+ cap: z.number().describe('The nearbyLimit that was applied.'),
174
+ notice: z
175
+ .string()
176
+ .optional()
177
+ .describe('Guidance when the point is offshore or unmapped, nothing is nearby, nearby is full, or no IANA timezone covers it.'),
178
+ },
179
+ errors: [
180
+ {
181
+ reason: 'unknown_feature_code',
182
+ code: JsonRpcErrorCode.ValidationError,
183
+ when: 'A featureCodes entry is not a GeoNames feature code.',
184
+ recovery: 'Look up valid codes with geonames_list_reference topic feature_codes, then retry with a listed code.',
185
+ severity: 'notice',
186
+ },
187
+ {
188
+ reason: 'conflicting_filters',
189
+ code: JsonRpcErrorCode.ValidationError,
190
+ when: 'cities was combined with featureClasses or featureCodes.',
191
+ recovery: 'Call geonames_reverse_geocode again with cities for the nearest populated places, or featureClasses/featureCodes for the nearest features of a type, not both.',
192
+ severity: 'notice',
193
+ },
194
+ {
195
+ reason: 'username_required',
196
+ code: JsonRpcErrorCode.Unauthorized,
197
+ when: "Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account.",
198
+ recovery: 'Call the tool again with geonamesUsername set to a free GeoNames account that has web services enabled, or ask the operator to set GEONAMES_USERNAME.',
199
+ severity: 'notice',
200
+ thrownBy: 'service',
201
+ },
202
+ {
203
+ reason: 'caller_account_rejected',
204
+ code: JsonRpcErrorCode.Unauthorized,
205
+ when: 'GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled).',
206
+ recovery: "Enable free web services for that account on its GeoNames account page, or call the tool again without geonamesUsername to use the server's account.",
207
+ severity: 'notice',
208
+ thrownBy: 'service',
209
+ },
210
+ {
211
+ reason: 'server_account_rejected',
212
+ code: JsonRpcErrorCode.ConfigurationError,
213
+ when: "GeoNames rejected the server's GEONAMES_USERNAME.",
214
+ recovery: 'The operator must set GEONAMES_USERNAME to a registered account with free web services enabled; until then call the tool again with geonamesUsername set to your own account.',
215
+ thrownBy: 'service',
216
+ },
217
+ {
218
+ reason: 'quota_exhausted',
219
+ code: JsonRpcErrorCode.RateLimited,
220
+ when: "GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call.",
221
+ recovery: "Wait for the window named in the message before calling again, or call again with a different GeoNames account: pass geonamesUsername, or omit it to use the server's.",
222
+ retryable: true,
223
+ thrownBy: 'service',
224
+ },
225
+ {
226
+ reason: 'upstream_rejected_parameter',
227
+ code: JsonRpcErrorCode.ValidationError,
228
+ when: 'GeoNames rejected a value the schema let through; the message carries its text.',
229
+ recovery: 'Correct the value named in the message and call again; geonames_list_reference lists valid feature classes, feature codes, and postal coverage.',
230
+ severity: 'notice',
231
+ thrownBy: 'service',
232
+ },
233
+ ],
234
+ async handler(input, ctx) {
235
+ const startedAt = Date.now();
236
+ ctx.enrich({ truncated: false, shown: 0, cap: input.nearbyLimit });
237
+ const { lat, lng, nearbyLimit, radiusKm, cities, featureClasses, featureCodes } = input;
238
+ if (cities !== undefined && (featureClasses !== undefined || featureCodes !== undefined)) {
239
+ throw ctx.fail('conflicting_filters', 'cities narrows the nearest populated places, while featureClasses and featureCodes switch to the nearest features of a type; pass one or the other.');
240
+ }
241
+ const unknownCodes = featureCodes?.filter((code) => getFeatureCode(code) === undefined) ?? [];
242
+ if (unknownCodes.length > 0) {
243
+ throw ctx.fail('unknown_feature_code', `Not a GeoNames feature code: ${unknownCodes.join(', ')}.`, { featureCodes: unknownCodes });
244
+ }
245
+ const service = getGeoNamesService();
246
+ const account = service.resolveAccount(input.geonamesUsername);
247
+ const nearbyKind = nearbyLimit === 0
248
+ ? 'none'
249
+ : featureClasses !== undefined || featureCodes !== undefined
250
+ ? 'features'
251
+ : 'populated_places';
252
+ /** Containment, then the ocean only when no country contains the point. */
253
+ const locate = async () => {
254
+ const subdivision = await service.subdivision(lat, lng, account, ctx);
255
+ if (subdivision !== undefined)
256
+ return { subdivision };
257
+ const remainingMs = TOOL_BUDGET_MS - (Date.now() - startedAt);
258
+ const ocean = await service.ocean(lat, lng, account, ctx, {
259
+ deadlineMs: Math.min(OCEAN_BUDGET_MS, remainingMs),
260
+ });
261
+ return ocean === undefined ? {} : { ocean };
262
+ };
263
+ const nearbyParams = { lat, lng, radiusKm, limit: nearbyLimit };
264
+ let nearbyLeg = Promise.resolve([]);
265
+ if (nearbyKind === 'populated_places') {
266
+ nearbyLeg = service.nearbyPlaces({ ...nearbyParams, cities }, account, ctx);
267
+ }
268
+ else if (nearbyKind === 'features') {
269
+ nearbyLeg = service.nearbyFeatures({ ...nearbyParams, featureClasses, featureCodes }, account, ctx);
270
+ }
271
+ const [{ subdivision, ocean }, nearby, timezone] = await Promise.all([
272
+ locate(),
273
+ nearbyLeg,
274
+ input.includeTimezone ? service.timezone(lat, lng, account, ctx) : undefined,
275
+ ]);
276
+ const shown = nearby.length;
277
+ ctx.enrich({ shown });
278
+ const fragments = [];
279
+ if (subdivision === undefined) {
280
+ fragments.push(ocean === undefined
281
+ ? 'GeoNames has no country or ocean for this point (polar or unmapped area); geonames_search_places with a boundingBox around it can still find named features.'
282
+ : `No country contains this point; it lies in ${inlineText(ocean.name)}. Coastal points just offshore resolve to the water body.`);
283
+ }
284
+ const widen = radiusKm < MAX_RADIUS_KM
285
+ ? `raise radiusKm (max ${MAX_RADIUS_KM})`
286
+ : 'search a wider area with geonames_search_places and a boundingBox';
287
+ if (nearbyKind === 'populated_places' && shown === 0) {
288
+ fragments.push(`No populated place within ${radiusKm} km${cities === undefined ? '' : ` in ${cities}`}; ${widen}${cities === undefined ? '' : ' or drop cities'}.`);
289
+ }
290
+ if (nearbyKind === 'features' && shown === 0) {
291
+ const filter = [
292
+ featureCodes && `with code ${featureCodes.join(', ')}`,
293
+ featureClasses && `of class ${featureClasses.join(', ')}`,
294
+ ]
295
+ .filter(Boolean)
296
+ .join(' or ');
297
+ fragments.push(`No feature ${filter} within ${radiusKm} km; ${widen} or widen the feature filter (geonames_list_reference topic feature_codes).`);
298
+ }
299
+ if (shown > 0 && shown === nearbyLimit) {
300
+ ctx.enrich.truncated({ shown, cap: nearbyLimit });
301
+ fragments.push(nearbyLimit < MAX_NEARBY
302
+ ? `Only the nearest ${nearbyLimit} are listed, and more may lie within ${radiusKm} km; raise nearbyLimit (max ${MAX_NEARBY}) to see them.`
303
+ : `Only the nearest ${MAX_NEARBY} are listed, the most one call returns, and more may lie within ${radiusKm} km; list the rest with geonames_search_places and a boundingBox.`);
304
+ }
305
+ if (input.includeTimezone && timezone?.timezoneId === undefined) {
306
+ fragments.push(timezone === undefined
307
+ ? 'GeoNames has no timezone for this point.'
308
+ : "No IANA timezone covers this point; the offsets are GeoNames' estimate for open water.");
309
+ }
310
+ if (fragments.length > 0)
311
+ ctx.enrich.notice(fragments.join(' '));
312
+ return {
313
+ lat,
314
+ lng,
315
+ ...(subdivision?.country === undefined ? {} : { country: subdivision.country }),
316
+ adminLevels: subdivision?.adminLevels ?? [],
317
+ ...(ocean === undefined ? {} : { ocean }),
318
+ nearbyKind,
319
+ nearby: nearby.map(toNearby),
320
+ ...(timezone === undefined ? {} : { timezone: toTimezone(timezone) }),
321
+ };
322
+ },
323
+ format: (result) => {
324
+ const lines = [`## GeoNames reverse geocode of ${result.lat}, ${result.lng}`, ''];
325
+ const { country, ocean, timezone } = result;
326
+ lines.push(`**Country:** ${country === undefined
327
+ ? 'None'
328
+ : `${country.countryName === undefined ? '' : `${inlineText(country.countryName)} `}(${inlineText(country.countryCode)})`}`);
329
+ if (ocean !== undefined) {
330
+ lines.push(`**Ocean or sea:** ${inlineText(ocean.name)}${ocean.geonameId === undefined ? '' : ` (geonameId ${ocean.geonameId})`}`);
331
+ }
332
+ lines.push('', '### Admin divisions');
333
+ if (result.adminLevels.length === 0) {
334
+ lines.push(country === undefined ? 'None: no country contains this point.' : 'None recorded.');
335
+ }
336
+ else {
337
+ lines.push('| Level | Name | Code | geonameId | ISO 3166-2 |', '|:---|:---|:---|:---|:---|');
338
+ for (const level of result.adminLevels) {
339
+ lines.push(`| ADM${level.level} | ${orNotAvailable(level.name)} | ${orNotAvailable(level.code)} | ${orNotAvailable(level.geonameId)} | ${orNotAvailable(level.isoCode)} |`);
340
+ }
341
+ }
342
+ lines.push('', `### ${NEARBY_TITLES[result.nearbyKind]} (nearbyKind ${result.nearbyKind})`);
343
+ if (result.nearby.length === 0) {
344
+ lines.push(result.nearbyKind === 'none' ? 'Not requested.' : 'None within the radius.');
345
+ }
346
+ else {
347
+ lines.push('| Distance (km) | geonameId | Name | Feature | Country | First-level division | Population | Lat, Lng |', '|:---|:---|:---|:---|:---|:---|:---|:---|');
348
+ for (const row of result.nearby) {
349
+ const name = row.toponymName === row.name
350
+ ? tableCell(row.name)
351
+ : `${tableCell(row.name)} (toponym: ${tableCell(row.toponymName)})`;
352
+ const feature = row.featureCode === undefined && row.featureClass === undefined
353
+ ? 'Not available'
354
+ : [
355
+ row.featureCode && tableCell(row.featureCode),
356
+ row.featureName && tableCell(row.featureName),
357
+ row.featureClass && `(class ${tableCell(row.featureClass)})`,
358
+ ]
359
+ .filter(Boolean)
360
+ .join(' ');
361
+ lines.push(`| ${[
362
+ orNotAvailable(row.distanceInKm),
363
+ row.geonameId,
364
+ name,
365
+ feature,
366
+ orNotAvailable(row.countryCode),
367
+ orNotAvailable(row.adminName1),
368
+ row.population === undefined ? 'Not available' : row.population.toLocaleString('en-US'),
369
+ row.lat === undefined || row.lng === undefined
370
+ ? 'Not available'
371
+ : `${row.lat}, ${row.lng}`,
372
+ ].join(' | ')} |`);
373
+ }
374
+ }
375
+ if (timezone !== undefined) {
376
+ lines.push('', '### Timezone', `- **IANA id:** ${timezone.timezoneId === undefined ? 'Not available' : inlineText(timezone.timezoneId)}`, `- **Country:** ${timezone.countryCode === undefined ? 'Not available' : inlineText(timezone.countryCode)}`, `- **UTC offsets (hours):** standard ${timezone.rawOffsetInHours}, 1 January ${timezone.gmtOffsetInHours}, 1 July ${timezone.dstOffsetInHours}`, `- **Local time:** ${timezone.localTime === undefined ? 'Not available' : inlineText(timezone.localTime)}`, `- **Sunrise:** ${timezone.sunrise === undefined ? 'Not available' : inlineText(timezone.sunrise)}`, `- **Sunset:** ${timezone.sunset === undefined ? 'Not available' : inlineText(timezone.sunset)}`);
377
+ }
378
+ return [{ type: 'text', text: lines.join('\n') }];
379
+ },
380
+ });
381
+ //# sourceMappingURL=reverse-geocode.tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reverse-geocode.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/reverse-geocode.tool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,133 @@
1
+ /**
2
+ * @fileoverview geonames_search_places — searches the GeoNames gazetteer by name and
3
+ * filters (country, feature class or code, population tier, bounding box) through
4
+ * `searchJSON`, one credit a call, cached for an hour.
5
+ * @module mcp-server/tools/definitions/search-places.tool
6
+ */
7
+ import { z } from '@cyanheads/mcp-ts-core';
8
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
9
+ export declare const searchPlacesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
10
+ query: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
11
+ match: z.ZodPreprocess<z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
12
+ any_field: "any_field";
13
+ exact_name: "exact_name";
14
+ name_prefix: "name_prefix";
15
+ name_required: "name_required";
16
+ }>>, unknown>, unknown>;
17
+ countries: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>, unknown>;
18
+ featureClasses: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodEnum<{
19
+ A: "A";
20
+ H: "H";
21
+ L: "L";
22
+ P: "P";
23
+ R: "R";
24
+ S: "S";
25
+ T: "T";
26
+ U: "U";
27
+ V: "V";
28
+ }>>>, unknown>;
29
+ featureCodes: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>, unknown>;
30
+ cities: z.ZodPreprocess<z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
31
+ cities1000: "cities1000";
32
+ cities15000: "cities15000";
33
+ cities5000: "cities5000";
34
+ }>>, unknown>, unknown>;
35
+ boundingBox: z.ZodPreprocess<z.ZodOptional<z.ZodObject<{
36
+ north: z.ZodNumber;
37
+ south: z.ZodNumber;
38
+ east: z.ZodNumber;
39
+ west: z.ZodNumber;
40
+ }, z.core.$strict>>, unknown>;
41
+ orderBy: z.ZodPreprocess<z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
42
+ population: "population";
43
+ relevance: "relevance";
44
+ }>>, unknown>, unknown>;
45
+ limit: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
46
+ offset: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
47
+ geonamesUsername: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
48
+ }, z.core.$strip>, z.ZodObject<{
49
+ places: z.ZodArray<z.ZodObject<{
50
+ geonameId: z.ZodNumber;
51
+ name: z.ZodString;
52
+ toponymName: z.ZodString;
53
+ lat: z.ZodOptional<z.ZodNumber>;
54
+ lng: z.ZodOptional<z.ZodNumber>;
55
+ featureClass: z.ZodOptional<z.ZodString>;
56
+ featureClassName: z.ZodOptional<z.ZodString>;
57
+ featureCode: z.ZodOptional<z.ZodString>;
58
+ featureName: z.ZodOptional<z.ZodString>;
59
+ countryCode: z.ZodOptional<z.ZodString>;
60
+ countryName: z.ZodOptional<z.ZodString>;
61
+ adminCode1: z.ZodOptional<z.ZodString>;
62
+ adminName1: z.ZodOptional<z.ZodString>;
63
+ iso3166_2: z.ZodOptional<z.ZodString>;
64
+ population: z.ZodOptional<z.ZodNumber>;
65
+ }, z.core.$strip>>;
66
+ nextOffset: z.ZodOptional<z.ZodNumber>;
67
+ }, z.core.$strip>, readonly [{
68
+ readonly reason: "query_or_filter_required";
69
+ readonly code: JsonRpcErrorCode.ValidationError;
70
+ readonly when: "Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given.";
71
+ readonly recovery: "Pass query, or at least one of countries, featureClasses, featureCodes, or boundingBox, then call geonames_search_places again.";
72
+ readonly severity: "notice";
73
+ }, {
74
+ readonly reason: "query_required";
75
+ readonly code: JsonRpcErrorCode.ValidationError;
76
+ readonly when: "match was set without query.";
77
+ readonly recovery: "Call geonames_search_places again with query text for the chosen match mode, or drop match to search by filters alone.";
78
+ readonly severity: "notice";
79
+ }, {
80
+ readonly reason: "unknown_feature_code";
81
+ readonly code: JsonRpcErrorCode.ValidationError;
82
+ readonly when: "A featureCodes entry is not a GeoNames feature code.";
83
+ readonly recovery: "Look up valid codes with geonames_list_reference topic feature_codes, then retry with a listed code.";
84
+ readonly severity: "notice";
85
+ }, {
86
+ readonly reason: "invalid_bounding_box";
87
+ readonly code: JsonRpcErrorCode.ValidationError;
88
+ readonly when: "boundingBox has south greater than or equal to north, or west greater than or equal to east.";
89
+ readonly recovery: "Call geonames_search_places again with south below north and west below east; split a box that crosses the 180° meridian into two searches.";
90
+ readonly severity: "notice";
91
+ }, {
92
+ readonly reason: "username_required";
93
+ readonly code: JsonRpcErrorCode.Unauthorized;
94
+ readonly when: "Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account.";
95
+ readonly recovery: "Call the tool again with geonamesUsername set to a free GeoNames account that has web services enabled, or ask the operator to set GEONAMES_USERNAME.";
96
+ readonly severity: "notice";
97
+ readonly thrownBy: "service";
98
+ }, {
99
+ readonly reason: "caller_account_rejected";
100
+ readonly code: JsonRpcErrorCode.Unauthorized;
101
+ readonly when: "GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled).";
102
+ readonly recovery: "Enable free web services for that account on its GeoNames account page, or call the tool again without geonamesUsername to use the server's account.";
103
+ readonly severity: "notice";
104
+ readonly thrownBy: "service";
105
+ }, {
106
+ readonly reason: "server_account_rejected";
107
+ readonly code: JsonRpcErrorCode.ConfigurationError;
108
+ readonly when: "GeoNames rejected the server's GEONAMES_USERNAME.";
109
+ readonly recovery: "The operator must set GEONAMES_USERNAME to a registered account with free web services enabled; until then call the tool again with geonamesUsername set to your own account.";
110
+ readonly thrownBy: "service";
111
+ }, {
112
+ readonly reason: "quota_exhausted";
113
+ readonly code: JsonRpcErrorCode.RateLimited;
114
+ readonly when: "GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call.";
115
+ readonly recovery: "Wait for the window named in the message before calling again, or call again with a different GeoNames account: pass geonamesUsername, or omit it to use the server's.";
116
+ readonly retryable: true;
117
+ readonly thrownBy: "service";
118
+ }, {
119
+ readonly reason: "upstream_rejected_parameter";
120
+ readonly code: JsonRpcErrorCode.ValidationError;
121
+ readonly when: "GeoNames rejected a value the schema let through; the message carries its text.";
122
+ readonly recovery: "Correct the value named in the message and call again; geonames_list_reference lists valid feature classes, feature codes, and postal coverage.";
123
+ readonly severity: "notice";
124
+ readonly thrownBy: "service";
125
+ }], {
126
+ readonly totalCount: z.ZodNumber;
127
+ readonly effectiveQuery: z.ZodString;
128
+ readonly truncated: z.ZodBoolean;
129
+ readonly shown: z.ZodNumber;
130
+ readonly cap: z.ZodNumber;
131
+ readonly notice: z.ZodOptional<z.ZodString>;
132
+ }>;
133
+ //# sourceMappingURL=search-places.tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search-places.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-places.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2CjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+X3B,CAAC"}