@cyanheads/gbif-biodiversity-mcp-server 0.2.0

package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Fetch a single GBIF occurrence record by key.
+ * @module mcp-server/tools/definitions/gbif-get-occurrence
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+export const gbifGetOccurrence = tool('gbif_get_occurrence', {
+    title: 'Get Occurrence Record',
+    description: 'Fetch a single occurrence record by its GBIF occurrence key. Returns the complete Darwin Core ' +
+        'record — all coordinates, administrative geography (GADM), dates, collections metadata, ' +
+        'collector identifiers, media links, and quality issue flags. Use the occurrence key from ' +
+        'gbif_search_occurrences results to fetch full detail.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        occurrenceKey: z.number().describe('GBIF occurrence key from gbif_search_occurrences results.'),
+    }),
+    output: z.object({
+        key: z.number().optional().describe('GBIF occurrence key.'),
+        datasetKey: z.string().optional().describe('UUID of the source dataset.'),
+        taxonKey: z.number().optional().describe('Backbone taxon key.'),
+        scientificName: z.string().optional().describe('Scientific name from occurrence record.'),
+        canonicalName: z.string().optional().describe('Canonical name without authorship.'),
+        kingdom: z.string().optional().describe('Kingdom classification.'),
+        phylum: z.string().optional().describe('Phylum classification.'),
+        order: z.string().optional().describe('Order classification.'),
+        family: z.string().optional().describe('Family classification.'),
+        genus: z.string().optional().describe('Genus classification.'),
+        species: z.string().optional().describe('Species canonical name.'),
+        taxonRank: z.string().optional().describe('Taxonomic rank of the identified taxon.'),
+        decimalLatitude: z
+            .number()
+            .optional()
+            .describe('Latitude in decimal degrees (WGS84). May be absent.'),
+        decimalLongitude: z
+            .number()
+            .optional()
+            .describe('Longitude in decimal degrees (WGS84). May be absent.'),
+        coordinateUncertaintyInMeters: z
+            .number()
+            .optional()
+            .describe('Coordinate uncertainty radius in meters. May be absent.'),
+        continent: z.string().optional().describe('Continent name. May be absent.'),
+        country: z.string().optional().describe('Country name. May be absent.'),
+        countryCode: z.string().optional().describe('ISO 3166-1 alpha-2 country code. May be absent.'),
+        stateProvince: z.string().optional().describe('State or province. May be absent.'),
+        locality: z.string().optional().describe('Locality description. May be absent.'),
+        publishingCountry: z
+            .string()
+            .optional()
+            .describe('Country code of the publishing organization.'),
+        eventDate: z
+            .string()
+            .optional()
+            .describe('Observation date as ISO 8601 string. May be absent.'),
+        year: z.number().optional().describe('Observation year. May be absent.'),
+        month: z.number().optional().describe('Observation month (1–12). May be absent.'),
+        day: z.number().optional().describe('Observation day. May be absent.'),
+        basisOfRecord: z.string().optional().describe('How the occurrence was recorded.'),
+        institutionCode: z
+            .string()
+            .optional()
+            .describe('Code of the contributing institution. May be absent.'),
+        collectionCode: z
+            .string()
+            .optional()
+            .describe('Collection code within the institution. May be absent.'),
+        catalogNumber: z
+            .string()
+            .optional()
+            .describe('Catalog number within the collection. May be absent.'),
+        recordedBy: z.string().optional().describe('Collector name(s). May be absent.'),
+        identifiedBy: z.string().optional().describe('Identifier name(s). May be absent.'),
+        individualCount: z.number().optional().describe('Number of individuals. May be absent.'),
+        sex: z.string().optional().describe('Sex of the individual(s). May be absent.'),
+        lifeStage: z.string().optional().describe('Life stage of the individual(s). May be absent.'),
+        issues: z.array(z.string()).optional().describe('GBIF data quality issue flags.'),
+        media: z
+            .array(z
+            .object({
+            type: z.string().optional().describe('Media type (StillImage, Sound, etc.).'),
+            format: z.string().optional().describe('MIME format of the media.'),
+            identifier: z.string().optional().describe('URL to the media file.'),
+            title: z.string().optional().describe('Media title.'),
+            license: z.string().optional().describe('License for the media.'),
+        })
+            .describe('A media item (image, audio, video) associated with the occurrence.'))
+            .optional()
+            .describe('Associated media (images, audio, video). May be absent.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The occurrenceKey does not exist in GBIF.',
+            recovery: 'Use gbif_search_occurrences to find valid occurrence keys.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Fetching occurrence record', { occurrenceKey: input.occurrenceKey });
+        let raw;
+        try {
+            raw = await getGbifService().getOccurrence(input.occurrenceKey, ctx);
+        }
+        catch (err) {
+            if (err instanceof McpError && err.code === -32001) {
+                throw ctx.fail('not_found', `Occurrence key ${input.occurrenceKey} not found in GBIF.`, {
+                    ...ctx.recoveryFor('not_found'),
+                });
+            }
+            throw err;
+        }
+        if (!raw.key) {
+            throw ctx.fail('not_found', `Occurrence key ${input.occurrenceKey} not found in GBIF.`, {
+                ...ctx.recoveryFor('not_found'),
+            });
+        }
+        return {
+            key: raw.key,
+            datasetKey: raw.datasetKey,
+            taxonKey: raw.taxonKey,
+            scientificName: raw.scientificName,
+            canonicalName: raw.canonicalName,
+            kingdom: raw.kingdom,
+            phylum: raw.phylum,
+            order: raw.order,
+            family: raw.family,
+            genus: raw.genus,
+            species: raw.species,
+            taxonRank: raw.taxonRank,
+            decimalLatitude: raw.decimalLatitude,
+            decimalLongitude: raw.decimalLongitude,
+            coordinateUncertaintyInMeters: raw.coordinateUncertaintyInMeters,
+            continent: raw.continent,
+            country: raw.country,
+            countryCode: raw.countryCode,
+            stateProvince: raw.stateProvince,
+            locality: raw.locality,
+            publishingCountry: raw.publishingCountry,
+            eventDate: raw.eventDate,
+            year: raw.year,
+            month: raw.month,
+            day: raw.day,
+            basisOfRecord: raw.basisOfRecord,
+            institutionCode: raw.institutionCode,
+            collectionCode: raw.collectionCode,
+            catalogNumber: raw.catalogNumber,
+            recordedBy: raw.recordedBy,
+            identifiedBy: raw.identifiedBy,
+            individualCount: raw.individualCount,
+            sex: raw.sex,
+            lifeStage: raw.lifeStage,
+            issues: raw.issues?.length ? raw.issues : undefined,
+            media: raw.media?.length
+                ? raw.media.map((m) => ({
+                    type: m.type,
+                    format: m.format,
+                    identifier: m.identifier,
+                    title: m.title,
+                    license: m.license,
+                }))
+                : undefined,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        const canonical = result.canonicalName ?? result.scientificName ?? 'Unknown taxon';
+        const sci = result.scientificName && result.scientificName !== canonical
+            ? ` [${result.scientificName}]`
+            : '';
+        lines.push(`## ${canonical}${sci}`);
+        if (result.key != null)
+            lines.push(`**Occurrence key:** ${result.key}`);
+        if (result.taxonKey != null)
+            lines.push(`**Taxon key:** ${result.taxonKey}`);
+        if (result.taxonRank)
+            lines.push(`**Rank:** ${result.taxonRank}`);
+        if (result.basisOfRecord)
+            lines.push(`**Basis of record:** ${result.basisOfRecord}`);
+        // Taxonomy
+        const taxParts = [];
+        if (result.kingdom)
+            taxParts.push(`Kingdom: ${result.kingdom}`);
+        if (result.phylum)
+            taxParts.push(`Phylum: ${result.phylum}`);
+        if (result.order)
+            taxParts.push(`Order: ${result.order}`);
+        if (result.family)
+            taxParts.push(`Family: ${result.family}`);
+        if (result.genus)
+            taxParts.push(`Genus: ${result.genus}`);
+        if (result.species)
+            taxParts.push(`Species: ${result.species}`);
+        if (taxParts.length > 0)
+            lines.push(`**Taxonomy:** ${taxParts.join(' › ')}`);
+        lines.push('');
+        if (result.eventDate) {
+            lines.push(`**Date:** ${result.eventDate}`);
+        }
+        else if (result.year == null) {
+            lines.push('**Date:** Not available');
+        }
+        if (result.year != null)
+            lines.push(`**Year:** ${result.year}`);
+        if (result.month != null)
+            lines.push(`**Month:** ${result.month}`);
+        if (result.day != null)
+            lines.push(`**Day:** ${result.day}`);
+        if (result.decimalLatitude != null && result.decimalLongitude != null) {
+            lines.push(`**Coordinates:** ${result.decimalLatitude}, ${result.decimalLongitude}${result.coordinateUncertaintyInMeters != null ? ` (±${result.coordinateUncertaintyInMeters}m)` : ''}`);
+        }
+        else {
+            lines.push('**Coordinates:** Not available');
+        }
+        const geo = [];
+        if (result.locality)
+            geo.push(result.locality);
+        if (result.stateProvince)
+            geo.push(result.stateProvince);
+        if (result.country)
+            geo.push(result.country);
+        if (result.continent)
+            geo.push(result.continent);
+        if (geo.length > 0)
+            lines.push(`**Location:** ${geo.join(', ')}${result.countryCode ? ` (${result.countryCode})` : ''}`);
+        else if (result.countryCode)
+            lines.push(`**Country code:** ${result.countryCode}`);
+        if (result.recordedBy)
+            lines.push(`**Recorded by:** ${result.recordedBy}`);
+        if (result.identifiedBy)
+            lines.push(`**Identified by:** ${result.identifiedBy}`);
+        if (result.individualCount != null)
+            lines.push(`**Individual count:** ${result.individualCount}`);
+        if (result.sex)
+            lines.push(`**Sex:** ${result.sex}`);
+        if (result.lifeStage)
+            lines.push(`**Life stage:** ${result.lifeStage}`);
+        lines.push('');
+        if (result.institutionCode)
+            lines.push(`**Institution:** ${result.institutionCode}`);
+        if (result.collectionCode)
+            lines.push(`**Collection:** ${result.collectionCode}`);
+        if (result.catalogNumber)
+            lines.push(`**Catalog number:** ${result.catalogNumber}`);
+        if (result.datasetKey)
+            lines.push(`**Dataset key:** ${result.datasetKey}`);
+        if (result.publishingCountry)
+            lines.push(`**Publishing country:** ${result.publishingCountry}`);
+        if (result.media?.length) {
+            lines.push(`\n**Media:** ${result.media.length} item(s)`);
+            for (const m of result.media) {
+                const mediaType = m.type ?? 'Media';
+                const mediaTitle = m.title ? ` — ${m.title}` : '';
+                const mediaFmt = m.format ? ` (${m.format})` : '';
+                const mediaLicense = m.license ? ` [${m.license}]` : '';
+                lines.push(`  - ${mediaType}${mediaTitle}${mediaFmt}${mediaLicense}${m.identifier ? `: ${m.identifier}` : ''}`);
+            }
+        }
+        if (result.issues?.length)
+            lines.push(`\n**Quality issues:** ${result.issues.join(', ')}`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-get-occurrence.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-get-occurrence.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-occurrence.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-occurrence.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview List direct children of a backbone taxon.
+ * @module mcp-server/tools/definitions/gbif-get-species-children
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const gbifGetSpeciesChildren: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    taxonKey: z.ZodNumber;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    children: z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodNumber>;
+        scientificName: z.ZodOptional<z.ZodString>;
+        canonicalName: z.ZodOptional<z.ZodString>;
+        rank: z.ZodOptional<z.ZodString>;
+        taxonomicStatus: z.ZodOptional<z.ZodString>;
+        vernacularName: z.ZodOptional<z.ZodString>;
+        numOccurrences: z.ZodOptional<z.ZodNumber>;
+        numDescendants: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    endOfRecords: z.ZodBoolean;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=gbif-get-species-children.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-species-children.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-species-children.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGjD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;6BA2FjC,CAAC"}

package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview List direct children of a backbone taxon.
+ * @module mcp-server/tools/definitions/gbif-get-species-children
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+export const gbifGetSpeciesChildren = tool('gbif_get_species_children', {
+    title: 'Get Species Children',
+    description: 'List direct children of a backbone taxon — genera within a family, species within a genus, ' +
+        'subspecies within a species. Paginated. Use gbif_match_species to get the taxonKey first, ' +
+        'then iterate with offset for large groups.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        taxonKey: z
+            .number()
+            .describe('GBIF backbone taxon key from gbif_match_species or another taxonomy tool.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(1000)
+            .default(20)
+            .describe('Number of children to return (default 20, max 1000).'),
+        offset: z.number().min(0).default(0).describe('Pagination offset.'),
+    }),
+    output: z.object({
+        children: z
+            .array(z
+            .object({
+            key: z.number().optional().describe('GBIF backbone taxon key.'),
+            scientificName: z.string().optional().describe('Full scientific name with authorship.'),
+            canonicalName: z.string().optional().describe('Scientific name without authorship.'),
+            rank: z.string().optional().describe('Taxonomic rank.'),
+            taxonomicStatus: z.string().optional().describe('ACCEPTED, SYNONYM, DOUBTFUL, etc.'),
+            vernacularName: z.string().optional().describe('Common name when available.'),
+            numOccurrences: z.number().optional().describe('Occurrence record count.'),
+            numDescendants: z.number().optional().describe('Count of child taxa under this node.'),
+        })
+            .describe('A direct child taxon with key, name, rank, and status.'))
+            .describe('Direct child taxa.'),
+        offset: z.number().describe('Current pagination offset.'),
+        limit: z.number().describe('Records returned in this page.'),
+        endOfRecords: z.boolean().describe('True when there are no more results after this page.'),
+    }),
+    async handler(input, ctx) {
+        ctx.log.info('Fetching species children', { taxonKey: input.taxonKey });
+        const raw = await getGbifService().getSpeciesChildren(input.taxonKey, { limit: input.limit, offset: input.offset }, ctx);
+        const children = (raw.results ?? []).map((r) => ({
+            key: r.key,
+            scientificName: r.scientificName,
+            canonicalName: r.canonicalName,
+            rank: r.rank,
+            taxonomicStatus: r.taxonomicStatus,
+            vernacularName: r.vernacularName,
+            numOccurrences: r.numOccurrences,
+            numDescendants: r.numDescendants,
+        }));
+        return {
+            children,
+            offset: raw.offset ?? input.offset,
+            limit: raw.limit ?? input.limit,
+            endOfRecords: raw.endOfRecords ?? true,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Showing:** ${result.children.length} | **Limit:** ${result.limit} | **End of records:** ${result.endOfRecords} (offset ${result.offset})`,
+        ];
+        for (const child of result.children) {
+            const name = child.canonicalName ?? 'Unknown';
+            const sci = child.scientificName && child.scientificName !== name ? ` [${child.scientificName}]` : '';
+            lines.push(`\n- **${name}**${sci}`);
+            if (child.key != null)
+                lines.push(`  Key: ${child.key}`);
+            if (child.rank)
+                lines.push(`  Rank: ${child.rank}`);
+            if (child.taxonomicStatus)
+                lines.push(`  Status: ${child.taxonomicStatus}`);
+            if (child.vernacularName)
+                lines.push(`  Common name: ${child.vernacularName}`);
+            if (child.numOccurrences != null)
+                lines.push(`  Occurrences: ${child.numOccurrences}`);
+            if (child.numDescendants != null)
+                lines.push(`  Descendants: ${child.numDescendants}`);
+        }
+        if (!result.endOfRecords) {
+            lines.push(`\n*More results available — use offset ${result.offset + result.limit} to continue.*`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-get-species-children.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-get-species-children.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-species-children.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-species-children.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Return the full parent chain for a GBIF taxon.
+ * @module mcp-server/tools/definitions/gbif-get-species-classification
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gbifGetSpeciesClassification: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    taxonKey: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    classification: z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodNumber>;
+        rank: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        scientificName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The taxonKey does not exist in the GBIF backbone.";
+    readonly recovery: "Use gbif_match_species to resolve a name to a valid backbone taxon key.";
+}]>;
+//# sourceMappingURL=gbif-get-species-classification.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-species-classification.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-species-classification.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAG3E,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;GAyFvC,CAAC"}

package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Return the full parent chain for a GBIF taxon.
+ * @module mcp-server/tools/definitions/gbif-get-species-classification
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+export const gbifGetSpeciesClassification = tool('gbif_get_species_classification', {
+    title: 'Get Species Classification',
+    description: 'Return the complete parent chain for a taxon — from kingdom (or domain) down to the taxon ' +
+        'itself — as an ordered array. Each entry has its rank, canonical name, and taxon key. ' +
+        'The array is returned root-first (kingdom → phylum → class → … → parent of given taxon). ' +
+        'Useful for building taxonomic trees or understanding placement without navigating the backbone level-by-level.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        taxonKey: z
+            .number()
+            .describe('GBIF backbone taxon key from gbif_match_species or another taxonomy tool.'),
+    }),
+    output: z.object({
+        classification: z
+            .array(z
+            .object({
+            key: z.number().optional().describe('Backbone taxon key for this rank.'),
+            rank: z.string().optional().describe('Taxonomic rank (KINGDOM, PHYLUM, CLASS, etc.).'),
+            name: z.string().optional().describe('Canonical name at this rank.'),
+            scientificName: z.string().optional().describe('Full scientific name with authorship.'),
+        })
+            .describe('A single rank entry in the classification chain.'))
+            .describe('Classification chain ordered from root (kingdom) to the immediate parent of the queried taxon.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The taxonKey does not exist in the GBIF backbone.',
+            recovery: 'Use gbif_match_species to resolve a name to a valid backbone taxon key.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Fetching species classification', { taxonKey: input.taxonKey });
+        const raw = await getGbifService().getSpeciesParents(input.taxonKey, ctx);
+        if (!Array.isArray(raw)) {
+            throw ctx.fail('not_found', `Taxon key ${input.taxonKey} not found in the GBIF backbone.`, {
+                ...ctx.recoveryFor('not_found'),
+            });
+        }
+        // GBIF /species/{key}/parents returns [] for both nonexistent keys and kingdom-level taxa.
+        // When empty, verify the taxon exists to distinguish the two cases.
+        if (raw.length === 0) {
+            try {
+                await getGbifService().getSpecies(input.taxonKey, ctx);
+            }
+            catch (err) {
+                if (err instanceof McpError && err.code === -32001) {
+                    throw ctx.fail('not_found', `Taxon key ${input.taxonKey} not found in the GBIF backbone.`, { ...ctx.recoveryFor('not_found') });
+                }
+                throw err;
+            }
+        }
+        const classification = raw.map((node) => ({
+            key: node.key,
+            rank: node.rank,
+            name: node.canonicalName,
+            scientificName: node.scientificName,
+        }));
+        return { classification };
+    },
+    format: (result) => {
+        const lines = [`**Classification chain** (${result.classification.length} ranks):\n`];
+        for (const [i, node] of result.classification.entries()) {
+            const indent = '  '.repeat(i);
+            const name = node.name ?? 'Unknown';
+            const rank = node.rank ?? '';
+            const key = node.key != null ? ` (key: ${node.key})` : '';
+            const sci = node.scientificName && node.scientificName !== name ? ` [${node.scientificName}]` : '';
+            lines.push(`${indent}${rank}: **${name}**${sci}${key}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-get-species-classification.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-get-species-classification.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-species-classification.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-species-classification.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Fetch a taxon record by GBIF backbone key.
+ * @module mcp-server/tools/definitions/gbif-get-species
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gbifGetSpecies: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    taxonKey: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodOptional<z.ZodNumber>;
+    scientificName: z.ZodOptional<z.ZodString>;
+    canonicalName: z.ZodOptional<z.ZodString>;
+    authorship: z.ZodOptional<z.ZodString>;
+    vernacularName: z.ZodOptional<z.ZodString>;
+    rank: z.ZodOptional<z.ZodString>;
+    taxonomicStatus: z.ZodOptional<z.ZodString>;
+    numDescendants: z.ZodOptional<z.ZodNumber>;
+    numOccurrences: z.ZodOptional<z.ZodNumber>;
+    publishedIn: z.ZodOptional<z.ZodString>;
+    extinct: z.ZodOptional<z.ZodBoolean>;
+    kingdom: z.ZodOptional<z.ZodString>;
+    phylum: z.ZodOptional<z.ZodString>;
+    class: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodString>;
+    family: z.ZodOptional<z.ZodString>;
+    genus: z.ZodOptional<z.ZodString>;
+    species: z.ZodOptional<z.ZodString>;
+    kingdomKey: z.ZodOptional<z.ZodNumber>;
+    phylumKey: z.ZodOptional<z.ZodNumber>;
+    classKey: z.ZodOptional<z.ZodNumber>;
+    orderKey: z.ZodOptional<z.ZodNumber>;
+    familyKey: z.ZodOptional<z.ZodNumber>;
+    genusKey: z.ZodOptional<z.ZodNumber>;
+    speciesKey: z.ZodOptional<z.ZodNumber>;
+    acceptedKey: z.ZodOptional<z.ZodNumber>;
+    accepted: z.ZodOptional<z.ZodString>;
+    parentKey: z.ZodOptional<z.ZodNumber>;
+    parent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The taxonKey does not exist in the GBIF backbone.";
+    readonly recovery: "Use gbif_match_species to resolve a name to a valid backbone key, or gbif_search_species to browse.";
+}]>;
+//# sourceMappingURL=gbif-get-species.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gbif-get-species.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gbif-get-species.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gbif-get-species.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAI3E,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4LzB,CAAC"}