@cyanheads/geonames-mcp-server 0.1.2 → 0.2.0

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 (69) hide show
  1. package/AGENTS.md +31 -17
  2. package/CLAUDE.md +31 -17
  3. package/Dockerfile +22 -7
  4. package/README.md +66 -122
  5. package/changelog/0.1.x/0.1.3.md +46 -0
  6. package/changelog/0.2.x/0.2.0.md +37 -0
  7. package/dist/index.js +2 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts +8 -5
  10. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -1
  11. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +84 -42
  12. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -1
  13. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +6 -0
  14. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -1
  15. package/dist/mcp-server/tools/definitions/get-children.tool.js +35 -18
  16. package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +6 -0
  18. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/get-countries.tool.js +32 -14
  20. package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js +3 -3
  22. package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +3 -1
  24. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/get-place.tool.js +35 -11
  26. package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/index.d.ts +37 -5
  28. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +6 -0
  30. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.js +34 -14
  32. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +85 -28
  35. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +12 -2
  37. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/search-places.tool.js +107 -26
  39. package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/shared-inputs.d.ts +62 -20
  41. package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/shared-inputs.js +94 -29
  43. package/dist/mcp-server/tools/shared-inputs.js.map +1 -1
  44. package/dist/services/geonames/country-codes.d.ts +7 -1
  45. package/dist/services/geonames/country-codes.d.ts.map +1 -1
  46. package/dist/services/geonames/country-codes.js +15 -1
  47. package/dist/services/geonames/country-codes.js.map +1 -1
  48. package/dist/services/geonames/geonames-service.d.ts +7 -3
  49. package/dist/services/geonames/geonames-service.d.ts.map +1 -1
  50. package/dist/services/geonames/geonames-service.js +85 -35
  51. package/dist/services/geonames/geonames-service.js.map +1 -1
  52. package/dist/services/geonames/response-parsers.d.ts +9 -5
  53. package/dist/services/geonames/response-parsers.d.ts.map +1 -1
  54. package/dist/services/geonames/response-parsers.js +102 -22
  55. package/dist/services/geonames/response-parsers.js.map +1 -1
  56. package/dist/services/geonames/types.d.ts +30 -13
  57. package/dist/services/geonames/types.d.ts.map +1 -1
  58. package/dist/services/geonames/types.js +4 -3
  59. package/dist/services/geonames/types.js.map +1 -1
  60. package/dist/services/geonames/upstream-errors.d.ts.map +1 -1
  61. package/dist/services/geonames/upstream-errors.js +7 -7
  62. package/dist/services/geonames/upstream-errors.js.map +1 -1
  63. package/dist/utils/inline-text.d.ts +57 -12
  64. package/dist/utils/inline-text.d.ts.map +1 -1
  65. package/dist/utils/inline-text.js +137 -20
  66. package/dist/utils/inline-text.js.map +1 -1
  67. package/package.json +15 -13
  68. package/server.json +10 -24
  69. package/skills/geonames-guide/SKILL.md +64 -0
@@ -1 +1 @@
1
- {"version":3,"file":"upstream-errors.js","sourceRoot":"","sources":["../../../src/services/geonames/upstream-errors.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"upstream-errors.js","sourceRoot":"","sources":["../../../src/services/geonames/upstream-errors.ts"],"names":[],"mappings":"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"}
@@ -1,25 +1,70 @@
1
1
  /**
2
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.
3
+ * GeoNames names, labels, and status text are community-edited, so `format()` and each
4
+ * `enrichmentTrailer` render print them, and the caller text echoed beside them, only
5
+ * through these helpers. Two mechanisms keep that text from opening a link, HTML tag,
6
+ * emphasis, code span, strikethrough, or character reference, or a block where it opens a
7
+ * line: a backslash before the markdown punctuation that would start one, and `<` and
8
+ * `&gt;` for `<` and `>`. Both round-trip, so a CommonMark parse of the rendered slot reads
9
+ * back the text as written; a bare URL prints as written too. The framework trailer prints
10
+ * enrichment verbatim, so a notice or `effectiveQuery` reaches `structuredContent` raw and
11
+ * is escaped only by its render. An error message carries no markdown escapes, because the
12
+ * framework escapes the `content[]` `Error:` line itself: the GeoNames text an
13
+ * `upstream_rejected_parameter` message forwards goes through {@link singleLineText} alone.
14
+ * Every other string reaches `structuredContent` as received, less the Unicode tag
15
+ * characters the service drops when it decodes a response.
16
+ *
17
+ * A slot takes its helper by where the text stands in its line:
18
+ * - after server-written text on the same line (a bold label's value, a value inside a
19
+ * composed sentence): {@link inlineText}; a markdown table cell: {@link tableCell};
20
+ * - at the start of a line's content (a heading, a list item, a block-quote line, a
21
+ * line of its own): {@link blockStartText};
22
+ * - a URL, in either position: {@link plainUrl}.
7
23
  * @module utils/inline-text
8
24
  */
9
25
  /**
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.
26
+ * Text on one line with nothing invisible in it: line breaks become spaces, and control and
27
+ * format characters are dropped (ZWNJ and ZWJ stay). No markdown escapes, so the result is
28
+ * the text as written wherever the reader escapes it, as the framework does for an error
29
+ * message's `content[]` line.
30
+ */
31
+ export declare function singleLineText(value: string): string;
32
+ /**
33
+ * Renders text for a slot inside a line, after server-written text: a bold label's value
34
+ * (`**Toponym name:** …`, and the `**effectiveQuery:** …` an `enrichmentTrailer` render
35
+ * writes) or a value inside a composed sentence. {@link singleLineText}, then backslash is
36
+ * escaped, then a character reference's `&`, `[` `]`, `*`, `` ` ``, `~`, and every `_` not
37
+ * between two letters, digits, or marks, and `<` / `>` become entities. A bare URL prints
38
+ * as written; `[label](url)` and `<url>` stay literal text. A block opens only at the start
39
+ * of a line, so `#`, `+`, `-`, ordinals, and spaces print as written (`#####`,
40
+ * `4. Wiener Gemeindebezirk`).
15
41
  */
16
42
  export declare function inlineText(value: string): string;
17
- /** {@link inlineText} plus `|` escaped, for a markdown table cell. */
43
+ /**
44
+ * {@link inlineText} for text that opens a line's content: a heading (`## …`), a list
45
+ * item (`- …`), a block-quote line (`> …`, the slot a notice's `enrichmentTrailer`
46
+ * render writes), or a line of its own. On top of the inline rules it drops the leading
47
+ * spaces, escapes a leading block marker (a `#` heading run, a `+` or `-` bullet, a line
48
+ * of dashes, or the `.` / `)` of a one-to-nine-digit ordinal), and escapes a closing `#`
49
+ * run, which a heading drops. `Route 4. North`, `4.5 Mile Creek`, and `#5 Mine` open no
50
+ * block and print as written.
51
+ */
52
+ export declare function blockStartText(value: string): string;
53
+ /**
54
+ * The `enrichmentTrailer` render for a `notice`: a block-quote line. The framework trailer
55
+ * prints values verbatim and `structuredContent` keeps the text as sent, so a notice that
56
+ * carries caller or GeoNames text is escaped here.
57
+ */
58
+ export declare const renderNotice: (value: unknown) => string;
59
+ /** {@link inlineText} plus `|` escaped, for a markdown table cell, whose content is inline. */
18
60
  export declare function tableCell(value: string): string;
19
61
  /**
20
62
  * 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.
63
+ * (GeoNames' `wikipediaURL`) gets `https://`; an `http`/`https` URL prints with unsafe
64
+ * characters, `*`, `~`, and underscores that could pair into emphasis percent-encoded, so
65
+ * it renders as written and still names the same resource; any other scheme prints as
66
+ * escaped text. The result starts with a scheme's first letter, so it takes no
67
+ * line-start escape at the start of a list item.
23
68
  */
24
69
  export declare function plainUrl(value: string): string;
25
70
  //# sourceMappingURL=inline-text.d.ts.map
@@ -1 +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"}
1
+ {"version":3,"file":"inline-text.d.ts","sourceRoot":"","sources":["../../src/utils/inline-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAsGH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAA8C,CAAC;AAE7F,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY9C"}
@@ -1,9 +1,25 @@
1
1
  /**
2
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.
3
+ * GeoNames names, labels, and status text are community-edited, so `format()` and each
4
+ * `enrichmentTrailer` render print them, and the caller text echoed beside them, only
5
+ * through these helpers. Two mechanisms keep that text from opening a link, HTML tag,
6
+ * emphasis, code span, strikethrough, or character reference, or a block where it opens a
7
+ * line: a backslash before the markdown punctuation that would start one, and `&lt;` and
8
+ * `&gt;` for `<` and `>`. Both round-trip, so a CommonMark parse of the rendered slot reads
9
+ * back the text as written; a bare URL prints as written too. The framework trailer prints
10
+ * enrichment verbatim, so a notice or `effectiveQuery` reaches `structuredContent` raw and
11
+ * is escaped only by its render. An error message carries no markdown escapes, because the
12
+ * framework escapes the `content[]` `Error:` line itself: the GeoNames text an
13
+ * `upstream_rejected_parameter` message forwards goes through {@link singleLineText} alone.
14
+ * Every other string reaches `structuredContent` as received, less the Unicode tag
15
+ * characters the service drops when it decodes a response.
16
+ *
17
+ * A slot takes its helper by where the text stands in its line:
18
+ * - after server-written text on the same line (a bold label's value, a value inside a
19
+ * composed sentence): {@link inlineText}; a markdown table cell: {@link tableCell};
20
+ * - at the start of a line's content (a heading, a list item, a block-quote line, a
21
+ * line of its own): {@link blockStartText};
22
+ * - a URL, in either position: {@link plainUrl}.
7
23
  * @module utils/inline-text
8
24
  */
9
25
  /** CR, LF, tab, and the Unicode line and paragraph separators: flattened to a space. */
@@ -14,39 +30,138 @@ const LINE_BREAKS = /[\r\n\t\u{2028}\u{2029}]/gu;
14
30
  * names need to spell correctly.
15
31
  */
16
32
  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
33
  /** An `&` that opens a named or numeric character reference, which renderers decode. */
20
34
  const CHARACTER_REFERENCE = /&(?=#\d+;|#x[\da-f]+;|[a-z][a-z\d]*;)/giu;
21
35
  /** Characters a plain-text URL percent-encodes so it cannot break out of its slot. */
22
36
  const URL_UNSAFE = /[\s\p{Cc}\p{Cf}<>[\]\\|`"]/gu;
37
+ /** `*` and `~`, which emphasis and strikethrough read even inside a bare URL. */
38
+ const URL_DELIMITERS = /[*~]/g;
23
39
  const SCHEME = /^([a-z][a-z0-9+.-]*):/i;
40
+ /** Link brackets and the emphasis, code-span, and strikethrough delimiters, escaped wherever they stand. */
41
+ const DELIMITERS = /[[\]*`~]/g;
42
+ /** A letter, digit, or combining mark. */
43
+ const WORD_CHAR = /[\p{L}\p{N}\p{M}]/u;
44
+ /** CommonMark punctuation: the Unicode P and S categories. */
45
+ const PUNCTUATION = /[\p{P}\p{S}]/u;
46
+ /** CommonMark whitespace, where the edge of the text (`''`) counts as whitespace. */
47
+ const isSpace = (char) => char === '' || /\s/u.test(char);
48
+ const isPunctuation = (char) => PUNCTUATION.test(char);
49
+ /** Spaces at the start: four or more open an indented code block, and fewer never render. */
50
+ const LEADING_SPACES = /^ +/;
24
51
  /**
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.
52
+ * At the start: an ATX heading `#` run, a `+` or `-` bullet or empty item marker, or a
53
+ * line of dashes (a thematic break or setext underline).
54
+ */
55
+ const LEADING_MARKER = /^(?=(?:#{1,6}|[+-])(?: |$)|-[- ]*$)/;
56
+ /** At the start: an ordered-list marker, one to nine digits then `.` or `)`. */
57
+ const LEADING_ORDINAL = /^(\d{1,9})([.)])(?= |$)/;
58
+ /** A run of `#` at the end, alone or after a space, which an ATX heading drops as its closing sequence. */
59
+ const CLOSING_HASHES = /(?<=^| )#+(?= *$)/;
60
+ /**
61
+ * The code points just before `start` and at `end`, each taken whole, so a letter
62
+ * outside the BMP counts as one (V8 misses a trailing astral code point under `[…]$`).
63
+ * The edge of the text reads as `''`.
64
+ */
65
+ function neighbors(text, start, end) {
66
+ return [
67
+ [...text.slice(Math.max(0, start - 2), start)].at(-1) ?? '',
68
+ [...text.slice(end, end + 2)][0] ?? '',
69
+ ];
70
+ }
71
+ /**
72
+ * Escapes a run of underscores unless it stands between two letters, digits, or marks,
73
+ * where CommonMark never reads it as emphasis (`W14_01`, `America/Los_Angeles`).
74
+ */
75
+ function escapeUnderscoreRun(run, offset, text) {
76
+ const [before, after] = neighbors(text, offset, offset + run.length);
77
+ return WORD_CHAR.test(before) && WORD_CHAR.test(after) ? run : run.replaceAll('_', '\\_');
78
+ }
79
+ /** Whether an underscore run between `before` and `after` can open or close emphasis, by CommonMark's flanking rules. */
80
+ function underscoreFlanking(before, after) {
81
+ const left = !isSpace(after) && (!isPunctuation(after) || isSpace(before) || isPunctuation(before));
82
+ const right = !isSpace(before) && (!isPunctuation(before) || isSpace(after) || isPunctuation(after));
83
+ return {
84
+ opens: left && (!right || isPunctuation(before)),
85
+ closes: right && (!left || isPunctuation(after)),
86
+ };
87
+ }
88
+ /**
89
+ * Percent-encodes a URL's underscore runs when one can open emphasis and a later one can
90
+ * close it, the only way they render as emphasis; otherwise every underscore stays
91
+ * (`Springfield,_Illinois`, `Paris_(Texas)`). `%5F` names the same resource as `_`.
92
+ */
93
+ function encodeEmphasisUnderscores(url) {
94
+ const runs = [...url.matchAll(/_+/g)].map(({ 0: run, index }) => underscoreFlanking(...neighbors(url, index, index + run.length)));
95
+ const opener = runs.findIndex(({ opens }) => opens);
96
+ if (opener === -1 || !runs.slice(opener + 1).some(({ closes }) => closes))
97
+ return url;
98
+ let next = 0;
99
+ return url.replace(/_+/g, (run) => {
100
+ const flanking = runs[next++];
101
+ return flanking?.opens || flanking?.closes ? '%5F'.repeat(run.length) : run;
102
+ });
103
+ }
104
+ /**
105
+ * Text on one line with nothing invisible in it: line breaks become spaces, and control and
106
+ * format characters are dropped (ZWNJ and ZWJ stay). No markdown escapes, so the result is
107
+ * the text as written wherever the reader escapes it, as the framework does for an error
108
+ * message's `content[]` line.
109
+ */
110
+ export function singleLineText(value) {
111
+ return value.replace(LINE_BREAKS, ' ').replace(INVISIBLE, '');
112
+ }
113
+ /**
114
+ * Renders text for a slot inside a line, after server-written text: a bold label's value
115
+ * (`**Toponym name:** …`, and the `**effectiveQuery:** …` an `enrichmentTrailer` render
116
+ * writes) or a value inside a composed sentence. {@link singleLineText}, then backslash is
117
+ * escaped, then a character reference's `&`, `[` `]`, `*`, `` ` ``, `~`, and every `_` not
118
+ * between two letters, digits, or marks, and `<` / `>` become entities. A bare URL prints
119
+ * as written; `[label](url)` and `<url>` stay literal text. A block opens only at the start
120
+ * of a line, so `#`, `+`, `-`, ordinals, and spaces print as written (`#####`,
121
+ * `4. Wiener Gemeindebezirk`).
30
122
  */
31
123
  export function inlineText(value) {
32
- return value
33
- .replace(LINE_BREAKS, ' ')
34
- .replace(INVISIBLE, '')
35
- .replace(AUTOLINK_TRIGGER, '[$&]')
124
+ return singleLineText(value)
36
125
  .replace(/\\/g, '\\\\')
37
126
  .replace(CHARACTER_REFERENCE, '\\&')
38
- .replace(/[[\]]/g, '\\$&')
127
+ .replace(DELIMITERS, '\\$&')
128
+ .replace(/_+/g, escapeUnderscoreRun)
39
129
  .replace(/</g, '&lt;')
40
130
  .replace(/>/g, '&gt;');
41
131
  }
42
- /** {@link inlineText} plus `|` escaped, for a markdown table cell. */
132
+ /**
133
+ * {@link inlineText} for text that opens a line's content: a heading (`## …`), a list
134
+ * item (`- …`), a block-quote line (`> …`, the slot a notice's `enrichmentTrailer`
135
+ * render writes), or a line of its own. On top of the inline rules it drops the leading
136
+ * spaces, escapes a leading block marker (a `#` heading run, a `+` or `-` bullet, a line
137
+ * of dashes, or the `.` / `)` of a one-to-nine-digit ordinal), and escapes a closing `#`
138
+ * run, which a heading drops. `Route 4. North`, `4.5 Mile Creek`, and `#5 Mine` open no
139
+ * block and print as written.
140
+ */
141
+ export function blockStartText(value) {
142
+ return inlineText(value)
143
+ .replace(LEADING_SPACES, '')
144
+ .replace(LEADING_MARKER, '\\')
145
+ .replace(LEADING_ORDINAL, '$1\\$2')
146
+ .replace(CLOSING_HASHES, '\\$&');
147
+ }
148
+ /**
149
+ * The `enrichmentTrailer` render for a `notice`: a block-quote line. The framework trailer
150
+ * prints values verbatim and `structuredContent` keeps the text as sent, so a notice that
151
+ * carries caller or GeoNames text is escaped here.
152
+ */
153
+ export const renderNotice = (value) => `> ${blockStartText(String(value))}`;
154
+ /** {@link inlineText} plus `|` escaped, for a markdown table cell, whose content is inline. */
43
155
  export function tableCell(value) {
44
156
  return inlineText(value).replace(/\|/g, '\\|');
45
157
  }
46
158
  /**
47
159
  * 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.
160
+ * (GeoNames' `wikipediaURL`) gets `https://`; an `http`/`https` URL prints with unsafe
161
+ * characters, `*`, `~`, and underscores that could pair into emphasis percent-encoded, so
162
+ * it renders as written and still names the same resource; any other scheme prints as
163
+ * escaped text. The result starts with a scheme's first letter, so it takes no
164
+ * line-start escape at the start of a list item.
50
165
  */
51
166
  export function plainUrl(value) {
52
167
  const trimmed = value.trim();
@@ -55,6 +170,8 @@ export function plainUrl(value) {
55
170
  return tableCell(trimmed);
56
171
  }
57
172
  const url = scheme === undefined ? `https://${trimmed}` : trimmed;
58
- return url.replace(URL_UNSAFE, (char) => encodeURIComponent(char));
173
+ return encodeEmphasisUnderscores(url
174
+ .replace(URL_UNSAFE, (char) => encodeURIComponent(char))
175
+ .replace(URL_DELIMITERS, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`));
59
176
  }
60
177
  //# sourceMappingURL=inline-text.js.map
@@ -1 +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"}
1
+ {"version":3,"file":"inline-text.js","sourceRoot":"","sources":["../../src/utils/inline-text.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/geonames-mcp-server",
3
- "version": "0.1.2",
3
+ "version": "0.2.0",
4
4
  "mcpName": "io.github.cyanheads/geonames-mcp-server",
5
5
  "description": "Search GeoNames places, walk admin hierarchies, reverse geocode, get postal codes and country info via MCP. STDIO or Streamable HTTP.",
6
6
  "type": "module",
@@ -18,7 +18,8 @@
18
18
  "CLAUDE.md",
19
19
  "AGENTS.md",
20
20
  "Dockerfile",
21
- "server.json"
21
+ "server.json",
22
+ "skills/"
22
23
  ],
23
24
  "scripts": {
24
25
  "build": "bun run scripts/build.ts",
@@ -70,7 +71,7 @@
70
71
  "url": "https://github.com/cyanheads/geonames-mcp-server/issues"
71
72
  },
72
73
  "license": "Apache-2.0",
73
- "packageManager": "bun@1.4.2",
74
+ "packageManager": "bun@1.4.4",
74
75
  "engines": {
75
76
  "bun": ">=1.4.0",
76
77
  "node": ">=24.0.0"
@@ -79,22 +80,23 @@
79
80
  "access": "public"
80
81
  },
81
82
  "dependencies": {
82
- "@cyanheads/mcp-ts-core": "^0.13.10",
83
- "pino-pretty": "^13.1.3",
84
- "zod": "^4.6.5"
83
+ "@cyanheads/mcp-ts-core": "^0.13.18",
84
+ "pino-pretty": "^13.2.0",
85
+ "zod": "^4.6.7"
85
86
  },
86
87
  "devDependencies": {
87
- "@biomejs/biome": "2.5.14",
88
- "@modelcontextprotocol/server": "^2.2.0",
88
+ "@biomejs/biome": "2.6.3",
89
+ "@modelcontextprotocol/server": "^2.4.0",
89
90
  "@socketsecurity/bun-security-scanner": "^1.1.3",
90
- "@types/node": "26.6.3",
91
- "@vitest/coverage-istanbul": "5.0.2",
91
+ "@types/node": "26.6.5",
92
+ "@vitest/coverage-istanbul": "5.0.5",
92
93
  "depcheck": "^1.4.7",
93
94
  "fast-check": "^4.10.2",
94
- "ignore": "^7.0.10",
95
- "tsc-alias": "^1.9.5",
95
+ "ignore": "^7.0.14",
96
+ "markdown-it": "15.0.3",
97
+ "tsc-alias": "^1.9.9",
96
98
  "typescript": "^7.0.2",
97
- "vitest": "^5.0.2"
99
+ "vitest": "^5.0.5"
98
100
  },
99
101
  "author": "Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)",
100
102
  "funding": [
package/server.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "url": "https://github.com/cyanheads/geonames-mcp-server",
8
8
  "source": "github"
9
9
  },
10
- "version": "0.1.2",
10
+ "version": "0.2.0",
11
11
  "remotes": [
12
12
  {
13
13
  "type": "streamable-http",
@@ -19,18 +19,8 @@
19
19
  "registryType": "npm",
20
20
  "registryBaseUrl": "https://registry.npmjs.org",
21
21
  "identifier": "@cyanheads/geonames-mcp-server",
22
- "runtimeHint": "node",
23
- "version": "0.1.2",
24
- "packageArguments": [
25
- {
26
- "type": "positional",
27
- "value": "run"
28
- },
29
- {
30
- "type": "positional",
31
- "value": "start:stdio"
32
- }
33
- ],
22
+ "runtimeHint": "npx",
23
+ "version": "0.2.0",
34
24
  "environmentVariables": [
35
25
  {
36
26
  "name": "GEONAMES_USERNAME",
@@ -55,19 +45,15 @@
55
45
  "registryType": "npm",
56
46
  "registryBaseUrl": "https://registry.npmjs.org",
57
47
  "identifier": "@cyanheads/geonames-mcp-server",
58
- "runtimeHint": "node",
59
- "version": "0.1.2",
60
- "packageArguments": [
48
+ "runtimeHint": "npx",
49
+ "version": "0.2.0",
50
+ "environmentVariables": [
61
51
  {
62
- "type": "positional",
63
- "value": "run"
52
+ "name": "MCP_TRANSPORT_TYPE",
53
+ "description": "Selects the HTTP transport.",
54
+ "format": "string",
55
+ "value": "http"
64
56
  },
65
- {
66
- "type": "positional",
67
- "value": "start:http"
68
- }
69
- ],
70
- "environmentVariables": [
71
57
  {
72
58
  "name": "GEONAMES_USERNAME",
73
59
  "description": "GeoNames account used when a call passes no geonamesUsername. Free accounts must enable free web services on their geonames.org account page.",
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: geonames-guide
3
+ description: Gates and identifier crossings for the geonames_* gazetteer tools. Covers moving from a postal code to gazetteer admin codes and geonameIds, a town's complete postal-code list, a city that exists as two features with two populations, ranking or summing places by population, searching inside a state or county, microstates, nearest-place lists that stop at a cap, and the timezone at a coordinate. Use before counting, ranking, or chaining geonames_* results.
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: cyanheads
7
+ version: "1.0"
8
+ ---
9
+
10
+ ## Scope
11
+
12
+ GeoNames holds named features as points, with a bounding box where one is recorded, plus their admin tree, a postal database, and country facts. It does not cover:
13
+
14
+ - **Street addresses.** No tool takes an address or a house number. Geocode the address elsewhere, such as an OpenStreetMap server, and bring the coordinate to `geonames_reverse_geocode`.
15
+ - **Boundaries.** A bounding box is not the outline (Gate 5). Only `geonames_reverse_geocode` says which divisions contain a point.
16
+ - **Distances between two places.** `distanceInKm` is measured only from a query point: on nearby rows, and on a country `geonames_reverse_geocode` matched within `coastalBufferKm`. For any other pair, compute the distance from the two `lat`/`lng` values.
17
+ - **Official statistics.** `population` is GeoNames' community-edited figure, and one city can carry two figures (Gate 2). Cite it as GeoNames, not as a census.
18
+
19
+ Where `geonames_get_place` lists a `wkdt` identifier, it is the Wikidata QID for a Wikidata server. Not every record has one: Seattle (5809844) lists only `iata` and `unlc`.
20
+
21
+ ## Identifiers
22
+
23
+ - **Postal rows carry no geonameId, and their admin codes can differ from search admin codes.** They come from the postal dataset. In one probe, Munich's 80331 had `adminCode1` BY, while the gazetteer codes Bavaria `02`; its `adminCode2` 091 and `adminCode3` 09162 happened to match. `geonames_search_places` with `countries` DE and `adminCode1` BY matched nothing. The postal BY equals the gazetteer's level-1 `isoCode`, not its `code`.
24
+ - **To cross from a postal row into the gazetteer, reverse-geocode its centroid.** Call `geonames_reverse_geocode` at the row's `lat`/`lng` with `nearbyLimit` 0. 80331's centroid returned 02 Bavaria, 091 Upper Bavaria, and 09162 Munich Urban District down to level 5, each with a geonameId and a code that search accepts. Never pass a postal row's admin code to search.
25
+
26
+ ## Gates
27
+
28
+ 1. **Get a town's postal codes from the postal database, with the admin name in the query.** Mode `place_name` matches its text against place, admin, and country names, and it has no admin filter.
29
+ - `Springfield` in US filled a 100-row page with rows from dozens of states, including East Springfield, West Springfield, and places with other names, and more pages remained.
30
+ - `Springfield Illinois` returned only rows for Springfield, IL.
31
+
32
+ Read to the last page (no `nextOffset`) before calling a list complete. A place record's `postalCodes` is a separate list that GeoNames links to the feature, and it can be shorter. In one probe, Springfield, IL (4250542) linked every code the postal database returned except 62711 and 62712. Never report that list as the complete set.
33
+
34
+ 2. **Say which feature's population you report.** Many cities are two features, each with its own geonameId and population. Seattle is the populated place 5809844 (PPLA2) and the admin division "City of Seattle" 7174408 (ADM3), and in one probe they carried 780,995 and 608,660. Nearest-place rows and a class P search return the populated place. Containment (`adminLevels`) returns the division, and Seattle's populated-place record lists that division at level 3. Name the geonameId and feature code beside any population you report.
35
+
36
+ 3. **Filter feature codes before you rank, sum, or count settlements.** Class P mixes a city with features whose populations overlap it, and with places that no longer exist:
37
+ - **Sections.** `Paris` in FR, class P, returned Paris (PPLC) beside its arrondissements, which were filed as PPL with their own populations, and beside PPLX sections.
38
+ - **Groups.** In Washington, ranked by population, Tri-Cities (PPLS) came second. It is a group of three cities that each appear as their own rows.
39
+ - **Former places.** PPLH (historical), PPLQ (abandoned), and PPLW (destroyed) are class P too.
40
+
41
+ Drop PPLX, PPLS, PPLH, PPLQ, and PPLW rows, and look for a city's subdivisions filed as PPL, before you add or rank populations. Without a class filter, other classes rank too. `Springfield, IL` returned the Springfield, IL Metro Area (RGNE), with a larger population than the city (PPLA), beside the airport, the township (ADM3), and a park. Set `featureClasses` P (or exact `featureCodes`) before `orderBy` population.
42
+
43
+ 4. **No population threshold exists above 15,000.** The `cities` tiers stop at 15,000. For "places over 100,000", sort with `orderBy` population and stop paging at the first row below the threshold.
44
+
45
+ 5. **Search inside a division with admin codes, not its box.** A bounding box is the rectangle around a division, so it takes in the neighbours. In one probe, the box from Texas's own record (4736286) matched about a third more airports than `countries` US with `adminCode1` TX. Its first page held airports in New Mexico, Arkansas, Oklahoma, Louisiana, and Mexico. For a country, use `countries`: the `geonames_get_countries` box is a rectangle too, and for Russia, Fiji, Kiribati, and New Zealand it crosses the 180° meridian, which search rejects. Use a box only where no admin code fits, such as around a point, or where the admin-code search returns only the division itself: City of Algona, WA (ADM3 `7172907`) matched just itself by `adminCode3`, while its box held the town (PPL), a school, and a church.
46
+
47
+ 6. **Check for a microstate or enclave before naming the country.** Containment polygons do not always carve them out. A point inside Vatican City returned Italy, Lazio, and Rome, down to Trionfale. Its nearest populated place, 0.09 km away, was Vatican City (PPLC, `countryCode` VA). When the nearest place a few hundred metres away carries another `countryCode`, report both rather than the containing country alone.
48
+
49
+ 7. **Take the timezone at a coordinate from `geonames_reverse_geocode`.** Set `includeTimezone`, with `nearbyLimit` 0 if you need nothing else. The timezone on a `geonames_get_place` record is the zone GeoNames associates with that feature, not one verified at its coordinates. On a feature with no country it can be far off. South Pacific Ocean (4030483, at −45, −130) carries Pacific/Tongatapu (+13), but `geonames_reverse_geocode` at those same coordinates finds no IANA zone and offsets of −9.
50
+
51
+ 8. **Nearest-place lists cannot be continued in distance order.** `geonames_reverse_geocode` lists at most the nearest 50 and does not page. Mode `nearby` of `geonames_find_postal_codes` lists at most 100 and takes no `offset`. Search orders only by relevance or population. In a dense city the cap covers little ground: in one probe, the nearest 8 places to downtown Seattle all lay within 1.2 km. To list every place or feature within a radius:
52
+ 1. Run the `geonames_search_places` call that the full-page notice of `geonames_reverse_geocode` prints; its box encloses the circle.
53
+ 2. Page to the end. The search reaches its first 5,100 rows, so split the box when `totalCount` runs past that.
54
+ 3. Compute each row's distance from its `lat`/`lng`, and keep the rows inside the radius. Drop sections by `featureCode` only before you rank or sum populations (Gate 3).
55
+
56
+ Postal codes have no such route: `geonames_find_postal_codes` takes no box, and a call from another point returns that point's nearest 100.
57
+
58
+ ## Workflows
59
+
60
+ **Every county or province of a state, with population.** Get the state's geonameId with `geonames_search_places`, using `featureCodes` ADM1 and `countries`. Then call `geonames_get_children` with `limit` 500. In one probe, one call returned all 254 Texas counties (ADM2), each with a population.
61
+
62
+ **What a point is in, and its local time.** Call `geonames_reverse_geocode` with `nearbyLimit` 0 and `includeTimezone`. That returns the country, the divisions, and the IANA zone with local time, without the nearby lookup's 3 or 4 credits. Add the nearby lookup only when you need a settlement name, and apply Gate 6 before naming the country.
63
+
64
+ **One place from an ambiguous name.** Put the admin name or code in the query text (`Springfield, IL` ranked Springfield, IL first), or pass `countries` with `adminCode1`. Add `featureClasses` P for a settlement or A for a division (Gate 3). Confirm the pick from `adminName1`, `featureCode`, and `population` before you chain its geonameId.