@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.
- package/AGENTS.md +21 -8
- package/CLAUDE.md +21 -8
- package/Dockerfile +6 -0
- package/README.md +59 -41
- package/changelog/0.8.x/0.8.0.md +37 -0
- package/changelog/0.8.x/0.8.1.md +39 -0
- package/changelog/template.md +10 -3
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +1 -0
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +7 -1
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-species.resource.js +3 -2
- package/dist/mcp-server/resources/definitions/gbif-species.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts +24 -4
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js +134 -47
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +30 -4
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js +22 -90
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts +1 -0
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js +11 -1
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts +11 -6
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js +89 -17
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +10 -5
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +5 -2
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +20 -12
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +11 -4
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +143 -74
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +43 -4
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +130 -95
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +8 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +61 -7
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +51 -6
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +158 -92
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +4 -4
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +5 -0
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +87 -26
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/utils.d.ts +287 -8
- package/dist/mcp-server/tools/utils.d.ts.map +1 -1
- package/dist/mcp-server/tools/utils.js +498 -30
- package/dist/mcp-server/tools/utils.js.map +1 -1
- package/dist/services/gbif/gbif-service.d.ts +73 -2
- package/dist/services/gbif/gbif-service.d.ts.map +1 -1
- package/dist/services/gbif/gbif-service.js +227 -92
- package/dist/services/gbif/gbif-service.js.map +1 -1
- package/dist/services/gbif/types.d.ts +192 -30
- package/dist/services/gbif/types.d.ts.map +1 -1
- package/dist/services/gbif/types.js +170 -5
- package/dist/services/gbif/types.js.map +1 -1
- package/package.json +10 -9
- package/server.json +5 -5
- 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.
|
|
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.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
|
-
|
|
280
|
+
Two skill trees live at the project root, written for different readers:
|
|
281
281
|
|
|
282
|
-
|
|
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
|
|
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.
|
|
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.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
|
-
|
|
280
|
+
Two skill trees live at the project root, written for different readers:
|
|
281
281
|
|
|
282
|
-
|
|
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
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/gbif-biodiversity-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/gbif-biodiversity-mcp-server) [](https://www.typescriptlang.org/) [](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,
|
|
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,
|
|
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
|
|
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
|
|
74
|
-
- Each result carries `name` and `matchType`, and on a match `taxonKey`, `matchedTaxonKey` (synonyms), and `confidence`;
|
|
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
|
|
81
|
-
- Returns the classification with rank keys, `authorship`, `vernacularName`, `numDescendants`, `
|
|
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, `
|
|
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`,
|
|
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
|
|
103
|
-
- Each child carries `key`, `canonicalName`, `rank`, `taxonomicStatus`, `vernacularName
|
|
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
|
|
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
|
-
-
|
|
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
|
|
129
|
-
- The full Darwin Core record: `occurrenceStatus` (`
|
|
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 `
|
|
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
|
|
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
|
|
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
|
-
-
|
|
186
|
-
-
|
|
187
|
-
-
|
|
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.
|
|
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.
|
package/changelog/template.md
CHANGED
|
@@ -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
|
|
125
|
-
last. In release-PR mode the `git-wrapup`
|
|
126
|
-
PR body's `## Changes` and the tag copies
|
|
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
|