@globalfishingwatch/mcp 0.0.2 → 0.0.4

package/README.md

@@ -2,10 +2,15 @@
 
 Access [Global Fishing Watch](https://globalfishingwatch.org) data from any MCP-compatible AI assistant or directly from the terminal. Search vessels, retrieve fishing and port-visit events, look up Marine Protected Areas, Exclusive Economic Zones and RFMOs, calculate fishing activity hours within any region, and compute aggregate event statistics.
 
+This package can be used in two modes:
+
+- **MCP server** — connect any MCP-compatible AI assistant (Claude, Cursor, Windsurf, VS Code…) to GFW data
+- **CLI** — query GFW data directly from the terminal
+
 ## Requirements
 
 - Node.js 18+
-- A [GFW API key](https://globalfishingwatch.org/our-apis/)
+- A [GFW API key](https://globalfishingwatch.org/our-apis/) — if not yet available, request one at https://globalfishingwatch.org/our-apis/tokens
 
 ---
 
@@ -142,6 +147,18 @@ npm install && npm run build
 
 Then replace `npx -y gfw-mcp-js` with `node /absolute/path/to/gfw-mcp/dist/bin.js` in any config above.
 
+### Available MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `vessel-search` | Search vessels by name, MMSI, IMO, callsign, flag, or gear type |
+| `vessel-by-id` | Fetch full vessel profile(s) by GFW vessel ID(s); returns metadata and a map URL |
+| `vessel-events` | Retrieve fishing, encounter, port visit, or loitering events; filter by vessel, region, date, confidence, and encounter type |
+| `events-stats` | Compute aggregate statistics (total events, unique vessels, flag breakdown) over a date range, optionally filtered by region and grouped by flag or gear type |
+| `region-id-lookup` | Resolve MPA, EEZ, or RFMO names to canonical region IDs |
+| `region-geometry` | Get the URL to fetch the GeoJSON geometry of a specific MPA, EEZ, or RFMO |
+| `vessel-report` | Calculate fishing or presence hours in a region (MPA, EEZ, RFMO) with optional flag, gear type, vessel type, and speed filters; supports groupBy flag/geartype |
+
 ---
 
 ## CLI
@@ -188,6 +205,22 @@ GFW_TOKEN=your_key npx gfw-mcp-js vessel-search --name "Maria"
 
 Search vessels by name, MMSI, IMO, callsign, flag, or activity date range.
 
+```bash
+npx gfw-mcp-js vessel-search [--name <name>] [--mmsi <mmsi>] [--imo <imo>]
+  [--callsign <cs>] [--flag <ISO3>] [--active-from <YYYY-MM-DD>]
+  [--active-to <YYYY-MM-DD>] [--limit <n>]
+```
+
+At least one filter must be provided.
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--mmsi` | 9-digit string |
+| `--imo` | 7-digit string |
+| `--flag` | ISO 3166-1 alpha-3 code (e.g. `ESP`, `CHN`, `USA`) |
+| `--active-from` / `--active-to` | `YYYY-MM-DD` |
+| `--limit` | 1–50 (default 10) |
+
 ```bash
 npx gfw-mcp-js vessel-search --name "Maria" --flag CHN
 npx gfw-mcp-js vessel-search --mmsi 123456789
@@ -198,6 +231,10 @@ npx gfw-mcp-js vessel-search --flag ESP --active-from 2024-01-01 --active-to 202
 
 Fetch full vessel profile(s) by GFW vessel ID.
 
+```bash
+npx gfw-mcp-js vessel-by-id --ids <id> [<id2> ...]
+```
+
 ```bash
 npx gfw-mcp-js vessel-by-id --ids abc123
 npx gfw-mcp-js vessel-by-id --ids abc123 def456 ghi789
@@ -207,6 +244,24 @@ npx gfw-mcp-js vessel-by-id --ids abc123 def456 ghi789
 
 Retrieve fishing, encounter, port visit, or loitering events.
 
+```bash
+npx gfw-mcp-js vessel-events --event-type <type>
+  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>
+  [--vessel-id <id>] [--limit <n>] [--offset <n>]
+  [--confidence <2|3|4> ...]          # port_visit only
+  [--encounter-types <type> ...]      # encounter only
+  [--region-type <MPA|EEZ|RFMO>] [--region-id <id>]
+```
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--event-type` | `fishing` \| `encounter` \| `port_visit` \| `loitering` |
+| `--start-date` / `--end-date` | `YYYY-MM-DD` |
+| `--limit` | 1–100 (default 20) |
+| `--confidence` | `2`, `3`, `4` (one or more; port_visit only; default `4`) |
+| `--encounter-types` | `CARRIER-FISHING` \| `CARRIER-BUNKER` \| `FISHING-BUNKER` \| `FISHING-FISHING` \| `SUPPORT-FISHING` (encounter only; default `CARRIER-FISHING SUPPORT-FISHING`) |
+| `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
+
 ```bash
 npx gfw-mcp-js vessel-events --event-type fishing --start-date 2024-01-01 --end-date 2024-06-01
 npx gfw-mcp-js vessel-events --event-type port_visit --vessel-id abc123 --start-date 2024-01-01 --end-date 2024-12-31
@@ -218,6 +273,23 @@ npx gfw-mcp-js vessel-events --event-type fishing --region-type EEZ --region-id
 
 Compute aggregate event statistics over a date range.
 
+```bash
+npx gfw-mcp-js events-stats --event-type <type>
+  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>
+  [--group-by <FLAG|GEARTYPE>]
+  [--region-type <MPA|EEZ|RFMO>] [--region-id <id>]
+  [--confidence <levels> ...] [--encounter-types <types> ...]
+```
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--event-type` | `fishing` \| `encounter` \| `port_visit` \| `loitering` |
+| `--start-date` / `--end-date` | `YYYY-MM-DD` |
+| `--group-by` | `FLAG` \| `GEARTYPE` (default `FLAG`) |
+| `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
+| `--confidence` | `2`, `3`, `4` (one or more; port_visit only; default `4`) |
+| `--encounter-types` | `CARRIER-FISHING` \| `CARRIER-BUNKER` \| `FISHING-BUNKER` \| `FISHING-FISHING` \| `SUPPORT-FISHING` (encounter only; default `CARRIER-FISHING SUPPORT-FISHING`) |
+
 ```bash
 npx gfw-mcp-js events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31
 npx gfw-mcp-js events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31 --group-by GEARTYPE
@@ -228,6 +300,17 @@ npx gfw-mcp-js events-stats --event-type encounter --start-date 2024-01-01 --end
 
 Resolve an MPA, EEZ, or RFMO name to its canonical ID.
 
+```bash
+npx gfw-mcp-js region-id-lookup --region-type <MPA|EEZ|RFMO> --query <name> [--limit <n>]
+```
+
+Use this before `vessel-report` or `vessel-events` when you only know the human-readable name of a region.
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
+| `--limit` | 1–20 (default 5) |
+
 ```bash
 npx gfw-mcp-js region-id-lookup --region-type MPA --query "Galapagos"
 npx gfw-mcp-js region-id-lookup --region-type EEZ --query "Patagonia" --limit 10
@@ -236,7 +319,15 @@ npx gfw-mcp-js region-id-lookup --region-type RFMO --query "WCPFC"
 
 #### `region-geometry`
 
-Get the GeoJSON URL for a specific region.
+Get the GeoJSON URL for a specific region (no API token required).
+
+```bash
+npx gfw-mcp-js region-geometry --region-type <MPA|EEZ|RFMO> --id <id>
+```
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
 
 ```bash
 npx gfw-mcp-js region-geometry --region-type EEZ --id 8386
@@ -245,7 +336,31 @@ npx gfw-mcp-js region-geometry --region-type MPA --id 12345
 
 #### `vessel-report`
 
-Calculate fishing or presence hours inside a region.
+Calculate fishing or presence hours inside a region. Date range must not exceed 1 year.
+
+> **Important:** This command must never be run in parallel. If multiple reports are needed, run them sequentially — one at a time, waiting for each to complete before starting the next.
+
+```bash
+npx gfw-mcp-js vessel-report --region-type <MPA|EEZ|RFMO> --region-id <id>
+  --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>
+  [--type <FISHING|PRESENCE>]
+  [--flags <ISO3> ...]
+  [--geartypes <type> ...]    # FISHING only
+  [--vessel-types <type> ...] # PRESENCE only
+  [--speeds <range> ...]      # PRESENCE only
+  [--group-by <VESSEL_ID|FLAG|GEARTYPE|FLAGANDGEARTYPE>]
+```
+
+| Parameter | Format / values |
+|-----------|----------------|
+| `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
+| `--start-date` / `--end-date` | `YYYY-MM-DD` (max range: 1 year) |
+| `--type` | `FISHING` (default) \| `PRESENCE` |
+| `--flags` | ISO 3166-1 alpha-3 codes (e.g. `ESP`, `CHN`); up to 10 |
+| `--geartypes` | `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` (FISHING only) |
+| `--vessel-types` | `carrier` \| `seismic_vessel` \| `passenger` \| `other` \| `support` \| `bunker` \| `gear` \| `cargo` \| `fishing` \| `discrepancy` (PRESENCE only) |
+| `--speeds` | `2-4` \| `4-6` \| `6-10` \| `10-15` \| `15-25` \| `>25` (PRESENCE only) |
+| `--group-by` | `VESSEL_ID` (default) \| `FLAG` \| `GEARTYPE` \| `FLAGANDGEARTYPE` (`GEARTYPE`/`FLAGANDGEARTYPE` only valid with `--type FISHING`) |
 
 ```bash
 npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31
@@ -265,20 +380,6 @@ npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 202
 
 ---
 
-## Available tools
-
-| Tool | Description |
-|------|-------------|
-| `vessel-search` | Search vessels by name, MMSI, IMO, callsign, flag, or gear type |
-| `vessel-by-id` | Fetch full vessel profile(s) by GFW vessel ID(s); returns metadata and a map URL |
-| `vessel-events` | Retrieve fishing, encounter, port visit, or loitering events; filter by vessel, region, date, confidence, and encounter type |
-| `events-stats` | Compute aggregate statistics (total events, unique vessels, flag breakdown) over a date range, optionally filtered by region and grouped by flag or gear type |
-| `region-id-lookup` | Resolve MPA, EEZ, or RFMO names to canonical region IDs |
-| `region-geometry` | Get the URL to fetch the GeoJSON geometry of a specific MPA, EEZ, or RFMO |
-| `vessel-report` | Calculate fishing or presence hours in a region (MPA, EEZ, RFMO) with optional flag, gear type, vessel type, and speed filters; supports groupBy flag/geartype |
-
----
-
 ## Environment variables
 
 | Variable | Default | Description |

package/dist/cli/auth.js

@@ -43,7 +43,7 @@ function resolveToken() {
 async function authLogin() {
     const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
     const token = await new Promise((resolve) => {
-        rl.question('Enter your GFW API token: ', (answer) => {
+        rl.question('Get your token at: https://globalfishingwatch.org/our-apis/tokens\nEnter your GFW API token: ', (answer) => {
             rl.close();
             resolve(answer.trim());
         });

package/dist/cli/index.js

@@ -13,34 +13,49 @@ const vessel_report_js_1 = require("../tools/vessel-report.js");
 function print(data) {
     console.log(JSON.stringify(data, null, 2));
 }
-function fail(message) {
-    console.error(`Error: ${message}`);
+function fail(message, stdout = 'error') {
+    if (stdout === 'error') {
+        console.error(`Error: ${message}`);
+    }
+    else {
+        console.log(`Error: ${message}`);
+    }
     process.exit(1);
 }
+const TOKEN_URL = 'https://globalfishingwatch.org/our-apis/tokens';
+const TOKEN_HINT = `\n  You need a GFW API token. Generate one at: ${TOKEN_URL}\n  Then run: gfw auth login`;
+function isAuthError(message) {
+    return /401|403|unauthorized|forbidden|no gfw api token/i.test(message);
+}
 async function run(fn) {
     try {
         // Inject token into env so gfwFetch picks it up
         process.env.API_KEY = (0, auth_js_1.resolveToken)();
         const result = await fn();
-        if (result && typeof result === 'object' && 'isError' in result && result.isError) {
-            fail(result.content?.[0]?.text ?? 'Unknown error');
+        if (result &&
+            typeof result === 'object' &&
+            'isError' in result &&
+            result.isError) {
+            const message = result.content?.[0]?.text ?? 'Unknown error';
+            fail(isAuthError(message) ? message + TOKEN_HINT : message);
         }
         print(result);
     }
     catch (err) {
-        fail(err instanceof Error ? err.message : String(err));
+        const message = err instanceof Error ? err.message : String(err);
+        fail(isAuthError(message) ? message + TOKEN_HINT : message, isAuthError(message) ? 'log' : 'error');
     }
 }
 const program = new commander_1.Command();
-program
-    .name('gfw')
-    .description('Global Fishing Watch CLI')
-    .version('1.0.0');
+program.name('gfw').description('Global Fishing Watch CLI').version('1.0.0');
 // ── auth ──────────────────────────────────────────────────────────────────────
 const auth = program.command('auth').description('Manage GFW API credentials');
 auth.command('login').description('Save a GFW API token').action(auth_js_1.authLogin);
 auth.command('logout').description('Remove stored token').action(auth_js_1.authLogout);
-auth.command('status').description('Show current token source').action(auth_js_1.authStatus);
+auth
+    .command('status')
+    .description('Show current token source')
+    .action(auth_js_1.authStatus);
 // ── vessel-search ─────────────────────────────────────────────────────────────
 program
     .command('vessel-search')
@@ -91,7 +106,9 @@ program
     limit: opts.limit,
     offset: opts.offset,
     confidence: opts.confidence?.length ? opts.confidence : undefined,
-    encounterTypes: opts.encounterTypes?.length ? opts.encounterTypes : undefined,
+    encounterTypes: opts.encounterTypes?.length
+        ? opts.encounterTypes
+        : undefined,
     regionType: opts.regionType,
     regionId: opts.regionId,
 })));
@@ -111,8 +128,12 @@ program
     eventType: opts.eventType,
     startDate: opts.startDate,
     endDate: opts.endDate,
-    confidence: opts.confidence?.length ? opts.confidence.map(Number) : undefined,
-    encounterTypes: opts.encounterTypes?.length ? opts.encounterTypes : undefined,
+    confidence: opts.confidence?.length
+        ? opts.confidence.map(Number)
+        : undefined,
+    encounterTypes: opts.encounterTypes?.length
+        ? opts.encounterTypes
+        : undefined,
     regionType: opts.regionType,
     regionId: opts.regionId,
     groupBy: opts.groupBy,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalfishingwatch/mcp",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "MCP server for Global Fishing Watch data — vessel search, events, fishing hours, and region lookups",
   "author": "Global Fishing Watch",
   "license": "Apache-2.0",