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

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 (91) hide show
  1. package/AGENTS.md +439 -0
  2. package/CLAUDE.md +439 -0
  3. package/Dockerfile +177 -0
  4. package/LICENSE +201 -0
  5. package/README.md +344 -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/0.1.x/0.1.2.md +26 -0
  9. package/changelog/template.md +151 -0
  10. package/dist/config/server-config.d.ts +13 -0
  11. package/dist/config/server-config.d.ts.map +1 -0
  12. package/dist/config/server-config.js +21 -0
  13. package/dist/config/server-config.js.map +1 -0
  14. package/dist/index.d.ts +8 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +30 -0
  17. package/dist/index.js.map +1 -0
  18. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts +96 -0
  19. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -0
  20. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +274 -0
  21. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -0
  22. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +90 -0
  23. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -0
  24. package/dist/mcp-server/tools/definitions/get-children.tool.js +287 -0
  25. package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -0
  26. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +90 -0
  27. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -0
  28. package/dist/mcp-server/tools/definitions/get-countries.tool.js +217 -0
  29. package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -0
  30. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.d.ts +64 -0
  31. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.d.ts.map +1 -0
  32. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js +168 -0
  33. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js.map +1 -0
  34. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +108 -0
  35. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -0
  36. package/dist/mcp-server/tools/definitions/get-place.tool.js +300 -0
  37. package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -0
  38. package/dist/mcp-server/tools/definitions/index.d.ts +760 -0
  39. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -0
  40. package/dist/mcp-server/tools/definitions/index.js +23 -0
  41. package/dist/mcp-server/tools/definitions/index.js.map +1 -0
  42. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +103 -0
  43. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -0
  44. package/dist/mcp-server/tools/definitions/list-reference.tool.js +233 -0
  45. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -0
  46. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts +142 -0
  47. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -0
  48. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +421 -0
  49. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -0
  50. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +145 -0
  51. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -0
  52. package/dist/mcp-server/tools/definitions/search-places.tool.js +385 -0
  53. package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -0
  54. package/dist/mcp-server/tools/shared-inputs.d.ts +140 -0
  55. package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -0
  56. package/dist/mcp-server/tools/shared-inputs.js +240 -0
  57. package/dist/mcp-server/tools/shared-inputs.js.map +1 -0
  58. package/dist/services/geonames/country-codes.d.ts +26 -0
  59. package/dist/services/geonames/country-codes.d.ts.map +1 -0
  60. package/dist/services/geonames/country-codes.js +284 -0
  61. package/dist/services/geonames/country-codes.js.map +1 -0
  62. package/dist/services/geonames/feature-codes.d.ts +27 -0
  63. package/dist/services/geonames/feature-codes.d.ts.map +1 -0
  64. package/dist/services/geonames/feature-codes.js +723 -0
  65. package/dist/services/geonames/feature-codes.js.map +1 -0
  66. package/dist/services/geonames/geonames-service.d.ts +103 -0
  67. package/dist/services/geonames/geonames-service.d.ts.map +1 -0
  68. package/dist/services/geonames/geonames-service.js +561 -0
  69. package/dist/services/geonames/geonames-service.js.map +1 -0
  70. package/dist/services/geonames/response-cache.d.ts +24 -0
  71. package/dist/services/geonames/response-cache.d.ts.map +1 -0
  72. package/dist/services/geonames/response-cache.js +44 -0
  73. package/dist/services/geonames/response-cache.js.map +1 -0
  74. package/dist/services/geonames/response-parsers.d.ts +38 -0
  75. package/dist/services/geonames/response-parsers.d.ts.map +1 -0
  76. package/dist/services/geonames/response-parsers.js +369 -0
  77. package/dist/services/geonames/response-parsers.js.map +1 -0
  78. package/dist/services/geonames/types.d.ts +226 -0
  79. package/dist/services/geonames/types.d.ts.map +1 -0
  80. package/dist/services/geonames/types.js +10 -0
  81. package/dist/services/geonames/types.js.map +1 -0
  82. package/dist/services/geonames/upstream-errors.d.ts +54 -0
  83. package/dist/services/geonames/upstream-errors.d.ts.map +1 -0
  84. package/dist/services/geonames/upstream-errors.js +187 -0
  85. package/dist/services/geonames/upstream-errors.js.map +1 -0
  86. package/dist/utils/inline-text.d.ts +25 -0
  87. package/dist/utils/inline-text.d.ts.map +1 -0
  88. package/dist/utils/inline-text.js +60 -0
  89. package/dist/utils/inline-text.js.map +1 -0
  90. package/package.json +108 -4
  91. package/server.json +120 -0
@@ -0,0 +1,226 @@
1
+ /**
2
+ * @fileoverview Domain types for the GeoNames service: normalized rows with
3
+ * GeoNames' absence placeholders (`population: 0`, `geonameId: 0`, `adminCode1: "00"`,
4
+ * empty strings) dropped, and string numbers parsed. The external-identifier types
5
+ * are also a runtime list, so the parser and the output schema share one source.
6
+ * @module services/geonames/types
7
+ */
8
+ import type { FeatureClass } from './feature-codes.js';
9
+ /** Where the GeoNames account for a call came from. */
10
+ export type AccountSource = 'caller' | 'server';
11
+ /** A gazetteer row as search, hierarchy, children, and the nearby endpoints return it. */
12
+ export interface Toponym {
13
+ adminCode1?: string;
14
+ adminName1?: string;
15
+ countryCode?: string;
16
+ countryGeonameId?: number;
17
+ countryName?: string;
18
+ /** Present on the nearby endpoints only. */
19
+ distanceInKm?: number;
20
+ featureClass?: string;
21
+ /** GeoNames' class label (`fclName`), trimmed. */
22
+ featureClassName?: string;
23
+ featureCode?: string;
24
+ /** GeoNames' code label (`fcodeName`). */
25
+ featureName?: string;
26
+ geonameId: number;
27
+ iso3166_2?: string;
28
+ /** Absent only when GeoNames sent a value that does not parse as a number. */
29
+ lat?: number;
30
+ lng?: number;
31
+ name: string;
32
+ population?: number;
33
+ toponymName: string;
34
+ }
35
+ /** Bounding box in decimal degrees. */
36
+ export interface BoundingBox {
37
+ east: number;
38
+ north: number;
39
+ south: number;
40
+ west: number;
41
+ }
42
+ /** One level of an administrative chain (1 = first-order division). */
43
+ export interface AdminLevel {
44
+ code?: string;
45
+ geonameId?: number;
46
+ /** ISO 3166-2 code at this level (reverse geocoding only). */
47
+ isoCode?: string;
48
+ level: number;
49
+ name?: string;
50
+ }
51
+ /** Timezone block of a full place record. */
52
+ export interface PlaceTimezone {
53
+ /** UTC offset in hours on 1 July (GeoNames' `dstOffset`). */
54
+ dstOffsetInHours?: number;
55
+ /** UTC offset in hours on 1 January (GeoNames' `gmtOffset`). */
56
+ gmtOffsetInHours?: number;
57
+ timezoneId?: string;
58
+ }
59
+ /** An alternate name of a place (pseudo-language entries are split out). */
60
+ export interface AlternateName {
61
+ isPreferredName?: boolean;
62
+ isShortName?: boolean;
63
+ lang?: string;
64
+ name: string;
65
+ }
66
+ /** The GeoNames pseudo-languages that carry an external identifier, in display order. */
67
+ export declare const IDENTIFIER_TYPES: readonly ['iata', 'icao', 'faac', 'tcid', 'unlc', 'wkdt'];
68
+ /** External identifier carried as a GeoNames pseudo-language alternate name. */
69
+ export interface ExternalIdentifier {
70
+ type: (typeof IDENTIFIER_TYPES)[number];
71
+ value: string;
72
+ }
73
+ /** The full `getJSON` record. */
74
+ export interface PlaceRecord extends Omit<Toponym, 'adminCode1' | 'adminName1' | 'distanceInKm'> {
75
+ adminLevels: AdminLevel[];
76
+ alternateNames: AlternateName[];
77
+ asciiName?: string;
78
+ boundingBox?: BoundingBox;
79
+ continentCode?: string;
80
+ demElevationInMeters?: number;
81
+ elevationInMeters?: number;
82
+ identifiers: ExternalIdentifier[];
83
+ links: string[];
84
+ postalCodes: string[];
85
+ timezone?: PlaceTimezone;
86
+ /** As received: GeoNames sends it without a scheme. */
87
+ wikipediaUrl?: string;
88
+ }
89
+ /** `childrenJSON` result; `totalCount` is GeoNames' own count, which can exceed the rows. */
90
+ export interface ChildrenResult {
91
+ children: Toponym[];
92
+ totalCount: number;
93
+ }
94
+ /** `countrySubdivisionJSON` containment for a point. */
95
+ export interface Subdivision {
96
+ adminLevels: AdminLevel[];
97
+ country?: {
98
+ countryCode: string;
99
+ countryName?: string;
100
+ /** Km from the point to the country, to the metre; only for a match within the `radius` buffer. */
101
+ distanceInKm?: number;
102
+ };
103
+ }
104
+ /** `oceanJSON` result. */
105
+ export interface Ocean {
106
+ geonameId?: number;
107
+ name: string;
108
+ }
109
+ /** `timezoneJSON` result; offshore points carry only the three offsets. */
110
+ export interface TimezoneInfo {
111
+ countryCode?: string;
112
+ countryName?: string;
113
+ /**
114
+ * UTC offset in hours on 1 July (GeoNames' `dstOffset`). With no `timezoneId`, GeoNames'
115
+ * `dstOffset: 0` is a placeholder and the standard offset stands in: open water has no DST.
116
+ */
117
+ dstOffsetInHours: number;
118
+ /** UTC offset in hours on 1 January (GeoNames' `gmtOffset`). */
119
+ gmtOffsetInHours: number;
120
+ /** GeoNames' local `YYYY-MM-DD HH:mm`. */
121
+ localTime?: string;
122
+ rawOffsetInHours: number;
123
+ sunrise?: string;
124
+ sunset?: string;
125
+ timezoneId?: string;
126
+ }
127
+ /** A postal-code row from `postalCodeSearchJSON` or `findNearbyPostalCodesJSON`. */
128
+ export interface PostalCode {
129
+ adminCode1?: string;
130
+ adminCode2?: string;
131
+ adminCode3?: string;
132
+ adminName1?: string;
133
+ adminName2?: string;
134
+ adminName3?: string;
135
+ countryCode: string;
136
+ /** Nearby lookups only. */
137
+ distanceInKm?: number;
138
+ iso3166_2?: string;
139
+ lat?: number;
140
+ lng?: number;
141
+ placeName: string;
142
+ postalCode: string;
143
+ }
144
+ /** A `countryInfoJSON` row. */
145
+ export interface CountryInfo {
146
+ areaInSqKm?: number;
147
+ boundingBox: BoundingBox;
148
+ capital?: string;
149
+ continentCode: string;
150
+ continentName: string;
151
+ countryCode: string;
152
+ countryName: string;
153
+ currencyCode?: string;
154
+ fipsCode?: string;
155
+ geonameId: number;
156
+ isoAlpha3: string;
157
+ isoNumeric?: string;
158
+ languages: string[];
159
+ population?: number;
160
+ postalCodeFormat?: string;
161
+ }
162
+ /** A `postalCodeCountryInfoJSON` row. */
163
+ export interface PostalCountry {
164
+ countryCode: string;
165
+ countryName: string;
166
+ maxPostalCode?: string;
167
+ minPostalCode?: string;
168
+ postalCodeCount: number;
169
+ }
170
+ /** How `searchJSON` matches `query`. */
171
+ export type SearchMatch = 'any_field' | 'exact_name' | 'name_prefix' | 'name_required';
172
+ /** Population tier filter (`cities`). */
173
+ export type CitiesTier = 'cities1000' | 'cities5000' | 'cities15000';
174
+ /**
175
+ * `searchJSON` parameters, mapped onto GeoNames' allowlisted names by the service.
176
+ * Like every parameter bag below, an optional field may also be passed as `undefined`.
177
+ */
178
+ export interface SearchParams {
179
+ boundingBox?: BoundingBox | undefined;
180
+ cities?: CitiesTier | undefined;
181
+ countries?: readonly string[] | undefined;
182
+ featureClasses?: readonly FeatureClass[] | undefined;
183
+ featureCodes?: readonly string[] | undefined;
184
+ limit: number;
185
+ /** Applied only with `query`. */
186
+ match?: SearchMatch | undefined;
187
+ offset: number;
188
+ orderBy?: 'population' | 'relevance' | undefined;
189
+ query?: string | undefined;
190
+ }
191
+ /** `searchJSON` result. */
192
+ export interface SearchResult {
193
+ places: Toponym[];
194
+ totalCount: number;
195
+ }
196
+ /**
197
+ * Child trees `childrenJSON` serves. GeoNames also documents `geography`, but its hierarchy
198
+ * dump holds no such edge, and a request for it answers with the administrative children.
199
+ */
200
+ export type ChildHierarchy = 'administrative' | 'dependency' | 'tourism';
201
+ /** Shared parameters of the two nearby endpoints. */
202
+ export interface NearbyParams {
203
+ lat: number;
204
+ limit: number;
205
+ lng: number;
206
+ radiusKm: number;
207
+ }
208
+ /** `findNearbyPlaceNameJSON` parameters. */
209
+ export interface NearbyPlacesParams extends NearbyParams {
210
+ cities?: CitiesTier | undefined;
211
+ }
212
+ /** `findNearbyJSON` parameters. */
213
+ export interface NearbyFeaturesParams extends NearbyParams {
214
+ featureClasses?: readonly FeatureClass[] | undefined;
215
+ featureCodes?: readonly string[] | undefined;
216
+ }
217
+ /** `postalCodeSearchJSON` parameters (code or place name). */
218
+ export interface PostalSearchParams {
219
+ countries?: readonly string[] | undefined;
220
+ limit: number;
221
+ placeName?: string | undefined;
222
+ postalCode?: string | undefined;
223
+ }
224
+ /** `findNearbyPostalCodesJSON` parameters. */
225
+ export type PostalNearbyParams = NearbyParams;
226
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/geonames/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * @fileoverview Domain types for the GeoNames service: normalized rows with
3
+ * GeoNames' absence placeholders (`population: 0`, `geonameId: 0`, `adminCode1: "00"`,
4
+ * empty strings) dropped, and string numbers parsed. The external-identifier types
5
+ * are also a runtime list, so the parser and the output schema share one source.
6
+ * @module services/geonames/types
7
+ */
8
+ /** The GeoNames pseudo-languages that carry an external identifier, in display order. */
9
+ export const IDENTIFIER_TYPES = ['iata', 'icao', 'faac', 'tcid', 'unlc', 'wkdt'];
10
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/geonames/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC"}
@@ -0,0 +1,54 @@
1
+ /**
2
+ * @fileoverview The one place GeoNames failures are classified: the body's
3
+ * `status.value` table, HTTP statuses outside the accept-list, unreadable bodies,
4
+ * transport failures, and local pacer sheds. Messages are composed here, never
5
+ * copied from GeoNames on auth or quota failures, because GeoNames' text embeds
6
+ * the account name.
7
+ * @module services/geonames/upstream-errors
8
+ */
9
+ import { McpError } from '@cyanheads/mcp-ts-core/errors';
10
+ import type { AccountSource } from './types.js';
11
+ /** GeoNames statuses that are results rather than failures: no record, no result, no postal code. */
12
+ export type MissStatus = 11 | 15 | 17;
13
+ /** The `data.reason` an error carries, when it is an `McpError` that sets one. */
14
+ export declare function reasonOf(error: unknown): unknown;
15
+ /** Neither a caller nor a server account is available. */
16
+ export declare function usernameRequired(): McpError;
17
+ /** Non-JSON, HTML, truncated, over-ceiling, redirected, or missing the endpoint's root key. Transient. */
18
+ export declare function upstreamUnreadable(): McpError;
19
+ /** A JSON body with the right root key whose rows fail the schema. Deterministic, so never retried. */
20
+ export declare function upstreamUnexpectedShape(endpoint: string): McpError;
21
+ /**
22
+ * An HTTP status outside the accept-list that carried no GeoNames status envelope.
23
+ * The hint promises a retry only for a status the retry ladder treats as transient
24
+ * (5xx, 408, 425, 429); any other is marked `retryable: false`.
25
+ */
26
+ export declare function upstreamHttpError(status: number): McpError;
27
+ /** The 10 s per-attempt timer fired before GeoNames answered. Transient. */
28
+ export declare function upstreamTimedOut(): McpError;
29
+ /**
30
+ * The retry ladder's total deadline (`withRetry`'s `retry_deadline_exceeded`) ran out
31
+ * before GeoNames answered: restated as `upstream_timeout` with its recovery hint.
32
+ */
33
+ export declare function upstreamDeadlineExceeded(error: McpError): McpError;
34
+ /** The request never reached GeoNames (DNS, connection, TLS). Transient. */
35
+ export declare function upstreamUnreachable(): McpError;
36
+ /** The account a status envelope arrived for, as {@link mapStatus} needs it. */
37
+ export interface StatusAccount {
38
+ source: AccountSource;
39
+ username: string;
40
+ }
41
+ /**
42
+ * Maps a GeoNames `{"status":{"value","message"}}` envelope. Returns the status for
43
+ * the three that are results (each endpoint decides what they mean); throws for the
44
+ * rest. `hasServerAccount` picks the caller-rejection recovery hint.
45
+ */
46
+ export declare function mapStatus(value: number, message: string, account: StatusAccount, hasServerAccount: boolean): MissStatus;
47
+ /**
48
+ * Restates a local pacer shed as `quota_exhausted` (`window: local`), so every tool's
49
+ * contract covers it with the same recovery. `pausedMs` is the account's cooldown
50
+ * gate: open (0) means the shed came from local pacing, closed means GeoNames
51
+ * reported a spent quota moments ago.
52
+ */
53
+ export declare function quotaFromShed(shed: unknown, source: AccountSource, pausedMs: number): McpError;
54
+ //# sourceMappingURL=upstream-errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"upstream-errors.d.ts","sourceRoot":"","sources":["../../../src/services/geonames/upstream-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAIL,QAAQ,EAMT,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qGAAqG;AACrG,MAAM,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEtC,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhD;AAsBD,0DAA0D;AAC1D,wBAAgB,gBAAgB,IAAI,QAAQ,CAK3C;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,IAAI,QAAQ,CAK7C;AAED,uGAAuG;AACvG,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAiB1D;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,IAAI,QAAQ,CAK3C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAWlE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,QAAQ,CAK9C;AAQD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,EACtB,gBAAgB,EAAE,OAAO,GACxB,UAAU,CAkEZ;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAa9F"}
@@ -0,0 +1,187 @@
1
+ /**
2
+ * @fileoverview The one place GeoNames failures are classified: the body's
3
+ * `status.value` table, HTTP statuses outside the accept-list, unreadable bodies,
4
+ * transport failures, and local pacer sheds. Messages are composed here, never
5
+ * copied from GeoNames on auth or quota failures, because GeoNames' text embeds
6
+ * the account name.
7
+ * @module services/geonames/upstream-errors
8
+ */
9
+ import { configurationError, internalError, JsonRpcErrorCode, McpError, rateLimited, serviceUnavailable, timeout, unauthorized, validationError, } from '@cyanheads/mcp-ts-core/errors';
10
+ import { defaultIsTransient, httpStatusToErrorCode } from '@cyanheads/mcp-ts-core/utils';
11
+ import { inlineText } from '../../utils/inline-text.js';
12
+ /** The `data.reason` an error carries, when it is an `McpError` that sets one. */
13
+ export function reasonOf(error) {
14
+ return error instanceof McpError ? error.data?.reason : undefined;
15
+ }
16
+ /** "this server's GeoNames account" / "the GeoNames account passed as geonamesUsername". */
17
+ function accountPhrase(source) {
18
+ return source === 'server'
19
+ ? "this server's GeoNames account"
20
+ : 'the GeoNames account passed as geonamesUsername';
21
+ }
22
+ const capitalize = (text) => `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
23
+ /**
24
+ * Replaces every occurrence of `username` (case-insensitive) with `{account}`, a
25
+ * placeholder with no characters the inline-text helper escapes.
26
+ */
27
+ function scrubAccount(text, username) {
28
+ return text.replace(new RegExp(username.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi'), '{account}');
29
+ }
30
+ /** Neither a caller nor a server account is available. */
31
+ export function usernameRequired() {
32
+ return unauthorized('No GeoNames account is available for this call: it passed no geonamesUsername and the server has no GEONAMES_USERNAME set.', { reason: 'username_required' });
33
+ }
34
+ /** Non-JSON, HTML, truncated, over-ceiling, redirected, or missing the endpoint's root key. Transient. */
35
+ export function upstreamUnreadable() {
36
+ return serviceUnavailable('GeoNames returned an unreadable response.', {
37
+ reason: 'upstream_unreadable',
38
+ recovery: { hint: 'GeoNames returned an unreadable response; retry shortly.' },
39
+ });
40
+ }
41
+ /** A JSON body with the right root key whose rows fail the schema. Deterministic, so never retried. */
42
+ export function upstreamUnexpectedShape(endpoint) {
43
+ return serviceUnavailable(`GeoNames returned ${endpoint} rows in an unexpected shape.`, {
44
+ reason: 'upstream_unexpected_shape',
45
+ retryable: false,
46
+ recovery: {
47
+ hint: 'GeoNames changed the shape of this response; retrying will not help. Report it to the server maintainer.',
48
+ },
49
+ });
50
+ }
51
+ /**
52
+ * An HTTP status outside the accept-list that carried no GeoNames status envelope.
53
+ * The hint promises a retry only for a status the retry ladder treats as transient
54
+ * (5xx, 408, 425, 429); any other is marked `retryable: false`.
55
+ */
56
+ export function upstreamHttpError(status) {
57
+ const code = httpStatusToErrorCode(status) ?? JsonRpcErrorCode.ServiceUnavailable;
58
+ const message = `GeoNames answered with HTTP ${status}.`;
59
+ const data = { reason: 'upstream_http_error', httpStatus: status };
60
+ if (defaultIsTransient(new McpError(code, message, data))) {
61
+ return new McpError(code, message, {
62
+ ...data,
63
+ recovery: { hint: `GeoNames answered with HTTP ${status}; retry in a minute.` },
64
+ });
65
+ }
66
+ return new McpError(code, message, {
67
+ ...data,
68
+ retryable: false,
69
+ recovery: {
70
+ hint: `GeoNames refused the request with HTTP ${status}, and retrying it will not help. Report the failure instead of calling again with the same arguments.`,
71
+ },
72
+ });
73
+ }
74
+ /** The 10 s per-attempt timer fired before GeoNames answered. Transient. */
75
+ export function upstreamTimedOut() {
76
+ return timeout('GeoNames did not answer within 10 seconds.', {
77
+ reason: 'upstream_timeout',
78
+ recovery: { hint: 'GeoNames is slow to answer; retry shortly.' },
79
+ });
80
+ }
81
+ /**
82
+ * The retry ladder's total deadline (`withRetry`'s `retry_deadline_exceeded`) ran out
83
+ * before GeoNames answered: restated as `upstream_timeout` with its recovery hint.
84
+ */
85
+ export function upstreamDeadlineExceeded(error) {
86
+ return timeout("GeoNames did not answer within this call's time budget.", {
87
+ reason: 'upstream_timeout',
88
+ deadlineMs: error.data?.deadlineMs,
89
+ retryAttempts: error.data?.retryAttempts,
90
+ recovery: { hint: 'GeoNames is slow to answer; retry shortly.' },
91
+ }, { cause: error });
92
+ }
93
+ /** The request never reached GeoNames (DNS, connection, TLS). Transient. */
94
+ export function upstreamUnreachable() {
95
+ return serviceUnavailable('GeoNames could not be reached.', {
96
+ reason: 'upstream_unreachable',
97
+ recovery: { hint: 'GeoNames could not be reached; retry shortly.' },
98
+ });
99
+ }
100
+ const QUOTA_WINDOWS = { 18: 'day', 19: 'hour', 20: 'week' };
101
+ const QUOTA_ADJECTIVES = { day: 'daily', hour: 'hourly', week: 'weekly' };
102
+ /** Status codes whose GeoNames text names the rejected parameter and is forwarded, scrubbed. */
103
+ const PARAMETER_STATUSES = new Set([14, 21, 24, 25, 27]);
104
+ /**
105
+ * Maps a GeoNames `{"status":{"value","message"}}` envelope. Returns the status for
106
+ * the three that are results (each endpoint decides what they mean); throws for the
107
+ * rest. `hasServerAccount` picks the caller-rejection recovery hint.
108
+ */
109
+ export function mapStatus(value, message, account, hasServerAccount) {
110
+ if (value === 11 || value === 15 || value === 17)
111
+ return value;
112
+ if (value === 10) {
113
+ throw account.source === 'caller'
114
+ ? unauthorized('GeoNames rejected the account passed as geonamesUsername.', {
115
+ reason: 'caller_account_rejected',
116
+ ...(hasServerAccount
117
+ ? {}
118
+ : {
119
+ recovery: {
120
+ hint: 'Enable free web services for that account on its GeoNames account page, then call the tool again with it.',
121
+ },
122
+ }),
123
+ })
124
+ : configurationError('GeoNames rejected the server account set in GEONAMES_USERNAME: the user does not exist or has not enabled free web services.', { reason: 'server_account_rejected' });
125
+ }
126
+ if (value === 18 || value === 19 || value === 20) {
127
+ const window = QUOTA_WINDOWS[value];
128
+ throw rateLimited(`GeoNames' ${QUOTA_ADJECTIVES[window]} credit limit is exhausted for ${accountPhrase(account.source)}.`, { reason: 'quota_exhausted', window, account: account.source });
129
+ }
130
+ if (PARAMETER_STATUSES.has(value)) {
131
+ throw validationError(`GeoNames rejected a parameter: ${inlineText(scrubAccount(message, account.username))}`, { reason: 'upstream_rejected_parameter', upstreamStatus: value });
132
+ }
133
+ switch (value) {
134
+ case 12:
135
+ throw serviceUnavailable('GeoNames reported an internal error for this request.', {
136
+ reason: 'upstream_error',
137
+ retryable: false,
138
+ recovery: {
139
+ hint: 'GeoNames failed on this request; retrying it unchanged will not help. Try different parameters.',
140
+ },
141
+ });
142
+ case 13:
143
+ throw timeout('GeoNames timed out querying its database.', {
144
+ reason: 'upstream_timeout',
145
+ recovery: { hint: 'GeoNames is slow to answer; retry shortly.' },
146
+ });
147
+ case 22:
148
+ throw serviceUnavailable('GeoNames reports that it is overloaded.', {
149
+ reason: 'upstream_overloaded',
150
+ recovery: { hint: 'GeoNames is overloaded; retry in a minute.' },
151
+ });
152
+ case 23:
153
+ throw internalError('GeoNames does not implement the service this server called.', {
154
+ reason: 'upstream_not_implemented',
155
+ retryable: false,
156
+ recovery: {
157
+ hint: 'This server called a GeoNames service that does not exist; retrying will not help. Report it to the server maintainer.',
158
+ },
159
+ });
160
+ default:
161
+ throw serviceUnavailable(`GeoNames returned error status ${value}.`, {
162
+ reason: 'upstream_status',
163
+ upstreamStatus: value,
164
+ recovery: { hint: 'GeoNames returned an unexpected error; retry in a minute.' },
165
+ });
166
+ }
167
+ }
168
+ /**
169
+ * Restates a local pacer shed as `quota_exhausted` (`window: local`), so every tool's
170
+ * contract covers it with the same recovery. `pausedMs` is the account's cooldown
171
+ * gate: open (0) means the shed came from local pacing, closed means GeoNames
172
+ * reported a spent quota moments ago.
173
+ */
174
+ export function quotaFromShed(shed, source, pausedMs) {
175
+ const retryAfter = shed instanceof McpError ? shed.data?.retryAfter : undefined;
176
+ const wait = typeof retryAfter === 'number' ? ` Retry in about ${retryAfter} s.` : '';
177
+ const message = pausedMs > 0
178
+ ? `GeoNames reported a spent credit limit for ${accountPhrase(source)} moments ago, so this server has paused calls on it.${wait}`
179
+ : `${capitalize(accountPhrase(source))} has more calls queued than this server paces within the call's time budget (at most 1,000 an hour, 4 at a time).${wait}`;
180
+ return rateLimited(message, {
181
+ reason: 'quota_exhausted',
182
+ window: 'local',
183
+ account: source,
184
+ ...(typeof retryAfter === 'number' ? { retryAfter } : {}),
185
+ });
186
+ }
187
+ //# sourceMappingURL=upstream-errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"upstream-errors.js","sourceRoot":"","sources":["../../../src/services/geonames/upstream-errors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,25 @@
1
+ /**
2
+ * @fileoverview Markdown-safe rendering of upstream-authored and caller-echoed text.
3
+ * GeoNames names, labels, and status text are community-edited, so `format()` and
4
+ * composed messages print them only through these helpers. `structuredContent`
5
+ * keeps every string as received, less the Unicode tag characters the service drops
6
+ * when it decodes a response.
7
+ * @module utils/inline-text
8
+ */
9
+ /**
10
+ * Renders text for an inline markdown slot (heading, bold label, list item, notice):
11
+ * line breaks become spaces, control and format characters are dropped, a bare URL's
12
+ * `://` or `www.` is bracketed (`https[:]//`, `www[.]`) so no renderer autolinks it,
13
+ * backslash is escaped, then a character reference's `&` and `[` `]`, and `<` / `>`
14
+ * become entities.
15
+ */
16
+ export declare function inlineText(value: string): string;
17
+ /** {@link inlineText} plus `|` escaped, for a markdown table cell. */
18
+ export declare function tableCell(value: string): string;
19
+ /**
20
+ * Renders a URL as plain text, never as a markdown link. A scheme-less value
21
+ * (GeoNames' `wikipediaURL`) gets `https://`; an `http`/`https` URL prints with
22
+ * unsafe characters percent-encoded; any other scheme prints as escaped text.
23
+ */
24
+ export declare function plainUrl(value: string): string;
25
+ //# sourceMappingURL=inline-text.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inline-text.d.ts","sourceRoot":"","sources":["../../src/utils/inline-text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhD;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ9C"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * @fileoverview Markdown-safe rendering of upstream-authored and caller-echoed text.
3
+ * GeoNames names, labels, and status text are community-edited, so `format()` and
4
+ * composed messages print them only through these helpers. `structuredContent`
5
+ * keeps every string as received, less the Unicode tag characters the service drops
6
+ * when it decodes a response.
7
+ * @module utils/inline-text
8
+ */
9
+ /** CR, LF, tab, and the Unicode line and paragraph separators: flattened to a space. */
10
+ const LINE_BREAKS = /[\r\n\t\u{2028}\u{2029}]/gu;
11
+ /**
12
+ * Controls and format characters (bidi marks, zero-width space, word joiner, BOM, soft
13
+ * hyphen, tag characters), except ZWNJ and ZWJ, which Persian, Arabic, and Indic
14
+ * names need to spell correctly.
15
+ */
16
+ const INVISIBLE = /(?![\u{200c}\u{200d}])[\p{Cc}\p{Cf}]/gu;
17
+ /** The `:` of an http, https, or ftp URL and the `.` after `www`: where GFM starts an autolink. */
18
+ const AUTOLINK_TRIGGER = /(?<=https?|ftp):(?=\/\/)|(?<=www)\./giu;
19
+ /** An `&` that opens a named or numeric character reference, which renderers decode. */
20
+ const CHARACTER_REFERENCE = /&(?=#\d+;|#x[\da-f]+;|[a-z][a-z\d]*;)/giu;
21
+ /** Characters a plain-text URL percent-encodes so it cannot break out of its slot. */
22
+ const URL_UNSAFE = /[\s\p{Cc}\p{Cf}<>[\]\\|`"]/gu;
23
+ const SCHEME = /^([a-z][a-z0-9+.-]*):/i;
24
+ /**
25
+ * Renders text for an inline markdown slot (heading, bold label, list item, notice):
26
+ * line breaks become spaces, control and format characters are dropped, a bare URL's
27
+ * `://` or `www.` is bracketed (`https[:]//`, `www[.]`) so no renderer autolinks it,
28
+ * backslash is escaped, then a character reference's `&` and `[` `]`, and `<` / `>`
29
+ * become entities.
30
+ */
31
+ export function inlineText(value) {
32
+ return value
33
+ .replace(LINE_BREAKS, ' ')
34
+ .replace(INVISIBLE, '')
35
+ .replace(AUTOLINK_TRIGGER, '[$&]')
36
+ .replace(/\\/g, '\\\\')
37
+ .replace(CHARACTER_REFERENCE, '\\&')
38
+ .replace(/[[\]]/g, '\\$&')
39
+ .replace(/</g, '&lt;')
40
+ .replace(/>/g, '&gt;');
41
+ }
42
+ /** {@link inlineText} plus `|` escaped, for a markdown table cell. */
43
+ export function tableCell(value) {
44
+ return inlineText(value).replace(/\|/g, '\\|');
45
+ }
46
+ /**
47
+ * Renders a URL as plain text, never as a markdown link. A scheme-less value
48
+ * (GeoNames' `wikipediaURL`) gets `https://`; an `http`/`https` URL prints with
49
+ * unsafe characters percent-encoded; any other scheme prints as escaped text.
50
+ */
51
+ export function plainUrl(value) {
52
+ const trimmed = value.trim();
53
+ const scheme = SCHEME.exec(trimmed)?.[1]?.toLowerCase();
54
+ if (scheme !== undefined && scheme !== 'http' && scheme !== 'https') {
55
+ return tableCell(trimmed);
56
+ }
57
+ const url = scheme === undefined ? `https://${trimmed}` : trimmed;
58
+ return url.replace(URL_UNSAFE, (char) => encodeURIComponent(char));
59
+ }
60
+ //# sourceMappingURL=inline-text.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inline-text.js","sourceRoot":"","sources":["../../src/utils/inline-text.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wFAAwF;AACxF,MAAM,WAAW,GAAG,4BAA4B,CAAC;AAEjD;;;;GAIG;AACH,MAAM,SAAS,GAAG,wCAAwC,CAAC;AAE3D,mGAAmG;AACnG,MAAM,gBAAgB,GAAG,wCAAwC,CAAC;AAElE,wFAAwF;AACxF,MAAM,mBAAmB,GAAG,0CAA0C,CAAC;AAEvE,sFAAsF;AACtF,MAAM,UAAU,GAAG,8BAA8B,CAAC;AAElD,MAAM,MAAM,GAAG,wBAAwB,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC;SACzB,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC;SACjC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,mBAAmB,EAAE,KAAK,CAAC;SACnC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC;SACzB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;IACxD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACpE,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAClE,OAAO,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC"}