@cyanheads/gbif-biodiversity-mcp-server 0.5.2 → 0.5.4

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 (63) hide show
  1. package/CLAUDE.md +57 -34
  2. package/Dockerfile +4 -3
  3. package/LICENSE +1 -1
  4. package/README.md +7 -5
  5. package/dist/config/server-config.d.ts +1 -0
  6. package/dist/config/server-config.d.ts.map +1 -1
  7. package/dist/config/server-config.js +12 -0
  8. package/dist/config/server-config.js.map +1 -1
  9. package/dist/index.js +2 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +5 -0
  12. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
  13. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +16 -4
  14. package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js +1 -1
  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 +20 -2
  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 +19 -7
  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.js +1 -1
  26. package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +1 -1
  28. package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +1 -1
  30. package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
  31. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +1 -1
  32. package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +3 -3
  34. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +1 -1
  35. package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts +19 -13
  37. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js +15 -2
  39. package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +8 -2
  41. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js +15 -3
  43. package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map +1 -1
  44. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts +10 -10
  45. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map +1 -1
  46. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js +21 -11
  47. package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
  48. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +1 -1
  49. package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map +1 -1
  50. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts +10 -4
  51. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js +15 -2
  53. package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/utils.d.ts +30 -3
  55. package/dist/mcp-server/tools/utils.d.ts.map +1 -1
  56. package/dist/mcp-server/tools/utils.js +38 -0
  57. package/dist/mcp-server/tools/utils.js.map +1 -1
  58. package/dist/services/gbif/gbif-service.d.ts +14 -1
  59. package/dist/services/gbif/gbif-service.d.ts.map +1 -1
  60. package/dist/services/gbif/gbif-service.js +110 -7
  61. package/dist/services/gbif/gbif-service.js.map +1 -1
  62. package/package.json +8 -8
  63. package/server.json +43 -3
package/CLAUDE.md CHANGED
@@ -1,10 +1,10 @@
1
1
  # Developer Protocol
2
2
 
3
3
  **Server:** @cyanheads/gbif-biodiversity-mcp-server
4
- **Version:** 0.5.2
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.14`
4
+ **Version:** 0.5.4
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
- **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
7
+ **MCP SDK:** `@modelcontextprotocol/sdk` ^1.30.0
8
8
  **Zod:** ^4.4.3
9
9
 
10
10
  > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
35
35
  - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
36
36
  - **Use `ctx.log`** for request-scoped logging. No `console` calls.
37
37
  - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
38
- - **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
38
+ - **Check `ctx.elicit`** for presence before calling.
39
39
  - **Secrets in env vars only** — never hardcoded.
40
40
  - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
41
41
 
@@ -115,12 +115,6 @@ export const reviewCode = prompt('review_code', {
115
115
  });
116
116
  ```
117
117
 
118
- ### Server instructions
119
-
120
- `createApp({ instructions })` — optional server-level orientation, sent to clients on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
121
-
122
- ---
123
-
124
118
  ### Server config
125
119
 
126
120
  ```ts
@@ -131,6 +125,7 @@ import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
131
125
  const ServerConfigSchema = z.object({
132
126
  apiKey: z.string().describe('External API key'),
133
127
  maxResults: z.coerce.number().default(100),
128
+ verboseLogging: z.stringbool().default(false).describe('Enable verbose logging'),
134
129
  });
135
130
 
136
131
  let _config: z.infer<typeof ServerConfigSchema> | undefined;
@@ -138,6 +133,7 @@ export function getServerConfig() {
138
133
  _config ??= parseEnvConfig(ServerConfigSchema, {
139
134
  apiKey: 'MY_API_KEY',
140
135
  maxResults: 'MY_MAX_RESULTS',
136
+ verboseLogging: 'MY_VERBOSE_LOGGING',
141
137
  });
142
138
  return _config;
143
139
  }
@@ -145,6 +141,25 @@ export function getServerConfig() {
145
141
 
146
142
  `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.
147
143
 
144
+ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.
145
+
146
+ ### Server identity and instructions
147
+
148
+ `createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):
149
+
150
+ ```ts
151
+ await createApp({
152
+ name: 'my-mcp-server',
153
+ title: 'My Server', // human-readable display name
154
+ websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL
155
+ description: 'One-line description.', // wins over MCP_SERVER_DESCRIPTION
156
+ icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],
157
+ instructions: 'Use shortcut alpha for the most common case.', // session-level context
158
+ });
159
+ ```
160
+
161
+ `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.
162
+
148
163
  ---
149
164
 
150
165
  ## Context
@@ -154,13 +169,14 @@ Handlers receive a unified `ctx` object. Key properties:
154
169
  | Property | Description |
155
170
  |:---------|:------------|
156
171
  | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
157
- | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
158
- | `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
159
- | `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
172
+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
173
+ | `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
174
+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |
175
+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |
160
176
  | `ctx.signal` | `AbortSignal` for cancellation. |
161
177
  | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
162
178
  | `ctx.requestId` | Unique request ID. |
163
- | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
179
+ | `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
164
180
 
165
181
  ---
166
182
 
@@ -168,7 +184,7 @@ Handlers receive a unified `ctx` object. Key properties:
168
184
 
169
185
  Handlers throw — the framework catches, classifies, and formats.
170
186
 
171
- **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
187
+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the wire (`data.recovery.hint`, mirrored into `content[]` text); override with an explicit `{ recovery: { hint: '...' } }` when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
172
188
 
173
189
  ```ts
174
190
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
@@ -180,7 +196,7 @@ errors: [
180
196
  ],
181
197
  async handler(input, ctx) {
182
198
  const item = await db.find(input.id);
183
- if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
199
+ if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));
184
200
  return item;
185
201
  }
186
202
  ```
@@ -243,7 +259,7 @@ src/
243
259
 
244
260
  ## Skills
245
261
 
246
- Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
262
+ Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
247
263
 
248
264
  **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
249
265
 
@@ -263,11 +279,12 @@ Available skills:
263
279
  | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
264
280
  | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
265
281
  | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
266
- | `devcheck` | Lint, format, typecheck, audit |
267
282
  | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
268
283
  | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
269
284
  | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
270
285
  | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
286
+ | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
287
+ | `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
271
288
  | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
272
289
  | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
273
290
  | `api-auth` | Auth modes, scopes, JWT/OAuth |
@@ -276,41 +293,47 @@ Available skills:
276
293
  | `api-context` | Context interface, logger, state, progress |
277
294
  | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
278
295
  | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
296
+ | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
279
297
  | `api-services` | LLM, Speech, Graph services |
280
298
  | `api-testing` | createMockContext, test patterns |
281
299
  | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
282
300
  | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
283
301
  | `api-workers` | Cloudflare Workers runtime |
284
302
 
303
+ **Chaining skills into pipelines.** When the user wants a multi-phase effort — build this server out, QA-and-fix the surface, update-and-ship — *and you can spawn sub-agents*, `skills/orchestrations/SKILL.md` sequences the task skills above into a gated pipeline with verification at each step. Read it to drive the run. Optional: skip it if you can't orchestrate sub-agents, and ignore it entirely if you were *spawned* as one — you've already been scoped to a single phase.
304
+
285
305
  When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
286
306
 
287
307
  ---
288
308
 
289
309
  ## Commands
290
310
 
291
- **Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. `bun` is slightly faster for script invocation but not required.
311
+ **Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
292
312
 
293
313
  | Command | Purpose |
294
314
  |:--------|:--------|
295
- | `npm run build` | Compile TypeScript |
296
- | `npm run rebuild` | Clean + build |
297
- | `npm run clean` | Remove build artifacts |
298
- | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
315
+ | `bun run build` | Compile TypeScript |
316
+ | `bun run rebuild` | Clean + build |
317
+ | `bun run clean` | Remove build artifacts |
318
+ | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
299
319
  | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
300
- | `npm run tree` | Generate directory structure doc |
301
- | `npm run format` | Auto-fix formatting |
302
- | `npm test` | Run tests |
303
- | `npm run start:stdio` | Production mode (stdio) |
304
- | `npm run start:http` | Production mode (HTTP) |
305
- | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
306
- | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
307
- | `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
320
+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
321
+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
322
+ | `bun run list-skills` | Print the skill registry |
323
+ | `bun run tree` | Generate directory structure doc |
324
+ | `bun run format` | Auto-fix formatting, including Biome's unsafe autofixes — review the diff; they can change behavior |
325
+ | `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
326
+ | `bun run start:stdio` | Production mode (stdio) |
327
+ | `bun run start:http` | Production mode (HTTP) |
328
+ | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
329
+ | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
330
+ | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
308
331
 
309
332
  ---
310
333
 
311
334
  ## Bundling
312
335
 
313
- `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
336
+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
314
337
 
315
338
  **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
316
339
 
@@ -328,14 +351,14 @@ Each per-version file opens with YAML frontmatter:
328
351
  ---
329
352
  summary: "One-line headline, ≤350 chars" # required — powers the rollup index
330
353
  breaking: false # optional — true flags breaking changes
331
- security: false # optional — true flags security fixes
354
+ security: false # optional — true ONLY for a source-code security fix, never a dependency CVE bump
332
355
  ---
333
356
 
334
357
  # 0.1.0 — YYYY-MM-DD
335
358
  ...
336
359
  ```
337
360
 
338
- `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
361
+ `breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
339
362
 
340
363
  `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
341
364
 
package/Dockerfile CHANGED
@@ -50,9 +50,10 @@ LABEL org.opencontainers.image.source="https://github.com/cyanheads/gbif-biodive
50
50
  COPY package.json bun.lock ./
51
51
 
52
52
  # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
53
- # that are not needed in the final production image.
53
+ # that are not needed in the final production image. `--omit=peer` drops the
54
+ # framework's optional peer tiers, which `--production` alone leaves in place.
54
55
  RUN --mount=type=cache,target=/root/.bun/install/cache \
55
- bun install --production --frozen-lockfile --ignore-scripts
56
+ bun install --production --omit=peer --frozen-lockfile --ignore-scripts
56
57
 
57
58
  # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
58
59
  # These are not bundled by default to keep the base image lean. Enable at build time
@@ -60,7 +61,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
60
61
  ARG OTEL_ENABLED=true
61
62
  RUN --mount=type=cache,target=/root/.bun/install/cache \
62
63
  if [ "$OTEL_ENABLED" = "true" ]; then \
63
- bun add @hono/otel \
64
+ bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
64
65
  @opentelemetry/instrumentation-http \
65
66
  @opentelemetry/exporter-metrics-otlp-http \
66
67
  @opentelemetry/exporter-trace-otlp-http \
package/LICENSE CHANGED
@@ -186,7 +186,7 @@ Apache License
186
186
  same "printed page" as the copyright notice for easier
187
187
  identification within third-party archives.
188
188
 
189
- Copyright 2025 Casey Hand @cyanheads
189
+ Copyright 2026 Casey Hand @cyanheads
190
190
 
191
191
  Licensed under the Apache License, Version 2.0 (the "License");
192
192
  you may not use this file except in compliance with the License.
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.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/gbif-biodiversity-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.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-^6.0.3-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.4-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
 
@@ -121,7 +121,7 @@ Search 2.4B+ GBIF occurrence records with full Darwin Core filtering.
121
121
  - Temporal filters: `year` as single year or range, `month` (1–12) for seasonal queries
122
122
  - `basisOfRecord` enum: `HUMAN_OBSERVATION`, `PRESERVED_SPECIMEN`, `MACHINE_OBSERVATION`, and more
123
123
  - `hasCoordinate` to require or exclude georeferenced records
124
- - Pagination capped at offset+limit ≈ 100,000 — use `gbif_occurrence_facets` for aggregate analysis beyond this
124
+ - Pagination capped at offset+limit = 100,001, the deepest page GBIF serves — use `gbif_occurrence_facets` for aggregate analysis beyond this
125
125
 
126
126
  ---
127
127
 
@@ -178,6 +178,7 @@ Fetch full dataset metadata by UUID.
178
178
  - Full description, citation text (for academic reference), license, DOI
179
179
  - Contacts with role, name, organization, and email
180
180
  - Temporal and geographic coverage ranges when the publisher declares them
181
+ - `recordCount` for `OCCURRENCE` datasets — the indexed occurrence total, matching what `gbif_search_datasets` reports; absent for other dataset types
181
182
  - `numConstituents` for aggregate datasets (e.g. iNaturalist, eBird)
182
183
  - Use after `gbif_search_datasets` or when an occurrence record's `datasetKey` needs provenance detail
183
184
 
@@ -213,7 +214,7 @@ GBIF-specific:
213
214
 
214
215
  - Full GBIF REST API v1 coverage: species taxonomy, occurrences, datasets, and publishers
215
216
  - `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
217
+ - 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
218
  - WKT polygon geometry support for geographic occurrence queries
218
219
  - Darwin Core field mapping with explicit provenance on sparse upstream fields
219
220
 
@@ -286,8 +287,8 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
286
287
 
287
288
  ### Prerequisites
288
289
 
289
- - [Bun v1.3.2](https://bun.sh/) or higher.
290
- - Optional: [GBIF API key](https://www.gbif.org/developer/summary) for higher rate limits.
290
+ - [Bun v1.3.0](https://bun.sh/) or higher.
291
+ - No credentials — the GBIF endpoints this server calls are public.
291
292
 
292
293
  ### Installation
293
294
 
@@ -326,6 +327,7 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
326
327
  | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |
327
328
  | `GBIF_BASE_URL` | GBIF API base URL override | `https://api.gbif.org/v1` |
328
329
  | `GBIF_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds | `10000` |
330
+ | `GBIF_USER_AGENT` | `User-Agent` sent on every GBIF request. GBIF asks integrators to identify themselves with a contact URL or email. | server name, version, and repository URL |
329
331
  | `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
330
332
 
331
333
  ## Running the server
@@ -6,6 +6,7 @@ import { z } from '@cyanheads/mcp-ts-core';
6
6
  declare const ServerConfigSchema: z.ZodObject<{
7
7
  baseUrl: z.ZodDefault<z.ZodString>;
8
8
  requestTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
9
+ userAgent: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
9
10
  }, z.core.$strip>;
10
11
  type ServerConfig = z.infer<typeof ServerConfigSchema>;
11
12
  export declare function getServerConfig(): ServerConfig;
@@ -1 +1 @@
1
- {"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;iBAMtB,CAAC;AAEH,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAIvD,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}
1
+ {"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;iBAiBtB,CAAC;AAEH,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAIvD,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}
@@ -10,12 +10,24 @@ const ServerConfigSchema = z.object({
10
10
  .number()
11
11
  .default(10_000)
12
12
  .describe('HTTP request timeout in milliseconds.'),
13
+ /**
14
+ * Blank is normalized to undefined so an install UI that submits an empty
15
+ * optional field falls back to the built-in identifier instead of sending
16
+ * `User-Agent: ""`.
17
+ */
18
+ userAgent: z
19
+ .string()
20
+ .trim()
21
+ .optional()
22
+ .transform((value) => value || undefined)
23
+ .describe('User-Agent header sent on every GBIF API request.'),
13
24
  });
14
25
  let _config;
15
26
  export function getServerConfig() {
16
27
  _config ??= parseEnvConfig(ServerConfigSchema, {
17
28
  baseUrl: 'GBIF_BASE_URL',
18
29
  requestTimeoutMs: 'GBIF_REQUEST_TIMEOUT_MS',
30
+ userAgent: 'GBIF_USER_AGENT',
19
31
  });
20
32
  return _config;
21
33
  }
@@ -1 +1 @@
1
- {"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACrF,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,uCAAuC,CAAC;CACrD,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,eAAe;QACxB,gBAAgB,EAAE,yBAAyB;KAC5C,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
1
+ {"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACrF,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,uCAAuC,CAAC;IACpD;;;;OAIG;IACH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,IAAI,EAAE;SACN,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,SAAS,CAAC;SACxC,QAAQ,CAAC,mDAAmD,CAAC;CACjE,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,eAAe;QACxB,gBAAgB,EAAE,yBAAyB;QAC3C,SAAS,EAAE,iBAAiB;KAC7B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
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; an optional API key only raises rate limits. 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 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,001 — switch to gbif_occurrence_facets for larger aggregate analysis.',
32
32
  tools: [
33
33
  gbifMatchSpecies,
34
34
  gbifBulkMatchSpecies,
@@ -53,6 +53,7 @@ await createApp({
53
53
  initGbifService(core.config, core.storage, {
54
54
  baseUrl: cfg.baseUrl,
55
55
  timeoutMs: cfg.requestTimeoutMs,
56
+ userAgent: cfg.userAgent,
56
57
  });
57
58
  },
58
59
  });
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,siBAAsiB;IACxiB,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;SAChC,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,6hBAA6hB;IAC/hB,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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"}
@@ -14,7 +14,7 @@ export const gbifBulkMatchSpecies = tool('gbif_bulk_match_species', {
14
14
  'matchType ERROR with the reason, leaving the rest of the batch intact. Resolves synonyms to ' +
15
15
  'the accepted backbone key. Common names are not supported — use gbif_search_species for ' +
16
16
  'vernacular searches. Below confidence 80, review the match.',
17
- annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
17
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
18
18
  input: z.object({
19
19
  names: z
20
20
  .array(z.string().min(1).describe('A scientific name to match, e.g. "Panthera leo".'))
@@ -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":"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,yBAAyB,EAAE;IAClE,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,wFAAwF;QACxF,8FAA8F;QAC9F,+FAA+F;QAC/F,wFAAwF;QACxF,8FAA8F;QAC9F,8FAA8F;QAC9F,0FAA0F;QAC1F,6DAA6D;IAC/D,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC/E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC,CAAC;aACrF,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,CACP,0FAA0F,CAC3F;QACH,MAAM,EAAE,CAAC;aACN,OAAO,EAAE;aACT,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CACP,yJAAyJ,CAC1J;KACJ,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC;aACP,KAAK,CACJ,CAAC;aACE,MAAM,CAAC;YACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;YACtE,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,+JAA+J,CAChK;YACH,cAAc,EAAE,CAAC;iBACd,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,sEAAsE,CAAC;YACnF,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,oEAAoE,CAAC;YACjF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YAC5E,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,mDAAmD,CAAC;YAChE,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,oEAAoE,CAAC;YACjF,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,CACP,+IAA+I,CAChJ;YACH,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,2DAA2D,CAAC;SACzE,CAAC;aACD,QAAQ,CAAC,mCAAmC,CAAC,CACjD;aACA,QAAQ,CAAC,4CAA4C,CAAC;KAC1D,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,6BAA6B,EAAE;YAC1C,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;YACzB,MAAM,EAAE,KAAK,CAAC,MAAM;SACrB,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;QAE9B,qFAAqF;QACrF,mFAAmF;QACnF,wFAAwF;QACxF,mEAAmE;QACnE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;YAC7B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;gBACzE,IAAI,GAAG,CAAC,QAAQ,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;oBAC9E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;gBACrC,CAAC;gBACD,OAAO;oBACL,IAAI;oBACJ,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,SAAS;oBAC/C,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,SAAS;oBAC7C,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;oBAC3B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,SAAS;oBAC/B,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,SAAS;oBACvC,SAAS,EAAE,GAAG,CAAC,SAAS;iBACzB,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO;oBACL,IAAI;oBACJ,SAAS,EAAE,OAAO;oBAClB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACxD,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CACH,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3B,IAAI,CAAC,CAAC,aAAa;gBAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC;YAC1E,IAAI,CAAC,CAAC,cAAc;gBAAE,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACnE,IAAI,CAAC,CAAC,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9C,IAAI,CAAC,CAAC,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YAC7C,IAAI,CAAC,CAAC,UAAU,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,UAAU,MAAM,CAAC,CAAC;YAC5E,IAAI,CAAC,CAAC,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACnD,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"}
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,13 +3,15 @@
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. ' +
10
12
  'Use for quick totals ("how many Aves records in Sweden?") or before deciding whether ' +
11
13
  'to paginate a full search. Accepts taxonKey, country, isGeoreferenced, datasetKey, and year.',
12
- annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
14
+ annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
13
15
  input: z.object({
14
16
  taxonKey: z
15
17
  .number()
@@ -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 }),