@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
package/AGENTS.md CHANGED
@@ -1,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** geonames-mcp-server
4
- **Version:** 0.1.2
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
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.
11
11
 
@@ -57,7 +57,7 @@ import {
57
57
  USERNAME_ALIASES,
58
58
  } from '@/mcp-server/tools/shared-inputs.js';
59
59
  import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
60
- import { inlineText } from '@/utils/inline-text.js';
60
+ import { blockStartText, tableCell } from '@/utils/inline-text.js';
61
61
 
62
62
  export const getHierarchyTool = tool('geonames_get_hierarchy', {
63
63
  title: 'Get a GeoNames hierarchy',
@@ -108,14 +108,14 @@ export const getHierarchyTool = tool('geonames_get_hierarchy', {
108
108
  return { found: true, geonameId, chain: chain.map(toLink) };
109
109
  },
110
110
 
111
- // GeoNames-authored text reaches content[] only through inlineText() / tableCell().
111
+ // GeoNames-authored text reaches content[] only through inlineText() / blockStartText() / tableCell().
112
112
  format: (result) => [{ type: 'text', text: /* heading, breadcrumb, table */ '' }],
113
113
  });
114
114
  ```
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
  });
@@ -188,7 +189,7 @@ Handlers receive a unified `ctx` object. Key properties:
188
189
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible: never log a GeoNames username or a request URL. |
189
190
  | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). Tools here write every required field at the top of the handler with a neutral value (`totalCount: 0`, `truncated: false`, `shown: 0`, `cap`), and write the composed `notice` last, since `.truncated()` also writes one and the last write wins. |
190
191
  | `ctx.fail` | Throws a declared contract `reason` — `throw ctx.fail('query_required', message)`. Typed against the tool's `errors[]`. |
191
- | `ctx.signal` | `AbortSignal` for cancellation; the service passes it to its retry ladder and fetch. |
192
+ | `ctx.signal` | `AbortSignal` for cancellation. The service races each call's shared request against it, so a cancelled call rejects at once with its own `signal.reason`; the retry ladder and fetch run on the single-flight's own signal, aborted only when no caller still waits. |
192
193
  | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
193
194
 
194
195
  ---
@@ -257,12 +258,12 @@ src/
257
258
  types.ts # Domain types
258
259
  mcp-server/
259
260
  tools/
260
- shared-inputs.ts # Shared input schemas, list/blank preprocessing, pre-request checks, paging
261
+ shared-inputs.ts # Shared input schemas, list/blank preprocessing, pre-request checks, the limit clamp, paging, the unlisted-countries notice fragment
261
262
  definitions/
262
263
  index.ts # allToolDefinitions barrel
263
264
  [tool-name].tool.ts # The eight geonames_* tools
264
265
  utils/
265
- inline-text.ts # Sanitizer for GeoNames-authored text in format()
266
+ inline-text.ts # Sanitizer for GeoNames-authored text in format() and enrichment trailer renders
266
267
  ```
267
268
 
268
269
  ---
@@ -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/` at a package's root, and `SKILL.md` — a deeper `skills/`, 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/`, `CLAUDE.md`, `AGENTS.md`, 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
 
@@ -399,7 +410,7 @@ security: false # optional — true ONLY for a source
399
410
 
400
411
  ## Publishing
401
412
 
402
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
413
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
403
414
 
404
415
  ---
405
416
 
@@ -425,15 +436,18 @@ import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
425
436
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
426
437
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
427
438
  - [ ] GeoNames wrapping: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
428
- - [ ] GeoNames wrapping: normalization and `format()` preserve uncertainty; placeholders (`population: 0`, `geonameId: 0`, empty strings, `adminCode1: "00"`) are dropped, never passed on as facts
439
+ - [ ] GeoNames wrapping: normalization and `format()` preserve uncertainty; placeholders (`population: 0`, `geonameId: 0`, empty strings, `adminCode1: "00"` with no admin id) are dropped, never passed on as facts; a `00` sent with an admin id is Monaco's real code and kept; a country record (its `countryId` its own geonameId) lists no admin level
429
440
  - [ ] GeoNames wrapping: tests include at least one sparse payload case with omitted upstream fields
430
441
  - [ ] New upstream parameters added to that endpoint's allowlist in `GeoNamesService` — GeoNames silently ignores a parameter it does not know
431
442
  - [ ] Every tool takes `geonamesUsername` (with `inputAliases: USERNAME_ALIASES`) and declares the five common error entries inline with `thrownBy: 'service'`
432
443
  - [ ] No GeoNames username in `ctx.log`, `ctx.state`, cache keys, output, enrichment, or error text
433
- - [ ] GeoNames-authored text rendered through `inlineText()` / `tableCell()` in `format()`; credit costs in tool descriptions match `docs/design.md`
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,11 +1,11 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** geonames-mcp-server
4
- **Version:** 0.1.2
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`
4
+ **Version:** 0.2.0
5
+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
8
- **Zod:** ^4.6.5
7
+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
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.
11
11
 
@@ -57,7 +57,7 @@ import {
57
57
  USERNAME_ALIASES,
58
58
  } from '@/mcp-server/tools/shared-inputs.js';
59
59
  import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
60
- import { inlineText } from '@/utils/inline-text.js';
60
+ import { blockStartText, tableCell } from '@/utils/inline-text.js';
61
61
 
62
62
  export const getHierarchyTool = tool('geonames_get_hierarchy', {
63
63
  title: 'Get a GeoNames hierarchy',
@@ -108,14 +108,14 @@ export const getHierarchyTool = tool('geonames_get_hierarchy', {
108
108
  return { found: true, geonameId, chain: chain.map(toLink) };
109
109
  },
110
110
 
111
- // GeoNames-authored text reaches content[] only through inlineText() / tableCell().
111
+ // GeoNames-authored text reaches content[] only through inlineText() / blockStartText() / tableCell().
112
112
  format: (result) => [{ type: 'text', text: /* heading, breadcrumb, table */ '' }],
113
113
  });
114
114
  ```
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
  });
@@ -188,7 +189,7 @@ Handlers receive a unified `ctx` object. Key properties:
188
189
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible: never log a GeoNames username or a request URL. |
189
190
  | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). Tools here write every required field at the top of the handler with a neutral value (`totalCount: 0`, `truncated: false`, `shown: 0`, `cap`), and write the composed `notice` last, since `.truncated()` also writes one and the last write wins. |
190
191
  | `ctx.fail` | Throws a declared contract `reason` — `throw ctx.fail('query_required', message)`. Typed against the tool's `errors[]`. |
191
- | `ctx.signal` | `AbortSignal` for cancellation; the service passes it to its retry ladder and fetch. |
192
+ | `ctx.signal` | `AbortSignal` for cancellation. The service races each call's shared request against it, so a cancelled call rejects at once with its own `signal.reason`; the retry ladder and fetch run on the single-flight's own signal, aborted only when no caller still waits. |
192
193
  | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |
193
194
 
194
195
  ---
@@ -257,12 +258,12 @@ src/
257
258
  types.ts # Domain types
258
259
  mcp-server/
259
260
  tools/
260
- shared-inputs.ts # Shared input schemas, list/blank preprocessing, pre-request checks, paging
261
+ shared-inputs.ts # Shared input schemas, list/blank preprocessing, pre-request checks, the limit clamp, paging, the unlisted-countries notice fragment
261
262
  definitions/
262
263
  index.ts # allToolDefinitions barrel
263
264
  [tool-name].tool.ts # The eight geonames_* tools
264
265
  utils/
265
- inline-text.ts # Sanitizer for GeoNames-authored text in format()
266
+ inline-text.ts # Sanitizer for GeoNames-authored text in format() and enrichment trailer renders
266
267
  ```
267
268
 
268
269
  ---
@@ -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/` at a package's root, and `SKILL.md` — a deeper `skills/`, 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/`, `CLAUDE.md`, `AGENTS.md`, 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
 
@@ -399,7 +410,7 @@ security: false # optional — true ONLY for a source
399
410
 
400
411
  ## Publishing
401
412
 
402
- **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
413
+ **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's brief may run a given release as `gated` instead — a `release-pr-review` pass on the open PR before `release-and-publish`. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history.
403
414
 
404
415
  ---
405
416
 
@@ -425,15 +436,18 @@ import { getGeoNamesService } from '@/services/geonames/geonames-service.js';
425
436
  - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
426
437
  - [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
427
438
  - [ ] GeoNames wrapping: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
428
- - [ ] GeoNames wrapping: normalization and `format()` preserve uncertainty; placeholders (`population: 0`, `geonameId: 0`, empty strings, `adminCode1: "00"`) are dropped, never passed on as facts
439
+ - [ ] GeoNames wrapping: normalization and `format()` preserve uncertainty; placeholders (`population: 0`, `geonameId: 0`, empty strings, `adminCode1: "00"` with no admin id) are dropped, never passed on as facts; a `00` sent with an admin id is Monaco's real code and kept; a country record (its `countryId` its own geonameId) lists no admin level
429
440
  - [ ] GeoNames wrapping: tests include at least one sparse payload case with omitted upstream fields
430
441
  - [ ] New upstream parameters added to that endpoint's allowlist in `GeoNamesService` — GeoNames silently ignores a parameter it does not know
431
442
  - [ ] Every tool takes `geonamesUsername` (with `inputAliases: USERNAME_ALIASES`) and declares the five common error entries inline with `thrownBy: 'service'`
432
443
  - [ ] No GeoNames username in `ctx.log`, `ctx.state`, cache keys, output, enrichment, or error text
433
- - [ ] GeoNames-authored text rendered through `inlineText()` / `tableCell()` in `format()`; credit costs in tool descriptions match `docs/design.md`
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.2 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
 
@@ -38,15 +43,15 @@ RUN bun run build
38
43
  #
39
44
  # Installs the production dependency tree for the target platform. Every step
40
45
  # here can run JavaScript — bunfig.toml's security scanner runs as a Bun
41
- # program, and so does the OTel script — so the stage runs on $BUILDPLATFORM
42
- # and cross-installs with `--os`/`--cpu`, which pick each platform-specific
43
- # optional dependency (native bindings such as DuckDB's) for the target. Only
44
- # `node_modules` leaves this stage.
46
+ # program, and so do the OTel and musl-prune scripts — so the stage runs on
47
+ # $BUILDPLATFORM and cross-installs with `--os`/`--cpu`, which pick each
48
+ # platform-specific optional dependency (native bindings such as DuckDB's) for
49
+ # the target. Only `node_modules` leaves this stage.
45
50
  #
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.2 AS deps
54
+ FROM --platform=$BUILDPLATFORM oven/bun:1.4.4 AS deps
50
55
 
51
56
  WORKDIR /usr/src/app
52
57
 
@@ -93,6 +98,15 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
93
98
  bun scripts/install-otel.ts --os="$TARGETOS" --cpu="$(cat .bun-cpu)"; \
94
99
  fi
95
100
 
101
+ # `--os`/`--cpu` have no libc counterpart, so a native dependency published in
102
+ # glibc and musl variants (DuckDB's bindings, for one) installs both. The
103
+ # runtime image is Debian (glibc) and never loads the musl copy; the script
104
+ # deletes every package whose own `libc` admits only musl. It follows every
105
+ # install, since a later `bun install` restores what it removes. A server on a
106
+ # musl (Alpine) runtime image drops these two lines.
107
+ COPY scripts/prune-musl-packages.ts ./scripts/
108
+ RUN bun scripts/prune-musl-packages.ts
109
+
96
110
  # The seeded scanner served only the installs above; keep it out of the image.
97
111
  RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
98
112
 
@@ -105,7 +119,7 @@ RUN rm -rf node_modules/@socketsecurity/bun-security-scanner
105
119
  # dependencies and build artifacts. Its only Bun invocations are HEALTHCHECK
106
120
  # and CMD, which run on the real target at container start.
107
121
  # ==============================================================================
108
- FROM oven/bun:1.4.2-slim AS production
122
+ FROM oven/bun:1.4.4-slim AS production
109
123
 
110
124
  WORKDIR /usr/src/app
111
125
 
@@ -127,6 +141,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
127
141
 
128
142
  # Copy the compiled application code from the build stage
129
143
  COPY --from=build /usr/src/app/dist ./dist
144
+ COPY --from=build /usr/src/app/skills ./skills
130
145
 
131
146
  # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
132
147
  # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves