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