@globalfishingwatch/mcp 0.0.5 → 0.0.7

package/README.md

@@ -1,4 +1,4 @@
-# gfw-mcp-js
+# @globalfishingwatch/mcp
 
 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.
 
@@ -19,10 +19,20 @@ This package can be used in two modes:
 ### Quick start (no install)
 
 ```bash
-npx gfw-mcp-js mcp
+GFW_TOKEN=your_gfw_api_key_here npx @globalfishingwatch/mcp mcp
 ```
 
-Set your API key via the `GFW_TOKEN` environment variable (or `API_KEY` for compatibility).
+`mcp` is a subcommand of the CLI that starts the MCP stdio server.
+
+### Authentication
+
+The MCP server resolves the API token in this order:
+
+1. `GFW_TOKEN` environment variable
+2. `API_KEY` environment variable (compatibility alias)
+3. `~/.gfw/config.json` (saved via `gfw auth login`)
+
+If you have already run `gfw auth login` from the CLI, the MCP server will pick up the stored token automatically — no need to set environment variables in your client config.
 
 ### Client configuration
 
@@ -36,7 +46,7 @@ Set your API key via the `GFW_TOKEN` environment variable (or `API_KEY` for comp
   "mcpServers": {
     "gfw": {
       "command": "npx",
-      "args": ["-y", "gfw-mcp-js", "mcp"],
+      "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
       "env": {
         "GFW_TOKEN": "your_gfw_api_key_here"
       }
@@ -48,7 +58,7 @@ Set your API key via the `GFW_TOKEN` environment variable (or `API_KEY` for comp
 #### Claude Code
 
 ```bash
-claude mcp add gfw -- npx -y gfw-mcp-js mcp
+claude mcp add gfw -- npx -y @globalfishingwatch/mcp mcp
 export GFW_TOKEN=your_gfw_api_key_here
 ```
 
@@ -61,7 +71,7 @@ export GFW_TOKEN=your_gfw_api_key_here
   "mcpServers": {
     "gfw": {
       "command": "npx",
-      "args": ["-y", "gfw-mcp-js", "mcp"],
+      "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
       "env": { "GFW_TOKEN": "your_gfw_api_key_here" }
     }
   }
@@ -77,7 +87,7 @@ export GFW_TOKEN=your_gfw_api_key_here
   "mcpServers": {
     "gfw": {
       "command": "npx",
-      "args": ["-y", "gfw-mcp-js", "mcp"],
+      "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
       "env": { "GFW_TOKEN": "your_gfw_api_key_here" }
     }
   }
@@ -94,7 +104,7 @@ export GFW_TOKEN=your_gfw_api_key_here
     "gfw": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "gfw-mcp-js", "mcp"],
+      "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
       "env": { "GFW_TOKEN": "your_gfw_api_key_here" }
     }
   }
@@ -112,7 +122,7 @@ export GFW_TOKEN=your_gfw_api_key_here
       "servers": {
         "gfw": {
           "command": "npx",
-          "args": ["-y", "gfw-mcp-js", "mcp"],
+          "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
           "env": { "GFW_TOKEN": "your_gfw_api_key_here" }
         }
       }
@@ -130,7 +140,7 @@ export GFW_TOKEN=your_gfw_api_key_here
   "mcpServers": {
     "gfw": {
       "command": "npx",
-      "args": ["-y", "gfw-mcp-js", "mcp"],
+      "args": ["-y", "@globalfishingwatch/mcp", "mcp"],
       "env": { "GFW_TOKEN": "your_gfw_api_key_here" }
     }
   }
@@ -145,7 +155,7 @@ cd gfw-mcp
 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.
+Then replace `npx -y @globalfishingwatch/mcp` with `node /absolute/path/to/gfw-mcp/dist/bin.js` in any config above.
 
 ### Available MCP tools
 
@@ -167,11 +177,11 @@ Then replace `npx -y gfw-mcp-js` with `node /absolute/path/to/gfw-mcp/dist/bin.j
 
 ```bash
 # Run without installing
-npx gfw-mcp-js --help
+npx @globalfishingwatch/mcp --help
 
 # Or install globally
-npm install -g gfw-mcp-js
-gfw-mcp-js --help
+npm install -g @globalfishingwatch/mcp
+gfw-mcp --help
 ```
 
 ### Authentication
@@ -184,19 +194,19 @@ Token resolution order:
 
 ```bash
 # Save token interactively (stored in ~/.gfw/config.json)
-npx gfw-mcp-js auth login
+npx @globalfishingwatch/mcp auth login
 
 # Check which token source is active
-npx gfw-mcp-js auth status
+npx @globalfishingwatch/mcp auth status
 
 # Remove stored token
-npx gfw-mcp-js auth logout
+npx @globalfishingwatch/mcp auth logout
 ```
 
 Or pass the token inline for a single command:
 
 ```bash
-GFW_TOKEN=your_key npx gfw-mcp-js vessel-search --name "Maria"
+GFW_TOKEN=your_key npx @globalfishingwatch/mcp vessel-search --name "Maria"
 ```
 
 ### Commands
@@ -206,7 +216,7 @@ 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>]
+npx @globalfishingwatch/mcp vessel-search [--name <name>] [--mmsi <mmsi>] [--imo <imo>]
   [--callsign <cs>] [--flag <ISO3>] [--active-from <YYYY-MM-DD>]
   [--active-to <YYYY-MM-DD>] [--limit <n>]
 ```
@@ -222,9 +232,9 @@ At least one filter must be provided.
 | `--limit` | 1–50 (default 10) |
 
 ```bash
-npx gfw-mcp-js vessel-search --name "Maria" --flag CHN
-npx gfw-mcp-js vessel-search --mmsi 123456789
-npx gfw-mcp-js vessel-search --flag ESP --active-from 2024-01-01 --active-to 2024-12-31 --limit 20
+npx @globalfishingwatch/mcp vessel-search --name "Maria" --flag CHN
+npx @globalfishingwatch/mcp vessel-search --mmsi 123456789
+npx @globalfishingwatch/mcp vessel-search --flag ESP --active-from 2024-01-01 --active-to 2024-12-31 --limit 20
 ```
 
 #### `vessel-by-id`
@@ -232,12 +242,12 @@ 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> ...]
+npx @globalfishingwatch/mcp 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
+npx @globalfishingwatch/mcp vessel-by-id --ids abc123
+npx @globalfishingwatch/mcp vessel-by-id --ids abc123 def456 ghi789
 ```
 
 #### `vessel-events`
@@ -245,7 +255,7 @@ 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>
+npx @globalfishingwatch/mcp 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
@@ -263,10 +273,10 @@ npx gfw-mcp-js vessel-events --event-type <type>
 | `--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
-npx gfw-mcp-js vessel-events --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --encounter-types CARRIER-FISHING SUPPORT-FISHING
-npx gfw-mcp-js vessel-events --event-type fishing --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-06-01
+npx @globalfishingwatch/mcp vessel-events --event-type fishing --start-date 2024-01-01 --end-date 2024-06-01
+npx @globalfishingwatch/mcp vessel-events --event-type port_visit --vessel-id abc123 --start-date 2024-01-01 --end-date 2024-12-31
+npx @globalfishingwatch/mcp vessel-events --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --encounter-types CARRIER-FISHING SUPPORT-FISHING
+npx @globalfishingwatch/mcp vessel-events --event-type fishing --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-06-01
 ```
 
 #### `events-stats`
@@ -274,7 +284,7 @@ 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>
+npx @globalfishingwatch/mcp 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>]
@@ -291,9 +301,9 @@ npx gfw-mcp-js events-stats --event-type <type>
 | `--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
-npx gfw-mcp-js events-stats --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --region-type RFMO --region-id WCPFC
+npx @globalfishingwatch/mcp events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31
+npx @globalfishingwatch/mcp events-stats --event-type fishing --start-date 2024-01-01 --end-date 2024-12-31 --group-by GEARTYPE
+npx @globalfishingwatch/mcp events-stats --event-type encounter --start-date 2024-01-01 --end-date 2024-12-31 --region-type RFMO --region-id WCPFC
 ```
 
 #### `region-id-lookup`
@@ -301,7 +311,7 @@ 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>]
+npx @globalfishingwatch/mcp 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.
@@ -312,9 +322,9 @@ Use this before `vessel-report` or `vessel-events` when you only know the human-
 | `--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
-npx gfw-mcp-js region-id-lookup --region-type RFMO --query "WCPFC"
+npx @globalfishingwatch/mcp region-id-lookup --region-type MPA --query "Galapagos"
+npx @globalfishingwatch/mcp region-id-lookup --region-type EEZ --query "Patagonia" --limit 10
+npx @globalfishingwatch/mcp region-id-lookup --region-type RFMO --query "WCPFC"
 ```
 
 #### `region-geometry`
@@ -322,7 +332,7 @@ npx gfw-mcp-js region-id-lookup --region-type RFMO --query "WCPFC"
 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>
+npx @globalfishingwatch/mcp region-geometry --region-type <MPA|EEZ|RFMO> --id <id>
 ```
 
 | Parameter | Format / values |
@@ -330,8 +340,8 @@ npx gfw-mcp-js region-geometry --region-type <MPA|EEZ|RFMO> --id <id>
 | `--region-type` | `MPA` \| `EEZ` \| `RFMO` |
 
 ```bash
-npx gfw-mcp-js region-geometry --region-type EEZ --id 8386
-npx gfw-mcp-js region-geometry --region-type MPA --id 12345
+npx @globalfishingwatch/mcp region-geometry --region-type EEZ --id 8386
+npx @globalfishingwatch/mcp region-geometry --region-type MPA --id 12345
 ```
 
 #### `vessel-report`
@@ -341,7 +351,7 @@ Calculate fishing or presence hours inside a region. Date range must not exceed
 > **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>
+npx @globalfishingwatch/mcp 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> ...]
@@ -363,10 +373,10 @@ npx gfw-mcp-js vessel-report --region-type <MPA|EEZ|RFMO> --region-id <id>
 | `--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
-npx gfw-mcp-js vessel-report --region-type MPA --region-id 12345 --start-date 2024-01-01 --end-date 2024-12-31 --flags CHN ESP
-npx gfw-mcp-js vessel-report --region-type RFMO --region-id WCPFC --start-date 2024-01-01 --end-date 2024-12-31 --type FISHING --group-by FLAG
-npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type PRESENCE --vessel-types fishing cargo
+npx @globalfishingwatch/mcp vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31
+npx @globalfishingwatch/mcp vessel-report --region-type MPA --region-id 12345 --start-date 2024-01-01 --end-date 2024-12-31 --flags CHN ESP
+npx @globalfishingwatch/mcp vessel-report --region-type RFMO --region-id WCPFC --start-date 2024-01-01 --end-date 2024-12-31 --type FISHING --group-by FLAG
+npx @globalfishingwatch/mcp vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 --type PRESENCE --vessel-types fishing cargo
 ```
 
 ### Output
@@ -374,8 +384,8 @@ npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 202
 All commands output JSON to stdout, ready to pipe to `jq`:
 
 ```bash
-npx gfw-mcp-js vessel-search --name "Maria" | jq '.results[].name'
-npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 | jq '.fishingHours'
+npx @globalfishingwatch/mcp vessel-search --name "Maria" | jq '.results[].name'
+npx @globalfishingwatch/mcp vessel-report --region-type EEZ --region-id 8386 --start-date 2024-01-01 --end-date 2024-12-31 | jq '.fishingHours'
 ```
 
 ---
@@ -394,11 +404,11 @@ npx gfw-mcp-js vessel-report --region-type EEZ --region-id 8386 --start-date 202
 ## Project structure
 
 ```
-bin.ts              # Dispatcher: routes to MCP server or CLI
-index.ts            # MCP server entry point (stdio transport)
+bin.ts              # Entry point: loads CLI (dist/bin.js registered as "mcp" binary)
+index.ts            # MCP server stdio setup (used by the `mcp` CLI command)
 mcp-server.ts       # McpServer creation and tool registration
 cli/
-  index.ts          # CLI entry point (commander)
+  index.ts          # CLI entry point (commander); includes the `mcp` subcommand
   auth.ts           # Token resolution and auth commands
 middleware/
   auth.ts           # Bearer / X-API-Key authentication middleware

package/dist/bin.js

@@ -1,19 +1,4 @@
 #!/usr/bin/env node
 "use strict";
-/**
- * Single entry point for the gfw-mcp-js package.
- *
- *   npx gfw-mcp-js mcp                        → start MCP stdio server
- *   npx gfw-mcp-js vessel-search --name Maria  → CLI one-shot
- *   npx gfw-mcp-js --help                      → CLI help
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-const [, , first] = process.argv;
-if (first === 'mcp') {
-    // Remove the 'mcp' argument so the MCP entry point sees a clean argv
-    process.argv.splice(2, 1);
-    import('./index.js').catch((err) => { console.error(err); process.exit(1); });
-}
-else {
-    import('./cli/index.js').catch((err) => { console.error(err); process.exit(1); });
-}
+require("./cli/index.js");

package/dist/cli/index.js

@@ -48,6 +48,18 @@ async function run(fn) {
 }
 const program = new commander_1.Command();
 program.name('gfw').description('Global Fishing Watch CLI').version('1.0.0');
+// ── mcp ───────────────────────────────────────────────────────────────────────
+program
+    .command('mcp')
+    .description('Start the GFW MCP stdio server')
+    .action(async () => {
+    const { createServer } = await import('../mcp-server.js');
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('GFW MCP Server running on stdio');
+});
 // ── 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);

package/dist/index.js

@@ -78,7 +78,7 @@ const server = (0, mcp_server_js_1.createServer)();
 async function main() {
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    console.error('Demo MCP Server running on stdio');
+    console.error('GFW MCP Server running on stdio');
 }
 main().catch((error) => {
     console.error('Fatal error in main():', error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalfishingwatch/mcp",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "MCP server for Global Fishing Watch data — vessel search, events, fishing hours, and region lookups",
   "author": "Global Fishing Watch",
   "license": "Apache-2.0",
@@ -14,9 +14,6 @@
     "ais"
   ],
   "main": "./dist/index.js",
-  "bin": {
-    "gfw-mcp": "./dist/bin.js"
-  },
   "files": [
     "dist/"
   ],