@globalfishingwatch/mcp 0.0.1

package/dist/lib/api.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gfwFetch = gfwFetch;
+const GFW_BASE = 'https://gateway.api.globalfishingwatch.org';
+/**
+ * Fetch wrapper for the GFW API.
+ * Automatically injects the Bearer token from API_KEY env var when present.
+ * Throws an Error if the response is not OK.
+ */
+async function gfwFetch(path, params) {
+    const url = new URL(`${GFW_BASE}${path}`);
+    if (params) {
+        Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    const apiKey = process.env.API_KEY;
+    console.error(`Making GFW API request to ${url}`);
+    const response = await fetch(url.toString(), {
+        headers: {
+            ...(apiKey && { Authorization: `Bearer ${apiKey}` }),
+            Referer: 'gfw-mcp-js',
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`GFW API error ${response.status}: ${response.statusText}`);
+    }
+    return response;
+}

package/dist/lib/map-url-generator.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateReportUrl = generateReportUrl;
+exports.generateVesselProfileUrl = generateVesselProfileUrl;
+exports.generatePortReportUrl = generatePortReportUrl;
+const qs_1 = require("qs");
+const types_1 = require("./types");
+const DATA_DATAVIEW_INSTANCES = {
+    FISHING: 'ais',
+    PRESENCE: 'presence',
+};
+const REGIONS_DATAVIEW_INSTANCES = {
+    MPA: 'context-layer-mpa',
+    EEZ: 'context-layer-eez',
+    RFMO: 'context-layer-rfmo',
+};
+const GFW_BASE_URL = 'https://globalfishingwatch.org/map';
+function generateReportUrl(regionId, regionType, type, startDate, endDate, filters = undefined) {
+    const baseUrl = '/fishing-activity/default-public';
+    let dynamicPath = `/report/${types_1.REGION_DATASETS[regionType]}/${regionId}?reportLoadVessels=true&start=${startDate}&end=${endDate}`;
+    const filtersCfg = {};
+    const dataviewAIS = {
+        id: DATA_DATAVIEW_INSTANCES['FISHING'],
+        cfg: {
+            vis: type === 'FISHING' ? true : false,
+            filters: type === 'FISHING' ? filters : undefined,
+        },
+    };
+    const dataviewPresence = {
+        id: DATA_DATAVIEW_INSTANCES['PRESENCE'],
+        cfg: {
+            vis: type === 'PRESENCE' ? true : false,
+            filters: type === 'PRESENCE' ? filters : undefined,
+        },
+    };
+    const dataviewVMS = {
+        id: 'vms',
+        cfg: {
+            vis: false,
+        },
+    };
+    const dataviewRegion = {
+        id: REGIONS_DATAVIEW_INSTANCES[regionType],
+        cfg: {
+            vis: true,
+        },
+    };
+    console.error('object', JSON.stringify({
+        dvIn: [dataviewAIS, dataviewVMS, dataviewPresence, dataviewRegion],
+    }));
+    const dataviewInstances = (0, qs_1.stringify)({ dvIn: [dataviewAIS, dataviewVMS, dataviewPresence, dataviewRegion] }, { arrayFormat: 'indices' });
+    dynamicPath += `&${dataviewInstances}`;
+    return `${GFW_BASE_URL}${baseUrl}${dynamicPath}`;
+}
+function generateVesselProfileUrl(vesselId, activeFrom, activeTo, events = []) {
+    const baseUrl = '/vessel';
+    let dynamicPath = `/${vesselId}?`;
+    if (activeFrom && activeTo) {
+        dynamicPath += `&activeFrom=${activeFrom}&activeTo=${activeTo}`;
+    }
+    if (events.length > 0) {
+        dynamicPath += events.map((e, i) => `vE[${i}]=${e}`).join('&');
+    }
+    return `${GFW_BASE_URL}${baseUrl}${dynamicPath}`;
+}
+function generatePortReportUrl(portId) {
+    return `${GFW_BASE_URL}/fishing-activity/default-public/ports-report/${portId}?portsReportDatasetId=public-global-port-visits-events:latest`;
+}

package/dist/lib/response.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolResponse = createToolResponse;
+exports.createErrorResponse = createErrorResponse;
+function createToolResponse(text, structured) {
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: structured,
+        isError: false,
+    };
+}
+function createErrorResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}

package/dist/lib/types.js

@@ -0,0 +1,14 @@
+"use strict";
+// ── Region datasets ──────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVITY_DATASETS = exports.REGION_DATASETS = void 0;
+exports.REGION_DATASETS = {
+    MPA: 'public-mpa-all',
+    EEZ: 'public-eez-areas',
+    RFMO: 'public-rfmo',
+};
+// ── Activity datasets ────────────────────────────────────────────────────────
+exports.ACTIVITY_DATASETS = {
+    FISHING: 'public-global-fishing-effort:v4.0',
+    PRESENCE: 'public-global-presence:v4.0',
+};

package/dist/mcp-server.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const vesselEvents = __importStar(require("./tools/vessel-events.js"));
+const eventsStats = __importStar(require("./tools/events-stats.js"));
+const vesselSearch = __importStar(require("./tools/vessel-search.js"));
+const vesselById = __importStar(require("./tools/vessel-by-id.js"));
+const regionIdLookup = __importStar(require("./tools/region-id-lookup.js"));
+const regionGeometry = __importStar(require("./tools/region-geometry.js"));
+const mpaVesselReport = __importStar(require("./tools/vessel-report.js"));
+function createServer() {
+    const server = new mcp_js_1.McpServer({ name: 'gfw', version: '1.0.0' });
+    vesselEvents.register(server);
+    eventsStats.register(server);
+    vesselSearch.register(server);
+    regionIdLookup.register(server);
+    regionGeometry.register(server);
+    vesselById.register(server);
+    mpaVesselReport.register(server);
+    return server;
+}

package/dist/middleware/auth.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authenticate = exports.API_KEY = void 0;
+exports.API_KEY = process.env.API_KEY;
+const AUTH_REQUIRED = !!exports.API_KEY;
+const authenticate = (req, res, next) => {
+    if (!AUTH_REQUIRED) {
+        return next();
+    }
+    const authHeader = req.headers.authorization;
+    let providedKey;
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+        providedKey = authHeader.substring(7);
+    }
+    else {
+        providedKey = req.headers['x-api-key'];
+    }
+    if (!providedKey || providedKey !== exports.API_KEY) {
+        return res.status(401).json({
+            error: 'Unauthorized',
+            message: 'Invalid or missing API key. Provide it via Authorization: Bearer <key> or X-API-Key header.',
+        });
+    }
+    next();
+};
+exports.authenticate = authenticate;

package/dist/tools/events-stats.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventsStats = eventsStats;
+exports.register = register;
+const zod_1 = require("zod");
+const api_js_1 = require("../lib/api.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',
+};
+const MAX_FETCH = 500;
+async function eventsStats({ eventType, startDate, endDate, confidence, encounterTypes, regionType, regionId, groupBy = 'FLAG', }) {
+    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 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,
+        'group-by': groupBy.toUpperCase(),
+        'time-filter-mode': 'START-DATE',
+        'includes[0]': 'EVENTS_GROUPED',
+        'includes[1]': 'TOTAL_COUNT',
+        'timeseries-interval': 'YEAR',
+    };
+    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/stats', params);
+    const data = await response.json();
+    return data;
+}
+function register(server) {
+    server.registerTool('events-stats', {
+        title: 'Events Statistics',
+        description: 'Compute aggregate statistics for events (fishing, encounters, port visits, loitering) over a date range. Optionally filter by region (MPA, EEZ, RFMO) and group results by flag or gear type. Returns total event count, unique flags, unique vessels, and grouped counts.',
+        inputSchema: {
+            eventType: zod_1.z
+                .enum(['fishing', 'encounter', 'port_visit', 'loitering'])
+                .describe('Type of event to analyse.'),
+            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.'),
+            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.'),
+            groupBy: zod_1.z
+                .enum(['FLAG', 'GEARTYPE'])
+                .optional()
+                .describe('Dimension to group events by in the "groups" output. Defaults to "flag". ' +
+                '"FLAG": counts per vessel flag state. ' +
+                '"GEARTYPE": counts per vessel gear type.'),
+        },
+        outputSchema: {
+            flags: zod_1.z
+                .array(zod_1.z.string())
+                .describe('All unique flag states found in the matching events.'),
+            numEvents: zod_1.z
+                .number()
+                .describe('Total number of matching events fetched (up to 500).'),
+            numFlags: zod_1.z.number().describe('Number of unique flag states.'),
+            numVessels: zod_1.z.number().describe('Number of unique vessels.'),
+            groups: zod_1.z
+                .array(zod_1.z.object({ name: zod_1.z.string(), value: zod_1.z.number() }))
+                .describe('Counts grouped by the chosen groupBy dimension, sorted descending by value. Empty when groupBy is not specified.'),
+        },
+    }, async (params) => {
+        try {
+            const data = await eventsStats(params);
+            return (0, response_js_1.createToolResponse)(JSON.stringify(data, null, 2), data);
+        }
+        catch (err) {
+            return (0, response_js_1.createErrorResponse)(`Failed to compute event statistics: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/tools/region-geometry.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regionGeometry = regionGeometry;
+exports.register = register;
+const zod_1 = require("zod");
+const response_js_1 = require("../lib/response.js");
+const types_js_1 = require("../lib/types.js");
+const GFW_BASE = 'https://gateway.api.globalfishingwatch.org';
+function regionGeometry({ regionType, id, }) {
+    const dataset = types_js_1.REGION_DATASETS[regionType];
+    const url = `${GFW_BASE}/v3/datasets/${dataset}/context-layers/${id}`;
+    return { regionType, id, url };
+}
+function register(server) {
+    server.registerTool('region-geometry', {
+        title: 'Region Geometry URL',
+        description: 'Returns the URL where the GeoJSON geometry of a specific Marine Protected Area (MPA), Exclusive Economic Zone (EEZ), or Regional Fisheries Management Organisation (RFMO) can be retrieved. Use region-id-lookup first to obtain the ID.',
+        inputSchema: {
+            regionType: zod_1.z
+                .enum(['MPA', 'EEZ', 'RFMO'])
+                .describe('Type of region: MPA (Marine Protected Area), EEZ (Exclusive Economic Zone), or RFMO (Regional Fisheries Management Organisation)'),
+            id: zod_1.z.string().describe('Canonical region ID as returned by region-id-lookup'),
+        },
+        outputSchema: {
+            regionType: zod_1.z.enum(['MPA', 'EEZ', 'RFMO']),
+            id: zod_1.z.string(),
+            url: zod_1.z.string().describe('URL to fetch the GeoJSON geometry of the region'),
+        },
+    }, async (params) => {
+        const output = regionGeometry(params);
+        return (0, response_js_1.createToolResponse)(JSON.stringify(output, null, 2), output);
+    });
+}

package/dist/tools/region-id-lookup.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regionIdLookup = regionIdLookup;
+exports.register = register;
+const zod_1 = require("zod");
+const api_js_1 = require("../lib/api.js");
+const response_js_1 = require("../lib/response.js");
+const types_js_1 = require("../lib/types.js");
+// Returns a simple similarity score: number of query words found in label
+function score(label, query) {
+    const lowerLabel = label.toLowerCase();
+    const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+    return words.filter((w) => lowerLabel.includes(w)).length;
+}
+async function regionIdLookup({ regionType, query, limit, }) {
+    const maxResults = limit ?? 5;
+    const dataset = types_js_1.REGION_DATASETS[regionType];
+    const response = await (0, api_js_1.gfwFetch)(`/v3/datasets/${dataset}/context-layers`);
+    const layers = await response.json();
+    const matches = layers
+        .map((layer) => ({ layer, s: score(layer.label, query) }))
+        .filter(({ s }) => s > 0)
+        .sort((a, b) => b.s - a.s)
+        .slice(0, maxResults)
+        .map(({ layer }) => ({
+        id: String(layer.id),
+        name: layer.label,
+        country: layer.iso3 ?? undefined,
+        source: dataset,
+    }));
+    return { regionType, query, limit: maxResults, matches };
+}
+function register(server) {
+    server.registerTool('region-id-lookup', {
+        title: 'Region ID Lookup',
+        description: 'Retrieve the canonical identifier (ID) for a Marine Protected Area (MPA), Exclusive Economic Zone (EEZ), or Regional Fisheries Management Organisation (RFMO) based on a human-readable name. When more than one match is returned, ask the user which region they meant before proceeding. Use this tool before requesting fishing hours to ensure you pass the correct region ID.',
+        inputSchema: {
+            regionType: zod_1.z
+                .enum(['MPA', 'EEZ', 'RFMO'])
+                .describe('Type of region to search: MPA (Marine Protected Area), EEZ (Exclusive Economic Zone), or RFMO (Regional Fisheries Management Organisation)'),
+            query: zod_1.z
+                .string()
+                .describe('Name or partial name of the region. Case-insensitive substring matching is applied.'),
+            limit: zod_1.z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe('Maximum number of results to return (default: 5, max: 20).'),
+        },
+        outputSchema: {
+            regionType: zod_1.z.enum(['MPA', 'EEZ', 'RFMO']),
+            query: zod_1.z.string(),
+            limit: zod_1.z.number(),
+            matches: zod_1.z.array(zod_1.z.object({
+                id: zod_1.z.string(),
+                name: zod_1.z.string(),
+                country: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('ISO 3166-1 alpha-3 country code, if available'),
+                source: zod_1.z.string().describe('Data source or catalogue identifier'),
+            })),
+        },
+    }, async (params) => {
+        try {
+            const output = await regionIdLookup(params);
+            return (0, response_js_1.createToolResponse)(JSON.stringify(output, null, 2), output);
+        }
+        catch (err) {
+            return (0, response_js_1.createErrorResponse)(`Failed to look up region: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/tools/vessel-by-id.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vesselById = vesselById;
+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 vesselById({ ids }) {
+    const params = {
+        'datasets[0]': DATASET,
+        ...Object.fromEntries(ids.map((id, i) => [`ids[${i}]`, id])),
+    };
+    const response = await (0, api_js_1.gfwFetch)('/v3/vessels', 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, results };
+}
+function register(server) {
+    server.registerTool('vessel-by-id', {
+        title: 'Vessel by ID',
+        description: 'Retrieve one or more vessels by their GFW vessel IDs. Returns the same metadata as vessel-search, including a mapUrl for each vessel. Use when you already know the vessel ID(s) and want to fetch their full profile.',
+        inputSchema: {
+            ids: zod_1.z
+                .array(zod_1.z.string().min(1))
+                .min(1)
+                .describe('List of GFW vessel IDs to look up.'),
+        },
+        outputSchema: {
+            total: 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 vesselById(params);
+            return (0, response_js_1.createToolResponse)(JSON.stringify(output, null, 2), output);
+        }
+        catch (err) {
+            return (0, response_js_1.createErrorResponse)(`Failed to fetch vessels: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}