@cyanheads/gbif-biodiversity-mcp-server 0.5.3 → 0.5.5

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 (76) hide show
  1. package/CLAUDE.md +1 -1
  2. package/README.md +8 -6
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +5 -0
  6. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
  7. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +16 -4
  8. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
  9. package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts +5 -0
  10. package/dist/mcp-server/resources/definitions/gbif-species.resource.d.ts.map +1 -1
  11. package/dist/mcp-server/resources/definitions/gbif-species.resource.js +6 -0
  12. package/dist/mcp-server/resources/definitions/gbif-species.resource.js.map +1 -1
  13. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts +2 -0
  14. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.d.ts.map +1 -1
  15. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js +33 -6
  16. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +7 -1
  18. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js +19 -1
  20. package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts +5 -0
  22. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts.map +1 -1
  23. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js +18 -6
  24. package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js.map +1 -1
  25. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts +5 -0
  26. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.d.ts.map +1 -1
  27. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js +6 -0
  28. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts +5 -0
  30. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +21 -4
  32. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts +8 -1
  34. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +17 -0
  36. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts +5 -0
  38. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts.map +1 -1
  39. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +6 -0
  40. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
  41. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +4 -1
  42. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +40 -5
  44. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +7 -1
  46. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +26 -4
  48. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +7 -1
  50. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts.map +1 -1
  51. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +14 -2
  52. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
  53. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +6 -6
  54. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
  55. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +21 -11
  56. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
  57. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts +7 -1
  58. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts.map +1 -1
  59. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +9 -0
  60. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
  61. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +7 -1
  62. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
  63. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +18 -2
  64. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
  65. package/dist/mcp-server/tools/utils.d.ts +28 -1
  66. package/dist/mcp-server/tools/utils.d.ts.map +1 -1
  67. package/dist/mcp-server/tools/utils.js +38 -0
  68. package/dist/mcp-server/tools/utils.js.map +1 -1
  69. package/dist/services/gbif/gbif-service.d.ts +10 -0
  70. package/dist/services/gbif/gbif-service.d.ts.map +1 -1
  71. package/dist/services/gbif/gbif-service.js +100 -5
  72. package/dist/services/gbif/gbif-service.js.map +1 -1
  73. package/dist/services/gbif/types.d.ts +7 -1
  74. package/dist/services/gbif/types.d.ts.map +1 -1
  75. package/package.json +1 -1
  76. package/server.json +3 -3
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.5.3
4
+ **Version:** 0.5.5
5
5
  **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.1`
6
6
  **Engines:** Bun ≥1.3.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
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.5.3-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-^1.30.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.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.5.5-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-^1.30.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.3.14-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
@@ -52,7 +52,7 @@ Match a scientific or common name against the GBIF backbone taxonomy.
52
52
  - Confidence score 0–100; below 80 warrants review
53
53
  - Full classification hierarchy with keys at each rank: kingdom, phylum, class, order, family, genus, species
54
54
  - `matchType NONE` indicates no usable match — try removing strict mode or broadening the name
55
- - Resolves synonyms: always returns the accepted backbone key regardless of which name form was queried
55
+ - Resolves synonyms: always returns the accepted backbone key regardless of which name form was queried; `matchedTaxonKey` carries the synonym's own key when the two differ
56
56
 
57
57
  ---
58
58
 
@@ -62,7 +62,8 @@ Match up to 50 scientific names against the GBIF backbone taxonomy in a single c
62
62
 
63
63
  - The batch counterpart to `gbif_match_species` — built for checklist, inventory, and species-list workflows that would otherwise need one round trip per name
64
64
  - Returns one result per input name, in input order; each carries `taxonKey`, `matchType`, and confidence
65
- - Per-name isolation: an unmatched name yields `matchType NONE` and a per-name lookup failure yields `matchType ERROR` — neither sinks the rest of the batch
65
+ - Per-name isolation: an unmatched name yields `matchType NONE` and a per-name lookup failure yields `matchType ERROR` with the message and, when the failure was classified, a `reason` — neither sinks the rest of the batch
66
+ - Same synonym resolution as `gbif_match_species`: `taxonKey` is the accepted taxon, `matchedTaxonKey` the synonym it was queried under
66
67
  - `strict: true` requires an exact match for every name; common names are not supported (use `gbif_search_species`)
67
68
 
68
69
  ---
@@ -121,7 +122,7 @@ Search 2.4B+ GBIF occurrence records with full Darwin Core filtering.
121
122
  - Temporal filters: `year` as single year or range, `month` (1–12) for seasonal queries
122
123
  - `basisOfRecord` enum: `HUMAN_OBSERVATION`, `PRESERVED_SPECIMEN`, `MACHINE_OBSERVATION`, and more
123
124
  - `hasCoordinate` to require or exclude georeferenced records
124
- - Pagination capped at offset+limit ≈ 100,000 — use `gbif_occurrence_facets` for aggregate analysis beyond this
125
+ - Pagination capped at offset+limit = 100,001, the deepest page GBIF serves — use `gbif_occurrence_facets` for aggregate analysis beyond this
125
126
 
126
127
  ---
127
128
 
@@ -154,7 +155,7 @@ Aggregate occurrence counts across a dimension.
154
155
 
155
156
  - Facets: `COUNTRY`, `YEAR`, `BASIS_OF_RECORD`, `DATASET_KEY`, `KINGDOM_KEY`, `PHYLUM_KEY`, `CLASS_KEY`, `ORDER_KEY`, `FAMILY_KEY`, `GENUS_KEY`, `SPECIES_KEY`, `PUBLISHING_COUNTRY`, `MONTH`
156
157
  - Scope with `taxonKey`, `country`, `year`, `geometry`, or `basisOfRecord` filters
157
- - Returns top-N values ranked by count (up to `facetLimit`, max 100) — no record payloads
158
+ - Returns one page of values ranked by count descending — up to `facetLimit` (max 100), the top ones only while `facetOffset` is 0 — with no record payloads
158
159
  - Page past the first `facetLimit` with `facetOffset` (advance by `facetLimit` per page) to walk high-cardinality facets like `DATASET_KEY`; enrichment echoes the applied `facetOffset` and sets `moreValuesLikely` when a full page suggests more values remain
159
160
  - Core tool for distribution analysis ("which countries have the most records?") and trend queries ("how has observation volume changed since 2010?")
160
161
 
@@ -178,6 +179,7 @@ Fetch full dataset metadata by UUID.
178
179
  - Full description, citation text (for academic reference), license, DOI
179
180
  - Contacts with role, name, organization, and email
180
181
  - Temporal and geographic coverage ranges when the publisher declares them
182
+ - `recordCount` for `OCCURRENCE` datasets — the indexed occurrence total, matching what `gbif_search_datasets` reports; absent for other dataset types
181
183
  - `numConstituents` for aggregate datasets (e.g. iNaturalist, eBird)
182
184
  - Use after `gbif_search_datasets` or when an occurrence record's `datasetKey` needs provenance detail
183
185
 
@@ -213,7 +215,7 @@ GBIF-specific:
213
215
 
214
216
  - Full GBIF REST API v1 coverage: species taxonomy, occurrences, datasets, and publishers
215
217
  - `gbif_match_species` as the entry point — resolves synonyms to backbone taxon keys used throughout
216
- - Occurrence pagination cap detection with `paginationNote` — redirects to facet aggregation before hitting the ~100,000 row limit
218
+ - Occurrence pagination guarded at GBIF's own offset+limit = 100,001 boundary — an over-cap request fails locally with a `notice` redirecting to facet aggregation, instead of spending the retry budget on a deterministic upstream rejection
217
219
  - WKT polygon geometry support for geographic occurrence queries
218
220
  - Darwin Core field mapping with explicit provenance on sparse upstream fields
219
221
 
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 and resolves synonyms, unlike the raw scientificName filter. Countries use ISO 3166-1 alpha-2; datasets and publishers are keyed by UUID, occurrences by integer key. Occurrence paging caps at offset+limit ≈ 100,000 — switch to gbif_occurrence_facets for larger aggregate analysis.',
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, unlike the raw scientificName filter. Countries use ISO 3166-1 alpha-2; datasets and publishers are keyed by UUID, occurrences by integer key. Occurrence paging caps at offset+limit=100,001 — switch to gbif_occurrence_facets for larger aggregate analysis.',
32
32
  tools: [
33
33
  gbifMatchSpecies,
34
34
  gbifBulkMatchSpecies,
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,+hBAA+hB;IACjiB,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,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,qnBAAqnB;IACvnB,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,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"}
@@ -38,5 +38,10 @@ export declare const gbifDatasetResource: import("@cyanheads/mcp-ts-core").Resou
38
38
  readonly code: JsonRpcErrorCode.NotFound;
39
39
  readonly when: "The datasetKey UUID does not match any dataset in GBIF.";
40
40
  readonly recovery: "Use gbif_search_datasets to find valid dataset keys, or check the UUID from an occurrence record's datasetKey field.";
41
+ }, {
42
+ readonly reason: "invalid_filter";
43
+ readonly code: JsonRpcErrorCode.InvalidParams;
44
+ readonly when: "The URI segment is not a UUID, or GBIF rejected the request as malformed.";
45
+ readonly recovery: "Address the resource with the 8-4-4-4-12 hex UUID exactly as gbif_search_datasets returns it, or as it appears in an occurrence record's datasetKey field.";
41
46
  }]>;
42
47
  //# sourceMappingURL=gbif-dataset.resource.d.ts.map
@@ -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;AAgB3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkI9B,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsJ9B,CAAC"}
@@ -4,7 +4,7 @@
4
4
  */
5
5
  import { resource, z } from '@cyanheads/mcp-ts-core';
6
6
  import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
7
- import { compactGeographicCoverages, compactTemporalCoverages, projectContacts, stripHtml, } from '../../../mcp-server/tools/utils.js';
7
+ import { compactGeographicCoverages, compactTemporalCoverages, isGbifUuid, projectContacts, resolveDatasetRecordCount, stripHtml, } from '../../../mcp-server/tools/utils.js';
8
8
  import { getGbifService } from '../../../services/gbif/gbif-service.js';
9
9
  /**
10
10
  * Fixed contact cap for the resource. The resource has no contactLimit input (unlike
@@ -19,7 +19,7 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
19
19
  "an occurrence record's datasetKey field.",
20
20
  mimeType: 'application/json',
21
21
  params: z.object({
22
- datasetKey: z.string().describe('Dataset UUID.'),
22
+ datasetKey: z.string().describe('Dataset UUID (8-4-4-4-12 hex).'),
23
23
  }),
24
24
  output: z.object({
25
25
  key: z.string().optional().describe('Dataset UUID.'),
@@ -30,7 +30,10 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
30
30
  doi: z.string().optional().describe('DOI for citation. May be absent.'),
31
31
  citationText: z.string().optional().describe('Full citation text. May be absent.'),
32
32
  publishingCountry: z.string().optional().describe('Publishing organization country.'),
33
- recordCount: z.number().optional().describe('Number of records. May be absent.'),
33
+ recordCount: z
34
+ .number()
35
+ .optional()
36
+ .describe('Occurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Fetched separately for OCCURRENCE datasets because the detail endpoint omits it; absent for other dataset types and when that lookup does not return in time.'),
34
37
  numConstituents: z.number().optional().describe('Number of sub-datasets. May be absent.'),
35
38
  contacts: z
36
39
  .array(z
@@ -92,9 +95,18 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
92
95
  when: 'The datasetKey UUID does not match any dataset in GBIF.',
93
96
  recovery: "Use gbif_search_datasets to find valid dataset keys, or check the UUID from an occurrence record's datasetKey field.",
94
97
  },
98
+ {
99
+ reason: 'invalid_filter',
100
+ code: JsonRpcErrorCode.InvalidParams,
101
+ when: 'The URI segment is not a UUID, or GBIF rejected the request as malformed.',
102
+ recovery: "Address the resource with the 8-4-4-4-12 hex UUID exactly as gbif_search_datasets returns it, or as it appears in an occurrence record's datasetKey field.",
103
+ },
95
104
  ],
96
105
  async handler(params, ctx) {
97
106
  ctx.log.debug('Fetching dataset resource', { datasetKey: params.datasetKey });
107
+ if (!isGbifUuid(params.datasetKey)) {
108
+ throw ctx.fail('invalid_filter', `datasetKey "${params.datasetKey}" is not a GBIF dataset UUID.`, { ...ctx.recoveryFor('invalid_filter') });
109
+ }
98
110
  let raw;
99
111
  try {
100
112
  raw = await getGbifService().getDataset(params.datasetKey, ctx);
@@ -123,7 +135,7 @@ export const gbifDatasetResource = resource('gbif://dataset/{datasetKey}', {
123
135
  doi: raw.doi,
124
136
  citationText: raw.citation?.text,
125
137
  publishingCountry: raw.publishingCountry,
126
- recordCount: raw.numRecords ?? raw.recordCount,
138
+ recordCount: await resolveDatasetRecordCount(raw, ctx),
127
139
  numConstituents: raw.numConstituents,
128
140
  ...projectContacts(raw.contacts, CONTACT_CAP),
129
141
  temporalCoverages: compactTemporalCoverages(raw.temporalCoverages),
@@ -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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"}
@@ -29,5 +29,10 @@ export declare const gbifSpeciesResource: import("@cyanheads/mcp-ts-core").Resou
29
29
  readonly code: JsonRpcErrorCode.NotFound;
30
30
  readonly when: "The taxonKey does not exist in the GBIF backbone.";
31
31
  readonly recovery: "Use gbif_match_species to resolve a name to a valid backbone key, or gbif_search_species to browse.";
32
+ }, {
33
+ readonly reason: "invalid_filter";
34
+ readonly code: JsonRpcErrorCode.InvalidParams;
35
+ readonly when: "GBIF rejected the taxonKey segment as unparseable — a value outside the 32-bit signed 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.";
32
37
  }]>;
33
38
  //# 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,EAA6B,MAAM,+BAA+B,CAAC;AAI5F,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;GAwF9B,CAAC"}
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,EAA6B,MAAM,+BAA+B,CAAC;AAI5F,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+F9B,CAAC"}
@@ -40,6 +40,12 @@ export const gbifSpeciesResource = resource('gbif://species/{taxonKey}', {
40
40
  when: 'The taxonKey does not exist in the GBIF backbone.',
41
41
  recovery: 'Use gbif_match_species to resolve a name to a valid backbone key, or gbif_search_species to browse.',
42
42
  },
43
+ {
44
+ reason: 'invalid_filter',
45
+ code: JsonRpcErrorCode.InvalidParams,
46
+ when: 'GBIF rejected the taxonKey segment as unparseable — a value outside the 32-bit signed integer range.',
47
+ 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.',
48
+ },
43
49
  ],
44
50
  async handler(params, ctx) {
45
51
  const taxonKey = parseInt(params.taxonKey, 10);
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-species.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-species.resource.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"gbif-species.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/gbif-species.resource.ts"],"names":[],"mappings":"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"}
@@ -10,6 +10,7 @@ export declare const gbifBulkMatchSpecies: import("@cyanheads/mcp-ts-core").Tool
10
10
  results: z.ZodArray<z.ZodObject<{
11
11
  name: z.ZodString;
12
12
  taxonKey: z.ZodOptional<z.ZodNumber>;
13
+ matchedTaxonKey: z.ZodOptional<z.ZodNumber>;
13
14
  scientificName: z.ZodOptional<z.ZodString>;
14
15
  canonicalName: z.ZodOptional<z.ZodString>;
15
16
  rank: z.ZodOptional<z.ZodString>;
@@ -17,6 +18,7 @@ export declare const gbifBulkMatchSpecies: import("@cyanheads/mcp-ts-core").Tool
17
18
  confidence: z.ZodOptional<z.ZodNumber>;
18
19
  matchType: z.ZodString;
19
20
  error: z.ZodOptional<z.ZodString>;
21
+ reason: z.ZodOptional<z.ZodString>;
20
22
  }, z.core.$strip>>;
21
23
  }, z.core.$strip>, undefined, undefined>;
22
24
  //# sourceMappingURL=gbif-bulk-match-species.tool.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-bulk-match-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-bulk-match-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;wCA+H/B,CAAC"}
1
+ {"version":3,"file":"gbif-bulk-match-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-bulk-match-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIjD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;wCA+J/B,CAAC"}
@@ -3,6 +3,7 @@
3
3
  * @module mcp-server/tools/definitions/gbif-bulk-match-species
4
4
  */
5
5
  import { tool, z } from '@cyanheads/mcp-ts-core';
6
+ import { McpError } from '@cyanheads/mcp-ts-core/errors';
6
7
  import { getGbifService } from '../../../services/gbif/gbif-service.js';
7
8
  export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
8
9
  title: 'Bulk Match Species Names',
@@ -11,9 +12,11 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
11
12
  'would otherwise need one round trip per name. Each name is matched independently and results ' +
12
13
  'are returned in input order, one entry per name. A name with no backbone match yields ' +
13
14
  'matchType NONE (no taxonKey) instead of failing the batch; a per-name lookup failure yields ' +
14
- 'matchType ERROR with the reason, leaving the rest of the batch intact. Resolves synonyms to ' +
15
- 'the accepted backbone key. Common names are not supported — use gbif_search_species for ' +
16
- 'vernacular searches. Below confidence 80, review the match.',
15
+ "matchType ERROR carrying that name's error message and, when the failure was classified, " +
16
+ 'a machine-readable reason — the rest of the batch is unaffected, and the call as a whole ' +
17
+ 'still succeeds. When a queried name is a synonym, taxonKey is the accepted taxon it resolves ' +
18
+ "to and matchedTaxonKey carries the synonym's own key. Common names are not supported — use " +
19
+ 'gbif_search_species for vernacular searches. Below confidence 80, review the match.',
17
20
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
18
21
  input: z.object({
19
22
  names: z
@@ -34,7 +37,11 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
34
37
  taxonKey: z
35
38
  .number()
36
39
  .optional()
37
- .describe('Matched GBIF backbone taxon key — use in gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets. Absent when matchType is NONE or ERROR.'),
40
+ .describe("GBIF backbone taxon key to pass to gbif_search_occurrences, gbif_count_occurrences, and gbif_occurrence_facets — the accepted taxon's key when this name is a synonym, otherwise the matched taxon's own key. Absent when matchType is NONE or ERROR."),
41
+ matchedTaxonKey: z
42
+ .number()
43
+ .optional()
44
+ .describe('Backbone key of the name that actually matched. Present only when it differs from taxonKey — that is, when a synonym was resolved to its accepted taxon.'),
38
45
  scientificName: z
39
46
  .string()
40
47
  .optional()
@@ -58,7 +65,11 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
58
65
  error: z
59
66
  .string()
60
67
  .optional()
61
- .describe('Failure reason when matchType is ERROR. Absent otherwise.'),
68
+ .describe('Failure message when matchType is ERROR. Absent otherwise.'),
69
+ reason: z
70
+ .string()
71
+ .optional()
72
+ .describe('Machine-readable failure identifier when matchType is ERROR — e.g. invalid_filter when GBIF rejected a supplied value. Absent when the failure carried no classification, and absent on every non-ERROR entry.'),
62
73
  })
63
74
  .describe('Match outcome for one input name.'))
64
75
  .describe('One result per input name, in input order.'),
@@ -79,9 +90,14 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
79
90
  if (raw.usageKey == null || raw.matchType == null || raw.matchType === 'NONE') {
80
91
  return { name, matchType: 'NONE' };
81
92
  }
93
+ // `/species/match` names the accepted taxon only as acceptedUsageKey; resolve
94
+ // so taxonKey is safe to hand to the occurrence tools (see gbif_match_species).
95
+ const matchedTaxonKey = raw.usageKey;
96
+ const taxonKey = raw.acceptedUsageKey ?? matchedTaxonKey;
82
97
  return {
83
98
  name,
84
- taxonKey: raw.usageKey,
99
+ taxonKey,
100
+ ...(taxonKey !== matchedTaxonKey && { matchedTaxonKey }),
85
101
  scientificName: raw.scientificName ?? undefined,
86
102
  canonicalName: raw.canonicalName ?? undefined,
87
103
  rank: raw.rank ?? undefined,
@@ -91,10 +107,16 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
91
107
  };
92
108
  }
93
109
  catch (err) {
110
+ // The per-name catch is the only place a classified failure can surface for this
111
+ // tool, so carry the thrown reason through rather than flattening to a message.
112
+ const reason = err instanceof McpError && typeof err.data?.reason === 'string'
113
+ ? err.data.reason
114
+ : undefined;
94
115
  return {
95
116
  name,
96
117
  matchType: 'ERROR',
97
118
  error: err instanceof Error ? err.message : String(err),
119
+ ...(reason && { reason }),
98
120
  };
99
121
  }
100
122
  }));
@@ -110,6 +132,9 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
110
132
  lines.push(`**Scientific name:** ${r.scientificName}`);
111
133
  if (r.taxonKey != null)
112
134
  lines.push(`**Taxon key:** ${r.taxonKey}`);
135
+ if (r.matchedTaxonKey != null) {
136
+ lines.push(`**Matched taxon key:** ${r.matchedTaxonKey} — this name is a synonym; the taxon key above is the accepted taxon it resolves to.`);
137
+ }
113
138
  if (r.rank)
114
139
  lines.push(`**Rank:** ${r.rank}`);
115
140
  if (r.status)
@@ -119,6 +144,8 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
119
144
  lines.push(`**Confidence:** ${r.confidence}/100`);
120
145
  if (r.error)
121
146
  lines.push(`**Error:** ${r.error}`);
147
+ if (r.reason)
148
+ lines.push(`**Reason:** ${r.reason}`);
122
149
  }
123
150
  return [{ type: 'text', text: lines.join('\n') }];
124
151
  },
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-bulk-match-species.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-bulk-match-species.tool.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"gbif-bulk-match-species.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-bulk-match-species.tool.ts"],"names":[],"mappings":"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"}
@@ -3,6 +3,7 @@
3
3
  * @module mcp-server/tools/definitions/gbif-count-occurrences
4
4
  */
5
5
  import { z } from '@cyanheads/mcp-ts-core';
6
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
6
7
  export declare const gbifCountOccurrences: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
7
8
  taxonKey: z.ZodOptional<z.ZodNumber>;
8
9
  country: z.ZodOptional<z.ZodString>;
@@ -11,5 +12,10 @@ export declare const gbifCountOccurrences: import("@cyanheads/mcp-ts-core").Tool
11
12
  year: z.ZodOptional<z.ZodString>;
12
13
  }, z.core.$strip>, z.ZodObject<{
13
14
  count: z.ZodNumber;
14
- }, z.core.$strip>, undefined, undefined>;
15
+ }, z.core.$strip>, readonly [{
16
+ readonly reason: "invalid_filter";
17
+ readonly code: JsonRpcErrorCode.InvalidParams;
18
+ readonly when: "datasetKey is not a UUID, or GBIF rejected another filter value as malformed.";
19
+ readonly recovery: "Supply datasetKey as the 8-4-4-4-12 hex UUID gbif_search_datasets returns; year is a single year or a \"min,max\" range.";
20
+ }], undefined>;
15
21
  //# sourceMappingURL=gbif-count-occurrences.tool.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-count-occurrences.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-count-occurrences.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,oBAAoB;;;;;;;;wCAkD/B,CAAC"}
1
+ {"version":3,"file":"gbif-count-occurrences.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-count-occurrences.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;cA0E/B,CAAC"}
@@ -3,7 +3,9 @@
3
3
  * @module mcp-server/tools/definitions/gbif-count-occurrences
4
4
  */
5
5
  import { tool, z } from '@cyanheads/mcp-ts-core';
6
+ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
6
7
  import { getGbifService } from '../../../services/gbif/gbif-service.js';
8
+ import { isGbifUuid } from '../utils.js';
7
9
  export const gbifCountOccurrences = tool('gbif_count_occurrences', {
8
10
  title: 'Count Occurrences',
9
11
  description: 'Count occurrences matching a taxon + location filter without fetching records. ' +
@@ -20,7 +22,10 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
20
22
  .boolean()
21
23
  .optional()
22
24
  .describe('When true, count only georeferenced records. When false, count only non-georeferenced records.'),
23
- datasetKey: z.string().optional().describe('Filter to a specific dataset UUID.'),
25
+ datasetKey: z
26
+ .string()
27
+ .optional()
28
+ .describe('Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets.'),
24
29
  year: z
25
30
  .string()
26
31
  .optional()
@@ -29,11 +34,24 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
29
34
  output: z.object({
30
35
  count: z.number().describe('Total occurrences matching the supplied filters.'),
31
36
  }),
37
+ errors: [
38
+ {
39
+ reason: 'invalid_filter',
40
+ code: JsonRpcErrorCode.InvalidParams,
41
+ when: 'datasetKey is not a UUID, or GBIF rejected another filter value as malformed.',
42
+ recovery: 'Supply datasetKey as the 8-4-4-4-12 hex UUID gbif_search_datasets returns; year is a single year or a "min,max" range.',
43
+ },
44
+ ],
32
45
  async handler(input, ctx) {
33
46
  ctx.log.info('Counting occurrences', {
34
47
  taxonKey: input.taxonKey,
35
48
  country: input.country,
36
49
  });
50
+ // GBIF's count endpoint answers 200 with a count of 0 for a malformed dataset
51
+ // key, so an unchecked typo returns a confident wrong number rather than an error.
52
+ if (input.datasetKey?.trim() && !isGbifUuid(input.datasetKey)) {
53
+ throw ctx.fail('invalid_filter', `datasetKey "${input.datasetKey}" is not a GBIF dataset UUID.`, { ...ctx.recoveryFor('invalid_filter') });
54
+ }
37
55
  const count = await getGbifService().countOccurrences({
38
56
  ...(input.taxonKey !== undefined && { taxonKey: input.taxonKey }),
39
57
  ...(input.country?.trim() && { country: input.country }),
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-count-occurrences.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-count-occurrences.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,wBAAwB,EAAE;IACjE,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,iFAAiF;QACjF,uFAAuF;QACvF,8FAA8F;IAChG,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,iIAAiI,CAClI;QACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;QAC9F,eAAe,EAAE,CAAC;aACf,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CACP,gGAAgG,CACjG;QACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAChF,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,6EAA6E,CAAC;KAC3F,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;KAC/E,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE;YACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC,gBAAgB,CACnD;YACE,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;YACjE,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YACxD,GAAG,CAAC,KAAK,CAAC,eAAe,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC;YACtF,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;YACjE,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;SAChD,EACD,GAAG,CACJ,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;CACtF,CAAC,CAAC"}
1
+ {"version":3,"file":"gbif-count-occurrences.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-count-occurrences.tool.ts"],"names":[],"mappings":"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"}
@@ -39,5 +39,10 @@ export declare const gbifGetDataset: import("@cyanheads/mcp-ts-core").ToolDefini
39
39
  readonly code: JsonRpcErrorCode.NotFound;
40
40
  readonly when: "The datasetKey UUID does not match any dataset in GBIF.";
41
41
  readonly recovery: "Use gbif_search_datasets to find valid dataset keys, or check the UUID from an occurrence record's datasetKey field.";
42
+ }, {
43
+ readonly reason: "invalid_filter";
44
+ readonly code: JsonRpcErrorCode.InvalidParams;
45
+ readonly when: "datasetKey is not a UUID, or GBIF rejected the request as malformed.";
46
+ readonly recovery: "Supply the 8-4-4-4-12 hex UUID exactly as gbif_search_datasets returns it, or as it appears in an occurrence record's datasetKey field — a dataset title or DOI is not a key.";
42
47
  }], undefined>;
43
48
  //# sourceMappingURL=gbif-get-dataset.tool.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"gbif-get-dataset.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-dataset.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAU3E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA+LzB,CAAC"}
1
+ {"version":3,"file":"gbif-get-dataset.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-dataset.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAY3E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmNzB,CAAC"}
@@ -5,18 +5,18 @@
5
5
  import { tool, z } from '@cyanheads/mcp-ts-core';
6
6
  import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
7
7
  import { getGbifService } from '../../../services/gbif/gbif-service.js';
8
- import { compactGeographicCoverages, compactTemporalCoverages, projectContacts, stripHtml, } from '../utils.js';
8
+ import { compactGeographicCoverages, compactTemporalCoverages, isGbifUuid, projectContacts, resolveDatasetRecordCount, stripHtml, } from '../utils.js';
9
9
  export const gbifGetDataset = tool('gbif_get_dataset', {
10
10
  title: 'Get Dataset',
11
11
  description: 'Fetch full dataset metadata by UUID key — title, description, citation text, contacts, license, ' +
12
- 'DOI, numConstituents (sub-datasets), and temporal/geographic coverage. Use after gbif_search_datasets ' +
12
+ 'DOI, record count, numConstituents (sub-datasets), and temporal/geographic coverage. Use after gbif_search_datasets ' +
13
13
  "or when an occurrence record's datasetKey needs provenance detail. " +
14
14
  'Contacts are capped by contactLimit (default 10); contactsTotal and contactsReturned report the full count.',
15
15
  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
16
16
  input: z.object({
17
17
  datasetKey: z
18
18
  .string()
19
- .describe('Dataset UUID from gbif_search_datasets or an occurrence record.'),
19
+ .describe('Dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets or an occurrence record.'),
20
20
  contactLimit: z
21
21
  .number()
22
22
  .int()
@@ -40,7 +40,10 @@ export const gbifGetDataset = tool('gbif_get_dataset', {
40
40
  .string()
41
41
  .optional()
42
42
  .describe('Country code of the publishing organization.'),
43
- recordCount: z.number().optional().describe('Number of records in the dataset. May be absent.'),
43
+ recordCount: z
44
+ .number()
45
+ .optional()
46
+ .describe('Occurrence records GBIF has indexed for this dataset, matching the figure gbif_search_datasets reports. Fetched separately for OCCURRENCE datasets because the detail endpoint omits it; absent for other dataset types and when that lookup does not return in time.'),
44
47
  numConstituents: z
45
48
  .number()
46
49
  .optional()
@@ -105,15 +108,24 @@ export const gbifGetDataset = tool('gbif_get_dataset', {
105
108
  when: 'The datasetKey UUID does not match any dataset in GBIF.',
106
109
  recovery: "Use gbif_search_datasets to find valid dataset keys, or check the UUID from an occurrence record's datasetKey field.",
107
110
  },
111
+ {
112
+ reason: 'invalid_filter',
113
+ code: JsonRpcErrorCode.InvalidParams,
114
+ when: 'datasetKey is not a UUID, or GBIF rejected the request as malformed.',
115
+ recovery: "Supply the 8-4-4-4-12 hex UUID exactly as gbif_search_datasets returns it, or as it appears in an occurrence record's datasetKey field — a dataset title or DOI is not a key.",
116
+ },
108
117
  ],
109
118
  async handler(input, ctx) {
110
119
  ctx.log.info('Fetching dataset record', { datasetKey: input.datasetKey });
120
+ if (!isGbifUuid(input.datasetKey)) {
121
+ throw ctx.fail('invalid_filter', `datasetKey "${input.datasetKey}" is not a GBIF dataset UUID.`, { ...ctx.recoveryFor('invalid_filter') });
122
+ }
111
123
  let raw;
112
124
  try {
113
125
  raw = await getGbifService().getDataset(input.datasetKey, ctx);
114
126
  }
115
127
  catch (err) {
116
- if (err instanceof McpError && err.code === -32001) {
128
+ if (err instanceof McpError && err.code === JsonRpcErrorCode.NotFound) {
117
129
  throw ctx.fail('not_found', `Dataset ${input.datasetKey} not found in GBIF.`, {
118
130
  ...ctx.recoveryFor('not_found'),
119
131
  });
@@ -134,7 +146,7 @@ export const gbifGetDataset = tool('gbif_get_dataset', {
134
146
  doi: raw.doi,
135
147
  citationText: raw.citation?.text,
136
148
  publishingCountry: raw.publishingCountry,
137
- recordCount: raw.numRecords ?? raw.recordCount,
149
+ recordCount: await resolveDatasetRecordCount(raw, ctx),
138
150
  numConstituents: raw.numConstituents,
139
151
  // contactLimit: 0 suppresses contact detail while projectContacts still reports
140
152
  // contactsTotal/contactsReturned, so callers learn the dataset has contacts.