@cyanheads/geonames-mcp-server 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/AGENTS.md +23 -9
  2. package/CLAUDE.md +23 -9
  3. package/Dockerfile +9 -3
  4. package/README.md +49 -110
  5. package/changelog/0.1.x/0.1.3.md +1 -0
  6. package/changelog/0.2.x/0.2.0.md +37 -0
  7. package/changelog/0.2.x/0.2.1.md +30 -0
  8. package/changelog/template.md +10 -3
  9. package/dist/index.js +2 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -1
  12. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +9 -4
  13. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -1
  14. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +6 -0
  15. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -1
  16. package/dist/mcp-server/tools/definitions/get-children.tool.js +18 -7
  17. package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +6 -0
  19. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-countries.tool.js +15 -5
  21. package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +3 -1
  23. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-place.tool.js +23 -8
  25. package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -1
  26. package/dist/mcp-server/tools/definitions/index.d.ts +23 -3
  27. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +6 -0
  29. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/list-reference.tool.js +13 -3
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -1
  33. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +53 -5
  34. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -1
  35. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +2 -2
  36. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -1
  37. package/dist/mcp-server/tools/definitions/search-places.tool.js +19 -8
  38. package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/shared-inputs.d.ts +6 -2
  40. package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -1
  41. package/dist/mcp-server/tools/shared-inputs.js +9 -3
  42. package/dist/mcp-server/tools/shared-inputs.js.map +1 -1
  43. package/dist/services/geonames/response-parsers.d.ts +1 -0
  44. package/dist/services/geonames/response-parsers.d.ts.map +1 -1
  45. package/dist/services/geonames/response-parsers.js +8 -1
  46. package/dist/services/geonames/response-parsers.js.map +1 -1
  47. package/dist/services/geonames/upstream-errors.d.ts.map +1 -1
  48. package/dist/services/geonames/upstream-errors.js +7 -7
  49. package/dist/services/geonames/upstream-errors.js.map +1 -1
  50. package/dist/utils/inline-text.d.ts +23 -18
  51. package/dist/utils/inline-text.d.ts.map +1 -1
  52. package/dist/utils/inline-text.js +26 -24
  53. package/dist/utils/inline-text.js.map +1 -1
  54. package/package.json +14 -12
  55. package/server.json +3 -3
  56. package/skills/geonames-guide/SKILL.md +64 -0
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** geonames-mcp-server
4
- **Version:** 0.1.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.2.1
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
8
  **Zod:** ^4.6.7
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -115,7 +115,7 @@ export const getHierarchyTool = tool('geonames_get_hierarchy', {
115
115
 
116
116
  ### Resources and prompts
117
117
 
118
- None. A resource read cannot carry `geonamesUsername`, so on a shared deployment it would always spend the server's account; every datum is reachable through the tools (`docs/design.md`, Design Decision 14).
118
+ No data resources and no prompts. A resource read cannot carry `geonamesUsername`, so on a shared deployment it would always spend the server's account; every datum is reachable through the tools (`docs/design.md`, Design Decision 14). The one resource is the published skill: `createApp({ skills: 'skills' })` serves `skills/geonames-guide/SKILL.md` as `skill://geonames-guide/SKILL.md`, a static file that spends no credit.
119
119
 
120
120
  ### Server config
121
121
 
@@ -162,6 +162,7 @@ await createApp({
162
162
  title: 'geonames-mcp-server', // must match the unscoped package name — enforced by lint:packaging
163
163
  instructions: 'GeoNames gazetteer: 13M+ places worldwide, each keyed by an integer geonameId. …',
164
164
  tools: allToolDefinitions,
165
+ skills: 'skills', // serves skills/geonames-guide/SKILL.md over MCP
165
166
  setup(core) { /* see below */ },
166
167
  teardown() { getGeoNamesService().dispose(); },
167
168
  });
@@ -280,9 +281,18 @@ src/
280
281
 
281
282
  ## Skills
282
283
 
283
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
284
+ Two skill trees live at the project root, written for different readers:
284
285
 
285
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
286
+ | Tree | For | Written by |
287
+ |:-----|:----|:-----------|
288
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
289
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
290
+
291
+ Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
292
+
293
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
294
+
295
+ **Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
286
296
 
287
297
  Available skills:
288
298
 
@@ -294,6 +304,7 @@ Available skills:
294
304
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
295
305
  | `add-resource` | Scaffold a new resource definition |
296
306
  | `add-prompt` | Scaffold a new prompt definition |
307
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
297
308
  | `add-service` | Scaffold a new service integration |
298
309
  | `add-test` | Scaffold test file for a tool, resource, or service |
299
310
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -341,7 +352,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
341
352
  | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
342
353
  | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
343
354
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
344
- | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
355
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |
345
356
  | `bun run list-skills` | Print the skill registry |
346
357
  | `bun run tree` | Generate directory structure doc |
347
358
  | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -362,7 +373,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
362
373
 
363
374
  ## Bundling
364
375
 
365
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
376
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs — `framework-skills/`, `skills/`, `.claude/`, `.agents/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package, such as the MCP SDK's `dist/ext/skills/`, is runtime code and stays); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
366
377
 
367
378
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`. A user-supplied variable also goes into the plugin manifests — `.claude-plugin/plugin.json` `userConfig` + `env`, `.codex-plugin/mcp.json` `env_vars` (see Checklist).
368
379
 
@@ -433,7 +444,10 @@ import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
433
444
  - [ ] GeoNames-authored text rendered in `format()` through `inlineText()` inside a line, `blockStartText()` where it opens a line (heading, list item, block quote, its own line), or `tableCell()`; enrichment values stay raw in `structuredContent`, escaped only by an `enrichmentTrailer` render; credit costs in tool descriptions match `docs/design.md`
434
445
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
435
446
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
447
+ - [ ] `plugin.json` + `mcp.json` (Agent Plugins 1.0.0 — read by Codex, Cursor, GitHub Copilot, VS Code, Kiro) populated — `plugin.json` `name` = the unscoped repo name (lowercase `a-z`, `0-9`, `-`, `.` only); `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords` from `package.json`; no other top-level field, `extensions` included. `mcp.json` holds one `"type": "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, and the same fixed `env` as `.codex-plugin/mcp.json`. Neither file carries a user-supplied variable (no `""`, no `${…}` besides `${PLUGIN_ROOT}`/`${PLUGIN_DATA}`): keys reach Codex through `.codex-plugin/mcp.json` `env_vars`, which works only while `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"`
436
448
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
437
449
  - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
438
450
  - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
451
+ - [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
452
+ - [ ] If the server publishes a skill in root `skills/`: `lint:packaging` passes, and `field-test` verified every gate and identifier claim in it against live tool behavior
439
453
  - [ ] `npm run devcheck` passes
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** geonames-mcp-server
4
- **Version:** 0.1.3
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.2.1
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
+ **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
8
8
  **Zod:** ^4.6.7
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -115,7 +115,7 @@ export const getHierarchyTool = tool('geonames_get_hierarchy', {
115
115
 
116
116
  ### Resources and prompts
117
117
 
118
- None. A resource read cannot carry `geonamesUsername`, so on a shared deployment it would always spend the server's account; every datum is reachable through the tools (`docs/design.md`, Design Decision 14).
118
+ No data resources and no prompts. A resource read cannot carry `geonamesUsername`, so on a shared deployment it would always spend the server's account; every datum is reachable through the tools (`docs/design.md`, Design Decision 14). The one resource is the published skill: `createApp({ skills: 'skills' })` serves `skills/geonames-guide/SKILL.md` as `skill://geonames-guide/SKILL.md`, a static file that spends no credit.
119
119
 
120
120
  ### Server config
121
121
 
@@ -162,6 +162,7 @@ await createApp({
162
162
  title: 'geonames-mcp-server', // must match the unscoped package name — enforced by lint:packaging
163
163
  instructions: 'GeoNames gazetteer: 13M+ places worldwide, each keyed by an integer geonameId. …',
164
164
  tools: allToolDefinitions,
165
+ skills: 'skills', // serves skills/geonames-guide/SKILL.md over MCP
165
166
  setup(core) { /* see below */ },
166
167
  teardown() { getGeoNamesService().dispose(); },
167
168
  });
@@ -280,9 +281,18 @@ src/
280
281
 
281
282
  ## Skills
282
283
 
283
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
284
+ Two skill trees live at the project root, written for different readers:
284
285
 
285
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
286
+ | Tree | For | Written by |
287
+ |:-----|:----|:-----------|
288
+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
289
+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
290
+
291
+ Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
292
+
293
+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
294
+
295
+ **Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
286
296
 
287
297
  Available skills:
288
298
 
@@ -294,6 +304,7 @@ Available skills:
294
304
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
295
305
  | `add-resource` | Scaffold a new resource definition |
296
306
  | `add-prompt` | Scaffold a new prompt definition |
307
+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
297
308
  | `add-service` | Scaffold a new service integration |
298
309
  | `add-test` | Scaffold test file for a tool, resource, or service |
299
310
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -341,7 +352,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
341
352
  | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
342
353
  | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
343
354
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
344
- | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
355
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |
345
356
  | `bun run list-skills` | Print the skill registry |
346
357
  | `bun run tree` | Generate directory structure doc |
347
358
  | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -362,7 +373,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
362
373
 
363
374
  ## Bundling
364
375
 
365
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
376
+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs — `framework-skills/`, `skills/`, `.claude/`, `.agents/`, `AGENTS.md`, and `CLAUDE.md` at a package's root, and `SKILL.md` anywhere (a `skills/` deeper in a package, such as the MCP SDK's `dist/ext/skills/`, is runtime code and stays); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
366
377
 
367
378
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`. A user-supplied variable also goes into the plugin manifests — `.claude-plugin/plugin.json` `userConfig` + `env`, `.codex-plugin/mcp.json` `env_vars` (see Checklist).
368
379
 
@@ -433,7 +444,10 @@ import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
433
444
  - [ ] GeoNames-authored text rendered in `format()` through `inlineText()` inside a line, `blockStartText()` where it opens a line (heading, list item, block quote, its own line), or `tableCell()`; enrichment values stay raw in `structuredContent`, escaped only by an `enrichmentTrailer` render; credit costs in tool descriptions match `docs/design.md`
434
445
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
435
446
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
447
+ - [ ] `plugin.json` + `mcp.json` (Agent Plugins 1.0.0 — read by Codex, Cursor, GitHub Copilot, VS Code, Kiro) populated — `plugin.json` `name` = the unscoped repo name (lowercase `a-z`, `0-9`, `-`, `.` only); `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords` from `package.json`; no other top-level field, `extensions` included. `mcp.json` holds one `"type": "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, and the same fixed `env` as `.codex-plugin/mcp.json`. Neither file carries a user-supplied variable (no `""`, no `${…}` besides `${PLUGIN_ROOT}`/`${PLUGIN_DATA}`): keys reach Codex through `.codex-plugin/mcp.json` `env_vars`, which works only while `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"`
436
448
  - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
437
449
  - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
438
450
  - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
451
+ - [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
452
+ - [ ] If the server publishes a skill in root `skills/`: `lint:packaging` passes, and `field-test` verified every gate and identifier claim in it against live tool behavior
439
453
  - [ ] `npm run devcheck` passes
package/Dockerfile CHANGED
@@ -14,7 +14,7 @@
14
14
  # output. A stage that compiles a native addon needs the target-arch toolchain
15
15
  # and cannot cross-compile this way — drop the flag there.
16
16
  # ==============================================================================
17
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS build
17
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS build
18
18
 
19
19
  WORKDIR /usr/src/app
20
20
 
@@ -29,6 +29,11 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
29
29
  # Copy the rest of the source code
30
30
  COPY . .
31
31
 
32
+ # The skills a server publishes (`createApp({ skills: 'skills' })`) are read at
33
+ # runtime from the application root. Created when the project has none, so the
34
+ # production stage's copy below holds with or without one.
35
+ RUN mkdir -p skills
36
+
32
37
  # Build the application
33
38
  RUN bun run build
34
39
 
@@ -46,7 +51,7 @@ RUN bun run build
46
51
  # A clean image rather than `FROM build`: the build stage's node_modules holds
47
52
  # devDependencies.
48
53
  # ==============================================================================
49
- FROM --platform=$BUILDPLATFORM oven/bun:1.4.3 AS deps
54
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
50
55
 
51
56
  WORKDIR /usr/src/app
52
57
 
@@ -114,7 +119,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
114
119
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
115
120
  # and CMD, which run on the real target at container start.
116
121
  # ==============================================================================
117
- FROM oven/bun:1.4.3-slim AS production
122
+ FROM oven/bun:1.4.4-slim AS production
118
123
 
119
124
  WORKDIR /usr/src/app
120
125
 
@@ -136,6 +141,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
136
141
 
137
142
  # Copy the compiled application code from the build stage
138
143
  COPY --from=build /usr/src/app/dist ./dist
144
+ COPY --from=build /usr/src/app/skills ./skills
139
145
 
140
146
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
141
147
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.1.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/geonames-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/geonames-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/geonames-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.2.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/geonames-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/geonames-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/geonames-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -48,7 +48,7 @@ The [GeoNames](https://www.geonames.org/) gazetteer: 13M+ places worldwide, link
48
48
 
49
49
  ### `geonames_search_places` <sub>tool</sub>
50
50
 
51
- - `query` (up to 200 characters) compared per `match`: `name_required` (default), `any_field`, `exact_name`, or `name_prefix`; filters `countries` (up to 10, by ISO alpha-2, alpha-3, or numeric code), `adminCode1`–`adminCode4`, `featureClasses`, `featureCodes` (up to 20), `cities` (`cities1000` / `cities5000` / `cities15000`), and `boundingBox`. A call needs `query` or one of `countries`, `featureClasses`, `featureCodes`, `boundingBox`
51
+ - `query` (up to 200 characters) compared per `match`: `name_required` (default), `any_field`, `exact_name`, or `name_prefix`; filters `countries` (up to 10, by ISO alpha-2, alpha-3, or numeric code), `adminCode1`–`adminCode4`, `featureClasses`, `featureCodes` (up to 20), `cities` (`cities1000` / `cities5000` / `cities15000`), and `boundingBox` (`west` above `east` crosses the 180° meridian, and the notice gives the longitude span). A call needs `query` or one of `countries`, `featureClasses`, `featureCodes`, `boundingBox`
52
52
  - A listed country also returns the territories GeoNames files under it (`GB` also returns IM, GG, JE, and GS), each place under its own `countryCode`; the notice names any country on the page that `countries` does not list
53
53
  - `adminCode1`–`adminCode4` search inside an admin division by its GeoNames code, as `geonames_get_place` and `geonames_reverse_geocode` return it in `adminLevels` (`countries: ["US"], adminCode1: "TX", featureCodes: ["AIRP"]` lists Texas airports). Codes are case-insensitive and zero padding counts (`02`, not `2`); they are not ISO 3166-2 or postal codes (Bavaria is `02`, not `BY`). Each needs exactly one country, and levels 2–4 need `adminCode1`
54
54
  - `limit` 1–1,000 (default 10), held to 100 per call with a notice when more remain; `offset` 0–5000, `orderBy` `relevance` or `population` (omitted, GeoNames' own order); returns `totalCount`, `effectiveQuery`, and `nextOffset`
@@ -61,6 +61,8 @@ The [GeoNames](https://www.geonames.org/) gazetteer: 13M+ places worldwide, link
61
61
 
62
62
  - One `geonameId`; an unknown id returns `found: false` with `guidance`
63
63
  - Returns `adminLevels` 1–5 (code, name, `geonameId`), timezone (UTC offsets on 1 January and 1 July), bounding box, recorded and DEM elevation, population, Wikipedia URL, `alternateNames`, `postalCodes`, `links`, and `identifiers` (IATA, ICAO, FAA, Transport Canada, UN/LOCODE, Wikidata)
64
+ - The timezone is the zone GeoNames associates with the record. On a record with no country (an ocean, a sea, a continent) a notice says so and gives the `geonames_reverse_geocode` call for the time at its coordinates
65
+ - `postalCodes` lists the codes GeoNames links to the feature, which can be fewer than `geonames_find_postal_codes` returns for the place
64
66
  - `nameLanguages` (up to 20 tags; `zh` also matches `zh-CN`) filters `alternateNames` only
65
67
 
66
68
  ---
@@ -76,7 +78,7 @@ The [GeoNames](https://www.geonames.org/) gazetteer: 13M+ places worldwide, link
76
78
 
77
79
  - `hierarchy`: `administrative` (default), `tourism` (islands, coasts, and their municipalities; almost all in Spain), or `dependency` (a country's dependent territories). Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L, islands class T
78
80
  - GeoNames answers a `tourism` or `dependency` request with the administrative children when the feature has no such tree. The tool compares the two lists and sets `sameAsAdministrative`, with a notice, when they match; the rows stay, since a real tree can match too
79
- - Fetches up to 1,000 children per parent once and caches them, so `nameContains`, `limit` (1–1,000, default 100, held to 500 per call with a notice when more remain), and `offset` cost no extra credits; a notice says when GeoNames lists more
81
+ - Fetches up to 1,000 children per parent once and caches them, so `nameContains`, `limit` (1–1,000, default 100, held to 500 per call with a notice when more remain), and `offset` cost no extra credits; a notice says when GeoNames lists more. A `nameContains` with no letter or digit fails before any request as `name_contains_unsearchable`
80
82
  - An unknown id returns `found: false`; a leaf returns an empty `children` list with a notice
81
83
 
82
84
  ---
@@ -86,6 +88,7 @@ The [GeoNames](https://www.geonames.org/) gazetteer: 13M+ places worldwide, link
86
88
  - `lat` / `lng` resolve to `country` and `adminLevels` (down to ADM5, each with its `geonameId` and ISO 3166-2 subdivision code where one exists) or, offshore, the `ocean`
87
89
  - `coastalBufferKm` (0–50, default 0) matches the nearest country within that distance when none contains the point, for harbor, pier, and shoreline fixes; a buffered match carries `country.distanceInKm`, and the nearby and timezone lookups keep the exact point
88
90
  - `nearby` lists the nearest populated places (`nearbyLimit` 0–1,000, default 5, held to 50 per call with a notice when more lie within the radius; `radiusKm` up to 300, default 20; optional `cities` tier) or, when `featureClasses` / `featureCodes` is set, the nearest features of that type; `nearbyKind` says which. `featureClasses` and `featureCodes` intersect
91
+ - When more than 50 lie within the radius, the notice prints the `geonames_search_places` call, with a `boundingBox` enclosing the radius, that lists them, up to the search's 5,100-row reach. The search returns rows by relevance, not distance, so read every page and keep the rows within `radiusKm`
89
92
  - Fails before any request with `conflicting_filters` (`cities` with a feature filter), `unknown_feature_code`, or `feature_filter_mismatch` (a code whose class is not listed, or a listed class with no code)
90
93
  - `includeTimezone` adds the IANA id, UTC offsets, local time, sunrise, and sunset (offsets only offshore, where both dates are reported at the standard offset)
91
94
 
@@ -98,20 +101,21 @@ The [GeoNames](https://www.geonames.org/) gazetteer: 13M+ places worldwide, link
98
101
  - A listed country also returns the territories GeoNames files under it (`GB` also returns IM, JE, and GG), each postal code under its own `countryCode`; the notice names any country on the page that `countries` does not list
99
102
  - `limit` 1–1,000 (default 10), held to 100 per call with a notice when more remain; `code` and `place_name` page with `offset` 0–5000 and return `nextOffset` while more rows remain below offset 5000; GeoNames reports no total, so `truncated` says whether more rows exist, never how many
100
103
  - Covers 122 countries; Ireland returns only Eircode routing keys and Malta only letter prefixes
104
+ - Admin codes on postal rows come from the postal dataset and can differ from the gazetteer's (Bavaria is `BY` here, `02` in search), so they are not `geonames_search_places` filters
101
105
 
102
106
  ---
103
107
 
104
108
  ### `geonames_get_countries` <sub>tool</sub>
105
109
 
106
- - Up to 250 `countries` by ISO alpha-2, alpha-3, or numeric code, a `continent`, `nameContains`, or no filter for all 250; `limit` 1–1,000 (default 50), held to 250 per call, with `offset`
107
- - Rows carry ISO and FIPS codes, `geonameId` (the starting point for `geonames_get_children`), capital, population, area, continent, languages, currency, postal-code format, and mainland bounding box; unknown codes land in `notFound`
110
+ - Up to 250 `countries` by ISO alpha-2, alpha-3, or numeric code, a `continent`, `nameContains`, or no filter for all 250; `limit` 1–1,000 (default 50), held to 250 per call, with `offset`; a `nameContains` with no letter or digit fails before any request as `name_contains_unsearchable`
111
+ - Rows carry ISO and FIPS codes, `geonameId` (the starting point for `geonames_get_children`), capital, population, area, continent, languages, currency, postal-code format, and GeoNames' bounding box for the country (a rectangle that can take in neighboring land and leave out outlying territory); unknown codes land in `notFound`
108
112
 
109
113
  ---
110
114
 
111
115
  ### `geonames_list_reference` <sub>tool</sub>
112
116
 
113
117
  - `topic`: `feature_classes` (9), `feature_codes` (684, filterable by `featureClass`), or `postal_countries` (122, with each country's code range and count); `featureClass` with another topic fails as `filter_not_applicable`
114
- - `nameContains`, `limit` 1–1,000 (default 100, held to 700 per call, which fits every topic), and `offset`; feature classes and codes are bundled and spend no credits
118
+ - `nameContains`, `limit` 1–1,000 (default 100, held to 700 per call, which fits every topic), and `offset`; feature classes and codes are bundled and spend no credits. A `nameContains` with no letter or digit fails before any request as `name_contains_unsearchable`
115
119
 
116
120
  ## Features
117
121
 
@@ -133,134 +137,49 @@ Agent-friendly output:
133
137
  Known limitations:
134
138
 
135
139
  - **Shared quota on a shared deployment.** All callers without their own username share the server account's 1,000 credits an hour. A burst of reverse geocodes (up to 7 credits each) can exhaust it, and GeoNames does not say when the window resets.
136
- - **Search and postal searches reach only offset 5000** on the free tier, and a page holds at most 100 rows, so a result set is reachable up to its 5,100th row. Nearby postal lookups do not page.
140
+ - **Search and postal searches reach only offset 5000** on the free tier, and a page holds at most 100 rows, so a result set is reachable up to its 5,100th row. Nearby postal lookups do not page: they return the nearest 100, which in a dense city covers little ground (0.19 km in central London).
137
141
  - **Children cap at 1,000 per parent.**
138
142
  - **Postal data covers 122 countries.** Ireland and Malta return only code prefixes. US nearby lookups place the first row at the query point rather than the ZIP centroid.
139
143
  - **Nearby radius tops out at 300 km** for places and features and 30 km for postal codes, GeoNames' free-tier ceilings.
140
- - **Bounding boxes cannot cross the 180° meridian.** Split such an area into two searches.
141
144
  - **Coastal points can resolve to the ocean without a buffer.** By default only a country that contains the point matches, so a harbor or shoreline point just outside the outline returns the sea while its nearby places are on land. Set `coastalBufferKm` (up to 50) to match the nearest country instead; in a strait that can be either shore.
142
145
  - **Microstates and enclaves can resolve to the surrounding country.** A point inside Vatican City returns Italy.
143
- - **Nearest populated places include sections and historical places.** In a dense city the nearest rows are often `PPLX` quarters or `PPLH` former districts; each row's `featureCode` says which, and `cities` restricts to places above a population tier.
146
+ - **Nearest populated places include sections and historical places.** In a dense city the nearest rows are often `PPLX` quarters or `PPLH` former districts; each row's `featureCode` says which. `cities` restricts to places above a population tier, but a city section (`PPLX`) with its own population passes it.
144
147
  - **Offshore timezones are offsets only.** No IANA id, local time, sunrise, or sunset is available at sea, and both dated offsets are the standard offset (open water has no DST).
148
+ - **A place record's timezone is GeoNames' association, not a lookup at its coordinates.** On a record with no country it can be far off (South Pacific Ocean carries Pacific/Tongatapu, +13), and a country-bearing record can still carry another country's zone, as some Antarctic seas do. `geonames_reverse_geocode` with `includeTimezone` gives the time at a point.
145
149
  - **`exact_name` matches alternate and historical names**, so a result's `name` can differ from the query: "Springfield" can return Plattsburg or Palmyra, MO.
146
150
  - **Data is community-edited and provided "as is".** Many features have no recorded population or elevation.
147
151
 
148
152
  ## Getting started
149
153
 
150
- ### Public Hosted Instance
154
+ Connect to the hosted instance, no install:
151
155
 
152
- A public instance is available at `https://geonames.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
153
-
154
- ```json
155
- {
156
- "mcpServers": {
157
- "geonames-mcp-server": {
158
- "type": "streamable-http",
159
- "url": "https://geonames.caseyjhand.com/mcp"
160
- }
161
- }
162
- }
156
+ ```sh
157
+ claude mcp add --transport http geonames-mcp-server https://geonames.caseyjhand.com/mcp
163
158
  ```
164
159
 
165
160
  A call that passes no `geonamesUsername` spends the hosted instance's GeoNames account, whose 1,000 credits an hour are shared by every such caller. Pass your own `geonamesUsername` to spend your account's quota instead.
166
161
 
167
- ### Self-Hosted / Local
168
-
169
- Add the following to your MCP client configuration file, with your GeoNames username in place of the placeholder.
162
+ Or run it locally:
170
163
 
171
- ```json
172
- {
173
- "mcpServers": {
174
- "geonames-mcp-server": {
175
- "type": "stdio",
176
- "command": "bunx",
177
- "args": ["@cyanheads/geonames-mcp-server@latest"],
178
- "env": {
179
- "MCP_TRANSPORT_TYPE": "stdio",
180
- "MCP_LOG_LEVEL": "info",
181
- "GEONAMES_USERNAME": "your_geonames_username"
182
- }
183
- }
184
- }
185
- }
164
+ ```sh
165
+ claude mcp add geonames-mcp-server -e GEONAMES_USERNAME=your_geonames_username -- npx -y @cyanheads/geonames-mcp-server
186
166
  ```
187
167
 
188
- Or with npx (no Bun required):
168
+ For other clients, add this to the MCP config file:
189
169
 
190
170
  ```json
191
171
  {
192
172
  "mcpServers": {
193
173
  "geonames-mcp-server": {
194
- "type": "stdio",
195
174
  "command": "npx",
196
- "args": ["-y", "@cyanheads/geonames-mcp-server@latest"],
197
- "env": {
198
- "MCP_TRANSPORT_TYPE": "stdio",
199
- "MCP_LOG_LEVEL": "info",
200
- "GEONAMES_USERNAME": "your_geonames_username"
201
- }
202
- }
203
- }
204
- }
205
- ```
206
-
207
- Or with Docker:
208
-
209
- ```json
210
- {
211
- "mcpServers": {
212
- "geonames-mcp-server": {
213
- "type": "stdio",
214
- "command": "docker",
215
- "args": [
216
- "run", "-i", "--rm",
217
- "-e", "MCP_TRANSPORT_TYPE=stdio",
218
- "-e", "GEONAMES_USERNAME=your_geonames_username",
219
- "ghcr.io/cyanheads/geonames-mcp-server:latest"
220
- ]
175
+ "args": ["-y", "@cyanheads/geonames-mcp-server"],
176
+ "env": { "GEONAMES_USERNAME": "your_geonames_username" }
221
177
  }
222
178
  }
223
179
  }
224
180
  ```
225
181
 
226
- For Streamable HTTP, set the transport and start the server:
227
-
228
- ```sh
229
- MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 GEONAMES_USERNAME=your_geonames_username bun run start:http
230
- # Server listens at http://localhost:3010/mcp
231
- ```
232
-
233
- ### Prerequisites
234
-
235
- - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
236
- - A free [GeoNames account](https://www.geonames.org/login) with free web services enabled on its [account page](https://www.geonames.org/manageaccount). GeoNames rejects calls from an account until they are enabled.
237
-
238
- ### Installation
239
-
240
- 1. **Clone the repository:**
241
-
242
- ```sh
243
- git clone https://github.com/cyanheads/geonames-mcp-server.git
244
- ```
245
-
246
- 2. **Navigate into the directory:**
247
-
248
- ```sh
249
- cd geonames-mcp-server
250
- ```
251
-
252
- 3. **Install dependencies:**
253
-
254
- ```sh
255
- bun install
256
- ```
257
-
258
- 4. **Configure environment:**
259
-
260
- ```sh
261
- cp .env.example .env
262
- # edit .env and set GEONAMES_USERNAME
263
- ```
182
+ Create a free [GeoNames account](https://www.geonames.org/login), then enable free web services on its [account page](https://www.geonames.org/manageaccount); GeoNames rejects calls from an account until they are enabled. For Docker or a source build, see [Running the server](#running-the-server).
264
183
 
265
184
  ## Configuration
266
185
 
@@ -296,24 +215,44 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
296
215
 
297
216
  ### Local development
298
217
 
299
- - **Build and run the production version**:
218
+ Requires [Bun v1.4.4](https://bun.sh/) or higher (or Node.js v24+).
219
+
220
+ - **Clone and install:**
221
+
222
+ ```sh
223
+ git clone https://github.com/cyanheads/geonames-mcp-server.git
224
+ cd geonames-mcp-server && bun install
225
+ cp .env.example .env # set GEONAMES_USERNAME
226
+ ```
227
+
228
+ - **Build and run:**
300
229
 
301
230
  ```sh
302
231
  # One-time build
303
232
  bun run rebuild
304
233
 
305
234
  # Run the built server
306
- bun run start:http
307
- # or
308
235
  bun run start:stdio
236
+ # or
237
+ bun run start:http # listens at http://localhost:3010/mcp
309
238
  ```
310
239
 
311
- - **Run checks and tests**:
240
+ - **Run checks and tests:**
241
+
312
242
  ```sh
313
- bun run devcheck # Lints, formats, type-checks, and more
314
- bun run test # Runs the test suite
243
+ bun run devcheck # Lint, format, typecheck, security
244
+ bun run test # Vitest test suite
245
+ bun run lint:mcp # Validate MCP definitions against spec
315
246
  ```
316
247
 
248
+ ### Docker
249
+
250
+ ```sh
251
+ docker run --rm -e GEONAMES_USERNAME=your_geonames_username -p 3010:3010 ghcr.io/cyanheads/geonames-mcp-server:latest
252
+ ```
253
+
254
+ The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/geonames-mcp-server`. To run it over stdio from an MCP client, use `"command": "docker"` with `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "GEONAMES_USERNAME=your_geonames_username", "ghcr.io/cyanheads/geonames-mcp-server:latest"]`. To build locally, `docker build -t geonames-mcp-server .`; OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
255
+
317
256
  ## Project structure
318
257
 
319
258
  | Directory | Purpose |
@@ -28,6 +28,7 @@ security: false
28
28
  - **Enrichment text** — `effectiveQuery` and notices carry the strings as received in `structuredContent`; the Markdown escaping applies only to `content[]` ([#16](https://github.com/cyanheads/geonames-mcp-server/issues/16)).
29
29
  - **Markdown in names** — `*`, `` ` ``, `~`, and non-intraword `_` in GeoNames text are escaped in `content[]` ([#23](https://github.com/cyanheads/geonames-mcp-server/issues/23)).
30
30
  - **Cancelled callers** — an aborted caller no longer cancels the upstream request that identical in-flight calls share, and a cancelled waiter rejects at once with its own reason ([#12](https://github.com/cyanheads/geonames-mcp-server/issues/12)).
31
+ - **MCP Registry launch** — both `server.json` npm packages start through `npx`, the HTTP one selecting its transport with `MCP_TRANSPORT_TYPE=http`; the previous `node run start:*` arguments did not start the server.
31
32
  - **Input descriptions** offer only the forms the advertised schema accepts (lists, canonical case, `geonameId` as a digit string); the other forms are still tolerated ([#25](https://github.com/cyanheads/geonames-mcp-server/issues/25)).
32
33
 
33
34
  ## Dependencies
@@ -0,0 +1,37 @@
1
+ ---
2
+ summary: "Publishes the geonames-guide agent skill over MCP, prints the search call that lists a full nearby page, notes the timezone of countryless records, rejects nameContains with no letter or digit, and keeps URLs as written in content[]."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.2.0 — 2026-10-29
8
+
9
+ ## Added
10
+
11
+ - **`geonames-guide` agent skill** — served as `skill://geonames-guide/SKILL.md` (listed by `resources/list`, template `skill://{+path}`) through `createApp({ skills: 'skills' })`; it covers postal-to-gazetteer crossings, population gates, searching inside a division, and the timezone at a coordinate. The server `instructions` point to it, and `skills/` ships in the npm package and the Docker image.
12
+ - **Root `plugin.json` and `mcp.json`** — the Agent Plugins manifest pair, with the unscoped server name and an `npx -y @cyanheads/geonames-mcp-server` stdio entry.
13
+
14
+ ## Changed
15
+
16
+ - **Full-page nearby notices** name the route to the rest ([#26](https://github.com/cyanheads/geonames-mcp-server/issues/26)): `geonames_reverse_geocode` prints the `geonames_search_places` call, with a `boundingBox` enclosing the radius, and says the search lists rows by relevance, so keep those within `radiusKm`; `geonames_find_postal_codes` mode `nearby` says it does not page and a call from another point returns that point's nearest 100.
17
+ - **`geonames_get_place` timezone notice** — a record with a `timezone` and no `countryCode` carries a `notice` on both surfaces saying the zone is the one GeoNames associates with the record, with the `geonames_reverse_geocode` call for the time at its coordinates ([#30](https://github.com/cyanheads/geonames-mcp-server/issues/30)). The `timezone` field description says the same for every record.
18
+ - **Tool descriptions** — `geonames_get_children` routes to `geonames_search_places` by country and admin codes for other feature types, for a parent with no children, and for one with more children than it returns; `adminCode1`–`adminCode3` on postal rows are marked as postal-dataset codes that `geonames_search_places` does not filter on; `postalCodes` on `geonames_get_place` is marked as possibly shorter than `geonames_find_postal_codes`; `cities` notes that PPLX sections with their own population pass.
19
+ - **`.mcpb` bundle** leaves out `src/`, `docs/`, `changelog/`, `CLAUDE.md`, `AGENTS.md`, the plugin manifests, and other repo-only root paths.
20
+
21
+ ## Fixed
22
+
23
+ - **`nameContains` with no letter or digit** — punctuation, symbols, emoji, or combining marks or invisible characters alone — fails as `name_contains_unsearchable` before any GeoNames request on `geonames_get_countries`, `geonames_get_children`, and `geonames_list_reference`; it used to match every row ([#29](https://github.com/cyanheads/geonames-mcp-server/issues/29)).
24
+ - **URLs in `content[]`** print as written, with no bracketed `https[:]//` or `www[.]`, so a CommonMark parse reads back the `structuredContent` value ([#28](https://github.com/cyanheads/geonames-mcp-server/issues/28)).
25
+ - **`structuredContent.error.message`** for `upstream_rejected_parameter` carries the GeoNames text without Markdown escapes; the `Error:` line of `content[]` is escaped by the framework (cyanheads/mcp-ts-core#760) ([#28](https://github.com/cyanheads/geonames-mcp-server/issues/28)).
26
+
27
+ ## Dependencies
28
+
29
+ - `@cyanheads/mcp-ts-core` ^0.13.15 → ^0.13.18
30
+ - `@modelcontextprotocol/server` ^2.3.1 → ^2.4.0 (dev)
31
+ - `@biomejs/biome` 2.5.15 → 2.6.3 (dev)
32
+ - `vitest` ^5.0.4 → ^5.0.5 (dev)
33
+ - `@vitest/coverage-istanbul` 5.0.4 → 5.0.5 (dev)
34
+ - `ignore` ^7.0.12 → ^7.0.14 (dev)
35
+ - `tsc-alias` ^1.9.7 → ^1.9.9 (dev)
36
+ - `markdown-it` 15.0.3 (dev, new — CommonMark round-trip tests)
37
+ - `packageManager` bun@1.4.3 → bun@1.4.4 (Docker base image `oven/bun:1.4.4`)
@@ -0,0 +1,30 @@
1
+ ---
2
+ summary: "geonames_search_places accepts a boundingBox with west above east as crossing the 180° meridian, geonames_reverse_geocode prints one such box when a full nearby page's radius meets the meridian, and the Country line of a continent record names the missing country."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.2.1 — 2026-11-15
8
+
9
+ ## Changed
10
+
11
+ - **`geonames_reverse_geocode` full-page nearby notice** prints the `geonames_search_places` call with one `boundingBox` whose `west` is above `east` when the radius crosses the 180° meridian, in place of the "box on each side" instruction ([#33](https://github.com/cyanheads/geonames-mcp-server/issues/33)). Boxes that stop short of the meridian, and the poles, print as before.
12
+ - **The framework's tool-error trailer** gains a `retry after <value>` term between `retryable` and the request id when the error carries `data.retryAfter` (`@cyanheads/mcp-ts-core` 0.13.19).
13
+
14
+ ## Fixed
15
+
16
+ - **`geonames_search_places` `boundingBox`** with `west` above `east` is read as crossing the 180° meridian, as GeoNames reads it, and sent unchanged; the Russia, Fiji, and Kiribati country boxes and crossing `geonames_get_place` boxes pass as they stand. Its notice gives the longitude span on every page, including a zero-hit one ([#31](https://github.com/cyanheads/geonames-mcp-server/issues/31)).
17
+ - **`invalid_bounding_box`** still rejects `south` at or above `north` and `west` equal to `east` (or `west` 180 with `east` -180) before any request; its recovery hint no longer advises splitting a crossing box ([#31](https://github.com/cyanheads/geonames-mcp-server/issues/31)).
18
+ - **A bounding box GeoNames writes as `east: -180`** (New Zealand's country row) is relayed as `180`, and `west: 180` as `-180`, in `geonames_get_countries` and `geonames_get_place` ([#31](https://github.com/cyanheads/geonames-mcp-server/issues/31)).
19
+ - **`geonames_get_countries` and `geonames_get_place` `boundingBox` descriptions** no longer call the box the country's mainland, and state that `west` above `east` crosses the 180° meridian ([#31](https://github.com/cyanheads/geonames-mcp-server/issues/31)).
20
+ - **`geonames_get_place` Country line** for a record with a continent and no country reads `- **Country:** Not available · continent AS` in `content[]`; `structuredContent` is unchanged ([#32](https://github.com/cyanheads/geonames-mcp-server/issues/32)).
21
+
22
+ ## Dependencies
23
+
24
+ - `@cyanheads/mcp-ts-core` ^0.13.18 → ^0.13.22
25
+ - `@biomejs/biome` 2.6.3 → 2.6.7 (dev)
26
+ - `@types/node` 26.6.5 → 26.6.6 (dev)
27
+ - `@vitest/coverage-istanbul` 5.0.5 → 5.1.0 (dev)
28
+ - `tsc-alias` ^1.9.9 → ^1.9.10 (dev)
29
+ - `vitest` ^5.0.5 → ^5.1.0 (dev)
30
+ - `engines.bun` >=1.4.0 → >=1.4.4