@cyanheads/gbif-biodiversity-mcp-server 0.2.0

package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Search GBIF datasets by keyword, type, or country.
+ * @module mcp-server/tools/definitions/gbif-search-datasets
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+import { stripHtml } from '../utils.js';
+export const gbifSearchDatasets = tool('gbif_search_datasets', {
+    title: 'Search Datasets',
+    description: 'Search GBIF datasets by keyword, type, country, or publishing organization. ' +
+        'Returns dataset title, description, license, record count, and DOI. ' +
+        'Use to find the source dataset behind a set of records, or to explore what data collections ' +
+        'are available for a taxon, country, or organization.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        q: z.string().optional().describe('Free-text search across dataset title and description.'),
+        type: z
+            .enum(['OCCURRENCE', 'CHECKLIST', 'METADATA', 'SAMPLING_EVENT'])
+            .optional()
+            .describe('Filter by dataset type. OCCURRENCE for observation records, CHECKLIST for species lists.'),
+        publishingCountry: z
+            .string()
+            .optional()
+            .describe('ISO 3166-1 alpha-2 country code of the publishing organization.'),
+        hostingOrg: z
+            .string()
+            .optional()
+            .describe('UUID of the hosting organization. From gbif_search_publishers results.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(1000)
+            .default(20)
+            .describe('Number of datasets to return (default 20, max 1000).'),
+        offset: z.number().min(0).default(0).describe('Pagination offset.'),
+    }),
+    output: z.object({
+        datasets: z
+            .array(z
+            .object({
+            key: z.string().optional().describe('Dataset UUID for gbif_get_dataset chaining.'),
+            title: z.string().optional().describe('Dataset title.'),
+            type: z.string().optional().describe('Dataset type (OCCURRENCE, CHECKLIST, etc.).'),
+            description: z.string().optional().describe('Brief description. May be absent.'),
+            license: z.string().optional().describe('License identifier. May be absent.'),
+            doi: z.string().optional().describe('DOI for citation. May be absent.'),
+            publishingCountry: z.string().optional().describe('Country code of the publisher.'),
+            recordCount: z.number().optional().describe('Number of records in the dataset.'),
+        })
+            .describe('A GBIF dataset with key, title, type, license, and record count.'))
+            .describe('Matching datasets.'),
+        totalCount: z.number().describe('Total matching datasets before pagination.'),
+        offset: z.number().describe('Current pagination offset.'),
+        limit: z.number().describe('Datasets 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('Searching datasets', { q: input.q, type: input.type });
+        const raw = await getGbifService().searchDatasets({
+            ...(input.q?.trim() && { q: input.q }),
+            ...(input.type && { type: input.type }),
+            ...(input.publishingCountry?.trim() && { publishingCountry: input.publishingCountry }),
+            ...(input.hostingOrg?.trim() && { hostingOrg: input.hostingOrg }),
+            limit: input.limit,
+            offset: input.offset,
+        }, ctx);
+        const datasets = (raw.results ?? []).map((r) => ({
+            key: r.key,
+            title: r.title,
+            type: r.type,
+            description: r.description ? stripHtml(r.description).slice(0, 300) : undefined,
+            license: r.license,
+            doi: r.doi,
+            publishingCountry: r.publishingCountry,
+            recordCount: r.numRecords ?? r.recordCount,
+        }));
+        return {
+            datasets,
+            totalCount: raw.count ?? 0,
+            offset: raw.offset ?? input.offset,
+            limit: raw.limit ?? input.limit,
+            endOfRecords: raw.endOfRecords ?? true,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Total matches:** ${result.totalCount} | **Showing:** ${result.datasets.length} | **Limit:** ${result.limit} | **End of records:** ${result.endOfRecords} (offset ${result.offset})`,
+        ];
+        for (const ds of result.datasets) {
+            lines.push(`\n## ${ds.title ?? 'Untitled dataset'}`);
+            if (ds.key)
+                lines.push(`**Key:** ${ds.key}`);
+            if (ds.type)
+                lines.push(`**Type:** ${ds.type}`);
+            if (ds.license)
+                lines.push(`**License:** ${ds.license}`);
+            if (ds.doi)
+                lines.push(`**DOI:** ${ds.doi}`);
+            if (ds.publishingCountry)
+                lines.push(`**Publishing country:** ${ds.publishingCountry}`);
+            if (ds.recordCount != null)
+                lines.push(`**Records:** ${ds.recordCount.toLocaleString()}`);
+            if (ds.description)
+                lines.push(`${ds.description}${ds.description.length >= 300 ? '…' : ''}`);
+        }
+        if (!result.endOfRecords) {
+            lines.push(`\n*More results — use offset ${result.offset + result.limit} to continue.*`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-search-datasets.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-search-datasets.tool.js.map

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

package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Search GBIF occurrence records with Darwin Core filters.
+ * @module mcp-server/tools/definitions/gbif-search-occurrences
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const gbifSearchOccurrences: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    taxonKey: z.ZodOptional<z.ZodNumber>;
+    scientificName: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+    decimalLatitude: z.ZodOptional<z.ZodString>;
+    decimalLongitude: z.ZodOptional<z.ZodString>;
+    geometry: z.ZodOptional<z.ZodString>;
+    year: z.ZodOptional<z.ZodString>;
+    month: z.ZodOptional<z.ZodNumber>;
+    basisOfRecord: z.ZodOptional<z.ZodEnum<{
+        HUMAN_OBSERVATION: "HUMAN_OBSERVATION";
+        MACHINE_OBSERVATION: "MACHINE_OBSERVATION";
+        PRESERVED_SPECIMEN: "PRESERVED_SPECIMEN";
+        LIVING_SPECIMEN: "LIVING_SPECIMEN";
+        MATERIAL_SAMPLE: "MATERIAL_SAMPLE";
+        MATERIAL_CITATION: "MATERIAL_CITATION";
+        OCCURRENCE: "OCCURRENCE";
+        LITERATURE: "LITERATURE";
+    }>>;
+    hasCoordinate: z.ZodOptional<z.ZodBoolean>;
+    isInCluster: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    occurrences: z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodNumber>;
+        taxonKey: z.ZodOptional<z.ZodNumber>;
+        scientificName: z.ZodOptional<z.ZodString>;
+        canonicalName: z.ZodOptional<z.ZodString>;
+        rank: z.ZodOptional<z.ZodString>;
+        decimalLatitude: z.ZodOptional<z.ZodNumber>;
+        decimalLongitude: z.ZodOptional<z.ZodNumber>;
+        coordinateUncertaintyInMeters: z.ZodOptional<z.ZodNumber>;
+        country: z.ZodOptional<z.ZodString>;
+        countryCode: z.ZodOptional<z.ZodString>;
+        stateProvince: z.ZodOptional<z.ZodString>;
+        locality: z.ZodOptional<z.ZodString>;
+        eventDate: z.ZodOptional<z.ZodString>;
+        year: z.ZodOptional<z.ZodNumber>;
+        month: z.ZodOptional<z.ZodNumber>;
+        day: z.ZodOptional<z.ZodNumber>;
+        basisOfRecord: z.ZodOptional<z.ZodString>;
+        individualCount: z.ZodOptional<z.ZodNumber>;
+        datasetKey: z.ZodOptional<z.ZodString>;
+        datasetName: z.ZodOptional<z.ZodString>;
+        publishingCountry: z.ZodOptional<z.ZodString>;
+        recordedBy: z.ZodOptional<z.ZodString>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    endOfRecords: z.ZodBoolean;
+}, z.core.$strip>, readonly [{
+    readonly reason: "upstream_error";
+    readonly code: JsonRpcErrorCode.InternalError;
+    readonly when: "The GBIF occurrence search API returned an unexpected error.";
+    readonly recovery: "Retry the request or narrow the filters. Check that geometry WKT is valid if supplied.";
+}]>;
+//# sourceMappingURL=gbif-search-occurrences.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js

@@ -0,0 +1,278 @@
+/**
+ * @fileoverview Search GBIF occurrence records with Darwin Core filters.
+ * @module mcp-server/tools/definitions/gbif-search-occurrences
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+const PAGINATION_CAP = 99_000;
+export const gbifSearchOccurrences = tool('gbif_search_occurrences', {
+    title: 'Search Occurrences',
+    description: 'Search 2.4B+ GBIF occurrence records with Darwin Core filters. Use taxonKey from gbif_match_species ' +
+        'for reliable results — it resolves synonyms automatically. Accepts country (ISO 3166-1 alpha-2), ' +
+        'bounding box (decimalLatitude/decimalLongitude ranges), WKT polygon geometry, year range, month, ' +
+        'basis of record, and coordinate filter. Pagination is capped at approximately offset+limit=100,000 — ' +
+        'use gbif_occurrence_facets for aggregate counts across large result sets.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        taxonKey: z
+            .number()
+            .optional()
+            .describe('GBIF backbone taxon key from gbif_match_species. Preferred over scientificName — matches all synonyms automatically.'),
+        scientificName: z
+            .string()
+            .optional()
+            .describe('Scientific name filter. Less precise than taxonKey — does not match synonyms. Use taxonKey from gbif_match_species for reliable results.'),
+        country: z
+            .string()
+            .optional()
+            .describe('ISO 3166-1 alpha-2 country code (e.g., "GB", "US", "DE", "SE").'),
+        decimalLatitude: z
+            .string()
+            .optional()
+            .describe('Latitude range as "min,max" (e.g., "47.0,48.5"). Decimal degrees, WGS84. Combine with decimalLongitude for a bounding box.'),
+        decimalLongitude: z
+            .string()
+            .optional()
+            .describe('Longitude range as "min,max" (e.g., "8.0,9.5"). Decimal degrees, WGS84. Combine with decimalLatitude for a bounding box.'),
+        geometry: z
+            .string()
+            .optional()
+            .describe('WKT polygon for geographic filtering (e.g., POLYGON((8 47, 9 47, 9 48, 8 48, 8 47))). Coordinates are longitude latitude. Takes precedence over decimalLatitude/decimalLongitude.'),
+        year: z
+            .string()
+            .optional()
+            .describe('Year or year range. Single year: "2024". Range: "2020,2024". Filters by observation year.'),
+        month: z
+            .number()
+            .min(1)
+            .max(12)
+            .optional()
+            .describe('Calendar month (1–12). Useful for seasonal distribution queries.'),
+        basisOfRecord: z
+            .enum([
+            'HUMAN_OBSERVATION',
+            'MACHINE_OBSERVATION',
+            'PRESERVED_SPECIMEN',
+            'LIVING_SPECIMEN',
+            'MATERIAL_SAMPLE',
+            'MATERIAL_CITATION',
+            'OCCURRENCE',
+            'LITERATURE',
+        ])
+            .optional()
+            .describe('Filter by how the occurrence was recorded. HUMAN_OBSERVATION covers citizen science. PRESERVED_SPECIMEN covers natural history collections.'),
+        hasCoordinate: z
+            .boolean()
+            .optional()
+            .describe('When true, return only georeferenced records. When false, include records without coordinates.'),
+        isInCluster: z
+            .boolean()
+            .optional()
+            .describe('Filter to records flagged as likely duplicates (true) or exclude them (false). Omit to include all.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(300)
+            .default(20)
+            .describe('Number of records to return (default 20, max 300).'),
+        offset: z
+            .number()
+            .min(0)
+            .default(0)
+            .describe('Pagination offset. GBIF caps offset+limit at approximately 100,000 — use gbif_occurrence_facets for aggregate analysis beyond this.'),
+    }),
+    output: z.object({
+        occurrences: z
+            .array(z
+            .object({
+            key: z
+                .number()
+                .optional()
+                .describe('GBIF occurrence key for gbif_get_occurrence chaining.'),
+            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.'),
+            rank: 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.'),
+            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 name. May be absent.'),
+            locality: z.string().optional().describe('Locality description. May be absent.'),
+            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.'),
+            individualCount: z
+                .number()
+                .optional()
+                .describe('Number of individuals. May be absent.'),
+            datasetKey: z.string().optional().describe('UUID of the source dataset.'),
+            datasetName: z
+                .string()
+                .optional()
+                .describe('Name of the source dataset. May be absent.'),
+            publishingCountry: z
+                .string()
+                .optional()
+                .describe('Country code of the publishing organization.'),
+            recordedBy: z.string().optional().describe('Collector name(s). May be absent.'),
+            issues: z
+                .array(z.string())
+                .optional()
+                .describe('GBIF data quality issue flags for this record.'),
+        })
+            .describe('A single occurrence record with location, taxon, date, and provenance fields.'))
+            .describe('Occurrence records matching the filters.'),
+        totalCount: z.number().describe('Total matching occurrences before pagination.'),
+        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.'),
+    }),
+    errors: [
+        {
+            reason: 'upstream_error',
+            code: JsonRpcErrorCode.InternalError,
+            when: 'The GBIF occurrence search API returned an unexpected error.',
+            recovery: 'Retry the request or narrow the filters. Check that geometry WKT is valid if supplied.',
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Searching occurrences', {
+            taxonKey: input.taxonKey,
+            country: input.country,
+            limit: input.limit,
+            offset: input.offset,
+        });
+        if (input.offset + input.limit > PAGINATION_CAP) {
+            throw ctx.fail('upstream_error', `offset + limit (${input.offset + input.limit}) exceeds the GBIF pagination cap of ~100,000. Use gbif_occurrence_facets for aggregate analysis, or reduce offset/limit.`, { ...ctx.recoveryFor('upstream_error') });
+        }
+        const raw = await getGbifService().searchOccurrences({
+            ...(input.taxonKey !== undefined && { taxonKey: input.taxonKey }),
+            ...(input.scientificName?.trim() && { scientificName: input.scientificName }),
+            ...(input.country?.trim() && { country: input.country }),
+            ...(input.decimalLatitude?.trim() && { decimalLatitude: input.decimalLatitude }),
+            ...(input.decimalLongitude?.trim() && { decimalLongitude: input.decimalLongitude }),
+            ...(input.geometry?.trim() && { geometry: input.geometry }),
+            ...(input.year?.trim() && { year: input.year }),
+            ...(input.month !== undefined && { month: input.month }),
+            ...(input.basisOfRecord && { basisOfRecord: input.basisOfRecord }),
+            ...(input.hasCoordinate !== undefined && { hasCoordinate: input.hasCoordinate }),
+            ...(input.isInCluster !== undefined && { isInCluster: input.isInCluster }),
+            limit: input.limit,
+            offset: input.offset,
+        }, ctx);
+        const occurrences = (raw.results ?? []).map((r) => ({
+            key: r.key,
+            taxonKey: r.taxonKey,
+            scientificName: r.scientificName,
+            canonicalName: r.canonicalName,
+            rank: r.taxonRank,
+            decimalLatitude: r.decimalLatitude,
+            decimalLongitude: r.decimalLongitude,
+            coordinateUncertaintyInMeters: r.coordinateUncertaintyInMeters,
+            country: r.country,
+            countryCode: r.countryCode,
+            stateProvince: r.stateProvince,
+            locality: r.locality,
+            eventDate: r.eventDate,
+            year: r.year,
+            month: r.month,
+            day: r.day,
+            basisOfRecord: r.basisOfRecord,
+            individualCount: r.individualCount,
+            datasetKey: r.datasetKey,
+            datasetName: r.datasetName,
+            publishingCountry: r.publishingCountry,
+            recordedBy: r.recordedBy,
+            issues: r.issues?.length ? r.issues : undefined,
+        }));
+        return {
+            occurrences,
+            totalCount: raw.count ?? 0,
+            offset: raw.offset ?? input.offset,
+            limit: raw.limit ?? input.limit,
+            endOfRecords: raw.endOfRecords ?? true,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Total matches:** ${result.totalCount} | **Showing:** ${result.occurrences.length} | **Limit:** ${result.limit} | **End of records:** ${result.endOfRecords} (offset ${result.offset})`,
+        ];
+        for (const occ of result.occurrences) {
+            const canonical = occ.canonicalName ?? occ.scientificName ?? 'Unknown taxon';
+            const sci = occ.scientificName && occ.scientificName !== canonical ? ` [${occ.scientificName}]` : '';
+            lines.push(`\n## ${canonical}${sci}`);
+            if (occ.key != null)
+                lines.push(`**Occurrence key:** ${occ.key}`);
+            if (occ.taxonKey != null)
+                lines.push(`**Taxon key:** ${occ.taxonKey}`);
+            if (occ.rank)
+                lines.push(`**Rank:** ${occ.rank}`);
+            if (occ.basisOfRecord)
+                lines.push(`**Basis of record:** ${occ.basisOfRecord}`);
+            if (occ.eventDate) {
+                lines.push(`**Date:** ${occ.eventDate}`);
+            }
+            if (occ.year != null)
+                lines.push(`**Year:** ${occ.year}`);
+            if (occ.month != null)
+                lines.push(`**Month:** ${occ.month}`);
+            if (occ.day != null)
+                lines.push(`**Day:** ${occ.day}`);
+            if (occ.decimalLatitude != null && occ.decimalLongitude != null) {
+                lines.push(`**Coordinates:** ${occ.decimalLatitude}, ${occ.decimalLongitude}${occ.coordinateUncertaintyInMeters != null ? ` (±${occ.coordinateUncertaintyInMeters}m)` : ''}`);
+            }
+            else {
+                lines.push('**Coordinates:** Not available');
+            }
+            const geo = [];
+            if (occ.locality)
+                geo.push(occ.locality);
+            if (occ.stateProvince)
+                geo.push(occ.stateProvince);
+            if (occ.country)
+                geo.push(occ.country);
+            if (geo.length > 0)
+                lines.push(`**Location:** ${geo.join(', ')}${occ.countryCode ? ` (${occ.countryCode})` : ''}`);
+            else if (occ.countryCode)
+                lines.push(`**Country code:** ${occ.countryCode}`);
+            if (occ.publishingCountry)
+                lines.push(`**Publishing country:** ${occ.publishingCountry}`);
+            if (occ.recordedBy)
+                lines.push(`**Recorded by:** ${occ.recordedBy}`);
+            if (occ.individualCount != null)
+                lines.push(`**Count:** ${occ.individualCount}`);
+            if (occ.datasetKey)
+                lines.push(`**Dataset:** ${occ.datasetName ?? occ.datasetKey} (key: ${occ.datasetKey})`);
+            if (occ.issues?.length)
+                lines.push(`**Issues:** ${occ.issues.join(', ')}`);
+        }
+        if (!result.endOfRecords) {
+            lines.push(`\n*More results — use offset ${result.offset + result.limit} to continue.*`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-search-occurrences.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-search-occurrences.tool.js.map

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

package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Search GBIF publishing organizations by name or country.
+ * @module mcp-server/tools/definitions/gbif-search-publishers
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const gbifSearchPublishers: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    publishers: z.ZodArray<z.ZodObject<{
+        key: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        country: z.ZodOptional<z.ZodString>;
+        city: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalCount: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    endOfRecords: z.ZodBoolean;
+}, z.core.$strip>, undefined>;
+//# sourceMappingURL=gbif-search-publishers.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Search GBIF publishing organizations by name or country.
+ * @module mcp-server/tools/definitions/gbif-search-publishers
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getGbifService } from '../../../services/gbif/gbif-service.js';
+export const gbifSearchPublishers = tool('gbif_search_publishers', {
+    title: 'Search Publishers',
+    description: 'Search organizations registered with GBIF by name fragment or country. ' +
+        'Returns organization key, title, and country — sufficient to chain into gbif_search_datasets ' +
+        'with hostingOrg, or to understand who publishes data for a region.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        q: z.string().optional().describe('Name fragment to search for. Matches organization names.'),
+        country: z
+            .string()
+            .optional()
+            .describe('ISO 3166-1 alpha-2 country code to filter organizations by country.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(1000)
+            .default(20)
+            .describe('Number of organizations to return (default 20, max 1000).'),
+        offset: z.number().min(0).default(0).describe('Pagination offset.'),
+    }),
+    output: z.object({
+        publishers: z
+            .array(z
+            .object({
+            key: z
+                .string()
+                .optional()
+                .describe('Organization UUID for gbif_search_datasets hostingOrg parameter.'),
+            title: z.string().optional().describe('Organization name.'),
+            country: z.string().optional().describe('ISO 3166-1 alpha-2 country code.'),
+            city: z.string().optional().describe('City. May be absent.'),
+        })
+            .describe('A GBIF-registered publishing organization.'))
+            .describe('Matching organizations.'),
+        totalCount: z.number().describe('Total matching organizations before pagination.'),
+        offset: z.number().describe('Current pagination offset.'),
+        limit: z.number().describe('Organizations 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('Searching publishers', { q: input.q, country: input.country });
+        const raw = await getGbifService().searchPublishers({
+            ...(input.q?.trim() && { q: input.q }),
+            ...(input.country?.trim() && { country: input.country }),
+            limit: input.limit,
+            offset: input.offset,
+        }, ctx);
+        const publishers = (raw.results ?? []).map((r) => ({
+            key: r.key,
+            title: r.title,
+            country: r.country,
+            city: r.city,
+        }));
+        return {
+            publishers,
+            totalCount: raw.count ?? 0,
+            offset: raw.offset ?? input.offset,
+            limit: raw.limit ?? input.limit,
+            endOfRecords: raw.endOfRecords ?? true,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Total matches:** ${result.totalCount} | **Showing:** ${result.publishers.length} | **Limit:** ${result.limit} | **End of records:** ${result.endOfRecords} (offset ${result.offset})`,
+        ];
+        for (const pub of result.publishers) {
+            lines.push(`\n- **${pub.title ?? 'Unknown'}**`);
+            if (pub.key)
+                lines.push(`  Key: ${pub.key}`);
+            const location = [];
+            if (pub.city)
+                location.push(pub.city);
+            if (pub.country)
+                location.push(pub.country);
+            if (location.length > 0)
+                lines.push(`  Location: ${location.join(', ')}`);
+        }
+        if (!result.endOfRecords) {
+            lines.push(`\n*More results — use offset ${result.offset + result.limit} to continue.*`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=gbif-search-publishers.tool.js.map

package/dist/mcp-server/tools/definitions/gbif-search-publishers.tool.js.map

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