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

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 (73) hide show
  1. package/AGENTS.md +2 -2
  2. package/CLAUDE.md +2 -2
  3. package/README.md +36 -32
  4. package/changelog/0.8.x/0.8.2.md +38 -0
  5. package/dist/index.js +1 -1
  6. package/dist/index.js.map +1 -1
  7. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +8 -0
  8. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
  9. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +27 -6
  10. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
  11. package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts +6 -3
  12. package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts.map +1 -1
  13. package/dist/mcp-server/resources/definitions/gbif-species.resource.js +31 -10
  14. package/dist/mcp-server/resources/definitions/gbif-species.resource.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +27 -10
  16. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js +15 -34
  18. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts +8 -0
  20. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js +43 -10
  22. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts +17 -0
  24. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js +130 -35
  26. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts +5 -3
  28. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +33 -14
  30. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
  31. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts +4 -2
  32. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts.map +1 -1
  33. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +33 -16
  34. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
  35. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts +6 -3
  36. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts.map +1 -1
  37. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +64 -24
  38. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +3 -2
  41. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +32 -10
  43. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +63 -39
  45. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +1 -1
  47. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
  48. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +27 -10
  49. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +23 -41
  51. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
  52. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts +1 -1
  53. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +1 -1
  54. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
  55. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +21 -3
  56. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
  57. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +29 -14
  58. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
  59. package/dist/mcp-server/tools/utils.d.ts +116 -35
  60. package/dist/mcp-server/tools/utils.d.ts.map +1 -1
  61. package/dist/mcp-server/tools/utils.js +307 -52
  62. package/dist/mcp-server/tools/utils.js.map +1 -1
  63. package/dist/services/gbif/gbif-service.d.ts +6 -1
  64. package/dist/services/gbif/gbif-service.d.ts.map +1 -1
  65. package/dist/services/gbif/gbif-service.js +12 -4
  66. package/dist/services/gbif/gbif-service.js.map +1 -1
  67. package/dist/services/gbif/types.d.ts +58 -15
  68. package/dist/services/gbif/types.d.ts.map +1 -1
  69. package/dist/services/gbif/types.js +24 -4
  70. package/dist/services/gbif/types.js.map +1 -1
  71. package/package.json +4 -4
  72. package/server.json +3 -3
  73. package/skills/gbif-biodiversity-guide/SKILL.md +11 -10
package/AGENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** @cyanheads/gbif-biodiversity-mcp-server
4
- **Version:** 0.8.1
4
+ **Version:** 0.8.2
5
5
  **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
6
  **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -353,7 +353,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
353
353
  | `bun run tree` | Generate directory structure doc |
354
354
  | `bun run format` | Auto-fix formatting (safe fixes only) |
355
355
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
356
- | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
356
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`). `vitest` is pinned at exactly `5.1.0` in `devDependencies`, because the forks pool in 5.1.1 calls `child.channel.unref()`, which Bun 1.4.4 does not implement, so every test file fails under `bun run test`; re-test on a newer Bun or Vitest before lifting the pin |
357
357
  | `bun run start:stdio` | Production mode (stdio) |
358
358
  | `bun run start:http` | Production mode (HTTP) |
359
359
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
package/CLAUDE.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** @cyanheads/gbif-biodiversity-mcp-server
4
- **Version:** 0.8.1
4
+ **Version:** 0.8.2
5
5
  **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.22`
6
6
  **Engines:** Bun ≥1.4.4, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -353,7 +353,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
353
353
  | `bun run tree` | Generate directory structure doc |
354
354
  | `bun run format` | Auto-fix formatting (safe fixes only) |
355
355
  | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
356
- | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
356
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`). `vitest` is pinned at exactly `5.1.0` in `devDependencies`, because the forks pool in 5.1.1 calls `child.channel.unref()`, which Bun 1.4.4 does not implement, so every test file fails under `bun run test`; re-test on a newer Bun or Vitest before lifting the pin |
357
357
  | `bun run start:stdio` | Production mode (stdio) |
358
358
  | `bun run start:http` | Production mode (HTTP) |
359
359
  | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
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.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/)
10
+ [![Version](https://img.shields.io/badge/Version-0.8.2-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
 
@@ -37,24 +37,24 @@ Species taxonomy, occurrence records, datasets, and publishers from the Global B
37
37
  |:---|:---|
38
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
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
- | `gbif_search_species` | Search or browse the backbone by name fragment, rank, or a kingdom, family, or genus name |
40
+ | `gbif_get_species` | Fetch a taxon usage by key, from the backbone or any checklist: classification, authorship, synonymy, vernacular name, descendant count |
41
+ | `gbif_search_species` | Search or browse the backbone by name fragment, rank, taxonomic status, 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
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
- | `gbif_get_occurrence` | Fetch one full Darwin Core occurrence record by key |
46
+ | `gbif_get_occurrence` | Fetch one Darwin Core occurrence record by key |
47
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, publishing organization key, coverage |
49
+ | `gbif_get_dataset` | Fetch full dataset metadata by UUID: citation, contacts, license, DOI, publishing organization key, coverage with bounding boxes, deletion timestamp |
50
50
  | `gbif_search_publishers` | Search GBIF-registered publishing organizations by name or country |
51
51
 
52
52
  ### Resources
53
53
 
54
54
  | Resource | Description |
55
55
  |:---|:---|
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, publishing organization key |
56
+ | `gbif://species/{taxonKey}` | Taxon usage record from the GBIF backbone or any checklist: classification, authorship, synonymy status, vernacular name |
57
+ | `gbif://dataset/{datasetKey}` | Dataset metadata: title, description, citation, license, contacts, coverage with bounding boxes, deletion timestamp, 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
 
@@ -84,48 +84,52 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
84
84
 
85
85
  ### `gbif_get_species` <sub>tool</sub>
86
86
 
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`
87
+ - One `taxonKey`, a non-negative integer (`0` is the backbone kingdom *incertae sedis*): a backbone key, or the taxon usage key of any checklist, such as a `gbif_search_species` row's `key`. A key no checklist has 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, `datasetKey` (the source checklist), `nubKey` (the mapped backbone key, the one the occurrence tools take as `taxonKey`; absent where the backbone has no mapping), `authorship`, `vernacularName`, `numDescendants`, `publishedIn`, and `parentKey`; `key`, the rank keys, `parentKey`, and `acceptedKey` are taxon usage keys of that checklist, equal to `nubKey` only on a backbone usage. A `taxonomicStatus` of `SYNONYM` comes with `acceptedKey` and `accepted`. GBIF's taxon record carries no occurrence count: use `gbif_count_occurrences` with `nubKey`
89
89
 
90
90
  ---
91
91
 
92
92
  ### `gbif_search_species` <sub>tool</sub>
93
93
 
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`
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
94
+ - `q` name fragment (scientific and vernacular), `rank`, `status`, `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`, the `taxonScope` applied, and the `status` values 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`
96
+ - `status` takes one or more of `ACCEPTED`, `DOUBTFUL`, `SYNONYM`, `HETEROTYPIC_SYNONYM`, `HOMOTYPIC_SYNONYM`, `PROPARTE_SYNONYM`, and `MISAPPLIED`, and a name matches when it carries any of them; `SYNONYM` matches only names whose status is exactly `SYNONYM`, not the heterotypic, homotypic, or pro parte forms. An empty list fails at the schema. `status: ["ACCEPTED"]` with `rank: "SPECIES"` and a `genus` lists that genus's accepted species
97
+ - `kingdom`, `family`, and `genus` take names, matched by their exact spelling in any letter case, never fuzzily; 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`
98
+ - 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`, `status`, `isExtinct`, or `q`, or walk a subtree with `gbif_get_species_children`, which has no ceiling
98
99
 
99
100
  ---
100
101
 
101
102
  ### `gbif_get_species_classification` <sub>tool</sub>
102
103
 
103
- - One `taxonKey`; returns `classification` root-first from kingdom to the immediate parent, each entry with `key`, `rank`, `name`, and `scientificName`
104
+ - One `taxonKey` (a backbone key or the taxon usage key of any checklist); returns `classification` root-first from kingdom to the immediate parent, each entry with `key`, `rank`, `name`, `scientificName`, `datasetKey`, and `nubKey`. The chain is read in the queried taxon's own checklist: each `key` is a taxon usage key there, and `nubKey` is the mapped backbone key the occurrence tools take, absent where the backbone has no mapping
104
105
  - 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
105
106
 
106
107
  ---
107
108
 
108
109
  ### `gbif_get_species_children` <sub>tool</sub>
109
110
 
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
111
+ - One `taxonKey` (a non-negative integer, a backbone key or the taxon usage key of any checklist; `0` is the backbone's *incertae sedis* kingdom), whose children are listed within its own checklist, 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`
112
+ - Each child carries `key` (its taxon usage key in the parent's checklist), `datasetKey`, `nubKey` (the mapped backbone key, absent where the backbone has no mapping), `canonicalName`, `rank`, `taxonomicStatus`, `vernacularName` when GBIF has one, and `numDescendants`; GBIF sends no occurrence count, so use `gbif_count_occurrences` with the child's `nubKey`. GBIF reports no total, so `endOfRecords` (with `truncated` while more remain) is the continuation signal
112
113
  - An empty later page gives offset-reset guidance; only an empty first page for an existing taxon means no direct children
113
114
 
114
115
  ---
115
116
 
116
117
  ### `gbif_search_occurrences` <sub>tool</sub>
117
118
 
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
119
+ - 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, WKT `geometry`, or `geoDistance` (a radius around a point), `elevation`, `depth`, `year`, `month` (one month or a range), `eventDate`, `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
120
+ - `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. Either value also leaves out the records GBIF has not matched to a taxon in that checklist, which a call with no `checklistKey` keeps. `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
121
+ - `country`, `basisOfRecord`, `taxonKey`, and `checklistTaxonKey` each take one value or a non-empty array, and a record matching any one member matches (`country: ["ES", "PT"]` covers both countries, and a facet call ranks them as one scope). `taxonKey` and `checklistTaxonKey` take at most 100 members; an empty array fails at the schema, and each member passes the check a single value does. Different filters still intersect (a taxon key with `scientificName` excepted, below), and an array is echoed in `scope` as the array
122
+ - `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`. `limit` and `offset` are integers, `taxonKey` is an integer or an array of them, and `month` is an integer 1–12 or a string
121
123
  - `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
124
  - `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
125
  - `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
126
  - `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
125
- - All supplied spatial filters intersect: combining `geometry` with latitude or longitude ranges restricts results to their overlap
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
+ - All supplied spatial filters intersect: combining `geometry` or `geoDistance` with latitude or longitude ranges restricts results to their overlap
128
+ - `geoDistance` is `"latitude,longitude,distance"`, latitude first, with the distance ending in a lowercase `km` or `m` (`"38.17,-3.95,25km"` and `"38.17,-3.95,25000m"` are the same circle). The unit is required, because GBIF reads a distance with no unit as meters, so any other form fails as `invalid_filter`
129
+ - `decimalLatitude`, `decimalLongitude`, `coordinateUncertaintyInMeters`, `elevation`, and `depth` 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, with an example range per field (`decimalLatitude "38,39"`, `decimalLongitude "-4,-3"`, `coordinateUncertaintyInMeters "0,1000"` for within 1 km, `elevation "2000,*"` for 2,000 m and above, `depth "200,*"` for 200 m and deeper), listing only the fields the notice names. `coordinateUncertaintyInMeters`, `elevation`, and `depth` also take `*` for one open end (`"*,1000"`, `"2000,*"`); a bare `*`, padded or not, fails as `invalid_filter` on these and on `year`, `month`, and `eventDate`. A `*` end with whitespace between it and the comma (`"* ,1990"`, `"2020, *"`) also fails as `invalid_filter` on `coordinateUncertaintyInMeters`, `year`, `month`, `elevation`, and `depth`, and the message gives the corrected form (`"*,1990"`), because GBIF answers that spacing with HTTP 404 and an empty body, as it does a bare `*`; whitespace on the outer side of a `*` end (`" *,1990"`) or beside a number end (`"*, 1990"`, `"1990 ,*"`) is read by GBIF and forwarded, and `eventDate` with that spacing goes to GBIF, whose 400 names the value
130
+ - `year` is one year or a `"min,max"` range, `month` an integer 1–12 or a string holding one month or an ascending range (`"3,5"` for March through May, with no wrap past December), and `eventDate` is `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`, each covering its whole period, or a range of any mix of them (`"2026-01-01,2026-06-30"`). `*` opens one end of each range (`"*,1990"`, `"2020,*"`), and any value, `"*,*"` included, drops records that carry no value for that field. GBIF rejects a time of day, a descending range, or an impossible date by name
127
131
  - 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
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`
132
+ - 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, so a name GBIF cannot resolve (one shared across kingdoms, or one it does not know) empties the combined query, the `taxonKey` records included; a zero then carries a notice saying so and naming two ways out: drop the name, or resolve it with `gbif_match_species` and add the returned key to the call's `taxonKey` (or `checklistTaxonKey`) array in place of the name. All 11 GBIF basis-of-record values are accepted, including `FOSSIL_SPECIMEN`, `OBSERVATION`, and `UNKNOWN`
129
133
  - Latitude, longitude and coordinate uncertainty are independent optional facts; text renders each supplied value, including zero, in decimal degrees or meters
130
134
  - `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`
131
135
 
@@ -141,7 +145,7 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
141
145
  ### `gbif_get_occurrence` <sub>tool</sub>
142
146
 
143
147
  - 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`
148
+ - The 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 and, where the publisher gave them, `informationWithheld` and `dataGeneralizations` (the coordinates are coarser than observed on purpose), GADM levels 0–3 under `gadm`, dates with `eventTime` and `dateIdentified`, `taxonomicStatus`, the backbone key at every rank (`kingdomKey` through `speciesKey`), `acceptedTaxonKey` and `acceptedScientificName` (the accepted taxon behind a synonym record), `iucnRedListCategory`, institution, collection, and catalog codes, `datasetName`, `recordedBy`, `identifiedBy`, and `recordNumber`, `occurrenceRemarks`, `habitat`, `samplingProtocol`, `organismQuantity` with `organismQuantityType`, `typeStatus` and `establishmentMeans`, `license` (the Creative Commons URL), `rightsHolder`, and `publishingOrganizationKey` (goes into `publishingOrg`), `references` (the link to the source record), `isInCluster`, `media` with each item's `rightsHolder`, `identifiers`, and `issues`. Each field is omitted when GBIF sends none
145
149
 
146
150
  ---
147
151
 
@@ -149,7 +153,7 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
149
153
 
150
154
  - `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`
151
155
  - 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`
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
156
+ - 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. GBIF pages a ranking only so far: `facetOffset + facetLimit` may reach 1,199,999 on any scope, past which the call fails as `pagination_cap_exceeded` before any request, and 500,000 on a scope ranking more than 500,001 buckets, where GBIF refuses a deeper page and the call fails the same way; when the next page at the same `facetLimit` would reach past position 500,001 (the lookahead bucket counts), the continuation notice names the `facetLimit` that lands the next page exactly on it, and that page carries a notice in place of a continuation, with `truncated` still set, so a walk at any `facetLimit` ends at position 500,001. To rank buckets past either, narrow the scope with filters (`taxonKey` of a class or order, `country`, `year`, `basisOfRecord`, or a `datasetKey` from a `DATASET_KEY` facet) and page each narrower scope from 0. 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
153
157
  - `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
158
  - `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
155
159
 
@@ -167,7 +171,7 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
167
171
  ### `gbif_get_dataset` <sub>tool</sub>
168
172
 
169
173
  - 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`
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`
174
+ - 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`, `geographicCoverages` (each a description, a `boundingBox` as GBIF sends it, or both; a `minLongitude` above `maxLongitude` is a box crossing the antimeridian), and `deleted`, GBIF's timestamp for a dataset it no longer publishes (it is then not searchable and GBIF indexes none of its occurrences; absent on a published dataset)
171
175
 
172
176
  ---
173
177
 
@@ -175,14 +179,14 @@ Both resources are also reachable via `gbif_get_species` and `gbif_get_dataset`;
175
179
 
176
180
  - `q` name fragment and `country` (alpha-2 or alpha-3, any case); up to 1,000 per page with integer `limit` and `offset`
177
181
  - Returns organization `key`, `title`, `country`, and `city`; the key chains into `gbif_search_datasets` as `publishingOrg`
178
- - A blank `q`, an empty `country`, or a country GBIF cannot parse fails as `invalid_filter`
182
+ - A blank `q`, an empty `country`, or a country GBIF cannot parse fails as `invalid_filter`. Besides the codes, GBIF parses its own enum name for a country (`UNITED_KINGDOM`, or `United Kingdom`), but no other name: `Britain`, `UK`, and numeric codes fail
179
183
 
180
184
  ---
181
185
 
182
186
  ### `gbif://species/{taxonKey}` <sub>resource</sub>
183
187
 
184
- - Taxon record as `application/json`: classification names, `authorship`, `vernacularName`, `taxonomicStatus` with `acceptedKey` and `accepted`, `numDescendants`
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
188
+ - Taxon usage record as `application/json`: classification names, `authorship`, `vernacularName`, `taxonomicStatus` with `acceptedKey` and `accepted`, `numDescendants`, `datasetKey` (the source checklist), and `nubKey` (the mapped backbone key the occurrence tools take); `key` and `acceptedKey` are taxon usage keys of that checklist
189
+ - `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 taxon usage key of any checklist, such as a search result's `key`
186
190
 
187
191
  ---
188
192
 
@@ -201,17 +205,17 @@ GBIF-specific:
201
205
  - Synonym-safe keys: `gbif_match_species` resolves a synonym to its accepted taxon, and the occurrence tools filter on that `taxonKey`
202
206
  - 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
207
  - 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
208
+ - 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 lowercase and alpha-3 forms silently match nothing there and a country name such as `Britain` draws a 400 upstream. `stateProvince` matches verbatim and case-sensitively, so take values from a `STATE_PROVINCE` facet
205
209
  - 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
206
210
 
207
211
  Agent-friendly output:
208
212
 
209
213
  - 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
210
214
  - Graceful partial failure: `gbif_bulk_match_species` returns a `NONE` or `ERROR` row per name instead of failing the batch
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
215
+ - Typed errors: `invalid_filter`, `not_found`, `no_match`, `unresolved_taxon_scope`, `conflicting_taxon_scope`, and `pagination_cap_exceeded` (on `gbif_search_occurrences`, `gbif_occurrence_facets`, `gbif_search_species`, and `gbif_search_datasets`), each with a recovery hint
212
216
  - Sparse fields omitted rather than null-filled: `extinct` appears only on taxa GBIF explicitly flags
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
214
- - Publisher descriptions retain paragraph breaks and decode numeric character references once; Markdown output renders publisher text literally
217
+ - Dataset metadata preserves temporal ranges, single dates, and verbatim periods such as `1975-current`, and geographic coverage bounding boxes as GBIF sends them; unsupported coverage entries are disclosed. A deleted dataset carries its `deleted` timestamp. An unavailable supplementary record count carries `recordCountNotice` while retaining metadata
218
+ - Publisher descriptions retain paragraph breaks and decode numeric character references once; Markdown output renders publisher text literally, in dataset and occurrence output alike. A value containing Markdown or character-reference syntax appears in `content[]` as numeric character references (`&#NN;`) standing for one character each, never part of the value; `structuredContent` carries every string as GBIF sent it. An http(s) URL in an occurrence record (`occurrenceID`, `references`, a media or `identifiers` entry) renders as a link whose text is the URL, and any other value as escaped text
215
219
 
216
220
  ## Getting started
217
221
 
@@ -0,0 +1,38 @@
1
+ ---
2
+ summary: "New occurrence filters (eventDate, geoDistance, elevation, depth, month ranges, array values), a species status filter, and richer occurrence and dataset records; facet paging ceilings, a bare * year, and checklist usage keys now report correctly."
3
+ breaking: false
4
+ security: false
5
+ ---
6
+
7
+ # 0.8.2 — 2026-11-19
8
+
9
+ ## Added
10
+
11
+ - **`status` on `gbif_search_species`** filters by one or more taxonomic statuses (`ACCEPTED`, `DOUBTFUL`, `SYNONYM`, and four more), OR-ed, and echoes the applied values as a `status` enrichment key. ([#96](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/96))
12
+ - **`eventDate`, `geoDistance`, `elevation`, and `depth` filters** on the occurrence tools, and `month` also takes a `"min,max"` range. A bare `*` is refused as `year`'s is, and `geoDistance` must end in a lowercase `km` or `m`. ([#97](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/97))
13
+ - **`country`, `basisOfRecord`, `taxonKey`, and `checklistTaxonKey`** on the occurrence tools take an array, OR-ed by GBIF (`taxonKey` and `checklistTaxonKey` up to 100 members); `scope` echoes the array. ([#98](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/98))
14
+ - **`gbif_get_occurrence`** returns `informationWithheld`, `dataGeneralizations`, `references`, `occurrenceRemarks`, `habitat`, `samplingProtocol`, `datasetName`, `organismQuantity`, `organismQuantityType`, `dateIdentified`, `isInCluster`, and the `kingdomKey` … `speciesKey` rank keys. Its text fields are escaped in `content[]` and `references` renders as a link. ([#99](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/99))
15
+
16
+ ## Changed
17
+
18
+ - **`checklistKey` description** states that either value leaves out the records GBIF has not matched to a taxon in that checklist.
19
+ - **`scientificName` descriptions** on the occurrence tools state that the name combines with a taxon key as a union, and what an unresolvable name does.
20
+
21
+ ## Fixed
22
+
23
+ - **`gbif_occurrence_facets` fails as `pagination_cap_exceeded`** past position 1,200,000, before any request (was `invalid_filter`), and past 500,001 on a scope ranking more buckets (was a reasonless `-32001` HTTP 404). The page landing on 500,001 carries a notice, not a continuation, and a continuation that would cross it names the `facetLimit` that lands on it. ([#91](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/91))
24
+ - **A bare `*` as `year`** fails as `invalid_filter` naming the open-ended forms; 0.8.1 sent it to GBIF, which answered a `-32001` HTTP 404. ([#93](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/93))
25
+ - **`gbif_get_species`, `gbif_get_species_children`, `gbif_get_species_classification`, and `gbif://species/{taxonKey}`** now return `nubKey` and `datasetKey` beside a checklist usage `key`, and no longer describe usage keys as backbone keys; `nubKey` is the key the occurrence tools take, absent where the backbone has no mapping. ([#94](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/94))
26
+ - **`gbif_get_dataset` and `gbif://dataset/{datasetKey}`** return `deleted` for a dataset GBIF has deleted, and each coverage's `boundingBox`; a coverage with a box and no description is kept. ([#95](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/95))
27
+ - **`gbif_search_species` descriptions** no longer require capitalized `kingdom`, `family`, and `genus` names, and the `gbif_search_publishers` `country` recovery names the forms GBIF parses: alpha-3 codes and its own country names. ([#100](https://github.com/cyanheads/gbif-biodiversity-mcp-server/issues/100))
28
+ - **`iucnRedListCategory`** accepts `NE` (Not Evaluated), which 0.8.1 rejected.
29
+ - **A `scientificName` GBIF cannot resolve, sent beside a taxon key,** empties the query; the zero's notice now names the name as the cause, where 0.8.1 printed the notice for a name sent alone.
30
+ - **`gbif_get_occurrence` and `gbif_search_occurrences`** escape publisher-written text in `content[]`, `eventTime` included, and render an http(s) media URL as a link, as `gbif_get_occurrence` also does for `occurrenceID` and identifier URLs.
31
+ - **The country-code rejection** on the occurrence tools and on `gbif_search_datasets` `publishingCountry` states what GBIF does with each form, where 0.8.1 said a country name matches nothing.
32
+ - **A `*` range end with whitespace between it and the comma** (`"* ,1990"`) on `year` or `coordinateUncertaintyInMeters` fails as `invalid_filter` naming the corrected form; 0.8.1 sent it to GBIF, which answered a bare 404.
33
+
34
+ ## Dependencies
35
+
36
+ - `@biomejs/biome` ^2.6.6 → ^2.6.8.
37
+ - `ignore` ^7.0.14 → ^7.0.16.
38
+ - `vitest` ^5.1.0 → 5.1.0 (pinned: the forks pool in 5.1.1 calls `child.channel.unref()`, which Bun 1.4.4 does not implement).
package/dist/index.js CHANGED
@@ -28,7 +28,7 @@ import { initGbifService } from './services/gbif/gbif-service.js';
28
28
  await createApp({
29
29
  name: 'gbif-biodiversity-mcp-server',
30
30
  title: 'gbif-biodiversity-mcp-server',
31
- instructions: 'Use the gbif_* tools to query species taxonomy, occurrences, datasets, and publishers via the GBIF API. Keyless — these endpoints need no credentials. Resolve any name with gbif_match_species first — it returns the backbone taxonKey the occurrence tools expect, resolving a synonym to its accepted taxon and reporting the matched synonym key alongside as matchedTaxonKey; the raw scientificName filter also resolves a synonym, but a name shared across kingdoms, such as Oenanthe, matches nothing there, where a key names exactly one taxon. A matchType of HIGHERRANK means GBIF matched at a higher rank — a misspelled species can come back as its genus or kingdom — so that taxonKey covers the whole higher taxon; the notice on the result names it. gbif_bulk_match_species resolves such a name when its entry is { name, kingdom }. checklistKey 7ddf754f-d193-4cc9-b351-99906754a03b (opt-in) selects the Catalogue of Life eXtended Release, the taxonomy GBIF now maintains: the match tools then return its case-sensitive string key as checklistTaxonKey, and the occurrence tools take one as checklistTaxonKey under the same checklistKey, where taxonKey is rejected and KINGDOM_KEY through SPECIES_KEY buckets are Catalogue of Life keys. gbif_search_species defaults to the GBIF Backbone Taxonomy checklist d7dddbf4-2cf0-4f39-9b2a-bb099caae36c and honors an explicit datasetKey. Its key is the source checklist usage key; use the optional nubKey for occurrence queries, otherwise resolve the name with gbif_match_species. The optional datasetKey identifies the source checklist. The kingdom, family, and genus filters on gbif_search_species take names and are resolved to backbone keys the same way before the search runs, since /species/search scopes by taxon key alone: the narrowest of the three supplied is what scopes, a name is matched exactly and capitalized as GBIF writes it, one that reaches no backbone taxon at that rank fails rather than widening the search, and pairing any of them with datasetKey matches nothing unless that checklist is the GBIF backbone. gbif_search_species pages to offset+limit 100,000 and gbif_search_datasets to 125,000; past that a request fails as pagination_cap_exceeded, and the notice on a larger match names the filters that narrow it. Countries use ISO 3166-1 alpha-2; datasets and publishers are keyed by UUID, occurrences by integer key. Omit a filter you do not want rather than sending it blank: GBIF ignores a parameter it is given with no value and answers with the whole unfiltered scope, so every optional filter on these tools rejects a blank or whitespace-only value instead of quietly widening the query. That rejection is a typed invalid_filter carrying the recovery hint the tool declares, except on country and publishingCountry of the occurrence tools, publishingCountry of gbif_search_datasets, and license of the occurrence tools, where the uppercase-only pattern (an enum, for license) rejects a blank or unknown value at the schema, so the failure is the generic -32602 invalid_arguments rejection, carrying the message of that pattern or enum instead. On the occurrence tools country and publishingCountry, and on gbif_search_datasets publishingCountry, the uppercase two-letter form is the only one accepted — lowercase and alpha-3 forms ("gb", "USA") match nothing on those routes, so those fields reject anything else rather than answering zero, while gbif_search_publishers resolves either form case-insensitively against the registry and needs no such constraint. An organization key from gbif_search_publishers chains into gbif_search_datasets two ways: publishingOrg for the datasets that organization published, hostingOrg for the ones its own installation serves. publishingOrg is almost always the one meant — most organizations publish through an installation someone else runs, so hostingOrg matches nothing for them — and supplying both intersects the two rather than combining them. gbif_get_dataset, the gbif://dataset/{datasetKey} resource, and each gbif_search_datasets row also return the publishingOrganizationKey of the dataset, and gbif_get_occurrence and every gbif_search_occurrences row return it for the record, which goes into publishingOrg the same way. The occurrence tools take publishingOrg too, scoping to everything that organization published across its datasets; a PUBLISHING_ORG facet lists the organizations in a scope. On the occurrence tools country is where the record was observed and publishingCountry is the country of the organization that published it — different questions that disagree on most records, so pick deliberately; stateProvince is matched verbatim, exactly and case-sensitively, and an unrecognized value returns zero records rather than an error, so take one from a STATE_PROVINCE facet instead of guessing a spelling. gadmGid is the normalized alternative: a GADM GID (ESP.1_1) GBIF derives from the coordinates of each record, matched exactly and taken from a GADM_LEVEL_0_GID … GADM_LEVEL_3_GID facet or the gadm field of gbif_get_occurrence; records without coordinates carry none. catalogNumber and institutionCode match whole values case-insensitively, recordedBy matches one collector exactly and case-sensitively (take a spelling from a RECORDED_BY facet), and mediaType is one of StillImage, MovingImage, Sound, InteractiveResource. typeStatus and establishmentMeans name a GBIF vocabulary concept and match it and every narrower one (Type covers every kind of type). For records to map, pair hasGeospatialIssue false with hasCoordinate true: GBIF often strips the coordinates of a flagged record. GBIF indexes absence records — a documented survey that looked for a taxon and did not find it — alongside sightings, so gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets all default occurrenceStatus to PRESENT and report the applied filter in their enrichment; pass ANY to include absences, or ABSENT for absences alone. Records, rows, and OCCURRENCE_STATUS buckets read DETECTED and NOT_DETECTED, the GBIF names for the same two states, and pass back unchanged as occurrenceStatus. For some taxa absences dominate: an unfiltered count can run five orders of magnitude above the sightings it appears to report. The dataset recordCount on gbif_search_datasets, gbif_get_dataset, and the gbif://dataset/{datasetKey} resource is not filtered that way — it spans every occurrenceStatus, so it can exceed a gbif_count_occurrences total for the same datasetKey. Occurrence paging caps at offset+limit=100,001 and GBIF exposes no cursor or scroll, so a larger result set is reached only by partitioning it: gbif_occurrence_facets with facet DATASET_KEY splits a scope into buckets that sum to its full total, since every occurrence carries exactly one datasetKey, and each bucket is then searchable on its own; a facet on a dimension a record can lack — YEAR, MONTH, STATE_PROVINCE, SPECIES_KEY, INSTITUTION_CODE, MEDIA_TYPE, RECORDED_BY, TYPE_STATUS, ESTABLISHMENT_MEANS, and the GADM_LEVEL_0_GID … GADM_LEVEL_3_GID GIDs (records without coordinates or outside every GADM unit at that level) — leaves those records in no bucket, and MEDIA_TYPE, RECORDED_BY, TYPE_STATUS, and ESTABLISHMENT_MEANS buckets overlap (a TYPE_STATUS or ESTABLISHMENT_MEANS record counts under its concept and every broader one), so their sums can pass the total. Search, count and facets accept the same biological filters and echo only effective supplied filters in scope, always including occurrenceStatus; isGeoreferenced is a count alias for hasCoordinate and conflicting values fail as invalid_filter. Repeat every biological filter on the facet call and each partition search so bucket counts reconcile. All supplied spatial filters intersect, while taxonKey and scientificName combine with OR. decimalLatitude, decimalLongitude, and coordinateUncertaintyInMeters take "min,max", both ends inclusive; a value without a comma matches only that exact value, not values near it. Key and GID buckets (KINGDOM_KEY through SPECIES_KEY, DATASET_KEY, PUBLISHING_ORG, GADM_LEVEL_0_GID through GADM_LEVEL_3_GID) are bare keys; includeLabels adds the name of each (the organization title for PUBLISHING_ORG, the area name for a GADM level) as label at one extra request per bucket, under a 10 s deadline, and notice counts any left unlabeled. This server cannot retrieve a result set in bulk — the GBIF Download API needs a GBIF.org account and returns an archive asynchronously, and the monthly GBIF Parquet snapshot on AWS Open Data is a bulk dataset; both are routes to take outside this server. The gbif-biodiversity-guide skill (skill://gbif-biodiversity-guide/SKILL.md) carries the gates 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.',
31
+ instructions: 'Use the gbif_* tools to query species taxonomy, occurrences, datasets, and publishers via the GBIF API. Keyless — these endpoints need no credentials. Resolve any name with gbif_match_species first — it returns the backbone taxonKey the occurrence tools expect, resolving a synonym to its accepted taxon and reporting the matched synonym key alongside as matchedTaxonKey; the raw scientificName filter also resolves a synonym, but a name shared across kingdoms, such as Oenanthe, matches nothing there, where a key names exactly one taxon. A matchType of HIGHERRANK means GBIF matched at a higher rank — a misspelled species can come back as its genus or kingdom — so that taxonKey covers the whole higher taxon; the notice on the result names it. gbif_bulk_match_species resolves such a name when its entry is { name, kingdom }. checklistKey 7ddf754f-d193-4cc9-b351-99906754a03b (opt-in) selects the Catalogue of Life eXtended Release, the taxonomy GBIF now maintains: the match tools then return its case-sensitive string key as checklistTaxonKey, and the occurrence tools take one as checklistTaxonKey under the same checklistKey, where taxonKey is rejected and KINGDOM_KEY through SPECIES_KEY buckets are Catalogue of Life keys; either checklistKey value also leaves out the records GBIF has not matched to a taxon in that checklist. gbif_search_species defaults to the GBIF Backbone Taxonomy checklist d7dddbf4-2cf0-4f39-9b2a-bb099caae36c and honors an explicit datasetKey. Its key is the source checklist usage key; use the optional nubKey for occurrence queries, otherwise resolve the name with gbif_match_species; gbif_get_species, gbif_get_species_children, and gbif_get_species_classification return the same datasetKey and nubKey beside each usage key. The optional datasetKey identifies the source checklist. The kingdom, family, and genus filters on gbif_search_species take names and are resolved to backbone keys the same way before the search runs, since /species/search scopes by taxon key alone: the narrowest of the three supplied is what scopes, a name is matched by its exact spelling in any letter case, one that reaches no backbone taxon at that rank fails rather than widening the search, and pairing any of them with datasetKey matches nothing unless that checklist is the GBIF backbone. gbif_search_species also takes status, one or more taxonomic statuses OR-ed, where SYNONYM matches only that exact status. gbif_search_species pages to offset+limit 100,000, gbif_search_datasets to 125,000, and gbif_occurrence_facets to facetOffset+facetLimit 1,199,999, or 500,000 on a scope ranking more than 500,001 buckets; past those a request fails as pagination_cap_exceeded, and the notice on a larger match names the filters that narrow it. Countries use ISO 3166-1 alpha-2; datasets and publishers are keyed by UUID, occurrences by integer key. Omit a filter you do not want rather than sending it blank: GBIF ignores a parameter it is given with no value and answers with the whole unfiltered scope, so every optional filter on these tools rejects a blank or whitespace-only value instead of quietly widening the query. That rejection is a typed invalid_filter carrying the recovery hint the tool declares, except on country and publishingCountry of the occurrence tools, publishingCountry of gbif_search_datasets, and license of the occurrence tools, where the uppercase-only pattern (an enum, for license) rejects a blank or unknown value at the schema, so the failure is the generic -32602 invalid_arguments rejection, carrying the message of that pattern or enum instead. On the occurrence tools country and publishingCountry, and on gbif_search_datasets publishingCountry, the uppercase two-letter form is the only one accepted — lowercase and alpha-3 forms ("gb", "USA") match nothing on those routes, so those fields reject anything else rather than answering zero, while gbif_search_publishers resolves either form case-insensitively against the registry and needs no such constraint. An organization key from gbif_search_publishers chains into gbif_search_datasets two ways: publishingOrg for the datasets that organization published, hostingOrg for the ones its own installation serves. publishingOrg is almost always the one meant — most organizations publish through an installation someone else runs, so hostingOrg matches nothing for them — and supplying both intersects the two rather than combining them. gbif_get_dataset, the gbif://dataset/{datasetKey} resource, and each gbif_search_datasets row also return the publishingOrganizationKey of the dataset, and gbif_get_occurrence and every gbif_search_occurrences row return it for the record, which goes into publishingOrg the same way. The occurrence tools take publishingOrg too, scoping to everything that organization published across its datasets; a PUBLISHING_ORG facet lists the organizations in a scope. On the occurrence tools country is where the record was observed and publishingCountry is the country of the organization that published it — different questions that disagree on most records, so pick deliberately; stateProvince is matched verbatim, exactly and case-sensitively, and an unrecognized value returns zero records rather than an error, so take one from a STATE_PROVINCE facet instead of guessing a spelling. gadmGid is the normalized alternative: a GADM GID (ESP.1_1) GBIF derives from the coordinates of each record, matched exactly and taken from a GADM_LEVEL_0_GID … GADM_LEVEL_3_GID facet or the gadm field of gbif_get_occurrence; records without coordinates carry none. catalogNumber and institutionCode match whole values case-insensitively, recordedBy matches one collector exactly and case-sensitively (take a spelling from a RECORDED_BY facet), and mediaType is one of StillImage, MovingImage, Sound, InteractiveResource. typeStatus and establishmentMeans name a GBIF vocabulary concept and match it and every narrower one (Type covers every kind of type). For records to map, pair hasGeospatialIssue false with hasCoordinate true: GBIF often strips the coordinates of a flagged record. GBIF indexes absence records — a documented survey that looked for a taxon and did not find it — alongside sightings, so gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets all default occurrenceStatus to PRESENT and report the applied filter in their enrichment; pass ANY to include absences, or ABSENT for absences alone. Records, rows, and OCCURRENCE_STATUS buckets read DETECTED and NOT_DETECTED, the GBIF names for the same two states, and pass back unchanged as occurrenceStatus. For some taxa absences dominate: an unfiltered count can run five orders of magnitude above the sightings it appears to report. The dataset recordCount on gbif_search_datasets, gbif_get_dataset, and the gbif://dataset/{datasetKey} resource is not filtered that way — it spans every occurrenceStatus, so it can exceed a gbif_count_occurrences total for the same datasetKey. A deleted dataset keeps resolving through gbif_get_dataset with a deleted timestamp, and GBIF indexes none of its occurrences. Occurrence paging caps at offset+limit=100,001 and GBIF exposes no cursor or scroll, so a larger result set is reached only by partitioning it: gbif_occurrence_facets with facet DATASET_KEY splits a scope into buckets that sum to its full total, since every occurrence carries exactly one datasetKey, and each bucket is then searchable on its own; a facet on a dimension a record can lack — YEAR, MONTH, STATE_PROVINCE, SPECIES_KEY, INSTITUTION_CODE, MEDIA_TYPE, RECORDED_BY, TYPE_STATUS, ESTABLISHMENT_MEANS, and the GADM_LEVEL_0_GID … GADM_LEVEL_3_GID GIDs (records without coordinates or outside every GADM unit at that level) — leaves those records in no bucket, and MEDIA_TYPE, RECORDED_BY, TYPE_STATUS, and ESTABLISHMENT_MEANS buckets overlap (a TYPE_STATUS or ESTABLISHMENT_MEANS record counts under its concept and every broader one), so their sums can pass the total. Search, count and facets accept the same biological filters and echo only effective supplied filters in scope, always including occurrenceStatus; isGeoreferenced is a count alias for hasCoordinate and conflicting values fail as invalid_filter. Repeat every biological filter on the facet call and each partition search so bucket counts reconcile. All supplied spatial filters intersect, geoDistance included (a radius around a point, written "38.17,-3.95,25km" with a km or m unit), while taxonKey and scientificName combine with OR, so a scientificName GBIF cannot resolve empties the whole query. country, basisOfRecord, taxonKey, and checklistTaxonKey take one value or an array, OR-ed within the filter, so a multi-country region is one call. decimalLatitude, decimalLongitude, coordinateUncertaintyInMeters, elevation, and depth take "min,max", both ends inclusive; a value without a comma matches only that exact value, not values near it. year, month, and eventDate take one value or "min,max", and on those and on elevation, depth, and coordinateUncertaintyInMeters "*" opens one end of a range but a bare "*" is rejected, as is whitespace between a "*" end and the comma ("* ,1990") on all of those but eventDate. Key and GID buckets (KINGDOM_KEY through SPECIES_KEY, DATASET_KEY, PUBLISHING_ORG, GADM_LEVEL_0_GID through GADM_LEVEL_3_GID) are bare keys; includeLabels adds the name of each (the organization title for PUBLISHING_ORG, the area name for a GADM level) as label at one extra request per bucket, under a 10 s deadline, and notice counts any left unlabeled. Where content[] shows &#NN; in publisher-supplied text, that is a character reference standing for one character so the text stays literal in Markdown, never part of the value; structuredContent carries every string as GBIF sent it, so take a value to pass back as a filter from there. This server cannot retrieve a result set in bulk — the GBIF Download API needs a GBIF.org account and returns an archive asynchronously, and the monthly GBIF Parquet snapshot on AWS Open Data is a bulk dataset; both are routes to take outside this server. The gbif-biodiversity-guide skill (skill://gbif-biodiversity-guide/SKILL.md) carries the gates 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.',
32
32
  // Declared here rather than left to MCP_SESSION_MODE, so a source run and the
33
33
  // container resolve the same posture. No handler calls ctx.requestInput, so
34
34
  // nothing needs the stateful-only elicitation path a 2025-era client relies on.
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY;AACZ,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kEAAkE,CAAC;AAC1G,OAAO,EAAE,4BAA4B,EAAE,MAAM,wEAAwE,CAAC;AACtH,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,8BAA8B;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,mBAAmB;AACnB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gEAAgE,CAAC;AACvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,8BAA8B;IACpC,KAAK,EAAE,8BAA8B;IACrC,YAAY,EACV,2qRAA2qR;IAC7qR,8EAA8E;IAC9E,4EAA4E;IAC5E,gFAAgF;IAChF,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,gBAAgB;QAChB,oBAAoB;QACpB,cAAc;QACd,iBAAiB;QACjB,4BAA4B;QAC5B,sBAAsB;QACtB,qBAAqB;QACrB,oBAAoB;QACpB,iBAAiB;QACjB,oBAAoB;QACpB,kBAAkB;QAClB,cAAc;QACd,oBAAoB;KACrB;IACD,SAAS,EAAE,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IACrD,OAAO,EAAE,EAAE;IACX,oFAAoF;IACpF,MAAM,EAAE,QAAQ;IAChB,6EAA6E;IAC7E,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE;YACzC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,SAAS,EAAE,GAAG,CAAC,gBAAgB;YAC/B,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY;AACZ,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,oBAAoB,EAAE,MAAM,gEAAgE,CAAC;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kEAAkE,CAAC;AAC1G,OAAO,EAAE,4BAA4B,EAAE,MAAM,wEAAwE,CAAC;AACtH,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,8BAA8B;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AACjG,mBAAmB;AACnB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gEAAgE,CAAC;AACvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,8BAA8B;IACpC,KAAK,EAAE,8BAA8B;IACrC,YAAY,EACV,4oUAA4oU;IAC9oU,8EAA8E;IAC9E,4EAA4E;IAC5E,gFAAgF;IAChF,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,gBAAgB;QAChB,oBAAoB;QACpB,cAAc;QACd,iBAAiB;QACjB,4BAA4B;QAC5B,sBAAsB;QACtB,qBAAqB;QACrB,oBAAoB;QACpB,iBAAiB;QACjB,oBAAoB;QACpB,kBAAkB;QAClB,cAAc;QACd,oBAAoB;KACrB;IACD,SAAS,EAAE,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IACrD,OAAO,EAAE,EAAE;IACX,oFAAoF;IACpF,MAAM,EAAE,QAAQ;IAChB,6EAA6E;IAC7E,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,KAAK,CAAC,IAAI;QACR,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE;YACzC,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,SAAS,EAAE,GAAG,CAAC,gBAAgB;YAC/B,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}
@@ -9,6 +9,7 @@ export declare const gbifDatasetResource: import("@cyanheads/mcp-ts-core").Resou
9
9
  }, z.core.$strip>, z.ZodObject<{
10
10
  key: z.ZodOptional<z.ZodString>;
11
11
  title: z.ZodOptional<z.ZodString>;
12
+ deleted: z.ZodOptional<z.ZodString>;
12
13
  type: z.ZodOptional<z.ZodString>;
13
14
  description: z.ZodOptional<z.ZodString>;
14
15
  license: z.ZodOptional<z.ZodString>;
@@ -39,6 +40,13 @@ export declare const gbifDatasetResource: import("@cyanheads/mcp-ts-core").Resou
39
40
  temporalCoverageNotice: z.ZodOptional<z.ZodString>;
40
41
  geographicCoverages: z.ZodOptional<z.ZodArray<z.ZodObject<{
41
42
  description: z.ZodOptional<z.ZodString>;
43
+ boundingBox: z.ZodOptional<z.ZodObject<{
44
+ minLatitude: z.ZodOptional<z.ZodNumber>;
45
+ maxLatitude: z.ZodOptional<z.ZodNumber>;
46
+ minLongitude: z.ZodOptional<z.ZodNumber>;
47
+ maxLongitude: z.ZodOptional<z.ZodNumber>;
48
+ globalCoverage: z.ZodOptional<z.ZodBoolean>;
49
+ }, z.core.$strip>>;
42
50
  }, z.core.$strip>>>;
43
51
  }, z.core.$strip>, readonly [{
44
52
  readonly reason: "not_found";
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-dataset.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-dataset.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAkB3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmL9B,CAAC"}
1
+ {"version":3,"file":"gbif-dataset.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-dataset.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAkB3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8M9B,CAAC"}
@@ -14,10 +14,7 @@ const CONTACT_CAP = 10;
14
14
  export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
15
15
  name: 'gbif-dataset',
16
16
  title: 'GBIF Dataset',
17
- description: 'Dataset metadata — title, description, citation, license, contacts, coverage, and the ' +
18
- 'publishing organization key that gbif_search_datasets takes as publishingOrg. ' +
19
- 'Stable URI for provenance context. Use the dataset UUID from gbif_search_datasets or ' +
20
- "an occurrence record's datasetKey field.",
17
+ description: "Dataset metadata — title, description, citation, license, contacts, temporal and geographic coverage with its bounding boxes, the deletion timestamp of a dataset GBIF no longer publishes, and the publishing organization key that gbif_search_datasets takes as publishingOrg. Stable URI for provenance context. Use the dataset UUID from gbif_search_datasets or an occurrence record's datasetKey field.",
21
18
  mimeType: 'application/json',
22
19
  params: z.object({
23
20
  datasetKey: z.string().describe('Dataset UUID (8-4-4-4-12 hex).'),
@@ -25,6 +22,10 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
25
22
  output: z.object({
26
23
  key: z.string().optional().describe('Dataset UUID.'),
27
24
  title: z.string().optional().describe('Dataset title.'),
25
+ deleted: z
26
+ .string()
27
+ .optional()
28
+ .describe('When GBIF deleted the dataset, as the timestamp GBIF sends (e.g. 2026-11-10T20:11:45.006+00:00). A deleted dataset is no longer published or searchable, and GBIF indexes none of its occurrences. Absent on a published dataset.'),
28
29
  type: z.string().optional().describe('Dataset type.'),
29
30
  description: z.string().optional().describe('Dataset description. May be absent.'),
30
31
  license: z.string().optional().describe('License identifier. May be absent.'),
@@ -106,10 +107,29 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
106
107
  .string()
107
108
  .optional()
108
109
  .describe('Geographic coverage description (e.g. "Worldwide"). May be absent.'),
110
+ boundingBox: z
111
+ .object({
112
+ minLatitude: z.number().optional().describe('Southern bound in decimal degrees.'),
113
+ maxLatitude: z.number().optional().describe('Northern bound in decimal degrees.'),
114
+ minLongitude: z
115
+ .number()
116
+ .optional()
117
+ .describe("Western bound in decimal degrees — EML's westBoundingCoordinate."),
118
+ maxLongitude: z
119
+ .number()
120
+ .optional()
121
+ .describe("Eastern bound in decimal degrees — EML's eastBoundingCoordinate."),
122
+ globalCoverage: z
123
+ .boolean()
124
+ .optional()
125
+ .describe("GBIF's global-coverage flag for the box, as sent."),
126
+ })
127
+ .optional()
128
+ .describe('Bounding box the dataset declares, with every value as GBIF sends it. GBIF maps EML west and east bounds to minLongitude and maxLongitude, so a minLongitude above maxLongitude is a box crossing the antimeridian, not an error. May be absent.'),
109
129
  })
110
- .describe('A geographic coverage entry.'))
130
+ .describe('A geographic coverage entry: a description, a bounding box, or both.'))
111
131
  .optional()
112
- .describe('Geographic coverage descriptions declared by the dataset. May be absent.'),
132
+ .describe('Geographic coverage declared by the dataset — descriptions and bounding boxes. May be absent.'),
113
133
  }),
114
134
  errors: [
115
135
  {
@@ -148,6 +168,7 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
148
168
  return {
149
169
  key: raw.key,
150
170
  title: raw.title,
171
+ deleted: raw.deleted,
151
172
  type: raw.type,
152
173
  description: raw.description ? stripHtml(raw.description) : undefined,
153
174
  license: raw.license,
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-dataset.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-dataset.resource.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"gbif-dataset.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-dataset.resource.ts"],"names":[],"mappings":"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"}
@@ -1,5 +1,6 @@
1
1
  /**
2
- * @fileoverview GBIF species resource — stable URI for taxon records from the backbone.
2
+ * @fileoverview GBIF species resource — stable URI for taxon usage records from the
3
+ * backbone or any other checklist.
3
4
  * @module mcp-server/resources/definitions/gbif-species
4
5
  */
5
6
  import { z } from '@cyanheads/mcp-ts-core';
@@ -8,6 +9,8 @@ export declare const gbifSpeciesResource: import("@cyanheads/mcp-ts-core").Resou
8
9
  taxonKey: z.ZodString;
9
10
  }, z.core.$strip>, z.ZodObject<{
10
11
  key: z.ZodOptional<z.ZodNumber>;
12
+ datasetKey: z.ZodOptional<z.ZodString>;
13
+ nubKey: z.ZodOptional<z.ZodNumber>;
11
14
  scientificName: z.ZodOptional<z.ZodString>;
12
15
  canonicalName: z.ZodOptional<z.ZodString>;
13
16
  authorship: z.ZodOptional<z.ZodString>;
@@ -27,12 +30,12 @@ export declare const gbifSpeciesResource: import("@cyanheads/mcp-ts-core").Resou
27
30
  }, z.core.$strip>, readonly [{
28
31
  readonly reason: "not_found";
29
32
  readonly code: JsonRpcErrorCode.NotFound;
30
- readonly when: "The taxonKey does not exist in the GBIF backbone.";
33
+ readonly when: "No GBIF checklist has a taxon usage with this taxonKey.";
31
34
  readonly recovery: "Use gbif_match_species to resolve a name to a valid backbone key, or gbif_search_species to browse.";
32
35
  }, {
33
36
  readonly reason: "invalid_filter";
34
37
  readonly code: JsonRpcErrorCode.InvalidParams;
35
38
  readonly when: "The taxonKey segment has malformed URI escapes, is not a whole signed decimal integer after one decode and surrounding-whitespace trimming, or is outside the signed 32-bit integer range.";
36
- readonly recovery: "Address the resource with a whole backbone taxon key as gbif_match_species or gbif_search_species returns it, rather than a constructed number.";
39
+ readonly recovery: "Address the resource with a whole taxon key as gbif_match_species or gbif_search_species returns it, rather than a constructed number.";
37
40
  }]>;
38
41
  //# sourceMappingURL=gbif-species.resource.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-species.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-species.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAI3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgH9B,CAAC"}
1
+ {"version":3,"file":"gbif-species.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-species.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAI3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsI9B,CAAC"}