@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.
- package/AGENTS.md +31 -17
- package/CLAUDE.md +31 -17
- package/Dockerfile +22 -7
- package/README.md +66 -122
- package/changelog/0.1.x/0.1.3.md +46 -0
- package/changelog/0.2.x/0.2.0.md +37 -0
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts +8 -5
- package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +84 -42
- package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-children.tool.js +35 -18
- package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-countries.tool.js +32 -14
- package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/get-hierarchy.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +3 -1
- package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-place.tool.js +35 -11
- package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +37 -5
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +6 -0
- package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-reference.tool.js +34 -14
- package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +85 -28
- package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +12 -2
- package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-places.tool.js +107 -26
- package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -1
- package/dist/mcp-server/tools/shared-inputs.d.ts +62 -20
- package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -1
- package/dist/mcp-server/tools/shared-inputs.js +94 -29
- package/dist/mcp-server/tools/shared-inputs.js.map +1 -1
- package/dist/services/geonames/country-codes.d.ts +7 -1
- package/dist/services/geonames/country-codes.d.ts.map +1 -1
- package/dist/services/geonames/country-codes.js +15 -1
- package/dist/services/geonames/country-codes.js.map +1 -1
- package/dist/services/geonames/geonames-service.d.ts +7 -3
- package/dist/services/geonames/geonames-service.d.ts.map +1 -1
- package/dist/services/geonames/geonames-service.js +85 -35
- package/dist/services/geonames/geonames-service.js.map +1 -1
- package/dist/services/geonames/response-parsers.d.ts +9 -5
- package/dist/services/geonames/response-parsers.d.ts.map +1 -1
- package/dist/services/geonames/response-parsers.js +102 -22
- package/dist/services/geonames/response-parsers.js.map +1 -1
- package/dist/services/geonames/types.d.ts +30 -13
- package/dist/services/geonames/types.d.ts.map +1 -1
- package/dist/services/geonames/types.js +4 -3
- package/dist/services/geonames/types.js.map +1 -1
- package/dist/services/geonames/upstream-errors.d.ts.map +1 -1
- package/dist/services/geonames/upstream-errors.js +7 -7
- package/dist/services/geonames/upstream-errors.js.map +1 -1
- package/dist/utils/inline-text.d.ts +57 -12
- package/dist/utils/inline-text.d.ts.map +1 -1
- package/dist/utils/inline-text.js +137 -20
- package/dist/utils/inline-text.js.map +1 -1
- package/package.json +15 -13
- package/server.json +10 -24
- 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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
8
|
-
**Zod:** ^4.6.
|
|
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 {
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
284
|
+
Two skill trees live at the project root, written for different readers:
|
|
284
285
|
|
|
285
|
-
|
|
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
|
|
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
|
|
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()`
|
|
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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.
|
|
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.
|
|
8
|
-
**Zod:** ^4.6.
|
|
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 {
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
284
|
+
Two skill trees live at the project root, written for different readers:
|
|
284
285
|
|
|
285
|
-
|
|
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
|
|
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
|
|
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()`
|
|
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.
|
|
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
|
|
42
|
-
# and cross-installs with `--os`/`--cpu`, which pick each
|
|
43
|
-
# optional dependency (native bindings such as DuckDB's) for
|
|
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.
|
|
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.
|
|
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
|