@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,90 @@
1
+ /**
2
+ * @fileoverview geonames_get_children — the direct children of a GeoNames feature in the
3
+ * administrative, tourism, or dependency tree (`childrenJSON`, 1 credit, cached a day). The
4
+ * whole list is fetched once, so paging and name filtering are local. A non-empty tourism
5
+ * or dependency list is compared with the administrative one, which GeoNames returns in its
6
+ * place when the feature has no such tree (1 more credit unless cached); an empty one is
7
+ * not, since by that fallback the administrative list is empty too.
8
+ * @module mcp-server/tools/definitions/get-children.tool
9
+ */
10
+ import { z } from '@cyanheads/mcp-ts-core';
11
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
12
+ export declare const getChildrenTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
13
+ geonameId: z.ZodPreprocess<z.ZodString, unknown>;
14
+ hierarchy: z.ZodPreprocess<z.ZodPreprocess<z.ZodDefault<z.ZodEnum<{
15
+ administrative: "administrative";
16
+ dependency: "dependency";
17
+ tourism: "tourism";
18
+ }>>, unknown>, unknown>;
19
+ nameContains: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
20
+ limit: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
21
+ offset: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
22
+ geonamesUsername: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
23
+ }, z.core.$strip>, z.ZodObject<{
24
+ found: z.ZodBoolean;
25
+ parentGeonameId: z.ZodNumber;
26
+ hierarchy: z.ZodEnum<{
27
+ administrative: "administrative";
28
+ dependency: "dependency";
29
+ tourism: "tourism";
30
+ }>;
31
+ sameAsAdministrative: z.ZodOptional<z.ZodBoolean>;
32
+ guidance: z.ZodOptional<z.ZodString>;
33
+ children: z.ZodArray<z.ZodObject<{
34
+ geonameId: z.ZodNumber;
35
+ name: z.ZodString;
36
+ toponymName: z.ZodString;
37
+ featureClass: z.ZodOptional<z.ZodString>;
38
+ featureCode: z.ZodOptional<z.ZodString>;
39
+ featureName: z.ZodOptional<z.ZodString>;
40
+ countryCode: z.ZodOptional<z.ZodString>;
41
+ adminCode1: z.ZodOptional<z.ZodString>;
42
+ adminName1: z.ZodOptional<z.ZodString>;
43
+ iso3166_2: z.ZodOptional<z.ZodString>;
44
+ lat: z.ZodOptional<z.ZodNumber>;
45
+ lng: z.ZodOptional<z.ZodNumber>;
46
+ population: z.ZodOptional<z.ZodNumber>;
47
+ }, z.core.$strip>>;
48
+ nextOffset: z.ZodOptional<z.ZodNumber>;
49
+ }, z.core.$strip>, readonly [{
50
+ readonly reason: "username_required";
51
+ readonly code: JsonRpcErrorCode.Unauthorized;
52
+ readonly when: "Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account.";
53
+ 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.";
54
+ readonly severity: "notice";
55
+ readonly thrownBy: "service";
56
+ }, {
57
+ readonly reason: "caller_account_rejected";
58
+ readonly code: JsonRpcErrorCode.Unauthorized;
59
+ readonly when: "GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled).";
60
+ 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.";
61
+ readonly severity: "notice";
62
+ readonly thrownBy: "service";
63
+ }, {
64
+ readonly reason: "server_account_rejected";
65
+ readonly code: JsonRpcErrorCode.ConfigurationError;
66
+ readonly when: "GeoNames rejected the server's GEONAMES_USERNAME.";
67
+ 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.";
68
+ readonly thrownBy: "service";
69
+ }, {
70
+ readonly reason: "quota_exhausted";
71
+ readonly code: JsonRpcErrorCode.RateLimited;
72
+ 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.";
73
+ 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.";
74
+ readonly retryable: true;
75
+ readonly thrownBy: "service";
76
+ }, {
77
+ readonly reason: "upstream_rejected_parameter";
78
+ readonly code: JsonRpcErrorCode.ValidationError;
79
+ readonly when: "GeoNames rejected a value the schema let through; the message carries its text.";
80
+ readonly recovery: "Correct the value named in the message and call again; geonames_list_reference lists valid feature classes, feature codes, and postal coverage.";
81
+ readonly severity: "notice";
82
+ readonly thrownBy: "service";
83
+ }], {
84
+ readonly totalCount: z.ZodNumber;
85
+ readonly truncated: z.ZodBoolean;
86
+ readonly shown: z.ZodNumber;
87
+ readonly cap: z.ZodNumber;
88
+ readonly notice: z.ZodOptional<z.ZodString>;
89
+ }>;
90
+ //# sourceMappingURL=get-children.tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"get-children.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-children.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA6DjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwS1B,CAAC"}
@@ -0,0 +1,287 @@
1
+ /**
2
+ * @fileoverview geonames_get_children — the direct children of a GeoNames feature in the
3
+ * administrative, tourism, or dependency tree (`childrenJSON`, 1 credit, cached a day). The
4
+ * whole list is fetched once, so paging and name filtering are local. A non-empty tourism
5
+ * or dependency list is compared with the administrative one, which GeoNames returns in its
6
+ * place when the feature has no such tree (1 more credit unless cached); an empty one is
7
+ * not, since by that fallback the administrative list is empty too.
8
+ * @module mcp-server/tools/definitions/get-children.tool
9
+ */
10
+ import { tool, z } from '@cyanheads/mcp-ts-core';
11
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
12
+ import { blankAsUnset, geonameIdInput, geonamesUsernameInput, limitInput, lowerCased, nameContainsInput, nameMatcher, offsetInput, paginate, USERNAME_ALIASES, } from '../shared-inputs.js';
13
+ import { getGeoNamesService } from '../../../services/geonames/geonames-service.js';
14
+ import { inlineText, tableCell } from '../../../utils/inline-text.js';
15
+ const HIERARCHIES = [
16
+ 'administrative',
17
+ 'tourism',
18
+ 'dependency',
19
+ ];
20
+ /** The most rows `childrenJSON` is asked for per parent. */
21
+ const FETCH_CAP = 1000;
22
+ const fallbackRule = (tree) => `GeoNames answers with the administrative children when a feature has no ${tree} tree`;
23
+ /**
24
+ * True when a tree's whole fetched list is the administrative one: the same geonameIds,
25
+ * each as often, in any order, and the same upstream total.
26
+ */
27
+ function isAdministrativeList(tree, administrative) {
28
+ if (administrative?.totalCount !== tree.totalCount ||
29
+ administrative.children.length !== tree.children.length) {
30
+ return false;
31
+ }
32
+ const sortedIds = ({ children }) => children.map((child) => child.geonameId).toSorted((a, b) => a - b);
33
+ const administrativeIds = sortedIds(administrative);
34
+ return sortedIds(tree).every((id, index) => id === administrativeIds[index]);
35
+ }
36
+ /** A child row as this tool returns it: the gazetteer fields minus the country label, id, and distance. */
37
+ const toChild = ({ countryGeonameId: _countryId, countryName: _countryName, distanceInKm: _distance, featureClassName: _className, ...child }) => child;
38
+ const orNotAvailable = (value) => value === undefined ? 'Not available' : tableCell(value);
39
+ export const getChildrenTool = tool('geonames_get_children', {
40
+ title: 'List GeoNames children',
41
+ description: "List the direct children of a GeoNames feature — Earth's continents, a continent's countries, a country's first-level divisions, a state's counties, a city's sections — in the administrative tree, or in the tourism tree (islands, coasts, and their municipalities; almost all in Spain) or the dependency tree (a country's dependent territories). Start from a country's geonameId (geonames_get_countries) or any admin division's. Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L and islands class T. For other feature types inside a place, use geonames_search_places with a boundingBox. GeoNames answers a tourism or dependency request with the administrative children when the feature has no such tree, so the tool compares the two lists and sets sameAsAdministrative when they match, keeping the rows (a real tree can match too). The full child list is fetched once (1 GeoNames credit) and cached, so paging and nameContains filtering are free; a tourism or dependency call also reads the administrative list for the comparison, 1 more credit unless it is cached.",
42
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
43
+ input: z.object({
44
+ geonameId: geonameIdInput.describe('GeoNames id of the parent feature, a positive integer up to 2147483647 such as 6252001 (United States), as returned in geonameId by the other geonames tools. A geonames.org/<id> URL is reduced to its id.'),
45
+ hierarchy: blankAsUnset(lowerCased(z.enum(HIERARCHIES).default('administrative'))).describe("Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached. Case-insensitive."),
46
+ nameContains: nameContainsInput.describe('Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation.'),
47
+ limit: limitInput(500, 100),
48
+ offset: offsetInput(),
49
+ geonamesUsername: geonamesUsernameInput,
50
+ }),
51
+ inputAliases: USERNAME_ALIASES,
52
+ output: z.object({
53
+ found: z.boolean().describe('False when GeoNames has no feature with this geonameId.'),
54
+ parentGeonameId: z.number().describe('The geonameId whose children were requested.'),
55
+ hierarchy: z.enum(HIERARCHIES).describe('The tree that was descended.'),
56
+ sameAsAdministrative: z
57
+ .boolean()
58
+ .optional()
59
+ .describe('Tourism and dependency trees only, when the feature has children there: true when they are exactly its administrative children (same geonameIds and total). GeoNames answers with the administrative children when a feature has no such tree, so true most likely means it has none; a real tree can also match.'),
60
+ guidance: z.string().optional().describe('What to do next; present only when found is false.'),
61
+ children: z
62
+ .array(z
63
+ .object({
64
+ geonameId: z
65
+ .number()
66
+ .describe('GeoNames feature id of the child: pass it to geonames_get_children again to descend further, or to geonames_get_place.'),
67
+ name: z.string().describe('Name of the child, as GeoNames displays it.'),
68
+ toponymName: z
69
+ .string()
70
+ .describe("GeoNames' main name for the feature, often the local-language form."),
71
+ featureClass: z
72
+ .string()
73
+ .optional()
74
+ .describe('One-letter feature class (A admin division, P populated place, …).'),
75
+ featureCode: z
76
+ .string()
77
+ .optional()
78
+ .describe('Feature code, such as ADM1 (first-order division) or PPLX (section).'),
79
+ featureName: z.string().optional().describe("GeoNames' name for the feature code."),
80
+ countryCode: z
81
+ .string()
82
+ .optional()
83
+ .describe('ISO 3166-1 alpha-2 code of the containing country.'),
84
+ adminCode1: z
85
+ .string()
86
+ .optional()
87
+ .describe('Code of the first-order admin division containing it.'),
88
+ adminName1: z
89
+ .string()
90
+ .optional()
91
+ .describe('Name of the first-order admin division containing it.'),
92
+ iso3166_2: z
93
+ .string()
94
+ .optional()
95
+ .describe('ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO.'),
96
+ lat: z
97
+ .number()
98
+ .optional()
99
+ .describe('Latitude in decimal degrees. Absent when GeoNames sent none.'),
100
+ lng: z
101
+ .number()
102
+ .optional()
103
+ .describe('Longitude in decimal degrees. Absent when GeoNames sent none.'),
104
+ population: z
105
+ .number()
106
+ .optional()
107
+ .describe('Population. Absent when GeoNames records none.'),
108
+ })
109
+ .describe('One child feature.'))
110
+ .describe("Children on this page, in GeoNames' order; empty when found is false or the feature has none."),
111
+ nextOffset: z.number().optional().describe('Offset of the next page; absent on the last page.'),
112
+ }),
113
+ enrichment: {
114
+ totalCount: z.number().describe('Children matching nameContains, before paging.'),
115
+ truncated: z.boolean().describe('True when more children remain past this page.'),
116
+ shown: z.number().describe('Children returned on this page.'),
117
+ cap: z.number().describe('The limit that was applied.'),
118
+ notice: z
119
+ .string()
120
+ .optional()
121
+ .describe('Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain, or GeoNames holds more children than it returns.'),
122
+ },
123
+ errors: [
124
+ {
125
+ reason: 'username_required',
126
+ code: JsonRpcErrorCode.Unauthorized,
127
+ when: "Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account.",
128
+ 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.',
129
+ severity: 'notice',
130
+ thrownBy: 'service',
131
+ },
132
+ {
133
+ reason: 'caller_account_rejected',
134
+ code: JsonRpcErrorCode.Unauthorized,
135
+ when: 'GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled).',
136
+ 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.",
137
+ severity: 'notice',
138
+ thrownBy: 'service',
139
+ },
140
+ {
141
+ reason: 'server_account_rejected',
142
+ code: JsonRpcErrorCode.ConfigurationError,
143
+ when: "GeoNames rejected the server's GEONAMES_USERNAME.",
144
+ 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.',
145
+ thrownBy: 'service',
146
+ },
147
+ {
148
+ reason: 'quota_exhausted',
149
+ code: JsonRpcErrorCode.RateLimited,
150
+ when: "GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call.",
151
+ 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.",
152
+ retryable: true,
153
+ thrownBy: 'service',
154
+ },
155
+ {
156
+ reason: 'upstream_rejected_parameter',
157
+ code: JsonRpcErrorCode.ValidationError,
158
+ when: 'GeoNames rejected a value the schema let through; the message carries its text.',
159
+ recovery: 'Correct the value named in the message and call again; geonames_list_reference lists valid feature classes, feature codes, and postal coverage.',
160
+ severity: 'notice',
161
+ thrownBy: 'service',
162
+ },
163
+ ],
164
+ async handler(input, ctx) {
165
+ ctx.enrich.total(0);
166
+ ctx.enrich({ truncated: false, shown: 0, cap: input.limit });
167
+ const { hierarchy } = input;
168
+ const parentGeonameId = Number(input.geonameId);
169
+ const service = getGeoNamesService();
170
+ const account = service.resolveAccount(input.geonamesUsername);
171
+ const result = await service.children(input.geonameId, hierarchy, account, ctx);
172
+ if (result === undefined) {
173
+ return {
174
+ found: false,
175
+ parentGeonameId,
176
+ hierarchy,
177
+ guidance: `No GeoNames feature has geonameId ${input.geonameId}. Find it with geonames_search_places or geonames_get_countries.`,
178
+ children: [],
179
+ };
180
+ }
181
+ const all = result.children;
182
+ const sameAsAdministrative = hierarchy === 'administrative' || all.length === 0
183
+ ? undefined
184
+ : isAdministrativeList(result, await service.children(input.geonameId, 'administrative', account, ctx));
185
+ const matcher = input.nameContains === undefined ? undefined : nameMatcher(input.nameContains);
186
+ const matches = matcher ? all.filter((child) => matcher([child.name, child.toponymName])) : all;
187
+ const { page, nextOffset } = paginate(matches, input.offset, input.limit);
188
+ ctx.enrich.total(matches.length);
189
+ ctx.enrich({ shown: page.length });
190
+ const fragments = [];
191
+ if (sameAsAdministrative) {
192
+ fragments.push(`These are the same children as the administrative tree's. ${fallbackRule(hierarchy)}, so this feature most likely has none; a real ${hierarchy} tree can also match its administrative children.`);
193
+ }
194
+ if (all.length === 0) {
195
+ fragments.push(hierarchy === 'administrative'
196
+ ? 'This feature has no children in the administrative tree. Try hierarchy tourism or dependency, or search inside it with geonames_search_places and a boundingBox.'
197
+ : `This feature has no children in the ${hierarchy} tree, nor in the administrative tree: ${fallbackRule(hierarchy)}. Try hierarchy ${hierarchy === 'tourism' ? 'dependency' : 'tourism'}, or search inside it with geonames_search_places and a boundingBox.`);
198
+ }
199
+ else if (matches.length === 0 && input.nameContains !== undefined) {
200
+ fragments.push(`No child name contains "${inlineText(input.nameContains)}" among ${all.length}; call again without nameContains to browse them all.`);
201
+ }
202
+ else if (page.length === 0) {
203
+ fragments.push(`offset ${input.offset} is past the last child (${matches.length}); call again with a smaller offset.`);
204
+ }
205
+ if (nextOffset !== undefined) {
206
+ const remaining = matches.length - nextOffset;
207
+ ctx.enrich.truncated({ shown: page.length, cap: input.limit });
208
+ fragments.push(`${remaining} more ${remaining === 1 ? 'child' : 'children'}; call again with offset ${nextOffset}.`);
209
+ }
210
+ if (result.totalCount > all.length) {
211
+ fragments.push(`GeoNames lists ${result.totalCount.toLocaleString('en-US')} children but returns at most ${FETCH_CAP.toLocaleString('en-US')} per parent; narrow with geonames_search_places using featureCodes and a boundingBox.`);
212
+ }
213
+ if (fragments.length > 0)
214
+ ctx.enrich.notice(fragments.join(' '));
215
+ return {
216
+ found: true,
217
+ parentGeonameId,
218
+ hierarchy,
219
+ ...(sameAsAdministrative === undefined ? {} : { sameAsAdministrative }),
220
+ children: page.map(toChild),
221
+ ...(nextOffset === undefined ? {} : { nextOffset }),
222
+ };
223
+ },
224
+ format: (result) => {
225
+ const tree = result.sameAsAdministrative
226
+ ? `${result.hierarchy} tree: same as the administrative children, GeoNames' answer when a feature has no ${result.hierarchy} tree`
227
+ : `${result.hierarchy} tree`;
228
+ const lines = [
229
+ `## GeoNames children of geonameId ${result.parentGeonameId} (${tree})`,
230
+ '',
231
+ `**Found:** ${result.found}`,
232
+ ];
233
+ if (result.sameAsAdministrative !== undefined) {
234
+ lines.push('', `**Same as administrative children:** ${result.sameAsAdministrative}`);
235
+ }
236
+ if (result.guidance !== undefined)
237
+ lines.push('', inlineText(result.guidance));
238
+ if (result.found && result.children.length === 0) {
239
+ lines.push('', 'No children on this page.');
240
+ }
241
+ if (result.children.length > 0) {
242
+ lines.push('', '| geonameId | Name | Feature | Country | First-level division | Population | Lat, Lng |', '|:---|:---|:---|:---|:---|:---|:---|');
243
+ for (const child of result.children) {
244
+ const name = child.toponymName === child.name
245
+ ? tableCell(child.name)
246
+ : `${tableCell(child.name)} (toponym: ${tableCell(child.toponymName)})`;
247
+ const feature = child.featureCode === undefined && child.featureClass === undefined
248
+ ? 'Not available'
249
+ : [
250
+ child.featureCode && tableCell(child.featureCode),
251
+ child.featureName && tableCell(child.featureName),
252
+ child.featureClass && `(class ${tableCell(child.featureClass)})`,
253
+ ]
254
+ .filter(Boolean)
255
+ .join(' ');
256
+ const admin1 = child.adminName1 === undefined &&
257
+ child.adminCode1 === undefined &&
258
+ child.iso3166_2 === undefined
259
+ ? 'Not available'
260
+ : [
261
+ child.adminName1 && tableCell(child.adminName1),
262
+ child.adminCode1 && `(code ${tableCell(child.adminCode1)})`,
263
+ child.iso3166_2 && `ISO ${tableCell(child.iso3166_2)}`,
264
+ ]
265
+ .filter(Boolean)
266
+ .join(' ');
267
+ lines.push(`| ${[
268
+ child.geonameId,
269
+ name,
270
+ feature,
271
+ orNotAvailable(child.countryCode),
272
+ admin1,
273
+ child.population === undefined
274
+ ? 'Not available'
275
+ : child.population.toLocaleString('en-US'),
276
+ child.lat === undefined || child.lng === undefined
277
+ ? 'Not available'
278
+ : `${child.lat}, ${child.lng}`,
279
+ ].join(' | ')} |`);
280
+ }
281
+ }
282
+ if (result.nextOffset !== undefined)
283
+ lines.push('', `Next page: offset ${result.nextOffset}.`);
284
+ return [{ type: 'text', text: lines.join('\n') }];
285
+ },
286
+ });
287
+ //# sourceMappingURL=get-children.tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"get-children.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-children.tool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,90 @@
1
+ /**
2
+ * @fileoverview geonames_get_countries — GeoNames country facts. The full country table
3
+ * is fetched once a day (1 credit) and cached; codes, continent, and name filter it
4
+ * locally.
5
+ * @module mcp-server/tools/definitions/get-countries.tool
6
+ */
7
+ import { z } from '@cyanheads/mcp-ts-core';
8
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
9
+ export declare const getCountriesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
10
+ countries: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodString>>, unknown>;
11
+ continent: z.ZodPreprocess<z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
12
+ AF: "AF";
13
+ AN: "AN";
14
+ AS: "AS";
15
+ EU: "EU";
16
+ NA: "NA";
17
+ OC: "OC";
18
+ SA: "SA";
19
+ }>>, unknown>, unknown>;
20
+ nameContains: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
21
+ limit: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
22
+ offset: z.ZodPreprocess<z.ZodDefault<z.ZodNumber>, unknown>;
23
+ geonamesUsername: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
24
+ }, z.core.$strip>, z.ZodObject<{
25
+ countries: z.ZodArray<z.ZodObject<{
26
+ countryCode: z.ZodString;
27
+ isoAlpha3: z.ZodString;
28
+ isoNumeric: z.ZodOptional<z.ZodString>;
29
+ fipsCode: z.ZodOptional<z.ZodString>;
30
+ countryName: z.ZodString;
31
+ geonameId: z.ZodNumber;
32
+ capital: z.ZodOptional<z.ZodString>;
33
+ continentCode: z.ZodString;
34
+ continentName: z.ZodString;
35
+ population: z.ZodOptional<z.ZodNumber>;
36
+ areaInSqKm: z.ZodOptional<z.ZodNumber>;
37
+ languages: z.ZodArray<z.ZodString>;
38
+ currencyCode: z.ZodOptional<z.ZodString>;
39
+ postalCodeFormat: z.ZodOptional<z.ZodString>;
40
+ boundingBox: z.ZodObject<{
41
+ north: z.ZodNumber;
42
+ south: z.ZodNumber;
43
+ east: z.ZodNumber;
44
+ west: z.ZodNumber;
45
+ }, z.core.$strip>;
46
+ }, z.core.$strip>>;
47
+ notFound: z.ZodArray<z.ZodString>;
48
+ nextOffset: z.ZodOptional<z.ZodNumber>;
49
+ }, z.core.$strip>, readonly [{
50
+ readonly reason: "username_required";
51
+ readonly code: JsonRpcErrorCode.Unauthorized;
52
+ readonly when: "Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account.";
53
+ 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.";
54
+ readonly severity: "notice";
55
+ readonly thrownBy: "service";
56
+ }, {
57
+ readonly reason: "caller_account_rejected";
58
+ readonly code: JsonRpcErrorCode.Unauthorized;
59
+ readonly when: "GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled).";
60
+ 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.";
61
+ readonly severity: "notice";
62
+ readonly thrownBy: "service";
63
+ }, {
64
+ readonly reason: "server_account_rejected";
65
+ readonly code: JsonRpcErrorCode.ConfigurationError;
66
+ readonly when: "GeoNames rejected the server's GEONAMES_USERNAME.";
67
+ 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.";
68
+ readonly thrownBy: "service";
69
+ }, {
70
+ readonly reason: "quota_exhausted";
71
+ readonly code: JsonRpcErrorCode.RateLimited;
72
+ 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.";
73
+ 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.";
74
+ readonly retryable: true;
75
+ readonly thrownBy: "service";
76
+ }, {
77
+ readonly reason: "upstream_rejected_parameter";
78
+ readonly code: JsonRpcErrorCode.ValidationError;
79
+ readonly when: "GeoNames rejected a value the schema let through; the message carries its text.";
80
+ readonly recovery: "Correct the value named in the message and call again; geonames_list_reference lists valid feature classes, feature codes, and postal coverage.";
81
+ readonly severity: "notice";
82
+ readonly thrownBy: "service";
83
+ }], {
84
+ readonly totalCount: z.ZodNumber;
85
+ readonly truncated: z.ZodBoolean;
86
+ readonly shown: z.ZodNumber;
87
+ readonly cap: z.ZodNumber;
88
+ readonly notice: z.ZodOptional<z.ZodString>;
89
+ }>;
90
+ //# sourceMappingURL=get-countries.tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"get-countries.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-countries.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA4BjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+O3B,CAAC"}