@globalfishingwatch/mcp 0.0.1

package/dist/tools/vessel-events.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vesselEvents = vesselEvents;
+exports.register = register;
+const zod_1 = require("zod");
+const api_js_1 = require("../lib/api.js");
+const map_url_generator_js_1 = require("../lib/map-url-generator.js");
+const response_js_1 = require("../lib/response.js");
+const types_js_1 = require("../lib/types.js");
+const datasetsByType = {
+    fishing: 'public-global-fishing-events:latest',
+    encounter: 'public-global-encounters-events:latest',
+    port_visit: 'public-global-port-visits-events:latest',
+    loitering: 'public-global-loitering-events:latest',
+};
+async function vesselEvents({ eventType, startDate, endDate, vesselId, limit, offset, confidence, encounterTypes, regionType, regionId, }) {
+    if (confidence !== undefined && eventType !== 'port_visit') {
+        return (0, response_js_1.createErrorResponse)('The confidence filter is only valid when eventType is "port_visit".');
+    }
+    if (encounterTypes !== undefined && eventType !== 'encounter') {
+        return (0, response_js_1.createErrorResponse)('The encounterTypes filter is only valid when eventType is "encounter".');
+    }
+    if ((regionType === undefined) !== (regionId === undefined)) {
+        return (0, response_js_1.createErrorResponse)('regionType and regionId must be provided together.');
+    }
+    const maxResults = limit ?? 20;
+    const pageOffset = offset ?? 0;
+    const dataset = datasetsByType[eventType];
+    const startIso = startDate
+        ? `${startDate}T00:00:00.000Z`
+        : new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+    const endIso = endDate
+        ? `${endDate}T23:59:59.999Z`
+        : new Date().toISOString();
+    const params = {
+        'datasets[0]': dataset,
+        'start-date': startIso,
+        'end-date': endIso,
+        limit: String(maxResults),
+        offset: String(pageOffset),
+        sort: '-start',
+    };
+    if (vesselId)
+        params['vessels[0]'] = vesselId;
+    if (regionType && regionId) {
+        params['region-ids[0]'] = regionId;
+        params['region-datasets[0]'] = types_js_1.REGION_DATASETS[regionType];
+    }
+    if (eventType === 'port_visit') {
+        const confidenceList = confidence ?? [4];
+        confidenceList.forEach((v, i) => {
+            params[`confidences[${i}]`] = String(v);
+        });
+    }
+    if (eventType === 'encounter') {
+        const encounterTypeList = encounterTypes ?? ['CARRIER-FISHING', 'SUPPORT-FISHING'];
+        const expanded = [];
+        for (const v of encounterTypeList) {
+            expanded.push(v);
+            if (v !== 'FISHING-FISHING') {
+                expanded.push(v.split('-').reverse().join('-'));
+            }
+        }
+        [...new Set(expanded)].forEach((v, i) => {
+            params[`encounter-types[${i}]`] = v;
+        });
+    }
+    const response = await (0, api_js_1.gfwFetch)('/v3/events', params);
+    const data = await response.json();
+    const entries = data.entries.map((e) => {
+        const extrafields = {};
+        if (eventType === 'port_visit') {
+            extrafields['port'] = {
+                name: e.port_visit?.intermediateAnchorage?.name ?? null,
+                id: e.port_visit?.intermediateAnchorage?.id ?? null,
+                flag: e.port_visit?.intermediateAnchorage?.flag ?? null,
+            };
+        }
+        else if (eventType === 'encounter') {
+            extrafields['encounteredVessel'] = {
+                name: e.encounter?.vessel?.name ?? null,
+                id: e.encounter?.vessel?.id ?? null,
+                flag: e.encounter?.vessel?.flag ?? null,
+                ssvid: e.encounter?.vessel?.ssvid ?? null,
+            };
+        }
+        return {
+            id: e.id,
+            type: e.type,
+            start: e.start,
+            end: e.end,
+            lat: e.position.lat,
+            lon: e.position.lon,
+            vesselId: e.vessel.id,
+            regions: {
+                mpa: e.regions.mpa ?? [],
+                eez: e.regions.eez ?? [],
+                rfmo: e.regions.rfmo ?? [],
+                fao: e.regions.fao ?? [],
+            },
+            ...extrafields,
+        };
+    });
+    const mapUrl = vesselId && startDate && endDate
+        ? (0, map_url_generator_js_1.generateVesselProfileUrl)(vesselId, startDate, endDate, [eventType])
+        : null;
+    return {
+        total: data.total,
+        limit: data.limit,
+        offset: data.offset,
+        nextOffset: data.nextOffset || 0,
+        entries,
+        mapUrl,
+    };
+}
+function register(server) {
+    server.registerTool('vessel-events', {
+        title: 'Vessel Events Lookup',
+        description: "Retrieve fishing events from the Global Fishing Watch API. Filter by event type, date range, vessel ID, and region. Results include event metadata, positions, vessel info, and the region IDs (EEZ, MPA, RFMO, FAO) where each event intersects. Use the regions fields in each entry to filter or group events by region — for example, to find all events inside a specific EEZ, MPA, RFMO, or FAO area. Each entry also includes a mapUrl linking to the vessel's profile on the Global Fishing Watch map — share this URL with the user when presenting results.",
+        inputSchema: {
+            eventType: zod_1.z
+                .enum(['fishing', 'encounter', 'port_visit', 'loitering'])
+                .describe('Type of event to retrieve.'),
+            startDate: zod_1.z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use ISO 8601 date format YYYY-MM-DD for startDate.')
+                .describe('Only include events on/after this date. If omitted, defaults to one month ago.'),
+            endDate: zod_1.z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use ISO 8601 date format YYYY-MM-DD for endDate. IMPORTANT! this date is exclusive.')
+                .describe('Only include events on/before this date. If omitted, defaults to today.'),
+            vesselId: zod_1.z
+                .string()
+                .optional()
+                .describe('Filter events by a specific vessel ID. Use the Vessel Search tool to find vessel IDs.'),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe('Maximum number of events to return (default 20, max 100).'),
+            offset: zod_1.z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Pagination offset (default 0).'),
+            confidence: zod_1.z
+                .array(zod_1.z.number().int().min(2).max(4))
+                .min(1)
+                .optional()
+                .describe('Confidence levels to include for port visits. Each value must be 2, 3, or 4. Only valid when eventType is "port_visit". ALWAYS default to [4] unless the user explicitly requests other confidence levels.'),
+            encounterTypes: zod_1.z
+                .array(zod_1.z.enum([
+                'CARRIER-FISHING',
+                'CARRIER-BUNKER',
+                'FISHING-BUNKER',
+                'FISHING-FISHING',
+                'SUPPORT-FISHING',
+            ]))
+                .min(1)
+                .optional()
+                .describe('Types of encounters to include. Only valid when eventType is "encounter". ALWAYS default to ["CARRIER-FISHING", "SUPPORT-FISHING"] unless the user explicitly requests other encounter types.'),
+            regionType: zod_1.z
+                .enum(['MPA', 'EEZ', 'RFMO'])
+                .optional()
+                .describe('Type of region to filter by: MPA (Marine Protected Area), EEZ (Exclusive Economic Zone), or RFMO (Regional Fisheries Management Organisation). Must be provided together with regionId.'),
+            regionId: zod_1.z
+                .string()
+                .optional()
+                .describe('Canonical ID of the region (MPA, EEZ, or RFMO). Use the Region ID Lookup tool if you only have the name. Must be provided together with regionType.'),
+        },
+        outputSchema: {
+            total: zod_1.z.number(),
+            limit: zod_1.z.number(),
+            offset: zod_1.z.number(),
+            nextOffset: zod_1.z.number().optional(),
+            entries: zod_1.z.array(zod_1.z.object({
+                id: zod_1.z.string(),
+                type: zod_1.z.string(),
+                start: zod_1.z.string(),
+                end: zod_1.z.string(),
+                lat: zod_1.z.number(),
+                lon: zod_1.z.number(),
+                vesselId: zod_1.z.string().nullish(),
+                vesselName: zod_1.z.string().nullish(),
+                vesselFlag: zod_1.z.string().nullish(),
+                regions: zod_1.z
+                    .object({
+                    mpa: zod_1.z.array(zod_1.z.string()),
+                    eez: zod_1.z.array(zod_1.z.string()),
+                    rfmo: zod_1.z.array(zod_1.z.string()),
+                    fao: zod_1.z.array(zod_1.z.string()),
+                })
+                    .describe('Region IDs where the event intersects, grouped by region type. Use these fields to filter or group events by region — for example, to find all events inside a specific EEZ, MPA, RFMO, or FAO area, match against the corresponding array.'),
+                port: zod_1.z
+                    .object({
+                    name: zod_1.z.string().nullish(),
+                    id: zod_1.z.string().nullish(),
+                    flag: zod_1.z.string().nullish(),
+                })
+                    .optional()
+                    .describe('Port details. Only present for port_visit events.'),
+                encounteredVessel: zod_1.z
+                    .object({
+                    name: zod_1.z.string().nullish(),
+                    id: zod_1.z.string().nullish(),
+                    flag: zod_1.z.string().nullish(),
+                    ssvid: zod_1.z.string().nullish(),
+                })
+                    .optional()
+                    .describe('The other vessel involved in the encounter. Only present for encounter events.'),
+            })),
+            mapUrl: zod_1.z
+                .string()
+                .nullish()
+                .describe("Global Fishing Watch map URL to view the vessel's profile for the queried period. IMPORTANT!! Always share this full link with the user when presenting results."),
+        },
+    }, async (params) => {
+        try {
+            const output = await vesselEvents(params);
+            return (0, response_js_1.createToolResponse)(JSON.stringify(output, null, 2), output);
+        }
+        catch (err) {
+            return (0, response_js_1.createErrorResponse)(`Failed to fetch vessel events: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/tools/vessel-report.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vesselReport = vesselReport;
+exports.register = register;
+const zod_1 = require("zod");
+const api_js_1 = require("../lib/api.js");
+const map_url_generator_js_1 = require("../lib/map-url-generator.js");
+const response_js_1 = require("../lib/response.js");
+const types_js_1 = require("../lib/types.js");
+async function vesselReport({ regionType, regionId, startDate, endDate, type, flags, vesselTypes, speeds, geartypes, groupBy, }) {
+    const activityType = type ?? 'FISHING';
+    const groupByValue = groupBy ?? 'VESSEL_ID';
+    const start = new Date(startDate);
+    const end = new Date(endDate);
+    const msInYear = 365 * 24 * 60 * 60 * 1000;
+    if (end.getTime() - start.getTime() > msInYear) {
+        return (0, response_js_1.createErrorResponse)('The report date range cannot exceed 1 year. Please reduce the range between startDate and endDate.');
+    }
+    if (activityType === 'PRESENCE' && (groupByValue === 'GEARTYPE' || groupByValue === 'FLAGANDGEARTYPE')) {
+        return (0, response_js_1.createErrorResponse)('groupBy "GEARTYPE" and "FLAGANDGEARTYPE" are only valid when type is "FISHING".');
+    }
+    if (activityType === 'FISHING' && Array.isArray(vesselTypes) && vesselTypes.length > 0) {
+        return (0, response_js_1.createErrorResponse)('vesselTypes filter is only valid when type is "PRESENCE".');
+    }
+    if (activityType === 'PRESENCE' && Array.isArray(geartypes) && geartypes.length > 0) {
+        return (0, response_js_1.createErrorResponse)('geartypes filter is only valid when type is "FISHING".');
+    }
+    const activityDataset = types_js_1.ACTIVITY_DATASETS[activityType];
+    const flagList = Array.isArray(flags) ? flags : [];
+    const speedList = Array.isArray(speeds) ? speeds : [];
+    const vesselTypeList = Array.isArray(vesselTypes) ? vesselTypes : [];
+    const geartypeList = Array.isArray(geartypes) ? geartypes : [];
+    const filters = [];
+    if (flagList.length > 0)
+        filters.push(`flag IN (${flagList.map((f) => `'${f}'`).join(',')})`);
+    if (speedList.length > 0)
+        filters.push(`speed IN (${speedList.map((s) => `'${s}'`).join(',')})`);
+    if (vesselTypeList.length > 0)
+        filters.push(`vessel_type IN (${vesselTypeList.map((t) => `'${t}'`).join(',')})`);
+    if (geartypeList.length > 0)
+        filters.push(`geartype IN (${geartypeList.map((g) => `'${g}'`).join(',')})`);
+    const params = {
+        format: 'JSON',
+        'datasets[0]': activityDataset,
+        'date-range': `${startDate}T00:00:00.000Z,${endDate}T23:59:59.999Z`,
+        'spatial-aggregation': 'true',
+        'temporal-resolution': 'ENTIRE',
+        'region-id': regionId,
+        'region-dataset': types_js_1.REGION_DATASETS[regionType],
+        'group-by': groupByValue,
+    };
+    if (filters.length > 0)
+        params['filters[0]'] = filters.join(' AND ');
+    const response = await (0, api_js_1.gfwFetch)('/v3/4wings/report', params);
+    const data = await response.json();
+    const allRows = data.entries.flatMap((entry) => entry[activityDataset] ?? []);
+    const fishingHours = allRows.reduce((sum, row) => sum + row.hours, 0);
+    const topVessels = groupByValue === 'VESSEL_ID'
+        ? [...allRows].sort((a, b) => b.hours - a.hours).slice(0, 10).map((row) => ({
+            vesselId: row.vesselId,
+            shipName: row.shipName,
+            mmsi: row.mmsi,
+            flag: row.flag,
+            geartype: row.geartype,
+            hours: row.hours,
+        }))
+        : undefined;
+    const rows = (() => {
+        if (groupByValue === 'VESSEL_ID')
+            return undefined;
+        const aggregated = new Map();
+        for (const row of allRows) {
+            const key = groupByValue === 'FLAG' ? row.flag
+                : groupByValue === 'GEARTYPE' ? row.geartype
+                    : `${row.flag}__${row.geartype}`;
+            const keyFields = groupByValue === 'FLAG' ? { flag: row.flag }
+                : groupByValue === 'GEARTYPE' ? { geartype: row.geartype }
+                    : { flag: row.flag, geartype: row.geartype };
+            const existing = aggregated.get(key);
+            if (existing) {
+                existing.hours += row.hours;
+            }
+            else {
+                aggregated.set(key, { key: keyFields, hours: row.hours });
+            }
+        }
+        return [...aggregated.values()].sort((a, b) => b.hours - a.hours).map(({ key, hours }) => ({ ...key, hours }));
+    })();
+    const gfwMapUrl = (0, map_url_generator_js_1.generateReportUrl)(regionId, regionType, activityType, startDate, endDate, {
+        speed: speedList,
+        vesselType: vesselTypeList,
+        geartype: geartypeList,
+        flag: flagList,
+    });
+    return {
+        regionType,
+        regionId,
+        dateRange: { start: startDate, end: endDate },
+        fishingHours,
+        ...(topVessels && { topVessels }),
+        ...(rows && { rows }),
+        ...(flagList.length > 0 && { flags: flagList }),
+        ...(vesselTypeList.length > 0 && { vesselTypes: vesselTypeList }),
+        ...(speedList.length > 0 && { speeds: speedList }),
+        ...(geartypeList.length > 0 && { geartypes: geartypeList }),
+        gfwMapUrl,
+    };
+}
+function register(server) {
+    server.registerTool('vessel-report', {
+        title: 'Activity Hours Calculator',
+        description: 'Returns the number of activity hours for a given time period in a specific Marine Protected Area (MPA), Exclusive Economic Zone (EEZ), or Regional Fisheries Management Organisation (RFMO) identified by its canonical region ID. Use the Region ID Lookup tool first if you only know the human-readable name. Optionally filters by one or multiple vessel flag states. This tool calculates and reports the total fishing activity hours detected within the region boundaries during the specified date range. The tool also provides a link to the Global Fishing Watch (GFW) map where users can view the detailed data and navigate the fishing activity visually. IMPORTANT: This tool must NEVER be called in parallel. If multiple reports are needed, call this tool sequentially, one at a time, waiting for each result before making the next call. IMPORTANT: The gfwMapUrl returned by this tool must NEVER be truncated, shortened, or summarized — always display it in its entirety.',
+        inputSchema: {
+            regionType: zod_1.z
+                .enum(['MPA', 'EEZ', 'RFMO'])
+                .describe('Type of region to analyze: MPA (Marine Protected Area), EEZ (Exclusive Economic Zone), or RFMO (Regional Fisheries Management Organisation)'),
+            regionId: zod_1.z
+                .string()
+                .describe('Canonical ID of the region (MPA, EEZ, or RFMO). Use the Region ID Lookup tool if you only have the name.'),
+            startDate: zod_1.z
+                .string()
+                .describe('Start date of the report period (ISO 8601 format: YYYY-MM-DD)'),
+            endDate: zod_1.z
+                .string()
+                .describe('End date of the report period (ISO 8601 format: YYYY-MM-DD). IMPORTANT! this date is exclusive. The range between startDate and endDate must not exceed 1 year.'),
+            type: zod_1.z
+                .enum(['FISHING', 'PRESENCE'])
+                .optional()
+                .describe('Type of activity data to use for the report. ' +
+                '"FISHING" (default) uses AIS-based fishing effort data — hours when a vessel was actively fishing as detected by its movement pattern. Use this to answer questions about fishing activity, fishing pressure, or fishing hours inside a region. ' +
+                '"PRESENCE" uses vessel presence data — hours when any vessel was present inside the region regardless of whether it was fishing. Use this when the question is about vessel traffic, transit, or total time spent in the area.'),
+            flags: zod_1.z
+                .array(zod_1.z
+                .string()
+                .regex(/^[A-Z]{3}$/, 'Use ISO 3166-1 alpha-3 country codes (e.g., "ESP").'))
+                .min(1)
+                .max(10)
+                .optional()
+                .describe('Optional list of vessel flag states (ISO 3166-1 alpha-3 codes, e.g., "ESP", "USA", "CHN"). When omitted, all flags are included.'),
+            vesselTypes: zod_1.z
+                .array(zod_1.z.enum([
+                'carrier',
+                'seismic_vessel',
+                'passenger',
+                'other',
+                'support',
+                'bunker',
+                'gear',
+                'cargo',
+                'fishing',
+                'discrepancy',
+            ]))
+                .min(1)
+                .optional()
+                .describe('Optional list of vessel types to filter by. Only applicable when type is "PRESENCE". When omitted, all vessel types are included.'),
+            speeds: zod_1.z
+                .array(zod_1.z.enum(['2-4', '4-6', '6-10', '10-15', '15-25', '>25']))
+                .min(1)
+                .optional()
+                .describe('Optional list of speed ranges to filter by. Only applicable when type is "PRESENCE". When omitted, all speeds are included.'),
+            geartypes: zod_1.z
+                .array(zod_1.z.enum([
+                'tuna_purse_seines',
+                'driftnets',
+                'trollers',
+                'set_longlines',
+                'purse_seines',
+                'pots_and_traps',
+                'other_fishing',
+                'dredge_fishing',
+                'set_gillnets',
+                'fixed_gear',
+                'trawlers',
+                'fishing',
+                'seiners',
+                'other_purse_seines',
+                'other_seines',
+                'squid_jigger',
+                'pole_and_line',
+                'drifting_longlines',
+            ]))
+                .min(1)
+                .optional()
+                .describe('Optional list of gear types to filter by. Only applicable when type is "FISHING". When omitted, all gear types are included.'),
+            groupBy: zod_1.z
+                .enum(['VESSEL_ID', 'FLAG', 'GEARTYPE', 'FLAGANDGEARTYPE'])
+                .optional()
+                .describe('How to group the report results. ' +
+                '"VESSEL_ID" (default): results grouped per individual vessel. ' +
+                '"FLAG": results aggregated by flag state. ' +
+                '"GEARTYPE": results aggregated by gear type — only valid when type is "FISHING". ' +
+                '"FLAGANDGEARTYPE": results aggregated by flag state and gear type combined — only valid when type is "FISHING".'),
+        },
+        outputSchema: {
+            regionType: zod_1.z.enum(['MPA', 'EEZ', 'RFMO']),
+            regionId: zod_1.z.string(),
+            dateRange: zod_1.z.object({ start: zod_1.z.string(), end: zod_1.z.string() }),
+            fishingHours: zod_1.z
+                .number()
+                .describe('Total number of fishing hours detected in the region during the specified date range'),
+            flags: zod_1.z
+                .array(zod_1.z.string().regex(/^[A-Z]{3}$/))
+                .optional()
+                .describe('Flag state filters applied (if any). ISO 3166-1 alpha-3 codes.'),
+            vesselTypes: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe('Vessel type filters applied (if any).'),
+            speeds: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe('Speed range filters applied (if any).'),
+            geartypes: zod_1.z
+                .array(zod_1.z.string())
+                .optional()
+                .describe('Gear type filters applied (if any).'),
+            gfwMapUrl: zod_1.z
+                .string()
+                .describe('URL to the Global Fishing Watch map showing the detailed fishing activity data for the specified region and date range. IMPORTANT!! Always share this full link with the user when presenting reports. NEVER truncate, shorten, or summarize this URL — always display it in its entirety.'),
+            topVessels: zod_1.z
+                .array(zod_1.z.object({
+                vesselId: zod_1.z.string(),
+                shipName: zod_1.z.string().nullish(),
+                mmsi: zod_1.z.string().nullish(),
+                flag: zod_1.z.string().nullish(),
+                geartype: zod_1.z.string().nullish(),
+                hours: zod_1.z.number(),
+            }))
+                .optional()
+                .describe('Top 10 vessels by hours. Only present when groupBy is "VESSEL_ID".'),
+            rows: zod_1.z
+                .array(zod_1.z.record(zod_1.z.string().or(zod_1.z.number())))
+                .optional()
+                .describe('Aggregated rows sorted by hours descending. Present when groupBy is "FLAG", "GEARTYPE", or "FLAGANDGEARTYPE". Each row contains the grouping fields plus "hours".'),
+        },
+    }, async (params) => {
+        try {
+            const output = await vesselReport(params);
+            if ('isError' in output)
+                return output;
+            const flagText = output.flags && output.flags.length > 0 ? `\nFlag Filters: ${output.flags.join(', ')}` : '';
+            const activityType = params.type ?? 'FISHING';
+            const responseText = `${activityType === 'FISHING' ? 'Fishing Hours Report' : 'Presence Hours Report'} for ${output.regionType} ID: ${output.regionId}${flagText}
+Date Range: ${output.dateRange.start} to ${output.dateRange.end}
+
+Total ${activityType} Hours: ${output.fishingHours} hours
+
+View detailed data on the Global Fishing Watch map:
+${output.gfwMapUrl}
+
+Full data: ${JSON.stringify(output, null, 2)}`;
+            return (0, response_js_1.createToolResponse)(responseText, output);
+        }
+        catch (err) {
+            const activityType = params.type ?? 'FISHING';
+            return (0, response_js_1.createErrorResponse)(`Failed to generate ${activityType} hours report: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/tools/vessel-search.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vesselSearch = vesselSearch;
+exports.register = register;
+const zod_1 = require("zod");
+const api_js_1 = require("../lib/api.js");
+const map_url_generator_js_1 = require("../lib/map-url-generator.js");
+const response_js_1 = require("../lib/response.js");
+const DATASET = 'public-global-vessel-identity:v4.0';
+async function vesselSearch({ name, mmsi, imo, callsign, flag, activeFrom, activeTo, limit, }) {
+    const maxResults = limit ?? 10;
+    const conditions = [];
+    if (callsign)
+        conditions.push(`callsign = '${callsign.toUpperCase()}'`);
+    if (flag)
+        conditions.push(`flag = '${flag.toUpperCase()}'`);
+    if (imo)
+        conditions.push(`imo = '${imo.toUpperCase()}'`);
+    if (mmsi)
+        conditions.push(`ssvid = '${mmsi.toUpperCase()}'`);
+    if (activeTo)
+        conditions.push(`transmissionDateFrom < '${activeTo}T23:59:59Z'`);
+    if (activeFrom)
+        conditions.push(`transmissionDateTo > '${activeFrom}T00:00:00Z'`);
+    if (name)
+        conditions.push(`shipname LIKE '*${name.toUpperCase()}*'`);
+    if (conditions.length === 0) {
+        return (0, response_js_1.createErrorResponse)('No search criteria provided. At least one filter must be specified for a meaningful search.');
+    }
+    const params = {
+        'datasets[0]': DATASET,
+        limit: String(maxResults),
+        where: conditions.join(' AND '),
+    };
+    const response = await (0, api_js_1.gfwFetch)('/v3/vessels/search', params);
+    const data = await response.json();
+    const results = data.entries.map((entry) => {
+        const info = entry.selfReportedInfo[0];
+        const combined = entry.combinedSourcesInfo[0];
+        const vesselId = info?.id ?? combined?.vesselId ?? '';
+        const from = info?.transmissionDateFrom;
+        const to = info?.transmissionDateTo;
+        return {
+            vesselId,
+            name: info?.shipname,
+            mmsi: info?.ssvid,
+            imo: info?.imo ?? undefined,
+            callsign: info?.callsign ?? undefined,
+            flag: info?.flag,
+            gearType: combined?.geartypes?.[0]?.name,
+            activeFrom: from,
+            activeTo: to,
+            mapUrl: vesselId ? (0, map_url_generator_js_1.generateVesselProfileUrl)(vesselId, from, to) : null,
+        };
+    });
+    return { total: data.total, limit: data.limit, results };
+}
+function register(server) {
+    server.registerTool('vessel-search', {
+        title: 'Vessel Search',
+        description: "Search vessels by name, MMSI, IMO, callsign, flag, gear type, or activity date range. Returns basic vessel metadata and identifiers, including a mapUrl for each vessel. Use the mapUrl to link the user directly to the vessel's profile on the Global Fishing Watch map. All filters are optional but at least one should be provided for meaningful results.",
+        inputSchema: {
+            name: zod_1.z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Vessel name or partial name (case-insensitive wildcard match).'),
+            mmsi: zod_1.z
+                .string()
+                .regex(/^[0-9]{9}$/, 'MMSI must be a 9-digit string.')
+                .optional()
+                .describe('Maritime Mobile Service Identity (9 digits).'),
+            imo: zod_1.z
+                .string()
+                .regex(/^[0-9]{7}$/, 'IMO must be a 7-digit string.')
+                .optional()
+                .describe('IMO number (7 digits).'),
+            callsign: zod_1.z
+                .string()
+                .trim()
+                .optional()
+                .describe('Vessel radio callsign (exact match).'),
+            flag: zod_1.z
+                .string()
+                .regex(/^[A-Z]{3}$/, 'Use ISO 3166-1 alpha-3 country code (e.g., "ESP").')
+                .optional()
+                .describe('Flag state ISO 3166-1 alpha-3 code (e.g., "ESP", "USA").'),
+            activeFrom: zod_1.z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use ISO 8601 date format YYYY-MM-DD for activeFrom.')
+                .optional()
+                .describe('Filter for vessels active on or after this date (ISO 8601).'),
+            activeTo: zod_1.z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use ISO 8601 date format YYYY-MM-DD for activeTo.')
+                .optional()
+                .describe('Filter for vessels active on or before this date (ISO 8601). IMPORTANT! this date is exclusive.'),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe('Maximum number of results to return (default 10, max 50).'),
+        },
+        outputSchema: {
+            total: zod_1.z.number(),
+            limit: zod_1.z.number(),
+            results: zod_1.z.array(zod_1.z.object({
+                vesselId: zod_1.z.string(),
+                name: zod_1.z.string().nullish(),
+                mmsi: zod_1.z.string().nullish(),
+                imo: zod_1.z.string().nullish(),
+                callsign: zod_1.z.string().nullish(),
+                flag: zod_1.z.string().nullish(),
+                gearType: zod_1.z.string().nullish(),
+                activeFrom: zod_1.z.string().nullish(),
+                activeTo: zod_1.z.string().nullish(),
+                mapUrl: zod_1.z
+                    .string()
+                    .nullish()
+                    .describe("Global Fishing Watch map URL to view this vessel's profile and track. IMPORTANT!! Always share this full link with the user when presenting vessel results."),
+            })),
+        },
+    }, async (params) => {
+        try {
+            const output = await vesselSearch(params);
+            return (0, response_js_1.createToolResponse)(JSON.stringify(output, null, 2), output);
+        }
+        catch (err) {
+            return (0, response_js_1.createErrorResponse)(`Failed to search vessels: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@globalfishingwatch/mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Global Fishing Watch data — vessel search, events, fishing hours, and region lookups",
+  "author": "Global Fishing Watch",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "global-fishing-watch",
+    "gfw",
+    "fishing",
+    "vessels",
+    "ais"
+  ],
+  "main": "./dist/index.js",
+  "bin": {
+    "gfw-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx index.ts",
+    "cli": "tsx cli/index.ts",
+    "link": "npm run build && npm link",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@sentry/node": "^10.48.0",
+    "axios": "^1.13.6",
+    "commander": "^14.0.3",
+    "express": "^5.1.0",
+    "qs": "^6.15.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/node": "^24.10.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}