@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.
- package/CLAUDE.md +57 -34
- package/Dockerfile +4 -3
- package/LICENSE +1 -1
- package/README.md +7 -5
- package/dist/config/server-config.d.ts +1 -0
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +12 -0
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts +5 -0
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js +16 -4
- package/dist/mcp-server/resources/definitions/gbif-dataset.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/gbif-bulk-match-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.d.ts +7 -1
- 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 +20 -2
- package/dist/mcp-server/tools/definitions/gbif-count-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts +5 -0
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js +19 -7
- package/dist/mcp-server/tools/definitions/gbif-get-dataset.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js +1 -1
- package/dist/mcp-server/tools/definitions/gbif-get-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.d.ts +3 -3
- package/dist/mcp-server/tools/definitions/gbif-match-species.tool.js +1 -1
- 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 +19 -13
- 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 +15 -2
- package/dist/mcp-server/tools/definitions/gbif-occurrence-facets.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.d.ts +8 -2
- 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 +15 -3
- 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 +10 -10
- 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 +21 -11
- package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js +1 -1
- 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 +10 -4
- 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 +15 -2
- package/dist/mcp-server/tools/definitions/gbif-search-species.tool.js.map +1 -1
- package/dist/mcp-server/tools/utils.d.ts +30 -3
- package/dist/mcp-server/tools/utils.d.ts.map +1 -1
- package/dist/mcp-server/tools/utils.js +38 -0
- package/dist/mcp-server/tools/utils.js.map +1 -1
- package/dist/services/gbif/gbif-service.d.ts +14 -1
- package/dist/services/gbif/gbif-service.d.ts.map +1 -1
- package/dist/services/gbif/gbif-service.js +110 -7
- package/dist/services/gbif/gbif-service.js.map +1 -1
- package/package.json +8 -8
- 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.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
298
|
-
| `
|
|
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
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
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
|
-
`
|
|
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
|
|
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
|
|
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
|
-
[](./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
|
|
|
@@ -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
|
|
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
|
|
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.
|
|
290
|
-
-
|
|
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
|
|
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;
|
|
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
|
|
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,
|
|
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;
|
|
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
|
|
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:
|
|
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":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,eAAe,EACf,SAAS,GACV,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGjE;;;GAGG;AACH,MAAM,WAAW,GAAG,EAAE,CAAC;AAEvB,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC,6BAA6B,EAAE;IACzE,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,cAAc;IACrB,WAAW,EACT,gFAAgF;QAChF,uFAAuF;QACvF,0CAA0C;IAC5C,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,
|
|
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:
|
|
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,
|
|
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>,
|
|
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;
|
|
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:
|
|
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
|
|
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 }),
|