@cyanheads/gbif-biodiversity-mcp-server 0.7.7 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/AGENTS.md +21 -8
  2. package/CLAUDE.md +21 -8
  3. package/Dockerfile +6 -0
  4. package/README.md +59 -41
  5. package/changelog/0.8.x/0.8.0.md +37 -0
  6. package/changelog/0.8.x/0.8.1.md +39 -0
  7. package/changelog/template.md +10 -3
  8. package/dist/index.js +3 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +1 -0
  11. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
  12. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +7 -1
  13. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
  14. package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts.map +1 -1
  15. package/dist/mcp-server/resources/definitions/gbif-species.resource.js +3 -2
  16. package/dist/mcp-server/resources/definitions/gbif-species.resource.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts +24 -4
  18. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js +134 -47
  20. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +30 -4
  22. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts.map +1 -1
  23. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js +22 -90
  24. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
  25. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts +1 -0
  26. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts.map +1 -1
  27. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js +11 -1
  28. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts +11 -6
  30. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js +89 -17
  32. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts +2 -2
  34. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +10 -5
  36. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts +2 -2
  38. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts.map +1 -1
  39. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +5 -2
  40. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
  41. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts +2 -2
  42. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +20 -12
  44. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +11 -4
  46. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +143 -74
  48. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +43 -4
  50. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
  51. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +130 -95
  52. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
  53. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +8 -1
  54. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts.map +1 -1
  55. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +61 -7
  56. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
  57. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +51 -6
  58. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
  59. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +158 -92
  60. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
  61. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +4 -4
  62. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
  63. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +5 -0
  64. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
  65. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +87 -26
  66. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
  67. package/dist/mcp-server/tools/utils.d.ts +287 -8
  68. package/dist/mcp-server/tools/utils.d.ts.map +1 -1
  69. package/dist/mcp-server/tools/utils.js +498 -30
  70. package/dist/mcp-server/tools/utils.js.map +1 -1
  71. package/dist/services/gbif/gbif-service.d.ts +73 -2
  72. package/dist/services/gbif/gbif-service.d.ts.map +1 -1
  73. package/dist/services/gbif/gbif-service.js +227 -92
  74. package/dist/services/gbif/gbif-service.js.map +1 -1
  75. package/dist/services/gbif/types.d.ts +192 -30
  76. package/dist/services/gbif/types.d.ts.map +1 -1
  77. package/dist/services/gbif/types.js +170 -5
  78. package/dist/services/gbif/types.js.map +1 -1
  79. package/package.json +10 -9
  80. package/server.json +5 -5
  81. package/skills/gbif-biodiversity-guide/SKILL.md +85 -0
package/AGENTS.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** @cyanheads/gbif-biodiversity-mcp-server
4
- **Version:** 0.7.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.8.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.
@@ -277,9 +277,18 @@ src/
277
277
 
278
278
  ## Skills
279
279
 
280
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
280
+ Two skill trees live at the project root, written for different readers:
281
281
 
282
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
282
+ | Tree | For | Written by |
283
+ |:-----|:----|:-----------|
284
+ | `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) |
285
+ | `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 |
286
+
287
+ 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.
288
+
289
+ 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.
290
+
291
+ **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.
283
292
 
284
293
  Available skills:
285
294
 
@@ -291,6 +300,7 @@ Available skills:
291
300
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
292
301
  | `add-resource` | Scaffold a new resource definition |
293
302
  | `add-prompt` | Scaffold a new prompt definition |
303
+ | `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 |
294
304
  | `add-service` | Scaffold a new service integration |
295
305
  | `add-test` | Scaffold test file for a tool, resource, or service |
296
306
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -338,7 +348,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
338
348
  | `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` |
339
349
  | `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` |
340
350
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
341
- | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
351
+ | `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) |
342
352
  | `bun run list-skills` | Print the skill registry |
343
353
  | `bun run tree` | Generate directory structure doc |
344
354
  | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -356,7 +366,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
356
366
 
357
367
  ## Bundling
358
368
 
359
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
369
+ `bun 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 ships); 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. 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.
360
370
 
361
371
  **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": ""`.
362
372
 
@@ -423,7 +433,10 @@ import { getMyService } from '@/services/my-domain/my-service.js';
423
433
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
424
434
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
425
435
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
436
+ - [ ] `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"`
426
437
  - [ ] `.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
427
438
  - [ ] `.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
428
439
  - [ ] `.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`
440
+ - [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
441
+ - [ ] 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
429
442
  - [ ] `npm run devcheck` passes
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** @cyanheads/gbif-biodiversity-mcp-server
4
- **Version:** 0.7.7
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
6
- **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
- **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
4
+ **Version:** 0.8.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.
@@ -277,9 +277,18 @@ src/
277
277
 
278
278
  ## Skills
279
279
 
280
- Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
280
+ Two skill trees live at the project root, written for different readers:
281
281
 
282
- **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
282
+ | Tree | For | Written by |
283
+ |:-----|:----|:-----------|
284
+ | `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) |
285
+ | `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 |
286
+
287
+ 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.
288
+
289
+ 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.
290
+
291
+ **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.
283
292
 
284
293
  Available skills:
285
294
 
@@ -291,6 +300,7 @@ Available skills:
291
300
  | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
292
301
  | `add-resource` | Scaffold a new resource definition |
293
302
  | `add-prompt` | Scaffold a new prompt definition |
303
+ | `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 |
294
304
  | `add-service` | Scaffold a new service integration |
295
305
  | `add-test` | Scaffold test file for a tool, resource, or service |
296
306
  | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -338,7 +348,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
338
348
  | `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` |
339
349
  | `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` |
340
350
  | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
341
- | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
351
+ | `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) |
342
352
  | `bun run list-skills` | Print the skill registry |
343
353
  | `bun run tree` | Generate directory structure doc |
344
354
  | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -356,7 +366,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
356
366
 
357
367
  ## Bundling
358
368
 
359
- `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
369
+ `bun 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 ships); 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. 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.
360
370
 
361
371
  **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": ""`.
362
372
 
@@ -423,7 +433,10 @@ import { getMyService } from '@/services/my-domain/my-service.js';
423
433
  - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
424
434
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
425
435
  - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
436
+ - [ ] `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"`
426
437
  - [ ] `.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
427
438
  - [ ] `.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
428
439
  - [ ] `.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`
440
+ - [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
441
+ - [ ] 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
429
442
  - [ ] `npm run devcheck` passes
package/Dockerfile CHANGED
@@ -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
 
@@ -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
  # The 'oven/bun' image already provides a non-root user named 'bun'.
141
147
  # We will use this existing user for enhanced security.
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-0.7.7-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/gbif-biodiversity-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/gbif-biodiversity-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gbif-biodiversity-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.8.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/gbif-biodiversity-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/gbif-biodiversity-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/gbif-biodiversity-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -35,18 +35,18 @@ Species taxonomy, occurrence records, datasets, and publishers from the Global B
35
35
 
36
36
  | Tool | Description |
37
37
  |:---|:---|
38
- | `gbif_match_species` | Match a scientific name to the GBIF backbone, returning its taxon key, confidence, and classification |
39
- | `gbif_bulk_match_species` | Match up to 50 scientific names in one call, one result per name in input order |
40
- | `gbif_get_species` | Fetch a backbone taxon by key: classification, authorship, synonymy, vernacular name, counts |
38
+ | `gbif_match_species` | Match a scientific name to the GBIF backbone or the Catalogue of Life, returning its taxon key, confidence, and classification |
39
+ | `gbif_bulk_match_species` | Match up to 50 scientific names, each optionally narrowed to a kingdom, in one call, one result per name in input order |
40
+ | `gbif_get_species` | Fetch a backbone taxon by key: classification, authorship, synonymy, vernacular name, descendant count |
41
41
  | `gbif_search_species` | Search or browse the backbone by name fragment, rank, or a kingdom, family, or genus name |
42
42
  | `gbif_get_species_classification` | Return a taxon's parent chain, root-first from kingdom to its immediate parent |
43
43
  | `gbif_get_species_children` | List a taxon's direct children, such as the genera in a family or the species in a genus |
44
- | `gbif_search_occurrences` | Search 3.9B+ occurrence records by taxon, place, date, basis of record, presence/absence, and IUCN category |
44
+ | `gbif_search_occurrences` | Search 3.9B+ occurrence records by taxon, place, date, basis of record, publishing organization, type status, establishment means, license, presence/absence, and IUCN category |
45
45
  | `gbif_count_occurrences` | Count occurrences matching a filter without fetching records |
46
46
  | `gbif_get_occurrence` | Fetch one full Darwin Core occurrence record by key |
47
- | `gbif_occurrence_facets` | Aggregate occurrence counts by country, year, dataset, taxon, status, and other dimensions |
47
+ | `gbif_occurrence_facets` | Aggregate occurrence counts by country, year, dataset, taxon, status, and other dimensions, optionally naming taxon, dataset, publishing organization, and GADM area buckets |
48
48
  | `gbif_search_datasets` | Search datasets by keyword, type, publishing country, or publishing or hosting organization |
49
- | `gbif_get_dataset` | Fetch full dataset metadata by UUID: citation, contacts, license, DOI, coverage |
49
+ | `gbif_get_dataset` | Fetch full dataset metadata by UUID: citation, contacts, license, DOI, publishing organization key, coverage |
50
50
  | `gbif_search_publishers` | Search GBIF-registered publishing organizations by name or country |
51
51
 
52
52
  ### Resources
@@ -54,62 +54,77 @@ Species taxonomy, occurrence records, datasets, and publishers from the Global B
54
54
  | Resource | Description |
55
55
  |:---|:---|
56
56
  | `gbif://species/{taxonKey}` | Taxon record from the GBIF backbone: classification, authorship, synonymy status, vernacular name |
57
- | `gbif://dataset/{datasetKey}` | Dataset metadata: title, description, citation, license, contacts, coverage |
57
+ | `gbif://dataset/{datasetKey}` | Dataset metadata: title, description, citation, license, contacts, coverage, publishing organization key |
58
58
 
59
59
  Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`; many MCP clients are tool-only and never surface resources.
60
60
 
61
+ ### Skills
62
+
63
+ | Skill | Description |
64
+ |:---|:---|
65
+ | `gbif-biodiversity-guide` | Agent guide: where each key comes from, which region filter selects which records, and the checks before quoting a count, a trend, or an absence. Installed with the Claude Code and Codex plugins and the `.mcpb`, and served over MCP at `skill://gbif-biodiversity-guide/SKILL.md` |
66
+
61
67
  ## Capability reference
62
68
 
63
69
  ### `gbif_match_species` <sub>tool</sub>
64
70
 
65
- - One scientific `name` (common names go to `gbif_search_species`), with optional `strict`, a `kingdom` to disambiguate, and an expected `rank`
66
- - Returns `taxonKey`, the accepted taxon to pass to the occurrence tools, plus `matchedTaxonKey` when a synonym was resolved, `matchType` (`EXACT`, `FUZZY`, `HIGHERRANK`), `confidence` 0–100 (review below 80), and the classification with a key at each rank
67
- - `matchType` `NONE` fails as `no_match`; a blank `kingdom` fails as `invalid_filter`
71
+ - One scientific `name` (common names go to `gbif_search_species`), with optional `strict`, a `kingdom` to disambiguate, an expected `rank`, and a `checklistKey`
72
+ - Returns `taxonKey`, the accepted taxon to pass to the occurrence tools, plus `matchedTaxonKey` when a synonym was resolved and `acceptedName` (its canonical name, without authorship) whenever GBIF's answer names the accepted taxon, `matchType` (`EXACT`, `FUZZY`, or `HIGHERRANK`: a match at a higher rank, such as a misspelled species falling back to its genus or kingdom, where `taxonKey` covers that whole taxon, or its accepted taxon when the taxon GBIF fell back to is a synonym, and a `notice` names it), `confidence` 0–100 (review below 80; a `HIGHERRANK` match can score above 90), and the classification with a key at each rank
73
+ - `matchType` `NONE` fails as `no_match`, carrying GBIF's note when it gives one (for several equal matches, set `kingdom`); a blank `kingdom` fails as `invalid_filter`
74
+ - `checklistKey` is opt-in. Omitted, or `d7dddbf4-2cf0-4f39-9b2a-bb099caae36c`, matches the GBIF Backbone, whose integer keys the occurrence and species tools take; GBIF no longer updates it. `7ddf754f-d193-4cc9-b351-99906754a03b` matches the Catalogue of Life eXtended Release, the taxonomy GBIF now maintains, where a recently described or revised name can match exactly. Its keys come back as case-sensitive strings in `checklistTaxonKey` (and `checklistMatchedTaxonKey` for a synonym) with no `taxonKey`, `matchedTaxonKey`, or rank keys. The occurrence tools take one as `checklistTaxonKey` with the same `checklistKey`; the species tools, which take a numeric backbone `taxonKey`, do not. `status` may then be `PROVISIONALLY_ACCEPTED` and `matchType` `VARIANT`. The route is `GBIF_BASE_URL` with its trailing `/v1` replaced by `/v2`, so a base URL not ending in `/v1` fails the call as a configuration error
68
75
 
69
76
  ---
70
77
 
71
78
  ### `gbif_bulk_match_species` <sub>tool</sub>
72
79
 
73
- - Scientific `names` with `strict`; the first 50 are processed in input order. With read-limit clamping enabled (default), extra names are returned in `unprocessedNames`, preserving order and duplicates for the next call
74
- - Each result carries `name` and `matchType`, and on a match `taxonKey`, `matchedTaxonKey` (synonyms), and `confidence`; an unmatched name is `NONE`, a failed lookup is `ERROR` with `error` and, when classified, `reason`, and neither fails the batch
80
+ - Scientific `names` with `strict` and `checklistKey` (as on `gbif_match_species`, applied to the whole batch); the first 50 are processed in input order. Each entry is a name string or `{ name, kingdom }`, where the entry's `kingdom` applies to that name alone and resolves a name shared across kingdoms such as *Oenanthe* (a bird genus and a plant genus). A blank `kingdom` on any entry, the unprocessed tail included, fails the call as `invalid_filter`. With read-limit clamping enabled (default), extra entries are returned in `unprocessedNames` exactly as submitted, preserving order and duplicates for the next call
81
+ - Each result carries `name` and `matchType`, and on a match `taxonKey`, `matchedTaxonKey` and `acceptedName` (synonyms), and `confidence`; a `HIGHERRANK` row carries a `note` naming the higher taxon GBIF matched and what its `taxonKey` covers: that taxon, or its accepted taxon when it is a synonym. An unmatched name is `NONE`, with GBIF's explanation in `note` when it gives one (such as several equal matches for a name shared across kingdoms, with a pointer to resubmit the entry with `kingdom` while it has none); a failed lookup is `ERROR` with `error` and, when classified, `reason`, and neither fails the batch
75
82
 
76
83
  ---
77
84
 
78
85
  ### `gbif_get_species` <sub>tool</sub>
79
86
 
80
- - One backbone `taxonKey`; a key not in the backbone fails as `not_found`, one GBIF cannot parse (a fraction, or past the 32-bit range) as `invalid_filter`
81
- - Returns the classification with rank keys, `authorship`, `vernacularName`, `numDescendants`, `numOccurrences`, `publishedIn`, and `parentKey`; a `taxonomicStatus` of `SYNONYM` comes with `acceptedKey` and `accepted`
87
+ - One backbone `taxonKey`, a non-negative integer (`0` is the backbone kingdom *incertae sedis*); a key not in the backbone fails as `not_found`, one past the 32-bit range as `invalid_filter`, and a fraction or negative key fails at the schema
88
+ - Returns the classification with rank keys, `authorship`, `vernacularName`, `numDescendants`, `publishedIn`, and `parentKey`; a `taxonomicStatus` of `SYNONYM` comes with `acceptedKey` and `accepted`. GBIF's taxon record carries no occurrence count: use `gbif_count_occurrences`
82
89
 
83
90
  ---
84
91
 
85
92
  ### `gbif_search_species` <sub>tool</sub>
86
93
 
87
- - `q` name fragment (scientific and vernacular), `rank`, `isExtinct`, and a checklist `datasetKey` (omit for the backbone); up to 1,000 per page with `offset`
88
- - Taxa carry the checklist usage `key`, optional source `datasetKey` and mapped backbone `nubKey`, `rank`, `taxonomicStatus`, classification names, `numOccurrences`, and `numDescendants`; enrichment reports `totalCount`, `endOfRecords`, and the `taxonScope` applied. Occurrence queries use `nubKey` when supplied; otherwise resolve the name with `gbif_match_species`. Omitted `datasetKey` selects GBIF Backbone Taxonomy `d7dddbf4-2cf0-4f39-9b2a-bb099caae36c`
94
+ - `q` name fragment (scientific and vernacular), `rank`, `isExtinct`, and a checklist `datasetKey` (omit for the backbone); up to 1,000 per page with integer `limit` and `offset`, where `offset + limit` may not exceed 100,000
95
+ - Taxa carry the checklist usage `key`, optional source `datasetKey` and mapped backbone `nubKey`, `rank`, `taxonomicStatus`, classification names, `vernacularName` (GBIF's own, else the first English vernacular name containing `q` when `q` is not part of the row's own scientific name, else the first English one), and `numDescendants`. `numOccurrences` appears only when GBIF supplies a positive value; its species search sends a `0` placeholder on every row, so count with `gbif_count_occurrences` on `nubKey` or a `SPECIES_KEY` facet. Enrichment reports `totalCount`, `endOfRecords`, and the `taxonScope` applied. Occurrence queries use `nubKey` when supplied; otherwise resolve the name with `gbif_match_species`. Omitted `datasetKey` selects GBIF Backbone Taxonomy `d7dddbf4-2cf0-4f39-9b2a-bb099caae36c`
89
96
  - `kingdom`, `family`, and `genus` take names, matched exactly as GBIF capitalizes them; the narrowest one scopes, and `kingdom` beside a narrower one disambiguates it. An unknown name fails as `unresolved_taxon_scope`, a genus outside the named family as `conflicting_taxon_scope`, and a scope paired with a non-backbone `datasetKey` matches nothing. A blank filter or a malformed `datasetKey` fails as `invalid_filter`
97
+ - GBIF's species search serves nothing past an `offset + limit` of 100,000, whatever the query. The sum is checked on the applied `limit` before any request, and a larger one fails as `pagination_cap_exceeded`. When `totalCount` exceeds 100,000, every page carries a notice naming the ceiling and the way past it: narrow with `kingdom`, `family`, `genus`, `rank`, `isExtinct`, or `q`, or walk a subtree with `gbif_get_species_children`, which has no ceiling
90
98
 
91
99
  ---
92
100
 
93
101
  ### `gbif_get_species_classification` <sub>tool</sub>
94
102
 
95
103
  - One `taxonKey`; returns `classification` root-first from kingdom to the immediate parent, each entry with `key`, `rank`, `name`, and `scientificName`
96
- - The queried taxon is not included (use `gbif_get_species`); a root taxon returns an empty chain with a notice, an unknown key fails as `not_found`, and one GBIF cannot parse as `invalid_filter`
104
+ - The queried taxon is not included (use `gbif_get_species`); a root taxon returns an empty chain with a notice, an unknown key fails as `not_found`, one past the 32-bit range as `invalid_filter`, and a fraction or negative key fails at the schema
97
105
 
98
106
  ---
99
107
 
100
108
  ### `gbif_get_species_children` <sub>tool</sub>
101
109
 
102
- - One `taxonKey`, up to 1,000 children per page with `offset`; no filters. An unknown key fails as `not_found`, one GBIF cannot parse as `invalid_filter`
103
- - Each child carries `key`, `canonicalName`, `rank`, `taxonomicStatus`, `vernacularName`, `numOccurrences`, and `numDescendants`; GBIF reports no total, so `endOfRecords` (with `truncated` while more remain) is the continuation signal
110
+ - One `taxonKey` (a non-negative integer; `0` is the backbone's *incertae sedis* kingdom), up to 1,000 children per page with integer `limit` and `offset`; no filters. A fraction or negative value fails at the schema; an unknown key fails as `not_found`, one past GBIF's 32-bit range as `invalid_filter`
111
+ - Each child carries `key`, `canonicalName`, `rank`, `taxonomicStatus`, `vernacularName` when GBIF has one, and `numDescendants`; GBIF sends no occurrence count, so use `gbif_count_occurrences` with the child's `key`. GBIF reports no total, so `endOfRecords` (with `truncated` while more remain) is the continuation signal
104
112
  - An empty later page gives offset-reset guidance; only an empty first page for an existing taxon means no direct children
105
113
 
106
114
  ---
107
115
 
108
116
  ### `gbif_search_occurrences` <sub>tool</sub>
109
117
 
110
- - Filters: `taxonKey` (preferred; `scientificName` does not match synonyms), `country`, `publishingCountry`, `stateProvince`, a `decimalLatitude`/`decimalLongitude` box or WKT `geometry`, `year`, `month`, `basisOfRecord`, `hasCoordinate`, `isInCluster`, `coordinateUncertaintyInMeters`, `datasetKey`, `occurrenceStatus`, `iucnRedListCategory`; up to 300 per page
118
+ - Filters: `taxonKey` (preferred: a key names exactly one taxon, where a `scientificName` shared across kingdoms, such as *Oenanthe*, matches nothing; `scientificName` does resolve synonyms), `checklistKey` with `checklistTaxonKey`, `country`, `publishingCountry`, `stateProvince`, `gadmGid`, a `decimalLatitude`/`decimalLongitude` box or WKT `geometry`, `year`, `month`, `basisOfRecord`, `hasCoordinate`, `hasGeospatialIssue`, `isInCluster`, `coordinateUncertaintyInMeters`, `datasetKey`, `publishingOrg`, `catalogNumber`, `institutionCode`, `recordedBy`, `mediaType`, `typeStatus`, `establishmentMeans`, `license`, `occurrenceStatus`, `iucnRedListCategory`; `includeMedia` adds each row's media; up to 300 per page
119
+ - `checklistKey` selects the taxonomy a taxon key is read in. Omitted, or `d7dddbf4-2cf0-4f39-9b2a-bb099caae36c`, is the GBIF Backbone and `taxonKey` takes its integer keys. `7ddf754f-d193-4cc9-b351-99906754a03b` is the Catalogue of Life eXtended Release: scope by one of its keys with `checklistTaxonKey` (such as `3WSJV`, the key `gbif_match_species` returns under the same `checklistKey`), which matches the taxon and every descendant, as `taxonKey` does. A key holds uppercase letters and digits only and is matched case-sensitively; a digit-only one such as `8288` (the genus *Tringa*) is not the Backbone `taxonKey` of the same spelling. `checklistTaxonKey` without the Catalogue of Life `checklistKey`, and `taxonKey` with it, fail as `invalid_filter` before any request, since GBIF answers a key from the other taxonomy with zero records or an unrelated taxon. Rows keep their Backbone `taxonKey` either way
120
+ - `gadmGid` is an uppercase GADM GID (`ESP.1_1`) GBIF derives from each record's coordinates, so records without coordinates match none; take one from a `GADM_LEVEL_0_GID`–`GADM_LEVEL_3_GID` facet or `gbif_get_occurrence`'s `gadm` field. `catalogNumber` and `institutionCode` match the whole value case-insensitively, `recordedBy` one collector exactly and case-sensitively (take a spelling from a `RECORDED_BY` facet), and `mediaType` is `StillImage`, `MovingImage`, `Sound`, or `InteractiveResource`. `taxonKey`, `month`, `limit`, and `offset` are integers
121
+ - `publishingOrg` is the UUID of the organization that published the records, across all its datasets; take one from `gbif_search_publishers`, a dataset's or an occurrence record's `publishingOrganizationKey`, or a `PUBLISHING_ORG` facet. It is not the organization hosting the installation, and not `publishingCountry`
122
+ - `typeStatus` and `establishmentMeans` are matched case-insensitively against GBIF's TypeStatus (51 concepts) and EstablishmentMeans (7) vocabularies, then sent and echoed in the concept's own spelling. A value matches its concept and every narrower one: `Type` covers every kind of type, `Lectotype` covers `Isolectotype`, `native` covers `nativeEndemic` and `nativeReintroduced`, `introduced` covers `introducedAssistedColonisation`. A value naming no concept fails as `invalid_filter` listing them
123
+ - `license` is `CC0_1_0`, `CC_BY_4_0`, or `CC_BY_NC_4_0`; a blank or other value fails at the schema as `-32602`, not `invalid_filter`
124
+ - `hasGeospatialIssue: true` keeps records GBIF flagged with a spatial issue (zero coordinates, coordinates out of range, outside the stated country); `false` keeps unflagged ones. GBIF often drops the coordinates of a flagged record, so pair `false` with `hasCoordinate: true` for records to map
111
125
  - All supplied spatial filters intersect: combining `geometry` with latitude or longitude ranges restricts results to their overlap
112
- - Records carry `key`, `taxonKey`, `taxonomicStatus`, coordinates, `eventDate` and `eventTime`, `basisOfRecord`, `occurrenceStatus`, `iucnRedListCategory`, `datasetKey`, and `issues`; enrichment reports `totalCount`, `endOfRecords`, and the `occurrenceStatus` applied
126
+ - `decimalLatitude`, `decimalLongitude`, and `coordinateUncertaintyInMeters` are ranges written `"min,max"`, both ends inclusive. A value without a comma is an exact match, not a range around it, and every result carries a notice saying so. `coordinateUncertaintyInMeters` also takes `*` for one open end (`"*,1000"`); a bare `*`, padded or not, fails as `invalid_filter`
127
+ - Records carry `key`, `taxonKey`, `taxonomicStatus`, coordinates, `eventDate` and `eventTime`, `basisOfRecord`, `occurrenceStatus`, `iucnRedListCategory`, `datasetKey`, `institutionCode`, `catalogNumber`, and `issues`, plus each of these where GBIF has it: `acceptedTaxonKey` and `acceptedScientificName` (the accepted taxon behind a synonym record, the name with authorship), `publishingOrganizationKey`, `license` (the record's Creative Commons URL; the `license` filter takes the code form), `rightsHolder`, `recordNumber` (the collector's number, not `catalogNumber`), `elevation` and `depth` in meters, and `typeStatus` and `establishmentMeans` (both go back unchanged to their filters). `occurrenceStatus` reads `DETECTED` or `NOT_DETECTED`, as GBIF serves it. With `includeMedia`, each row also carries every media item of its record as `{ type, identifier, license, rightsHolder }` in source order, whatever `mediaType` selected; it is off by default because it adds to both response surfaces. Enrichment reports `totalCount`, `endOfRecords`, and the `occurrenceStatus` applied
113
128
  - Search, count and facets echo the same `scope`: effective supplied biological filters, with `occurrenceStatus` always included and pagination controls excluded. `ANY` is echoed but omitted upstream. `taxonKey` and `scientificName` combine with OR. All 11 GBIF basis-of-record values are accepted, including `FOSSIL_SPECIMEN`, `OBSERVATION`, and `UNKNOWN`
114
129
  - Latitude, longitude and coordinate uncertainty are independent optional facts; text renders each supplied value, including zero, in decimal degrees or meters
115
130
  - `offset + limit` caps at 100,001 and GBIF has no cursor; a deeper request fails as `pagination_cap_exceeded`, and a larger match is reached by partitioning on a `DATASET_KEY` facet from `gbif_occurrence_facets`. A rejected filter value fails as `invalid_filter`
@@ -125,38 +140,40 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
125
140
 
126
141
  ### `gbif_get_occurrence` <sub>tool</sub>
127
142
 
128
- - One `occurrenceKey` from a search result; an unknown key fails as `not_found`, one GBIF cannot parse as `invalid_filter`
129
- - The full Darwin Core record: `occurrenceStatus` (`ABSENT` is a survey that found nothing, not a sighting), coordinates, GADM levels 0–3 under `gadm`, dates with `eventTime`, `taxonomicStatus`, `iucnRedListCategory`, institution, collection, and catalog codes, `recordedBy` and `identifiedBy`, `media`, `identifiers`, and `issues`
143
+ - One `occurrenceKey` from a search result, a positive integer (a non-positive or fractional key is rejected at the schema); an unknown key fails as `not_found`
144
+ - The full Darwin Core record: `occurrenceStatus` (`NOT_DETECTED` is a survey that found nothing, not a sighting; the `occurrenceStatus` filter takes `ABSENT` or `NOT_DETECTED` for it), coordinates with `elevation` and `depth` in meters, GADM levels 0–3 under `gadm`, dates with `eventTime`, `taxonomicStatus`, `acceptedTaxonKey` and `acceptedScientificName` (the accepted taxon behind a synonym record), `iucnRedListCategory`, institution, collection, and catalog codes, `recordedBy`, `identifiedBy`, and `recordNumber`, `typeStatus` and `establishmentMeans`, `license` (the Creative Commons URL), `rightsHolder`, and `publishingOrganizationKey` (goes into `publishingOrg`), `media` with each item's `rightsHolder`, `identifiers`, and `issues`
130
145
 
131
146
  ---
132
147
 
133
148
  ### `gbif_occurrence_facets` <sub>tool</sub>
134
149
 
135
- - `facet` is one of `COUNTRY`, `STATE_PROVINCE`, `YEAR`, `MONTH`, `BASIS_OF_RECORD`, `DATASET_KEY`, `PUBLISHING_COUNTRY`, `KINGDOM_KEY`, `PHYLUM_KEY`, `CLASS_KEY`, `ORDER_KEY`, `FAMILY_KEY`, `GENUS_KEY`, `SPECIES_KEY`, `OCCURRENCE_STATUS`, `IUCN_RED_LIST_CATEGORY`; up to 100 values per page (`facetLimit`, default 10), paged with `facetOffset`
150
+ - `facet` is one of `COUNTRY`, `STATE_PROVINCE`, `YEAR`, `MONTH`, `BASIS_OF_RECORD`, `DATASET_KEY`, `PUBLISHING_COUNTRY`, `KINGDOM_KEY`, `PHYLUM_KEY`, `CLASS_KEY`, `ORDER_KEY`, `FAMILY_KEY`, `GENUS_KEY`, `SPECIES_KEY`, `OCCURRENCE_STATUS`, `IUCN_RED_LIST_CATEGORY`, `GADM_LEVEL_0_GID`–`GADM_LEVEL_3_GID`, `INSTITUTION_CODE`, `MEDIA_TYPE`, `RECORDED_BY`, `PUBLISHING_ORG`, `TYPE_STATUS`, `ESTABLISHMENT_MEANS`, `LICENSE`; up to 100 values per page (`facetLimit`, default 10), paged with `facetOffset`
136
151
  - Accepts every biological filter listed for `gbif_search_occurrences`, with the same constraints and spatial intersection. Repeat them on the facet call and each partition search to preserve the population. Returns `totalOccurrences` and `counts` ranked by count; a rejected scope value fails as `invalid_filter`
137
152
  - Each facet request fetches one extra bucket to prove continuation. `truncated`, `shown`, and `cap` appear only when that bucket exists; advance `facetOffset` by the exposed page size. An exactly full final page carries no truncation flag. Empty later pages give offset-reset guidance; an empty first page distinguishes zero matching occurrences from a dimension with no data
138
- - `DATASET_KEY` buckets sum to the scope's full total, so it is the facet for partitioning a search too large to page; `YEAR`, `MONTH`, `STATE_PROVINCE`, and `SPECIES_KEY` drop records that lack the field. Pass `facet: OCCURRENCE_STATUS` with `occurrenceStatus: ANY` for the presence/absence split
153
+ - `DATASET_KEY` buckets sum to the scope's full total, so it is the facet for partitioning a search too large to page; `YEAR`, `MONTH`, `STATE_PROVINCE`, `SPECIES_KEY`, `INSTITUTION_CODE`, `MEDIA_TYPE`, `RECORDED_BY`, `TYPE_STATUS`, and `ESTABLISHMENT_MEANS` drop records that lack the field, and the GADM levels drop records without coordinates or outside every GADM unit at that level. `MEDIA_TYPE` and `RECORDED_BY` buckets overlap (a record with two media types or two collectors counts in each), and so do `TYPE_STATUS` and `ESTABLISHMENT_MEANS` (a record counts under its concept and every broader one: an `Isolectotype` also under `Lectotype` and `Type`), so their sums can exceed `totalOccurrences`. `INSTITUTION_CODE` buckets come back lowercased and `institutionCode` takes them unchanged; `PUBLISHING_ORG`, `TYPE_STATUS`, `ESTABLISHMENT_MEANS`, and `LICENSE` buckets go back unchanged as `publishingOrg`, `typeStatus`, `establishmentMeans`, and `license`, and `GADM_LEVEL_*_GID` buckets as `gadmGid`. `OCCURRENCE_STATUS` buckets read `DETECTED` and `NOT_DETECTED`, which the `occurrenceStatus` filter takes unchanged. `KINGDOM_KEY`–`SPECIES_KEY` buckets are Backbone keys for `taxonKey`, or, under the Catalogue of Life `checklistKey`, Catalogue of Life keys for `checklistTaxonKey`. Pass `facet: OCCURRENCE_STATUS` with `occurrenceStatus: ANY` for the presence/absence split
154
+ - `includeLabels: true` names each bucket on a `KINGDOM_KEY`–`SPECIES_KEY`, `DATASET_KEY`, `PUBLISHING_ORG`, or `GADM_LEVEL_0_GID`–`GADM_LEVEL_3_GID` page: `counts[].label` is the taxon's `canonicalName`, the dataset `title`, the organization `title`, or the administrative area's `name`. Taxon buckets are looked up in the taxonomy `checklistKey` selects, never by the shape of the key, since `8288` is a Catalogue of Life genus and a Backbone family. It costs one GBIF request per exposed bucket (never the lookahead), at most 8 in flight server-wide, no retries, and one 10 s deadline per page; a bucket whose lookup fails, finds no name, or misses it has no `label` and is counted in `notice`, which points an unlabeled GADM bucket at `gbif_get_occurrence`'s `gadm` field. Other dimensions ignore it, and without it a facet call is one request. Labeling Catalogue of Life buckets reads the `/v2` route, so a `GBIF_BASE_URL` not ending in `/v1` fails that call as a configuration error
139
155
 
140
156
  ---
141
157
 
142
158
  ### `gbif_search_datasets` <sub>tool</sub>
143
159
 
144
- - Filters: `q`, `type` (`OCCURRENCE`, `CHECKLIST`, `METADATA`, `SAMPLING_EVENT`), `publishingCountry`, `publishingOrg`, `hostingOrg`; up to 1,000 per page
145
- - Returns `key`, `title`, `type`, `license`, `doi`, `recordCount`, and a 300-character `description` preview, with `descriptionTruncated` flagging a cut (`gbif_get_dataset` has the full text)
160
+ - Filters: `q`, `type` (`OCCURRENCE`, `CHECKLIST`, `METADATA`, `SAMPLING_EVENT`), `publishingCountry`, `publishingOrg`, `hostingOrg`; up to 1,000 per page, where `offset + limit` may not exceed 125,000
161
+ - Returns `key`, `title`, `type`, `license`, `doi`, `recordCount`, `publishingOrganizationKey` and `publishingOrganizationTitle`, and a 300-character `description` preview, with `descriptionTruncated` flagging a cut (`gbif_get_dataset` has the full text). `publishingOrganizationKey` goes back in as `publishingOrg`. `limit` and `offset` are integers
146
162
  - `publishingOrg` matches the organization whose data it is and is the usual chain from `gbif_search_publishers`; `hostingOrg` matches the organization whose installation serves it, and the two together intersect. Both take the lowercase UUID form; anything else, like any rejected filter value, fails as `invalid_filter`
163
+ - GBIF's dataset search serves nothing past an `offset + limit` of 125,000. The sum is checked on the applied `limit` before any request, and a larger one fails as `pagination_cap_exceeded`. When `totalCount` exceeds 125,000, every page carries a notice naming the ceiling and the way past it: `type` splits the index with no gap or overlap, since every dataset has exactly one of the four types, and `q`, `publishingCountry`, `publishingOrg`, and `hostingOrg` narrow it further
147
164
 
148
165
  ---
149
166
 
150
167
  ### `gbif_get_dataset` <sub>tool</sub>
151
168
 
152
169
  - One `datasetKey` UUID and `contactLimit` (default 10, max 100; `0` drops contact detail but keeps `contactsTotal`); a malformed key fails as `invalid_filter`, an unknown one as `not_found`
153
- - Returns `description`, `citationText`, `license`, `doi`, `recordCount`, `numConstituents`, `contacts` with `contactsTotal` and `contactsReturned`, `temporalCoverages`, and `geographicCoverages`
170
+ - Returns `description`, `citationText`, `license`, `doi`, `publishingOrganizationKey` (goes into `gbif_search_datasets` as `publishingOrg`; the detail record carries no organization name), `recordCount`, `numConstituents`, `contacts` with `contactsTotal` and `contactsReturned`, `temporalCoverages`, and `geographicCoverages`
154
171
 
155
172
  ---
156
173
 
157
174
  ### `gbif_search_publishers` <sub>tool</sub>
158
175
 
159
- - `q` name fragment and `country` (alpha-2 or alpha-3, any case); up to 1,000 per page
176
+ - `q` name fragment and `country` (alpha-2 or alpha-3, any case); up to 1,000 per page with integer `limit` and `offset`
160
177
  - Returns organization `key`, `title`, `country`, and `city`; the key chains into `gbif_search_datasets` as `publishingOrg`
161
178
  - A blank `q`, an empty `country`, or a country GBIF cannot parse fails as `invalid_filter`
162
179
 
@@ -165,13 +182,13 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
165
182
  ### `gbif://species/{taxonKey}` <sub>resource</sub>
166
183
 
167
184
  - Taxon record as `application/json`: classification names, `authorship`, `vernacularName`, `taxonomicStatus` with `acceptedKey` and `accepted`, `numDescendants`
168
- - `taxonKey` is a whole signed decimal integer within the signed 32-bit range. The segment is URI-decoded once and surrounding whitespace is trimmed; leading `+`, zero padding and their percent-encoded equivalents are accepted. An unknown key fails as `not_found`; malformed escapes, suffixes, fractions, exponents, hexadecimal forms, embedded whitespace and out-of-range values fail as `invalid_filter` before a request. Use a backbone key from `gbif_match_species` or a search result's `nubKey`, resolving its name when that mapping is absent
185
+ - `taxonKey` is a whole signed decimal integer within the signed 32-bit range; `0` is the backbone kingdom *incertae sedis*. The segment is URI-decoded once and surrounding whitespace is trimmed; leading `+`, zero padding and their percent-encoded equivalents are accepted. An unknown key fails as `not_found`; malformed escapes, suffixes, fractions, exponents, hexadecimal forms, embedded whitespace and out-of-range values fail as `invalid_filter` before a request. Use a backbone key from `gbif_match_species` or a search result's `nubKey`, resolving its name when that mapping is absent
169
186
 
170
187
  ---
171
188
 
172
189
  ### `gbif://dataset/{datasetKey}` <sub>resource</sub>
173
190
 
174
- - The `gbif_get_dataset` record as `application/json`, with contacts fixed at 10
191
+ - The `gbif_get_dataset` record as `application/json`, including `publishingOrganizationKey`, with contacts fixed at 10
175
192
  - `datasetKey` comes from `gbif_search_datasets` or an occurrence record; an unknown key fails as `not_found`, a malformed one as `invalid_filter`
176
193
 
177
194
  ## Features
@@ -180,17 +197,18 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
180
197
 
181
198
  GBIF-specific:
182
199
 
183
- - GBIF API v1 species, occurrence, dataset, and organization endpoints, keyless, with an identifying `User-Agent` on every request
200
+ - GBIF API v1 species, occurrence, dataset, organization, and GADM endpoints, plus v2 species matching for the Catalogue of Life, keyless, with an identifying `User-Agent` on every request
184
201
  - Synonym-safe keys: `gbif_match_species` resolves a synonym to its accepted taxon, and the occurrence tools filter on that `taxonKey`
185
- - Sightings by default: the search, count, and facet tools default `occurrenceStatus` to `PRESENT`, excluding absence records. Dataset `recordCount` spans every status, so it runs higher than a `gbif_count_occurrences` total for the same key
186
- - Strict country codes: on the occurrence tools and `gbif_search_datasets`, `country` (where a record was observed) and `publishingCountry` (the publisher's country) accept only uppercase ISO 3166-1 alpha-2, because other forms silently match nothing there. `stateProvince` matches verbatim and case-sensitively, so take values from a `STATE_PROVINCE` facet
187
- - Blank filters rejected: GBIF reads an empty parameter as no filter, so an optional filter sent blank or whitespace-only fails as `invalid_filter` instead of widening the query. Omit a field to leave it off
202
+ - Opt-in Catalogue of Life matching: `checklistKey` on both match tools matches against the Catalogue of Life eXtended Release and returns string keys in separate fields, and the occurrence tools take them as `checklistTaxonKey`, so a Catalogue of Life key never lands in a backbone integer field
203
+ - Sightings by default: the search, count, and facet tools default `occurrenceStatus` to `PRESENT`, excluding absence records. Records and facet buckets read `DETECTED` and `NOT_DETECTED`, which the filter takes as well as `PRESENT` and `ABSENT`. Dataset `recordCount` spans every status, so it can exceed a `gbif_count_occurrences` total for the same key
204
+ - Strict country codes: `country` (where a record was observed) and `publishingCountry` (the publisher's country) on the occurrence tools, and `publishingCountry` on `gbif_search_datasets`, accept only uppercase ISO 3166-1 alpha-2, because other forms silently match nothing there. `stateProvince` matches verbatim and case-sensitively, so take values from a `STATE_PROVINCE` facet
205
+ - Blank filters rejected: GBIF reads an empty parameter as no filter, so an optional filter sent blank or whitespace-only fails as `invalid_filter` instead of widening the query. The exception is a blank `country` or `publishingCountry` on the occurrence tools, or a blank `publishingCountry` on `gbif_search_datasets`, which fails earlier at the uppercase pattern as `-32602 invalid_arguments`, as does a blank or unknown `license` at its enum. Omit a field to leave it off
188
206
 
189
207
  Agent-friendly output:
190
208
 
191
- - Scope echo: enrichment reports `totalCount`, `endOfRecords`, the `occurrenceStatus` applied, and the resolved `taxonScope`, with notices on empty results, over-cap totals, and a `stateProvince` that matched nothing
209
+ - Scope echo: enrichment reports `totalCount`, `endOfRecords`, the `occurrenceStatus` applied, and the resolved `taxonScope`, with notices on empty results, over-cap totals, and a `scientificName`, `stateProvince`, `gadmGid`, or `recordedBy` that matched nothing
192
210
  - Graceful partial failure: `gbif_bulk_match_species` returns a `NONE` or `ERROR` row per name instead of failing the batch
193
- - Typed errors: `invalid_filter`, `not_found`, `no_match`, `unresolved_taxon_scope`, `conflicting_taxon_scope`, and `pagination_cap_exceeded`, each with a recovery hint
211
+ - Typed errors: `invalid_filter`, `not_found`, `no_match`, `unresolved_taxon_scope`, `conflicting_taxon_scope`, and `pagination_cap_exceeded` (on `gbif_search_occurrences`, `gbif_search_species`, and `gbif_search_datasets`), each with a recovery hint
194
212
  - Sparse fields omitted rather than null-filled: `extinct` appears only on taxa GBIF explicitly flags
195
213
  - Dataset metadata preserves temporal ranges, single dates, and verbatim periods such as `1975-current`; unsupported coverage entries are disclosed. An unavailable supplementary record count carries `recordCountNotice` while retaining metadata
196
214
  - Publisher descriptions retain paragraph breaks and decode numeric character references once; Markdown output renders publisher text literally
@@ -273,7 +291,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
273
291
 
274
292
  ### Prerequisites
275
293
 
276
- - [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
294
+ - [Bun v1.4.4](https://bun.sh/) or higher (or Node.js v24+).
277
295
  - No credentials: the GBIF endpoints this server calls are public.
278
296
 
279
297
  ### Installation
@@ -307,8 +325,8 @@ cp .env.example .env
307
325
 
308
326
  | Variable | Description | Default |
309
327
  |:---|:---|:---|
310
- | `GBIF_BASE_URL` | GBIF API base URL. | `https://api.gbif.org/v1` |
311
- | `GBIF_CLAMP_READ_LIMITS` | Clamp oversized read limits to the documented caps and disclose requested/applied values. Bulk matching processes the first 50 names and returns the remainder in `unprocessedNames`. Set `false` to advertise and enforce rejecting maxima instead. Strict boolean parsing rejects malformed values. | `true` |
328
+ | `GBIF_BASE_URL` | GBIF API base URL. Keep the trailing `/v1`: `checklistKey` on the match tools, and `includeLabels` on `gbif_occurrence_facets` under the Catalogue of Life `checklistKey`, call the `/v2` route derived by replacing it, and fail as a configuration error without it. | `https://api.gbif.org/v1` |
329
+ | `GBIF_CLAMP_READ_LIMITS` | Clamp oversized whole-number read limits to the documented caps and disclose requested/applied values. Bulk matching processes the first 50 names and returns the remainder in `unprocessedNames`. Set `false` to advertise and enforce rejecting maxima instead. Strict boolean parsing rejects malformed values. | `true` |
312
330
  | `GBIF_REQUEST_TIMEOUT_MS` | Per-request HTTP timeout, in ms. | `10000` |
313
331
  | `GBIF_USER_AGENT` | `User-Agent` sent on every GBIF request. GBIF asks integrators to identify themselves with a contact URL or email. | server name, version, and repository URL |
314
332
  | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
@@ -0,0 +1,37 @@
1
+ ---
2
+ summary: "Published agent skill gbif-biodiversity-guide, new occurrence filters (gadmGid, catalogNumber, institutionCode, recordedBy, mediaType), labeled facet buckets, and integer-typed numeric inputs."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.8.0 — 2026-11-01
8
+
9
+ ## Added
10
+
11
+ - **Published agent skill `gbif-biodiversity-guide`** (root `skills/`), served over MCP at `skill://gbif-biodiversity-guide/SKILL.md` and shipped with the plugin and `.mcpb` installs — the checks for choosing a region filter, reading counts and trends, reconciling a name list, tracing records to collections and publishers, and concluding a taxon is absent.
12
+ - **`gadmGid` filter and `GADM_LEVEL_0_GID` … `GADM_LEVEL_3_GID` facets** on the occurrence tools select records by normalized GADM admin area instead of the verbatim `stateProvince` string. A blank or malformed GID fails as `invalid_filter`; one that matches nothing returns a notice naming the GADM facets. ([#77](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/77))
13
+ - **`catalogNumber`, `institutionCode`, `recordedBy`, and `mediaType` filters** and `INSTITUTION_CODE`, `MEDIA_TYPE`, and `RECORDED_BY` facets on the occurrence tools; `gbif_search_occurrences` rows carry `institutionCode` and `catalogNumber`. A `recordedBy` that matches nothing returns a notice pointing at the `RECORDED_BY` facet. ([#78](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/78))
14
+ - **`gbif_occurrence_facets` `includeLabels`** adds `counts[].label` (taxon `canonicalName` or dataset `title`) to `KINGDOM_KEY` … `SPECIES_KEY` and `DATASET_KEY` buckets. Opt-in, one request per bucket under a 10 s deadline; unlabeled buckets are counted in `notice`. ([#76](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/76))
15
+ - **`publishingOrganizationKey`** on `gbif_get_dataset`, `gbif_search_datasets` rows, and `gbif://dataset/{datasetKey}`, plus `publishingOrganizationTitle` on search rows; the key goes back in as `publishingOrg`. ([#79](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/79))
16
+ - **`GBIF_USER_AGENT`** is forwarded through the Claude Code and Codex plugin manifests; root `plugin.json` and `mcp.json` added for Agent Plugins clients.
17
+
18
+ ## Changed
19
+
20
+ - **22 numeric inputs are now integer-typed** — `taxonKey` (6 tools), `occurrenceKey`, `limit` and `offset` (5 paged tools), `facetLimit`, `facetOffset`, `month` (3 occurrence tools). Fractions, negative `taxonKey`, non-positive `occurrenceKey`, and integers past 2^53−1 now fail as `invalid_arguments` before any request; previously fractions were sent upstream or clamped, and values past 2^53−1 clamped. Over-cap integers still clamp. ([#75](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/75))
21
+ - **`gbif_match_species` and `gbif_bulk_match_species` disclose `HIGHERRANK` matches** — a `notice` (single) or per-row `note` (bulk) names the matched rank and taxon and says what `taxonKey` covers — that whole taxon, or its accepted taxon when the fallback taxon is a synonym; GBIF's ambiguity note on a `NONE` surfaces in the `no_match` message and bulk row. `taxonKey` values are unchanged. ([#73](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/73))
22
+ - **`gbif_search_species` omits `numOccurrences`** unless GBIF supplies a positive value, and `vernacularName` now comes from the row's English `vernacularNames[]` entries. ([#74](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/74))
23
+ - **`.mcpb` bundle cleaner** also strips node-gyp build output and build-only package files, and `.mcpbignore` lists every root dev path.
24
+
25
+ ## Fixed
26
+
27
+ - **Taxon key `0`** (the *incertae sedis* kingdom) resolves on `gbif_get_species`, `gbif://species/0`, and `gbif_match_species`, and `format()` renders `(0)` after a key. ([#80](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/80))
28
+ - **`.mcpb` bundle cleaner** no longer deletes a dependency's own `skills/` code directory (the MCP SDK's `dist/ext/skills/`), whose removal stops the bundle starting.
29
+
30
+ ## Dependencies
31
+
32
+ - `@cyanheads/mcp-ts-core` ^0.13.15 → ^0.13.18.
33
+ - `@biomejs/biome` ^2.6.2 → ^2.6.4.
34
+ - `@types/node` ^26.6.5 → ^26.6.6.
35
+ - `ignore` ^7.0.13 → ^7.0.14.
36
+ - `tsc-alias` ^1.9.8 → ^1.9.9.
37
+ - `@modelcontextprotocol/server` 2.3.1 → 2.4.0 (transitive).
@@ -0,0 +1,39 @@
1
+ ---
2
+ summary: "Catalogue of Life eXtended Release keys on the match and occurrence tools, new occurrence filters and facets, richer occurrence records, per-name kingdoms in bulk matching, and offset ceilings on species and dataset search."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.8.1 — 2026-11-12
8
+
9
+ ## Added
10
+
11
+ - **`checklistKey` on `gbif_match_species` and `gbif_bulk_match_species`** (opt-in) selects the Catalogue of Life eXtended Release, `7ddf754f-d193-4cc9-b351-99906754a03b`, the taxonomy GBIF now maintains in place of the frozen Backbone. Matches return string keys as `checklistTaxonKey` / `checklistMatchedTaxonKey`; `taxonKey` is absent. The `/v2` route is derived from a `GBIF_BASE_URL` ending in `/v1`, and any other base fails as a ConfigurationError. ([#89](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/89))
12
+ - **`checklistKey` + `checklistTaxonKey` on the occurrence tools** scope by a Catalogue of Life key (sent upstream as `taxonKey`). `taxonKey` is rejected alongside them, and `KINGDOM_KEY` … `SPECIES_KEY` bucket labels follow `checklistKey`, never key shape. ([#90](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/90))
13
+ - **`publishingOrg`, `hasGeospatialIssue`, `typeStatus`, `establishmentMeans`, and `license` filters** on the occurrence tools, and `PUBLISHING_ORG`, `TYPE_STATUS`, `ESTABLISHMENT_MEANS`, and `LICENSE` facets, with `PUBLISHING_ORG` bucket labels. `typeStatus` and `establishmentMeans` are canonicalized against GBIF's vocabularies and match narrower concepts too. ([#86](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/86))
14
+ - **`gbif_get_occurrence` and every `gbif_search_occurrences` row** carry `license`, `rightsHolder`, `publishingOrganizationKey`, `acceptedTaxonKey`, `acceptedScientificName`, `recordNumber`, `elevation`, `depth`, `typeStatus`, and `establishmentMeans`; media items carry `rightsHolder`. `gbif_search_occurrences` returns media only with the new `includeMedia`. ([#87](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/87))
15
+ - **`gbif_bulk_match_species` entries** are a name string or `{ name, kingdom }`, and `unprocessedNames` returns entries as submitted. A blank entry `kingdom` fails as `invalid_filter`. ([#81](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/81))
16
+ - **`acceptedName` on synonym matches** from `gbif_match_species` and `gbif_bulk_match_species`, read from the match response with no extra request. ([#85](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/85))
17
+ - **`gbif_occurrence_facets` `includeLabels`** names `GADM_LEVEL_0_GID` … `GADM_LEVEL_3_GID` buckets; a bucket whose lookup returns an empty 200 stays unlabeled. ([#88](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/88))
18
+ - **`occurrenceStatus`** on the occurrence tools also takes `DETECTED` and `NOT_DETECTED`, the names GBIF serves on records and `OCCURRENCE_STATUS` buckets, sent and echoed as given. The default stays `PRESENT`.
19
+ - **A `scientificName` filter that matches nothing** returns a notice naming the cross-kingdom-homonym reading and the `gbif_match_species` + `kingdom` route.
20
+
21
+ ## Changed
22
+
23
+ - **`.mcpb` bundle cleaner** also strips `AGENTS.md` and `CLAUDE.md` at any dependency's root and `SKILL.md` files anywhere under `node_modules/`.
24
+
25
+ ## Fixed
26
+
27
+ - **`gbif_search_species` and `gbif_search_datasets` check `offset + limit` against GBIF's ceilings** (100,000 and 125,000) on the applied limit before any request, failing as `pagination_cap_exceeded` instead of a retried 500 or a blank-filter error. A total past the ceiling draws a notice naming the narrowing routes. ([#84](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/84))
28
+ - **A comma-less `decimalLatitude`, `decimalLongitude`, or `coordinateUncertaintyInMeters`** matches only that exact value and now draws a notice on every result, across search, count, and facets. A bare `*` (padded too) fails as `invalid_filter` instead of GBIF's bare 404. ([#83](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/83))
29
+ - **`scientificName` descriptions** no longer claim the filter misses synonyms; it resolves them.
30
+ - **`gbif_bulk_match_species`** escapes the markdown heading of each name, and its per-name catch rethrows caller cancellation and ConfigurationError instead of recording them as per-name errors.
31
+ - **`gbif_occurrence_facets` `includeLabels` under the Catalogue of Life** refuses a non-`/v1` `GBIF_BASE_URL` before the aggregation request.
32
+
33
+ ## Dependencies
34
+
35
+ - `@cyanheads/mcp-ts-core` ^0.13.18 → ^0.13.22 (GBIF's error body no longer rides on `error.data`; its explanation is still folded into the error message).
36
+ - `@biomejs/biome` ^2.6.4 → ^2.6.6.
37
+ - `tsc-alias` ^1.9.9 → ^1.9.10.
38
+ - `vitest` ^5.0.5 → ^5.1.0.
39
+ - `engines.bun` >=1.4.0 → >=1.4.4.
@@ -116,14 +116,21 @@ security: false
116
116
  resolves to whatever real item already owns 42, and timeline previews pull
117
117
  in that unrelated item's metadata.
118
118
 
119
+ Outside reporters: when the issue or PR came from outside the project
120
+ (`git-wrapup` step 5 says how to tell), thank its author in the same
121
+ parenthetical, profile linked by full URL for the same reason:
122
+
123
+ ([#38](https://github.com/cyanheads/mcp-ts-core/issues/38), thanks [@octocat](https://github.com/octocat)!)
124
+
119
125
  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
120
126
  via `gh release create --notes-from-tag`. It is a condensed digest of this
121
127
  entry, never a copy, and its format is owned by the `release-and-publish`
122
128
  skill (step 4, "Create the annotated tag"): a short subject line without the
123
129
  version, flat headline bullets — no Keep-a-Changelog section headers, no
124
- gates line — at most one deps line, issue backlinks, and the changelog link
125
- last. In release-PR mode the `git-wrapup` skill authors those bullets as the
126
- PR body's `## Changes` and the tag copies them.
130
+ gates line — at most one deps line, issue backlinks with any outside-reporter
131
+ thanks, and the changelog link last. In release-PR mode the `git-wrapup`
132
+ skill authors those bullets as the PR body's `## Changes` and the tag copies
133
+ them.
127
134
  -->
128
135
 
129
136
  ## Added