@cyanheads/gbif-biodiversity-mcp-server 0.6.1 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +1 -1
- package/README.md +20 -10
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js +44 -16
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +5 -0
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +26 -6
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +47 -16
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +5 -3
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +78 -17
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +59 -25
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +55 -8
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +2 -2
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +37 -8
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/utils.d.ts +23 -0
- package/dist/mcp-server/tools/utils.d.ts.map +1 -1
- package/dist/mcp-server/tools/utils.js +29 -0
- package/dist/mcp-server/tools/utils.js.map +1 -1
- package/dist/services/gbif/gbif-service.d.ts +7 -0
- package/dist/services/gbif/gbif-service.d.ts.map +1 -1
- package/dist/services/gbif/gbif-service.js +8 -0
- package/dist/services/gbif/gbif-service.js.map +1 -1
- package/package.json +1 -1
- 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.
|
|
4
|
+
**Version:** 0.7.1
|
|
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
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/gbif-biodiversity-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/gbif-biodiversity-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
| `gbif_count_occurrences` | Count occurrences matching a filter without fetching records — fast single-number response, filtered to sightings by default |
|
|
40
40
|
| `gbif_get_occurrence` | Fetch a single occurrence record by key — full Darwin Core record with GADM geography, presence/absence status, conservation status, media, and quality flags |
|
|
41
41
|
| `gbif_occurrence_facets` | Aggregate occurrence counts by a dimension — country, year, basis of record, dataset, kingdom, presence/absence, IUCN Red List category |
|
|
42
|
-
| `gbif_search_datasets` | Search GBIF datasets by keyword, type, country, or
|
|
42
|
+
| `gbif_search_datasets` | Search GBIF datasets by keyword, type, country, publishing organization, or hosting organization |
|
|
43
43
|
| `gbif_get_dataset` | Fetch full dataset metadata by UUID — title, description, citation, contacts, license, DOI, coverage |
|
|
44
44
|
| `gbif_search_publishers` | Search GBIF-registered publishing organizations by name fragment or country |
|
|
45
45
|
|
|
@@ -53,6 +53,7 @@ Match a scientific or common name against the GBIF backbone taxonomy.
|
|
|
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
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
|
+
- `kingdom` disambiguates a name that appears in more than one kingdom, and is rejected when supplied blank: GBIF drops a blank one and matches against the whole backbone — `Parus major` resolves to taxon 9705453 with `kingdom=` exactly as it does with no `kingdom` at all, where `Plantae` resolves to 9711704 — so the undisambiguated answer would come back looking like a disambiguated one. Omit the field to match against the whole backbone
|
|
56
57
|
|
|
57
58
|
---
|
|
58
59
|
|
|
@@ -87,7 +88,8 @@ Search or browse the GBIF backbone taxonomy.
|
|
|
87
88
|
- Accepts name fragments matching scientific and vernacular names
|
|
88
89
|
- Filter by rank, kingdom, family, or genus to scope browsing
|
|
89
90
|
- `isExtinct` filter for extinct vs. extant taxa
|
|
90
|
-
- Scope to a specific checklist dataset with `datasetKey`
|
|
91
|
+
- Scope to a specific checklist dataset with `datasetKey` — omit the field for the GBIF backbone
|
|
92
|
+
- `q` and `datasetKey` are rejected when supplied blank rather than dropped: a blank `datasetKey` returns the unfiltered backbone result, and `q=` returns the whole 46,623,747-name index where `q=` with a space returns nothing. Omit a filter to leave it off — see the note under `gbif_search_occurrences`
|
|
91
93
|
- Paginated — limit up to 1000, use offset to walk through large groups
|
|
92
94
|
|
|
93
95
|
---
|
|
@@ -118,9 +120,11 @@ List direct children of a backbone taxon.
|
|
|
118
120
|
Search 3.9B+ GBIF occurrence records with full Darwin Core filtering.
|
|
119
121
|
|
|
120
122
|
- Use `taxonKey` from `gbif_match_species` for reliable results — resolves synonyms automatically; `scientificName` filter does not
|
|
121
|
-
- Geographic filters: `country` (ISO 3166-1 alpha-2), `stateProvince`, bounding box (`decimalLatitude`/`decimalLongitude` ranges as "min,max"), or WKT polygon (`geometry`)
|
|
123
|
+
- Geographic filters: `country` (ISO 3166-1 alpha-2, uppercase), `stateProvince`, bounding box (`decimalLatitude`/`decimalLongitude` ranges as "min,max"), or WKT polygon (`geometry`)
|
|
122
124
|
- `publishingCountry` (ISO 3166-1 alpha-2, uppercase) is the country of the *publishing organization*, not of the observation — a different question from `country`, and the two disagree on most records: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations
|
|
125
|
+
- Both country filters take the uppercase two-letter form only. GBIF parses a lowercase or alpha-3 code and then matches the verbatim string, so `gb` and `USA` return zero records instead of an error; the schema pattern turns that silent wrong answer into a validation error naming the accepted form. A two-letter code GBIF does not assign (`XX`) is rejected upstream by name and surfaces as `invalid_filter`
|
|
123
126
|
- `stateProvince` is matched verbatim — exact and case-sensitive, with no controlled vocabulary behind it. Take a value from a `STATE_PROVINCE` facet rather than guessing; an unmatched value returns zero records instead of an error, and the enrichment notice says so when it happens
|
|
127
|
+
- Every filter is checked whenever it is supplied, not only when it holds a value. GBIF ignores a parameter it is given with no value and answers 200 with the unfiltered scope, so a blank filter used to widen the query silently: `stateProvince: ""` returns all 60,290,950 records of a `taxonKey=212` + `country=GB` scope where `England` returns 47,672,439 — the same total, and the same first record, as a call that sends no `stateProvince` at all. A blank or whitespace-only value now fails as `invalid_filter` instead. Omit a field to leave that filter off
|
|
124
128
|
- Temporal filters: `year` as single year or range, `month` (1–12) for seasonal queries
|
|
125
129
|
- `basisOfRecord` enum: `HUMAN_OBSERVATION`, `PRESERVED_SPECIMEN`, `MACHINE_OBSERVATION`, and more
|
|
126
130
|
- `hasCoordinate` to require or exclude georeferenced records
|
|
@@ -136,7 +140,7 @@ Search 3.9B+ GBIF occurrence records with full Darwin Core filtering.
|
|
|
136
140
|
Count occurrences matching a filter without fetching any records.
|
|
137
141
|
|
|
138
142
|
- Backed by `/occurrence/search` at `limit=0` — no record payload, and the same endpoint `gbif_search_occurrences` queries, so the two agree on the same question. GBIF's dedicated `/occurrence/count` endpoint takes a closed parameter set that rejects `occurrenceStatus` and `iucnRedListCategory` outright
|
|
139
|
-
- Supported filters: `taxonKey`, `country`, `publishingCountry`, `stateProvince`, `isGeoreferenced`, `datasetKey`, `year`, `occurrenceStatus`, `iucnRedListCategory`
|
|
143
|
+
- Supported filters: `taxonKey`, `country`, `publishingCountry`, `stateProvince`, `isGeoreferenced`, `datasetKey`, `year`, `occurrenceStatus`, `iucnRedListCategory`. `country` and `publishingCountry` take the uppercase alpha-2 form only, and a blank filter is rejected rather than dropped, both for the reasons given under `gbif_search_occurrences`
|
|
140
144
|
- Counts sightings only by default, matching `gbif_search_occurrences`. For absence-heavy taxa the unfiltered figure is a different question entirely — *Radicipes gracilis* has 2,351,582 indexed records of which 79 are presences
|
|
141
145
|
- Use to assess result set size before deciding whether to paginate a full search. A count above 100,001 means paging cannot reach the end of it, and the enrichment notice says so and names the partition route
|
|
142
146
|
|
|
@@ -162,7 +166,7 @@ Fetch a single occurrence record by GBIF occurrence key.
|
|
|
162
166
|
Aggregate occurrence counts across a dimension.
|
|
163
167
|
|
|
164
168
|
- Facets: `COUNTRY`, `STATE_PROVINCE`, `YEAR`, `BASIS_OF_RECORD`, `DATASET_KEY`, `KINGDOM_KEY`, `PHYLUM_KEY`, `CLASS_KEY`, `ORDER_KEY`, `FAMILY_KEY`, `GENUS_KEY`, `SPECIES_KEY`, `PUBLISHING_COUNTRY`, `MONTH`, `OCCURRENCE_STATUS`, `IUCN_RED_LIST_CATEGORY`
|
|
165
|
-
- Scope with `taxonKey`, `country`, `publishingCountry`, `stateProvince`, `year`, `geometry`, `basisOfRecord`, `datasetKey`, `occurrenceStatus`, or `iucnRedListCategory` filters — so a `PUBLISHING_COUNTRY
|
|
169
|
+
- Scope with `taxonKey`, `country`, `publishingCountry`, `stateProvince`, `year`, `geometry`, `basisOfRecord`, `datasetKey`, `occurrenceStatus`, or `iucnRedListCategory` filters — so a `COUNTRY`, `PUBLISHING_COUNTRY`, or `STATE_PROVINCE` bucket can be passed straight back to drill into it. `country` and `publishingCountry` take the uppercase alpha-2 form only, and a blank filter is rejected rather than dropped, both for the reasons given under `gbif_search_occurrences`
|
|
166
170
|
- Aggregates sightings only by default, matching the search and count tools. To measure the presence/absence split itself, pass `facet: OCCURRENCE_STATUS` with `occurrenceStatus: ANY`
|
|
167
171
|
- 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
|
|
168
172
|
- `DATASET_KEY` is the basis for splitting a result set too large for `gbif_search_occurrences` to page: every occurrence carries exactly one `datasetKey`, so its buckets sum to the scope's full total, and it has the cardinality to cut a large scope into pageable pieces. `BASIS_OF_RECORD` and `PUBLISHING_COUNTRY` are gap-free too and both have a matching filter on the occurrence tools, so either can drive a further split of a bucket still over the cap — but on that scope they return 9 and 41 buckets against `DATASET_KEY`'s 550, too coarse for the first cut. A dimension a record can lack drops that record: a 60,290,950-record scope faceted by `YEAR` sums to 59,407,400, leaving 883,550 undated records out, and `MONTH`, `STATE_PROVINCE`, and `SPECIES_KEY` behave the same way — `STATE_PROVINCE` included, even though the occurrence tools can filter on it
|
|
@@ -174,12 +178,16 @@ Aggregate occurrence counts across a dimension.
|
|
|
174
178
|
|
|
175
179
|
### `gbif_search_datasets`
|
|
176
180
|
|
|
177
|
-
Search GBIF datasets by keyword, type, country, or
|
|
181
|
+
Search GBIF datasets by keyword, type, country, publishing organization, or hosting organization.
|
|
178
182
|
|
|
179
|
-
- Filters: free-text query, dataset type (`OCCURRENCE`, `CHECKLIST`, `METADATA`, `SAMPLING_EVENT`),
|
|
183
|
+
- Filters: free-text query, dataset type (`OCCURRENCE`, `CHECKLIST`, `METADATA`, `SAMPLING_EVENT`), `publishingCountry` (ISO 3166-1 alpha-2, uppercase), publishing and hosting organization UUIDs (lowercase)
|
|
184
|
+
- `publishingCountry` takes the uppercase two-letter form only, for the same reason the occurrence filters do: `/dataset/search` matches the verbatim stored code, so `gb` and `GBR` return zero datasets where `GB` returns 2,416. A two-letter code GBIF does not assign (`XX`) is rejected upstream by name and surfaces as `invalid_filter`
|
|
180
185
|
- Returns title, type, description, license, DOI, and record count. `recordCount` spans every `occurrenceStatus`, absences included — `gbif_count_occurrences` with the same key counts sightings only by default, so the two figures differ by design
|
|
181
186
|
- The `description` is a 300-character preview — `descriptionTruncated` flags when it was shortened, and `gbif_get_dataset` returns the full text
|
|
182
|
-
-
|
|
187
|
+
- An organization key from `gbif_search_publishers` chains in two ways, and they answer different questions. `publishingOrg` matches the organization whose data it is; `hostingOrg` matches the organization whose installation serves it. `publishingOrg` is almost always the one meant — Butterfly Conservation (`0d72dd7f-6f05-46af-85c2-8b6e77ce5534`) publishes 3 datasets and hosts none, while the National Biodiversity Network (`07f617d0-c688-11d8-bf62-b8a03c50a862`) hosts 984, those 3 among them, and publishes 1
|
|
188
|
+
- Supplying both organization filters intersects them rather than combining them, so the same key in both fields returns only what that organization published *and* serves. An empty result under both is called out by name in the response notice
|
|
189
|
+
- Both take the lowercase 8-4-4-4-12 hex UUID form and are checked before the request goes out, because GBIF answers the two silent ways of getting them wrong with a wrong result rather than an error: an empty organization value returns the whole 123,527-dataset index, and these two filters are matched case-sensitively, so an upper-cased key returns 0 where the same key lowercased matches. Both fail locally as `invalid_filter`, as a malformed value does
|
|
190
|
+
- The free-text `q` is rejected blank on the same ground, and the route makes the case plainly: `q=` returns all 123,527 datasets while `q=` with a single space returns none. One character between the whole index and an empty page is not a distinction to leave to chance — omit the field to browse without a term
|
|
183
191
|
- Paginated — limit up to 1000
|
|
184
192
|
|
|
185
193
|
---
|
|
@@ -202,7 +210,9 @@ Fetch full dataset metadata by UUID.
|
|
|
202
210
|
Search organizations registered with GBIF.
|
|
203
211
|
|
|
204
212
|
- Filter by name fragment or country
|
|
205
|
-
-
|
|
213
|
+
- `country` here is unconstrained on purpose: the registry endpoint matches the *parsed* country rather than the verbatim string, so `gb`, `GBR`, and `GB` all return the same 223 organizations. The uppercase-only rule the occurrence tools and `gbif_search_datasets` carry exists to close a silent zero that does not occur on this route. One value is rejected — an empty `country`, which the registry answers with all 3,561 registered organizations rather than an error; omit the field to search every country. Whitespace alone is left to the registry, which answers it with `400 Cannot parse … into a known Country`, an error naming the value
|
|
214
|
+
- `q` is rejected blank in both forms, because the registry drops either one and answers with all 3,561 organizations against 460 for `museum`; omit the field to browse without a name term
|
|
215
|
+
- Returns organization key, title, and country. The key chains into `gbif_search_datasets` as `publishingOrg` for the datasets the organization published, or as `hostingOrg` for the ones its own installation serves. `publishingOrg` is the usual chain: of the first 25 GB organizations the registry lists, all 25 host no datasets while 13 publish one or two
|
|
206
216
|
- Paginated — limit up to 1000
|
|
207
217
|
|
|
208
218
|
## Resources
|
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, unlike the raw scientificName filter. Countries use ISO 3166-1 alpha-2; datasets and publishers are keyed by UUID, occurrences by integer key. 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. 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. 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 will exceed a gbif_count_occurrences total for the same datasetKey by design. 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 — leaves those records in no bucket, stateProvince included even though the occurrence tools can filter on it, while BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free and both have a matching search filter, making either a sound second cut on a bucket still over the cap though too coarse for the first. Bucket sums reconcile only against the same occurrenceStatus, and only when the facet call repeats the search filters — gbif_occurrence_facets accepts a narrower set than gbif_search_occurrences and gbif_count_occurrences, so re-apply whatever it cannot take on each per-datasetKey search. 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.',
|
|
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. 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, where the uppercase-only pattern rejects it at the schema and the failure arrives as JSON-RPC -32602 with empty structuredContent. 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. 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. 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. 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 will exceed a gbif_count_occurrences total for the same datasetKey by design. 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 — leaves those records in no bucket, stateProvince included even though the occurrence tools can filter on it, while BASIS_OF_RECORD and PUBLISHING_COUNTRY are gap-free and both have a matching search filter, making either a sound second cut on a bucket still over the cap though too coarse for the first. Bucket sums reconcile only against the same occurrenceStatus, and only when the facet call repeats the search filters — gbif_occurrence_facets accepts a narrower set than gbif_search_occurrences and gbif_count_occurrences, so re-apply whatever it cannot take on each per-datasetKey search. 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.',
|
|
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,
|
|
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,guIAAguI;IACluI,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"}
|
|
@@ -33,8 +33,8 @@ export declare const gbifCountOccurrences: import("@cyanheads/mcp-ts-core").Tool
|
|
|
33
33
|
}, z.core.$strip>, readonly [{
|
|
34
34
|
readonly reason: "invalid_filter";
|
|
35
35
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
36
|
-
readonly when: "datasetKey is not
|
|
37
|
-
readonly recovery: "
|
|
36
|
+
readonly when: "A filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected another filter value as malformed.";
|
|
37
|
+
readonly recovery: "A blank filter is not a way to skip one — omit the field instead. Otherwise: 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; country and publishingCountry are codes GBIF assigns, so take one from a COUNTRY or PUBLISHING_COUNTRY facet on gbif_occurrence_facets.";
|
|
38
38
|
}], {
|
|
39
39
|
readonly occurrenceStatus: z.ZodString;
|
|
40
40
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
@@ -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;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+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;AAWjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuL/B,CAAC"}
|
|
@@ -6,12 +6,13 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
7
|
import { getGbifService } from '../../../services/gbif/gbif-service.js';
|
|
8
8
|
import { IUCN_RED_LIST_CATEGORY_VALUES, OCCURRENCE_STATUS_VALUES } from '../../../services/gbif/types.js';
|
|
9
|
-
import { isGbifUuid, occurrenceStatusNotice, overPaginationCapNotice, stateProvinceNoMatchNotice, } from '../utils.js';
|
|
9
|
+
import { firstBlankFilter, isGbifUuid, occurrenceStatusNotice, overPaginationCapNotice, stateProvinceNoMatchNotice, } from '../utils.js';
|
|
10
10
|
export const gbifCountOccurrences = tool('gbif_count_occurrences', {
|
|
11
11
|
title: 'Count Occurrences',
|
|
12
12
|
description: 'Count occurrences matching a taxon + location filter without fetching records. ' +
|
|
13
13
|
'Use for quick totals ("how many Aves records in Sweden?") or before deciding whether ' +
|
|
14
|
-
'to paginate a full search. Accepts taxonKey, country
|
|
14
|
+
'to paginate a full search. Accepts taxonKey, country (uppercase ISO 3166-1 alpha-2), ' +
|
|
15
|
+
'publishingCountry, stateProvince, ' +
|
|
15
16
|
'isGeoreferenced, datasetKey, year, ' +
|
|
16
17
|
'occurrenceStatus, and iucnRedListCategory. Counts sightings only by default, matching ' +
|
|
17
18
|
'gbif_search_occurrences — GBIF also indexes absence records, and for some taxa they are ' +
|
|
@@ -26,17 +27,18 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
|
|
|
26
27
|
.describe('GBIF backbone taxon key from gbif_match_species. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).'),
|
|
27
28
|
country: z
|
|
28
29
|
.string()
|
|
30
|
+
.regex(/^[A-Z]{2}$/, 'country must be an uppercase ISO 3166-1 alpha-2 code such as GB, US, or SE. Lowercase ("gb"), alpha-3 ("USA"), and country names ("Britain") match no records upstream.')
|
|
29
31
|
.optional()
|
|
30
|
-
.describe('ISO 3166-1 alpha-2 code of where the occurrence was recorded (e.g., "GB", "US"). Not the publisher\'s country — that is publishingCountry, and the two disagree on most records.'),
|
|
32
|
+
.describe('ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded (e.g., "GB", "US"). Not the publisher\'s country — that is publishingCountry, and the two disagree on most records. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here. Take a value from a COUNTRY facet on gbif_occurrence_facets; an uppercase pair GBIF does not know ("XX") is rejected upstream by name.'),
|
|
31
33
|
publishingCountry: z
|
|
32
34
|
.string()
|
|
33
|
-
.regex(/^[A-Z]{2}
|
|
35
|
+
.regex(/^[A-Z]{2}$/, 'publishingCountry must be an uppercase ISO 3166-1 alpha-2 code such as GB, US, or SE. Lowercase ("us"), alpha-3 ("USA"), and country names ("Britain") match no records upstream.')
|
|
34
36
|
.optional()
|
|
35
37
|
.describe('ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. The two differ constantly: of 60,290,950 records observed in GB, 1,548,928 were published by US organizations. Take a value from a PUBLISHING_COUNTRY facet on gbif_occurrence_facets. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.'),
|
|
36
38
|
stateProvince: z
|
|
37
39
|
.string()
|
|
38
40
|
.optional()
|
|
39
|
-
.describe('State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring.'),
|
|
41
|
+
.describe('State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. GBIF stores what each dataset recorded without normalizing it, so there is no vocabulary to guess from: "England", "England - Greater London", and "Greater London" are three distinct values, and "england" is none of them. Take one from a STATE_PROVINCE facet on gbif_occurrence_facets scoped the same way and pass it back unchanged — an unmatched value counts zero rather than erroring. Omit the field to count across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.'),
|
|
40
42
|
isGeoreferenced: z
|
|
41
43
|
.boolean()
|
|
42
44
|
.optional()
|
|
@@ -44,11 +46,11 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
|
|
|
44
46
|
datasetKey: z
|
|
45
47
|
.string()
|
|
46
48
|
.optional()
|
|
47
|
-
.describe('Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default.'),
|
|
49
|
+
.describe('Filter to a specific dataset UUID (8-4-4-4-12 hex) from gbif_search_datasets. Omit the field to count across every dataset — an empty string is rejected rather than read as no filter, because GBIF answers a blank datasetKey with the unfiltered total. The result is not the recordCount the dataset tools and the gbif://dataset/{datasetKey} resource report for the same key: that figure spans every occurrenceStatus, while this count applies occurrenceStatus below, PRESENT by default.'),
|
|
48
50
|
year: z
|
|
49
51
|
.string()
|
|
50
52
|
.optional()
|
|
51
|
-
.describe('Year or year range (e.g., "2024" or "2020,2024"). Both endpoints inclusive.'),
|
|
53
|
+
.describe('Year or year range (e.g., "2024" or "2020,2024"). Both endpoints inclusive. Omit the field to count across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered total.'),
|
|
52
54
|
occurrenceStatus: z
|
|
53
55
|
.enum(OCCURRENCE_STATUS_VALUES)
|
|
54
56
|
.default('PRESENT')
|
|
@@ -75,8 +77,8 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
|
|
|
75
77
|
{
|
|
76
78
|
reason: 'invalid_filter',
|
|
77
79
|
code: JsonRpcErrorCode.InvalidParams,
|
|
78
|
-
when: 'datasetKey is not
|
|
79
|
-
recovery: '
|
|
80
|
+
when: 'A filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected another filter value as malformed.',
|
|
81
|
+
recovery: 'A blank filter is not a way to skip one — omit the field instead. Otherwise: 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; country and publishingCountry are codes GBIF assigns, so take one from a COUNTRY or PUBLISHING_COUNTRY facet on gbif_occurrence_facets.',
|
|
80
82
|
},
|
|
81
83
|
],
|
|
82
84
|
async handler(input, ctx) {
|
|
@@ -84,19 +86,45 @@ export const gbifCountOccurrences = tool('gbif_count_occurrences', {
|
|
|
84
86
|
taxonKey: input.taxonKey,
|
|
85
87
|
country: input.country,
|
|
86
88
|
});
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
89
|
+
/**
|
|
90
|
+
* Both string filters this tool forwards, checked on presence rather than on a
|
|
91
|
+
* non-blank value. `/occurrence/search` ignores a parameter it is given with no
|
|
92
|
+
* value and answers the unfiltered total, so the `?.trim()` spread these fields
|
|
93
|
+
* used to sit behind widened the count and reported it as the caller's own:
|
|
94
|
+
* `stateProvince: ""` counts all 60,290,950 records of a `taxonKey=212` +
|
|
95
|
+
* `country=GB` scope where `England` counts 47,672,439, and a whitespace-only
|
|
96
|
+
* value does the same. A count is the whole output here, so nothing else in the
|
|
97
|
+
* response contradicts the wrong figure.
|
|
98
|
+
*/
|
|
99
|
+
const blankFilter = firstBlankFilter({
|
|
100
|
+
stateProvince: input.stateProvince,
|
|
101
|
+
year: input.year,
|
|
102
|
+
});
|
|
103
|
+
if (blankFilter) {
|
|
104
|
+
throw ctx.fail('invalid_filter', `${blankFilter} was supplied blank. Omit the field to leave it unfiltered — a blank value is not a way to skip a filter.`, { ...ctx.recoveryFor('invalid_filter') });
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* Checked whenever datasetKey is present, not only when it is non-blank. A
|
|
108
|
+
* malformed key is rejected locally so the failure carries this tool's recovery
|
|
109
|
+
* hint instead of a bare upstream 400 that costs a round trip and the retry
|
|
110
|
+
* budget. The empty string is rejected for the opposite reason: it draws no error
|
|
111
|
+
* at all — `/occurrence/search?datasetKey=` answers 200 with the unfiltered scope,
|
|
112
|
+
* so a `?.trim()` guard dropped the filter and returned all 2,351,689,943 records
|
|
113
|
+
* under taxonKey 212 to a caller who believed the count was scoped to one dataset.
|
|
114
|
+
* Letter case stays unchecked: this route resolves a key either way, unlike
|
|
115
|
+
* `/dataset/search`'s two organization filters.
|
|
116
|
+
*/
|
|
117
|
+
if (input.datasetKey !== undefined && !isGbifUuid(input.datasetKey)) {
|
|
90
118
|
throw ctx.fail('invalid_filter', `datasetKey "${input.datasetKey}" is not a GBIF dataset UUID.`, { ...ctx.recoveryFor('invalid_filter') });
|
|
91
119
|
}
|
|
92
120
|
const count = await getGbifService().countOccurrences({
|
|
93
121
|
...(input.taxonKey !== undefined && { taxonKey: input.taxonKey }),
|
|
94
|
-
...(input.country
|
|
122
|
+
...(input.country && { country: input.country }),
|
|
95
123
|
...(input.publishingCountry && { publishingCountry: input.publishingCountry }),
|
|
96
|
-
...(input.stateProvince
|
|
124
|
+
...(input.stateProvince !== undefined && { stateProvince: input.stateProvince }),
|
|
97
125
|
...(input.isGeoreferenced !== undefined && { isGeoreferenced: input.isGeoreferenced }),
|
|
98
|
-
...(input.datasetKey
|
|
99
|
-
...(input.year
|
|
126
|
+
...(input.datasetKey !== undefined && { datasetKey: input.datasetKey }),
|
|
127
|
+
...(input.year !== undefined && { year: input.year }),
|
|
100
128
|
...(input.occurrenceStatus !== 'ANY' && { occurrenceStatus: input.occurrenceStatus }),
|
|
101
129
|
...(input.iucnRedListCategory && { iucnRedListCategory: input.iucnRedListCategory }),
|
|
102
130
|
}, ctx);
|
|
@@ -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,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACnG,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,wBAAwB,EAAE;IACjE,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,iFAAiF;QACjF,uFAAuF;QACvF,
|
|
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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"}
|
|
@@ -46,6 +46,11 @@ export declare const gbifMatchSpecies: import("@cyanheads/mcp-ts-core").ToolDefi
|
|
|
46
46
|
readonly code: JsonRpcErrorCode.NotFound;
|
|
47
47
|
readonly when: "matchType is NONE — no candidate met the match threshold.";
|
|
48
48
|
readonly recovery: "Try a broader name, remove the strict flag, or search with gbif_search_species instead.";
|
|
49
|
+
}, {
|
|
50
|
+
readonly reason: "invalid_filter";
|
|
51
|
+
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
52
|
+
readonly when: "kingdom was supplied blank or whitespace-only, which disambiguates nothing.";
|
|
53
|
+
readonly recovery: "Supply kingdom as a backbone kingdom name such as Animalia, Plantae, or Fungi, or omit the field to match against the whole backbone — a blank value is not a way to skip the filter.";
|
|
49
54
|
}], {
|
|
50
55
|
readonly notice: z.ZodOptional<z.ZodString>;
|
|
51
56
|
}>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gbif-match-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-match-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"gbif-match-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-match-species.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,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6O3B,CAAC"}
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
7
|
import { getGbifService } from '../../../services/gbif/gbif-service.js';
|
|
8
|
+
import { firstBlankFilter } from '../utils.js';
|
|
8
9
|
export const gbifMatchSpecies = tool('gbif_match_species', {
|
|
9
10
|
title: 'Match Species Name',
|
|
10
11
|
description: 'Match a scientific name against the GBIF backbone taxonomy. ' +
|
|
@@ -27,7 +28,7 @@ export const gbifMatchSpecies = tool('gbif_match_species', {
|
|
|
27
28
|
kingdom: z
|
|
28
29
|
.string()
|
|
29
30
|
.optional()
|
|
30
|
-
.describe('Narrow the match to a specific kingdom (e.g., "Animalia", "Plantae", "Fungi") to disambiguate names that appear in multiple kingdoms.'),
|
|
31
|
+
.describe('Narrow the match to a specific kingdom (e.g., "Animalia", "Plantae", "Fungi") to disambiguate names that appear in multiple kingdoms. Omit the field to match against the whole backbone — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the undisambiguated match, which is indistinguishable from a match that honored the kingdom.'),
|
|
31
32
|
rank: z
|
|
32
33
|
.enum(['KINGDOM', 'PHYLUM', 'CLASS', 'ORDER', 'FAMILY', 'GENUS', 'SPECIES', 'SUBSPECIES'])
|
|
33
34
|
.optional()
|
|
@@ -77,10 +78,10 @@ export const gbifMatchSpecies = tool('gbif_match_species', {
|
|
|
77
78
|
.describe('Guidance when the queried name was a synonym and taxonKey was resolved to the accepted taxon. Absent when the matched name is already the accepted one.'),
|
|
78
79
|
},
|
|
79
80
|
/**
|
|
80
|
-
*
|
|
81
|
-
* schema can produce — a malformed kingdom, an
|
|
82
|
-
* long, or control-character name all come
|
|
83
|
-
*
|
|
81
|
+
* `invalid_filter` covers a locally rejected value only. `/species/match` answers
|
|
82
|
+
* HTTP 200 for every input this schema can produce — a malformed kingdom, an
|
|
83
|
+
* out-of-enum rank, and an empty, very long, or control-character name all come
|
|
84
|
+
* back as a normal match or matchType NONE — so nothing upstream can raise it.
|
|
84
85
|
*/
|
|
85
86
|
errors: [
|
|
86
87
|
{
|
|
@@ -89,13 +90,32 @@ export const gbifMatchSpecies = tool('gbif_match_species', {
|
|
|
89
90
|
when: 'matchType is NONE — no candidate met the match threshold.',
|
|
90
91
|
recovery: 'Try a broader name, remove the strict flag, or search with gbif_search_species instead.',
|
|
91
92
|
},
|
|
93
|
+
{
|
|
94
|
+
reason: 'invalid_filter',
|
|
95
|
+
code: JsonRpcErrorCode.InvalidParams,
|
|
96
|
+
when: 'kingdom was supplied blank or whitespace-only, which disambiguates nothing.',
|
|
97
|
+
recovery: 'Supply kingdom as a backbone kingdom name such as Animalia, Plantae, or Fungi, or omit the field to match against the whole backbone — a blank value is not a way to skip the filter.',
|
|
98
|
+
},
|
|
92
99
|
],
|
|
93
100
|
async handler(input, ctx) {
|
|
94
101
|
ctx.log.info('Matching species name', { name: input.name, strict: input.strict });
|
|
102
|
+
/**
|
|
103
|
+
* Checked on presence rather than on a non-blank value. `/species/match` ignores
|
|
104
|
+
* a blank kingdom and matches against the whole backbone: `Parus major` with
|
|
105
|
+
* `kingdom=` and with `kingdom=%20%20` each resolve to usageKey 9705453 at
|
|
106
|
+
* confidence 99, the same as omitting the field, where `kingdom=Plantae` resolves
|
|
107
|
+
* to 9711704 instead. The undisambiguated answer is the one the caller reached
|
|
108
|
+
* for this field to avoid, and nothing in the response says the constraint was
|
|
109
|
+
* dropped.
|
|
110
|
+
*/
|
|
111
|
+
const blankFilter = firstBlankFilter({ kingdom: input.kingdom });
|
|
112
|
+
if (blankFilter) {
|
|
113
|
+
throw ctx.fail('invalid_filter', `${blankFilter} was supplied blank. Omit the field to leave it unfiltered — a blank value is not a way to skip a filter.`, { ...ctx.recoveryFor('invalid_filter') });
|
|
114
|
+
}
|
|
95
115
|
const raw = await getGbifService().matchSpecies({
|
|
96
116
|
name: input.name,
|
|
97
117
|
strict: input.strict,
|
|
98
|
-
...(input.kingdom
|
|
118
|
+
...(input.kingdom !== undefined && { kingdom: input.kingdom }),
|
|
99
119
|
...(input.rank && { rank: input.rank }),
|
|
100
120
|
}, ctx);
|
|
101
121
|
if (raw.matchType === 'NONE' || !raw.usageKey) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gbif-match-species.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-match-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;
|
|
1
|
+
{"version":3,"file":"gbif-match-species.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-match-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,oBAAoB,EAAE;IACzD,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,8DAA8D;QAC9D,2FAA2F;QAC3F,4FAA4F;QAC5F,2FAA2F;QAC3F,wFAAwF;QACxF,0FAA0F;QAC1F,gFAAgF;QAChF,uGAAuG;IACzG,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,CACP,kOAAkO,CACnO;QACH,MAAM,EAAE,CAAC;aACN,OAAO,EAAE;aACT,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CACP,wJAAwJ,CACzJ;QACH,OAAO,EAAE,CAAC;aACP,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yXAAyX,CAC1X;QACH,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;aACzF,QAAQ,EAAE;aACV,QAAQ,CACP,mFAAmF,CACpF;KACJ,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,0JAA0J,CAC3J;QACH,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,0JAA0J,CAC3J;QACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QACvF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QACpF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;QAC5E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;QAC3F,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,yDAAyD,CAAC;QACtE,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,gEAAgE,CAAC;QAC7E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;QACxE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QACtE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACpE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACpE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QACtE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACpE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;QACvF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QACjF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC/E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC7E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC7E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC/E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC7E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;KAClF,CAAC;IAEF,uEAAuE;IACvE,UAAU,EAAE;QACV,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,yJAAyJ,CAC1J;KACJ;IAED;;;;;OAKG;IACH,MAAM,EAAE;QACN;YACE,MAAM,EAAE,UAAU;YAClB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,2DAA2D;YACjE,QAAQ,EACN,yFAAyF;SAC5F;QACD;YACE,MAAM,EAAE,gBAAgB;YACxB,IAAI,EAAE,gBAAgB,CAAC,aAAa;YACpC,IAAI,EAAE,6EAA6E;YACnF,QAAQ,EACN,uLAAuL;SAC1L;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAClF;;;;;;;;WAQG;QACH,MAAM,WAAW,GAAG,gBAAgB,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,GAAG,CAAC,IAAI,CACZ,gBAAgB,EAChB,GAAG,WAAW,2GAA2G,EACzH,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,CACzC,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,cAAc,EAAE,CAAC,YAAY,CAC7C;YACE,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9D,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;SACxC,EACD,GAAG,CACJ,CAAC;QAEF,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC9C,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,0BAA0B,KAAK,CAAC,IAAI,GAAG,EAAE;gBAClE,GAAG,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC;QAED;;;;;WAKG;QACH,MAAM,eAAe,GAAG,GAAG,CAAC,QAAQ,CAAC;QACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,gBAAgB,IAAI,eAAe,CAAC;QACzD,MAAM,eAAe,GAAG,QAAQ,KAAK,eAAe,CAAC;QAErD,IAAI,eAAe,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,MAAM,CACf,IAAI,KAAK,CAAC,IAAI,4BAA4B,eAAe,YAAY,GAAG,CAAC,MAAM,IAAI,SAAS,eAAe,QAAQ,sKAAsK,QAAQ,yBAAyB,CAC3T,CAAC;QACJ,CAAC;QAED,OAAO;YACL,QAAQ;YACR,GAAG,CAAC,eAAe,IAAI,EAAE,eAAe,EAAE,CAAC;YAC3C,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,aAAa,EAAE,GAAG,CAAC,aAAa;YAChC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,UAAU,EAAE,GAAG,CAAC,UAAU;SAC3B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,aAAa;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;QACnE,IAAI,MAAM,CAAC,cAAc;YAAE,KAAK,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;QACvF,IAAI,MAAM,CAAC,QAAQ,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7E,IAAI,MAAM,CAAC,eAAe,IAAI,IAAI,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CACR,0BAA0B,MAAM,CAAC,eAAe,6FAA6F,CAC9I,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACxD,IAAI,MAAM,CAAC,MAAM;YAAE,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QACxE,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,MAAM,CAAC,UAAU,MAAM,CAAC,CAAC;QACtF,MAAM,mBAAmB,GAAa,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,OAAO;YAChB,mBAAmB,CAAC,IAAI,CACtB,YAAY,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAClF,CAAC;QACJ,IAAI,MAAM,CAAC,MAAM;YACf,mBAAmB,CAAC,IAAI,CACtB,WAAW,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9E,CAAC;QACJ,IAAI,MAAM,CAAC,KAAK;YACd,mBAAmB,CAAC,IAAI,CACtB,UAAU,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1E,CAAC;QACJ,IAAI,MAAM,CAAC,KAAK;YACd,mBAAmB,CAAC,IAAI,CACtB,UAAU,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1E,CAAC;QACJ,IAAI,MAAM,CAAC,MAAM;YACf,mBAAmB,CAAC,IAAI,CACtB,WAAW,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9E,CAAC;QACJ,IAAI,MAAM,CAAC,KAAK;YACd,mBAAmB,CAAC,IAAI,CACtB,UAAU,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC1E,CAAC;QACJ,IAAI,MAAM,CAAC,OAAO;YAChB,mBAAmB,CAAC,IAAI,CACtB,YAAY,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAClF,CAAC;QACJ,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,uBAAuB,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}
|
|
@@ -68,8 +68,8 @@ export declare const gbifOccurrenceFacets: import("@cyanheads/mcp-ts-core").Tool
|
|
|
68
68
|
}, z.core.$strip>, readonly [{
|
|
69
69
|
readonly reason: "invalid_filter";
|
|
70
70
|
readonly code: JsonRpcErrorCode.InvalidParams;
|
|
71
|
-
readonly when: "datasetKey is not
|
|
72
|
-
readonly recovery: "The message names the rejected value.
|
|
71
|
+
readonly when: "A scope filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected the geometry or year scope as malformed.";
|
|
72
|
+
readonly recovery: "The message names the rejected value. A blank scope filter is not a way to skip one — omit the field instead. Otherwise correct that one filter: geometry is a closed WKT ring in longitude latitude order, year is a single year or \"min,max\", datasetKey is a UUID from gbif_search_datasets, and country and publishingCountry are codes GBIF assigns, so take one from a COUNTRY or PUBLISHING_COUNTRY facet.";
|
|
73
73
|
}], {
|
|
74
74
|
readonly facetLimit: z.ZodNumber;
|
|
75
75
|
readonly facetOffset: z.ZodNumber;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"gbif-occurrence-facets.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-occurrence-facets.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;
|
|
1
|
+
{"version":3,"file":"gbif-occurrence-facets.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-occurrence-facets.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAwCjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0Q/B,CAAC"}
|
|
@@ -6,7 +6,7 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
|
|
|
6
6
|
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
|
|
7
7
|
import { getGbifService } from '../../../services/gbif/gbif-service.js';
|
|
8
8
|
import { IUCN_RED_LIST_CATEGORY_VALUES, OCCURRENCE_STATUS_VALUES } from '../../../services/gbif/types.js';
|
|
9
|
-
import { isGbifUuid, occurrenceStatusNotice, stateProvinceNoMatchNotice } from '../utils.js';
|
|
9
|
+
import { firstBlankFilter, isGbifUuid, occurrenceStatusNotice, stateProvinceNoMatchNotice, } from '../utils.js';
|
|
10
10
|
const BASIS_OF_RECORD_VALUES = [
|
|
11
11
|
'HUMAN_OBSERVATION',
|
|
12
12
|
'MACHINE_OBSERVATION',
|
|
@@ -42,7 +42,8 @@ export const gbifOccurrenceFacets = tool('gbif_occurrence_facets', {
|
|
|
42
42
|
'facetLimit at facetOffset 0, a later slice of the same ranking past that. No record payloads returned. ' +
|
|
43
43
|
'Core tool for distribution analysis and trend queries: "which countries have the most records ' +
|
|
44
44
|
'for this species?", "how has observation volume changed since 2010?". ' +
|
|
45
|
-
'Scope the aggregation with taxonKey, country
|
|
45
|
+
'Scope the aggregation with taxonKey, country (uppercase ISO 3166-1 alpha-2), ' +
|
|
46
|
+
'publishingCountry, stateProvince, year, ' +
|
|
46
47
|
'geometry, basisOfRecord, datasetKey, ' +
|
|
47
48
|
'occurrenceStatus, or iucnRedListCategory filters. Also the way to split a result set too ' +
|
|
48
49
|
'large for gbif_search_occurrences to page (offset+limit caps at 100,001): facet by ' +
|
|
@@ -60,21 +61,22 @@ export const gbifOccurrenceFacets = tool('gbif_occurrence_facets', {
|
|
|
60
61
|
.describe('Backbone taxon key to scope the aggregation. Matches the given taxon and all descendant taxa (subspecies, varieties, etc.).'),
|
|
61
62
|
country: z
|
|
62
63
|
.string()
|
|
64
|
+
.regex(/^[A-Z]{2}$/, 'country must be an uppercase ISO 3166-1 alpha-2 code such as GB, US, or SE. Lowercase ("gb"), alpha-3 ("USA"), and country names ("Britain") match no records upstream.')
|
|
63
65
|
.optional()
|
|
64
|
-
.describe(
|
|
66
|
+
.describe('ISO 3166-1 alpha-2 code, uppercase, of where the occurrence was recorded, to scope to one country. Not the publisher\'s country — that is publishingCountry, and the two disagree on most records. Scope to one country, or pass back a value this tool returned under facet COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("gb", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.'),
|
|
65
67
|
publishingCountry: z
|
|
66
68
|
.string()
|
|
67
|
-
.regex(/^[A-Z]{2}
|
|
69
|
+
.regex(/^[A-Z]{2}$/, 'publishingCountry must be an uppercase ISO 3166-1 alpha-2 code such as GB, US, or SE. Lowercase ("us"), alpha-3 ("USA"), and country names ("Britain") match no records upstream.')
|
|
68
70
|
.optional()
|
|
69
71
|
.describe('ISO 3166-1 alpha-2 code, uppercase, of the organization that published the record — not where the occurrence was observed, which is country. Scope to one publisher country, or pass back a value this tool returned under facet PUBLISHING_COUNTRY to drill into that bucket. Lowercase and alpha-3 forms ("us", "USA") match nothing upstream, which is why only the uppercase two-letter form is accepted here.'),
|
|
70
72
|
stateProvince: z
|
|
71
73
|
.string()
|
|
72
74
|
.optional()
|
|
73
|
-
.describe('State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so "England", "England - Greater London", and "Greater London" are three distinct values, "england" is none of them, and an unmatched value aggregates zero records rather than erroring.'),
|
|
75
|
+
.describe('State, province, or first-level administrative division, matched as a verbatim string — exact and case-sensitive. Pass back a value this tool returned under facet STATE_PROVINCE rather than a guessed one: GBIF stores what each dataset recorded without normalizing it, so "England", "England - Greater London", and "Greater London" are three distinct values, "england" is none of them, and an unmatched value aggregates zero records rather than erroring. Omit the field to aggregate across every state or province — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.'),
|
|
74
76
|
year: z
|
|
75
77
|
.string()
|
|
76
78
|
.optional()
|
|
77
|
-
.describe('Year or year range (e.g., "2020,2024") to scope the aggregation. Both endpoints inclusive.'),
|
|
79
|
+
.describe('Year or year range (e.g., "2020,2024") to scope the aggregation. Both endpoints inclusive. Omit the field to aggregate across every year — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.'),
|
|
78
80
|
basisOfRecord: z
|
|
79
81
|
.enum(BASIS_OF_RECORD_VALUES)
|
|
80
82
|
.optional()
|
|
@@ -82,11 +84,11 @@ export const gbifOccurrenceFacets = tool('gbif_occurrence_facets', {
|
|
|
82
84
|
geometry: z
|
|
83
85
|
.string()
|
|
84
86
|
.optional()
|
|
85
|
-
.describe('WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude.'),
|
|
87
|
+
.describe('WKT polygon to scope the aggregation to a geographic area (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Omit the field to aggregate everywhere — a blank or whitespace-only value is rejected rather than dropped, because GBIF answers one with the unfiltered aggregation.'),
|
|
86
88
|
datasetKey: z
|
|
87
89
|
.string()
|
|
88
90
|
.optional()
|
|
89
|
-
.describe('Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record.'),
|
|
91
|
+
.describe('Scope the aggregation to a single dataset by its GBIF dataset UUID (8-4-4-4-12 hex). Obtain one from gbif_search_datasets, gbif_get_dataset, a DATASET_KEY facet, or the datasetKey field on an occurrence record. Omit the field to aggregate across every dataset — an empty string is rejected rather than read as no scope, because GBIF answers a blank datasetKey with the unfiltered aggregation.'),
|
|
90
92
|
occurrenceStatus: z
|
|
91
93
|
.enum(OCCURRENCE_STATUS_VALUES)
|
|
92
94
|
.default('PRESENT')
|
|
@@ -138,25 +140,54 @@ export const gbifOccurrenceFacets = tool('gbif_occurrence_facets', {
|
|
|
138
140
|
{
|
|
139
141
|
reason: 'invalid_filter',
|
|
140
142
|
code: JsonRpcErrorCode.InvalidParams,
|
|
141
|
-
when: 'datasetKey is not
|
|
142
|
-
recovery: 'The message names the rejected value.
|
|
143
|
+
when: 'A scope filter was supplied blank or whitespace-only, datasetKey is not an 8-4-4-4-12 hex UUID, a two-letter country or publishingCountry code is one GBIF does not know, or GBIF rejected the geometry or year scope as malformed.',
|
|
144
|
+
recovery: 'The message names the rejected value. A blank scope filter is not a way to skip one — omit the field instead. Otherwise correct that one filter: geometry is a closed WKT ring in longitude latitude order, year is a single year or "min,max", datasetKey is a UUID from gbif_search_datasets, and country and publishingCountry are codes GBIF assigns, so take one from a COUNTRY or PUBLISHING_COUNTRY facet.',
|
|
143
145
|
},
|
|
144
146
|
],
|
|
145
147
|
async handler(input, ctx) {
|
|
146
148
|
ctx.log.info('Fetching occurrence facets', { facet: input.facet, taxonKey: input.taxonKey });
|
|
147
|
-
|
|
149
|
+
/**
|
|
150
|
+
* Every string scope filter this tool forwards, checked on presence rather than
|
|
151
|
+
* on a non-blank value. `/occurrence/search` ignores a parameter it is given with
|
|
152
|
+
* no value and answers the unfiltered aggregation, so the `?.trim()` spread these
|
|
153
|
+
* fields used to sit behind partitioned a wider scope than the caller asked
|
|
154
|
+
* about: `stateProvince: ""` aggregates all 60,290,950 records of a
|
|
155
|
+
* `taxonKey=212` + `country=GB` scope where `England` aggregates 47,672,439, and
|
|
156
|
+
* a whitespace-only value does the same. Buckets hide the substitution better
|
|
157
|
+
* than a record list does — nothing in them says which scope they cover.
|
|
158
|
+
*/
|
|
159
|
+
const blankFilter = firstBlankFilter({
|
|
160
|
+
stateProvince: input.stateProvince,
|
|
161
|
+
year: input.year,
|
|
162
|
+
geometry: input.geometry,
|
|
163
|
+
});
|
|
164
|
+
if (blankFilter) {
|
|
165
|
+
throw ctx.fail('invalid_filter', `${blankFilter} was supplied blank. Omit the field to leave it unfiltered — a blank value is not a way to skip a filter.`, { ...ctx.recoveryFor('invalid_filter') });
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Checked whenever datasetKey is present, not only when it is non-blank. A
|
|
169
|
+
* malformed key is rejected locally so the failure carries this tool's recovery
|
|
170
|
+
* hint instead of a bare upstream 400 that costs a round trip and the retry
|
|
171
|
+
* budget. The empty string is rejected for the opposite reason: it draws no error
|
|
172
|
+
* at all — `/occurrence/search?datasetKey=` answers 200 with the unfiltered scope,
|
|
173
|
+
* so a `?.trim()` guard dropped the scope and aggregated all 2,351,689,943 records
|
|
174
|
+
* under taxonKey 212 for a caller who believed the buckets covered one dataset.
|
|
175
|
+
* Letter case stays unchecked: this route resolves a key either way, unlike
|
|
176
|
+
* `/dataset/search`'s two organization filters.
|
|
177
|
+
*/
|
|
178
|
+
if (input.datasetKey !== undefined && !isGbifUuid(input.datasetKey)) {
|
|
148
179
|
throw ctx.fail('invalid_filter', `datasetKey "${input.datasetKey}" is not a GBIF dataset UUID.`, { ...ctx.recoveryFor('invalid_filter') });
|
|
149
180
|
}
|
|
150
181
|
const raw = await getGbifService().getOccurrenceFacets({
|
|
151
182
|
facet: input.facet,
|
|
152
183
|
...(input.taxonKey !== undefined && { taxonKey: input.taxonKey }),
|
|
153
|
-
...(input.country
|
|
184
|
+
...(input.country && { country: input.country }),
|
|
154
185
|
...(input.publishingCountry && { publishingCountry: input.publishingCountry }),
|
|
155
|
-
...(input.stateProvince
|
|
156
|
-
...(input.year
|
|
186
|
+
...(input.stateProvince !== undefined && { stateProvince: input.stateProvince }),
|
|
187
|
+
...(input.year !== undefined && { year: input.year }),
|
|
157
188
|
...(input.basisOfRecord && { basisOfRecord: input.basisOfRecord }),
|
|
158
|
-
...(input.geometry
|
|
159
|
-
...(input.datasetKey
|
|
189
|
+
...(input.geometry !== undefined && { geometry: input.geometry }),
|
|
190
|
+
...(input.datasetKey !== undefined && { datasetKey: input.datasetKey }),
|
|
160
191
|
...(input.occurrenceStatus !== 'ANY' && { occurrenceStatus: input.occurrenceStatus }),
|
|
161
192
|
...(input.iucnRedListCategory && { iucnRedListCategory: input.iucnRedListCategory }),
|
|
162
193
|
facetLimit: input.facetLimit,
|