@gaiventures/pilotfish-mcp-managed 0.1.10 → 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +103 -84
  2. package/cli.js +1 -1
  3. package/package.json +6 -3
package/README.md CHANGED
@@ -1,80 +1,84 @@
1
1
  # pilotfish MCP (managed)
2
2
 
3
- > This package connects your agent to a pilotfish account: **[sign up](https://pilotfish.gai.ventures/signup)**
4
- > with Google, add credits, and connect. See [Getting started](#getting-started).
5
- >
6
- > No account is needed for [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp),
7
- > the open MCP that runs a browser on your own machine.
3
+ [![npm](https://img.shields.io/npm/v/@gaiventures/pilotfish-mcp-managed)](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
8
4
 
9
- Your [pilotfish](https://pilotfish.gai.ventures) account as an [MCP](https://modelcontextprotocol.io) server, for
10
- any agent: Claude Code, OpenAI Codex CLI, Cursor, Claude Desktop, VS Code, or your own client. Everything the
11
- pilotfish app does, as tools. Tasks run in pilotfish's cloud browser **as you**:
5
+ Hand whole browser tasks to [pilotfish](https://pilotfish.gai.ventures) from any AI agent. Your agent says what
6
+ it wants done ("find the cheapest flight to Lisbon on the 12th", "check my LinkedIn job matches"). pilotfish
7
+ does it in a cloud browser, signed in as you, and returns the answer.
12
8
 
13
- - your saved logins and site profiles (sign-ins persist across runs);
14
- - saved tasks, and sessions you can carry on with follow-ups;
15
- - residential IPs, stealth browsing and CAPTCHA handling, on by default with per-site settings;
16
- - live view and take control, replays, and spending.
9
+ Works with Claude Code, Claude.ai, Claude Desktop, Codex CLI, Cursor, VS Code and any other
10
+ [MCP](https://modelcontextprotocol.io) client.
17
11
 
18
- **Everything runs in pilotfish's cloud.** This package is only a small relay for agents that can start a
19
- **stdio** server and nothing else. It forwards MCP messages to pilotfish's hosted endpoint,
20
- `https://pilotfish-be.gai.ventures/mcp`, with your key. Agents that speak Streamable HTTP connect to that
21
- endpoint directly and need no package at all.
12
+ ## Why managed
22
13
 
23
- For a browser on your own machine with no account and no key, use
24
- [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp) instead.
14
+ - **One call per task.** pilotfish plans and runs the task on its own models and checks the answer.
15
+ Your agent spends a tool call or two, not a context full of web pages.
16
+ - **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs,
17
+ and two-factor codes, emailed codes and phone sign-in by code are handled.
18
+ - **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
19
+ are on by default, with per-site settings. When something truly needs you, you get a link.
20
+ - **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. Follow up on a session later
21
+ and it picks up where it left off.
22
+ - **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one
23
+ cost.
24
+ - **Safe with money and messages.** Payments, orders and messages wait for your approval unless you allow them up
25
+ front, and your codes and passwords never pass through the agent.
25
26
 
26
- ## Getting started
27
+ Prefer to drive a browser on your own computer, for free? Use the local
28
+ [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp). It needs no account.
27
29
 
28
- 1. **Sign up** at [pilotfish.gai.ventures/signup](https://pilotfish.gai.ventures/signup): agree to the terms and
29
- continue with Google.
30
- 2. **Add credits.** Pay as you go, from $10, under **Usage → Credits**. Tasks draw on them at the
31
- [published prices](https://pilotfish.gai.ventures/pricing), and each one shows its cost while it runs.
32
- 3. **Connect your agent.** Open **Connect an agent** in the app, then follow [Credentials](#credentials) and
33
- [Connect](#connect) below.
30
+ ## Get started
34
31
 
35
- Until you have an account, the endpoint and this package refuse your agent: there is no account or key to sign in
36
- with. For volume rates or your own proxies, [talk to sales](https://pilotfish.gai.ventures/contact) or write to
37
- [nitin@gai.ventures](mailto:nitin@gai.ventures).
38
-
39
- ## Credentials
40
-
41
- Once you're signed in, open **Connect an agent** in the pilotfish app
42
- (`https://pilotfish.gai.ventures/connect`):
43
-
44
- - **No key (OAuth):** Claude.ai, Claude Desktop and Claude Code sign in by themselves. Give them the endpoint
45
- URL; they open pilotfish's sign-in and a consent page.
46
- - **An MCP key (`pf_…`):** *Create key*. Each key can be shown again, copied, rotated or revoked there. Make one
47
- per agent. A key acts as you, and stops working if you leave the workspace.
32
+ 1. **Sign up** at [pilotfish.gai.ventures/signup](https://pilotfish.gai.ventures/signup) with your Google account.
33
+ 2. **Add credits.** Pay as you go, from $10, under **Usage → Credits**.
34
+ 3. **Connect your agent** with the steps below. Open **Connect an agent** in the app to sign in with OAuth or
35
+ create an MCP key.
48
36
 
49
37
  ## Connect
50
38
 
51
- **Claude Code** (with a key; drop `--header` to sign in with OAuth instead):
39
+ The endpoint is `https://pilotfish-be.gai.ventures/mcp`. Clients that take a URL connect to it directly and need
40
+ no package. This package is a small relay for clients that can only start a local (stdio) server.
41
+
42
+ ### Claude Code
52
43
 
53
44
  ```sh
54
- claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp --header "Authorization: Bearer pf_YOUR_KEY"
45
+ claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
55
46
  ```
56
47
 
57
- **Claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector →
58
- `https://pilotfish-be.gai.ventures/mcp` → sign in.
48
+ Claude Code opens pilotfish's sign-in the first time. To use a key instead, add
49
+ `--header "Authorization: Bearer pf_YOUR_KEY"`.
59
50
 
60
- **Cursor, Windsurf, VS Code and other clients that take a URL** (`mcp.json`):
51
+ ### Claude.ai and Claude Desktop
52
+
53
+ Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.ventures/mcp`, then sign in.
54
+
55
+ ### Cursor, Windsurf, VS Code and other clients that take a URL
61
56
 
62
57
  ```json
63
- { "mcpServers": { "pilotfish": { "url": "https://pilotfish-be.gai.ventures/mcp", "headers": { "Authorization": "Bearer pf_YOUR_KEY" } } } }
58
+ {
59
+ "mcpServers": {
60
+ "pilotfish": {
61
+ "url": "https://pilotfish-be.gai.ventures/mcp",
62
+ "headers": { "Authorization": "Bearer pf_YOUR_KEY" }
63
+ }
64
+ }
65
+ }
64
66
  ```
65
67
 
66
- **OpenAI Codex CLI** (`~/.codex/config.toml`), through this package:
68
+ ### Codex CLI
69
+
70
+ In `~/.codex/config.toml`, through this package:
67
71
 
68
72
  ```toml
69
73
  [mcp_servers.pilotfish]
70
74
  command = "npx"
71
75
  args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
72
76
  env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
73
- # browser_task waits up to 600 s for a result by default; Codex's default per-call limit is 60 s.
77
+ # browser_task waits up to 600 s for a result; Codex stops a call after 60 s by default.
74
78
  tool_timeout_sec = 660
75
79
  ```
76
80
 
77
- **Any stdio-only agent**, through this package:
81
+ ### Any client that starts a local server
78
82
 
79
83
  ```json
80
84
  {
@@ -88,55 +92,70 @@ tool_timeout_sec = 660
88
92
  }
89
93
  ```
90
94
 
91
- Check a key without an agent. It prints the endpoint and the tools, or why the key was refused:
95
+ ### Check a key
92
96
 
93
- ```sh
94
- PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check # macOS, Linux, Git Bash
95
- ```
97
+ Prints the endpoint and the tools, or why the key was refused:
96
98
 
97
- ```powershell
98
- $env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check # Windows PowerShell
99
+ ```sh
100
+ PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
99
101
  ```
100
102
 
101
- ## Settings
103
+ In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
102
104
 
103
- For this package (an agent that connects to the URL needs none of them).
105
+ ## MCP keys
104
106
 
105
- | Variable | Default | Meaning |
106
- | --- | --- | --- |
107
- | `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required for this package. |
108
- | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API (or its `/mcp` URL). |
107
+ Create keys under **Connect an agent** in the app (`https://pilotfish.gai.ventures/connect`). Make one per agent;
108
+ each can be shown again, copied, rotated or revoked there. A key acts as you and stops working if you leave your
109
+ organization. Clients that sign in with OAuth (Claude.ai, Claude Desktop, Claude Code) need no key.
109
110
 
110
111
  ## Tools
111
112
 
112
113
  | Tool | What it does |
113
114
  | --- | --- |
114
- | `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole task as you. Waits for the result (up to `wait_seconds`, default 600; the job carries on after) or, with `wait: false`, returns the job id at once. Stealth and CAPTCHA handling are on by default; `false` turns either off for the run. `model`: auto (Haiku does the task, Sonnet checks it), or opus / sonnet / haiku for every step. `files`: up to 10 attachments (`{name, type?, data}` base64, 25 MB each), as the app's Attach files. |
115
- | `get_job` `{id, wait_seconds?}` | Status, the open question and its answer link, result, cost so far (model, residential IP, browser, CAPTCHA), live-view link, session, and the session's files (attached and downloaded). Optionally waits for the job to end or need you. |
116
- | `get_file` `{id, file_id}` | One of the session's files: up to 5 MB comes back in the result (an image as an image, text as text, anything else embedded); larger ones are linked in the app. |
117
- | `list_jobs` `{status?, limit?}` | Your recent jobs with cost; `[replay]` marks recorded ones. |
118
- | `follow_up` `{id, text, model?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found. `model` picks this turn's model (omitted: the session's last pick). |
119
- | `rerun_job` `{id, wait?}` | The same task with the same settings, as a new job. |
120
- | `answer_job` `{id, question_id, answer}` | yes / no / done / cancel / text. Never codes or passwords: those go on the answer page. |
121
- | `message_job` `{id, text}` | Steer a running job ("use the cheaper one"); read before its next step. |
122
- | `take_control` `{id}` / `hand_back` `{id}` | Pause a running job and get a link to drive its browser yourself; then let it carry on from there. |
123
- | `cancel_job` `{id}` | Stop a job. Cancelling a waiting tool call cancels its job too. |
124
- | `get_replay` `{id}` | The job's step timeline with timings and obstacles, and a link to its replay video (MP4, valid 1 hour). |
125
- | `list_saved_tasks` | Your saved tasks: settings, runs, last run, what the last run needed. |
126
- | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run one, with optional tweaks for this run only. |
115
+ | `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole task as you. Waits for the result (up to `wait_seconds`, default 600; the task carries on after that), or with `wait: false` returns the job id at once. `model`: `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-6-luna`, `gpt-5-mini` or `gpt-5-nano`. `region`: the country to browse from. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
116
+ | `get_job` `{id, wait_seconds?}` | A job's status, open question and its answer link, result, cost so far, live-view link and files. Can wait for the job to finish or need you. |
117
+ | `get_file` `{id, file_id}` | One of the session's files, attached or downloaded. Up to 5 MB comes back in the result; larger files are linked. |
118
+ | `list_jobs` `{status?, limit?}` | Your recent jobs with their cost; `[replay]` marks recorded ones. |
119
+ | `follow_up` `{id, text, model?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found. |
120
+ | `rerun_job` `{id, wait?}` | Run the same task with the same settings again. |
121
+ | `answer_job` `{id, question_id, answer}` | Answer a job's question: yes, no, done, cancel or text. Codes and passwords go on the answer page, never here. |
122
+ | `message_job` `{id, text}` | Steer a running job ("take the cheaper one"). It reads the message before its next step. |
123
+ | `take_control` `{id}` / `hand_back` `{id}` | Pause a job and get a link to drive its browser yourself, then let it carry on from there. |
124
+ | `cancel_job` `{id}` | Stop a job. Cancelling a tool call that is waiting on a job stops the job too. |
125
+ | `get_replay` `{id}` | The job's steps with timings and what got in the way, and a link to its replay video (valid for an hour). |
126
+ | `list_saved_tasks` | Your saved tasks, their settings and how their last run went. |
127
+ | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run a saved task, with optional changes for this run only. |
127
128
  | `save_task` `{name, task? \| from_job?, …settings}` | Save a task, or a job's task with the settings it ran with. |
128
- | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task, change its task, or change only the settings given. |
129
- | `delete_saved_task` `{id}` | Delete a saved task (its runs stay in history). |
130
- | `delete_session` `{id}` | Delete a session from history: its turns, events, replay and files (logins, saved tasks and spending stay). |
131
- | `list_logins` | Sites with saved logins: accounts, whether a password / 2FA key is stored, OTP channel, per-site settings, what recent runs met. Never a value. Logins are added in the app. |
132
- | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Authorised sites; per-site residential IP (auto / always / never), stealth, CAPTCHA solving; what the server offers. |
133
- | `get_usage` `{days?}` | Your credit balance (and auto reload, when on); this month's spend against your limits; the period by category and by model. |
134
-
135
- When a job needs you (a code, a CAPTCHA it could not clear, a sign-in, approving a payment), a client with
136
- URL-mode elicitation opens pilotfish's answer page for you; other clients get the link in the tool result, with the
137
- job's watch-only live view. The answer page itself shows the live view with control, so a code, a sign-in or a
138
- CAPTCHA can be handled there. Codes and passwords never pass through the agent.
129
+ | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task or change its task or settings. |
130
+ | `delete_saved_task` `{id}` | Delete a saved task. Its past runs stay in your history. |
131
+ | `delete_session` `{id}` | Delete a session from your history: its turns, replay and files. Logins, saved tasks and spending stay. |
132
+ | `list_logins` | Sites you have saved logins for, with what is stored and each site's settings. Never a password or code. Logins are added in the app. |
133
+ | `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings: residential IP (auto, always or never), stealth and CAPTCHA solving. |
134
+ | `get_usage` `{days?}` | Your credit balance, this month's spending against your limits, and spending by category and model. |
135
+
136
+ ## When a job needs you
137
+
138
+ A one-time code, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that support it open
139
+ pilotfish's answer page for you, and other clients get the link in the tool result. The answer page shows the
140
+ browser live and lets you take over, so you can type a code or sign in right there.
141
+
142
+ ## Pricing
143
+
144
+ Pay as you go from prepaid credit: the browser by the minute, residential traffic by the GB, models at their token
145
+ price plus 20%, and CAPTCHAs per solve. Each task shows its cost as it runs. Full prices are on
146
+ [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume pricing or your own proxies,
147
+ [talk to us](https://pilotfish.gai.ventures/contact).
148
+
149
+ ## Settings
150
+
151
+ Only for this package. Clients that connect to the URL need none.
152
+
153
+ | Variable | Default | Meaning |
154
+ | --- | --- | --- |
155
+ | `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required. |
156
+ | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
139
157
 
140
158
  ## License
141
159
 
142
- MIT (this relay). The pilotfish service is subject to its own terms.
160
+ This relay is MIT licensed. The pilotfish service is covered by its
161
+ [terms](https://pilotfish.gai.ventures/terms).
package/cli.js CHANGED
@@ -10,7 +10,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
10
10
  import { isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
11
11
 
12
12
  // packages/mcp-managed/dist/version.js
13
- var VERSION = true ? "0.1.10" : "0.0.0-dev";
13
+ var VERSION = true ? "0.1.12" : "0.0.0-dev";
14
14
 
15
15
  // packages/mcp-managed/dist/bridge.js
16
16
  var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@gaiventures/pilotfish-mcp-managed",
3
- "version": "0.1.10",
4
- "description": "Your pilotfish account for any MCP agent: cloud browser tasks, saved logins, live view, replays.",
3
+ "version": "0.1.12",
4
+ "description": "Whole browser tasks done in pilotfish's cloud for any MCP agent, signed in with your saved logins.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
@@ -29,9 +29,12 @@
29
29
  "mcp",
30
30
  "mcp-server",
31
31
  "model-context-protocol",
32
+ "pilotfish",
32
33
  "browser-automation",
34
+ "browser-agent",
35
+ "ai-agent",
33
36
  "cloud-browser",
34
- "pilotfish",
37
+ "web-automation",
35
38
  "claude-code",
36
39
  "codex",
37
40
  "cursor"