@gaiventures/pilotfish-mcp-managed 0.1.20 → 0.1.22
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.
- package/README.md +174 -82
- package/cli.js +5 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,48 +2,48 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
|
|
4
4
|
|
|
5
|
-
Hand whole browser tasks to [pilotfish](https://pilotfish.gai.ventures) from any AI agent. Your agent says what
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
files.
|
|
5
|
+
Hand whole browser tasks to [pilotfish](https://pilotfish.gai.ventures) from any AI agent. Your agent says what it
|
|
6
|
+
wants done ("download last month's invoices from our AWS billing console", "pull the risk factors from Apple's latest
|
|
7
|
+
10-K on SEC EDGAR"). pilotfish does it in a cloud browser and returns the answer and any files.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
[MCP](https://modelcontextprotocol.io) client.
|
|
9
|
+
It works with Claude Code, Claude.ai, Claude Desktop, Codex CLI, Cursor, VS Code and any other
|
|
10
|
+
[MCP](https://modelcontextprotocol.io) client. Clients that take a URL connect to `https://pilotfish-be.gai.ventures/mcp`
|
|
11
|
+
directly. This package is a small relay for clients that can only start a local (stdio) server.
|
|
12
12
|
|
|
13
|
-
> **You need a pilotfish account
|
|
14
|
-
>
|
|
15
|
-
>
|
|
13
|
+
> **You need a pilotfish account.** [Sign up with Google](https://pilotfish.gai.ventures/signup): you name your
|
|
14
|
+
> organization and become its admin. Or accept an invitation to join someone else's. Tasks are paid from the
|
|
15
|
+
> organization's credits.
|
|
16
|
+
|
|
17
|
+
Want a browser on your own computer for free, driven by your agent's own model, with no account? Use the open
|
|
18
|
+
[`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp) instead.
|
|
16
19
|
|
|
17
20
|
## Why managed
|
|
18
21
|
|
|
19
|
-
- **One call per task.** pilotfish plans and runs the task on its own models and checks the answer.
|
|
20
|
-
|
|
21
|
-
- **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs,
|
|
22
|
-
|
|
22
|
+
- **One call per task.** pilotfish plans and runs the task on its own models and checks the answer. Your agent spends
|
|
23
|
+
a tool call or two, not a context full of web pages.
|
|
24
|
+
- **Signed in as you.** Save a login once in the app and every task can use it. Sessions are kept between runs, and
|
|
25
|
+
two-factor codes, emailed codes and phone sign-in by code are handled.
|
|
23
26
|
- **Gets through where plain browsers stop.** Residential IPs in your country, stealth browsing and CAPTCHA solving
|
|
24
27
|
are on by default, with per-site settings. When something truly needs you, you get a link.
|
|
25
|
-
- **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps.
|
|
26
|
-
|
|
27
|
-
- **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
front, and your codes and passwords never pass through the agent.
|
|
31
|
-
|
|
32
|
-
Prefer to drive a browser on your own computer, for free? Use the local
|
|
33
|
-
[`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp). It needs no account.
|
|
28
|
+
- **Always on.** Tasks run in the cloud, so they carry on while your laptop sleeps. A follow-up picks up the same
|
|
29
|
+
session where it left off.
|
|
30
|
+
- **You can see everything.** Watch any task live or take control, replay it afterwards, and see what each one cost.
|
|
31
|
+
- **Safe with money and messages.** Payments, orders and messages wait for a person's yes unless the task's own words
|
|
32
|
+
allow them, and codes and passwords never pass through the agent.
|
|
34
33
|
|
|
35
34
|
## Get started
|
|
36
35
|
|
|
37
|
-
1. **Sign up
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
36
|
+
1. **Have an account.** [Sign up with Google](https://pilotfish.gai.ventures/signup) and name your organization (you
|
|
37
|
+
become its primary admin), or accept an emailed invitation to join an existing one as a member or an admin.
|
|
38
|
+
2. **Make sure the organization has credits.** Admins add them under **Usage → Credits** in the app (pay as you go,
|
|
39
|
+
from $10, with optional auto reload). Members run tasks on the organization's credits within any allowance an
|
|
40
|
+
admin sets for them.
|
|
41
|
+
3. **Connect your agent** (below). The simplest way is to sign in from your client, which then acts as you. Scripts,
|
|
42
|
+
servers and shared agents use one of the organization's API keys instead.
|
|
42
43
|
|
|
43
44
|
## Connect
|
|
44
45
|
|
|
45
|
-
The endpoint is `https://pilotfish-be.gai.ventures/mcp
|
|
46
|
-
no package. This package is a small relay for clients that can only start a local (stdio) server.
|
|
46
|
+
The endpoint is `https://pilotfish-be.gai.ventures/mcp` (Streamable HTTP).
|
|
47
47
|
|
|
48
48
|
### Claude Code
|
|
49
49
|
|
|
@@ -51,14 +51,15 @@ no package. This package is a small relay for clients that can only start a loca
|
|
|
51
51
|
claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
-
Claude Code
|
|
55
|
-
`--header "Authorization: Bearer pf_YOUR_KEY"
|
|
54
|
+
Then run `/mcp` in Claude Code, choose pilotfish and sign in with your pilotfish account. To use an API key instead,
|
|
55
|
+
add `--header "Authorization: Bearer pf_YOUR_KEY"` to the command.
|
|
56
56
|
|
|
57
57
|
### Claude.ai and Claude Desktop
|
|
58
58
|
|
|
59
|
-
Settings → Connectors → Add custom connector
|
|
59
|
+
**Settings → Connectors → Add custom connector**, paste `https://pilotfish-be.gai.ventures/mcp`, connect, and sign in.
|
|
60
|
+
No key is needed.
|
|
60
61
|
|
|
61
|
-
### Cursor, Windsurf
|
|
62
|
+
### Cursor, Windsurf and other clients that take a URL
|
|
62
63
|
|
|
63
64
|
```json
|
|
64
65
|
{
|
|
@@ -71,6 +72,24 @@ Settings → Connectors → Add custom connector → `https://pilotfish-be.gai.v
|
|
|
71
72
|
}
|
|
72
73
|
```
|
|
73
74
|
|
|
75
|
+
A client that supports MCP sign-in (OAuth) can leave out `headers` and sign in instead.
|
|
76
|
+
|
|
77
|
+
### VS Code
|
|
78
|
+
|
|
79
|
+
In `.vscode/mcp.json`:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"servers": {
|
|
84
|
+
"pilotfish": {
|
|
85
|
+
"type": "http",
|
|
86
|
+
"url": "https://pilotfish-be.gai.ventures/mcp",
|
|
87
|
+
"headers": { "Authorization": "Bearer pf_YOUR_KEY" }
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
74
93
|
### Codex CLI
|
|
75
94
|
|
|
76
95
|
In `~/.codex/config.toml`, through this package:
|
|
@@ -80,7 +99,7 @@ In `~/.codex/config.toml`, through this package:
|
|
|
80
99
|
command = "npx"
|
|
81
100
|
args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
|
|
82
101
|
env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
|
|
83
|
-
#
|
|
102
|
+
# A call returns within 120 s (the task carries on); Codex stops a call after 60 s by default.
|
|
84
103
|
tool_timeout_sec = 180
|
|
85
104
|
```
|
|
86
105
|
|
|
@@ -98,6 +117,10 @@ tool_timeout_sec = 180
|
|
|
98
117
|
}
|
|
99
118
|
```
|
|
100
119
|
|
|
120
|
+
The relay needs Node.js 22 or newer. It only forwards messages to the endpoint with your key; the browser runs in
|
|
121
|
+
pilotfish's cloud. On native Windows, if your client cannot start `npx`, use `"command": "cmd"` with
|
|
122
|
+
`"args": ["/c", "npx", "-y", "@gaiventures/pilotfish-mcp-managed"]`.
|
|
123
|
+
|
|
101
124
|
### Check a key
|
|
102
125
|
|
|
103
126
|
Prints the endpoint and the tools, or why the key was refused:
|
|
@@ -106,86 +129,155 @@ Prints the endpoint and the tools, or why the key was refused:
|
|
|
106
129
|
PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
|
|
107
130
|
```
|
|
108
131
|
|
|
109
|
-
In Windows PowerShell:
|
|
132
|
+
In Windows PowerShell:
|
|
110
133
|
|
|
111
|
-
|
|
134
|
+
```powershell
|
|
135
|
+
$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`--version` prints the relay's version.
|
|
139
|
+
|
|
140
|
+
## Signing in or an API key
|
|
141
|
+
|
|
142
|
+
| | **Signing in** (OAuth) | **An organization API key** (`pf_…`) |
|
|
143
|
+
| --- | --- | --- |
|
|
144
|
+
| Who it acts as | You | The organization, as no particular person |
|
|
145
|
+
| Who can use it | Only you | Anyone who has the key: keep it secret |
|
|
146
|
+
| Saved logins, site profiles, saved tasks | Yours | The organization's own set, apart from every person's |
|
|
147
|
+
| Tasks it sees | Your own; an admin can also open any of the organization's tasks by id | Only the tasks started with that key |
|
|
148
|
+
| Paid from | The organization's credits, within your allowance if you have one | The organization's credits, within the key's allowance if it has one |
|
|
149
|
+
| Who sets it up | You, from your client | The organization's admins, under **Org settings → API keys** |
|
|
150
|
+
|
|
151
|
+
**About keys.** Admins create, show again, copy, rotate and revoke keys under **Org settings → API keys**
|
|
152
|
+
(`https://pilotfish.gai.ventures/org?view=keys`). Rotating gives a new value under the same name, and the old one stops
|
|
153
|
+
working at once; rotate a key when someone who had it leaves. Each key has its own page with what it spent, its tasks
|
|
154
|
+
through the MCP and the API, and its sessions. An admin can give a key an allowance: a spending limit on the
|
|
155
|
+
organization's credits, with an optional automatic top-up.
|
|
156
|
+
|
|
157
|
+
## Organizations, members and money
|
|
158
|
+
|
|
159
|
+
Everyone is in one organization, and its credits pay for every task its people and its keys run.
|
|
160
|
+
|
|
161
|
+
| | **Primary admin** | **Admins** | **Members** |
|
|
162
|
+
| --- | --- | --- | --- |
|
|
163
|
+
| Run tasks, connect agents, save logins | Yes | Yes | Yes |
|
|
164
|
+
| Add credits, card, auto reload | Yes | Yes | No |
|
|
165
|
+
| Monthly limit and overage | Yes | Yes | No |
|
|
166
|
+
| Invite people, change roles, set allowances | Yes | Yes | No |
|
|
167
|
+
| Create and manage API keys | Yes | Yes | No |
|
|
168
|
+
| See everyone's tasks and spending | Yes | Yes | No: their own, and their allowance |
|
|
169
|
+
| Hand the primary admin role to someone else | Yes | No | No |
|
|
170
|
+
|
|
171
|
+
- **Allowances.** An admin may give a member (or a key) a spending limit on the organization's credits. No limit is
|
|
172
|
+
the default. When it is used up, new tasks are refused and running ones pause until an admin raises it.
|
|
173
|
+
- **The monthly limit.** An admin may set one for the whole organization. The primary admin is emailed at 80% and at
|
|
174
|
+
100%; at the limit, tasks pause and new ones are refused until an admin turns on overage or raises the limit.
|
|
175
|
+
- **One task at a time** per person and per key. Another task started meanwhile is refused until the first finishes
|
|
176
|
+
or is stopped.
|
|
177
|
+
- **Check-ins on long tasks.** A task that has spent a set amount ($1 by default) pauses and says what it found so
|
|
178
|
+
far; carry on with a follow-up, and it checks in again at the next step of that amount.
|
|
179
|
+
- **What your agent sees.** A refused task comes back with the reason and whom to ask:
|
|
180
|
+
|
|
181
|
+
| Reason | What it says | What to do |
|
|
182
|
+
| --- | --- | --- |
|
|
183
|
+
| `no_credits` | You're out of credits, or the balance is too low to start a task | An admin adds credits under **Usage → Credits**, or turns on auto reload |
|
|
184
|
+
| `allocation_used` | You've used your (or this key's) allowance, naming the admins to ask | An admin raises the allowance |
|
|
185
|
+
| `org_limit` | The organization has reached its monthly limit | An admin turns on overage or raises the limit |
|
|
186
|
+
| `one_session` | You already have a task running | Wait for it to finish, or stop it with `cancel_job` |
|
|
112
187
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
188
|
+
`get_usage` shows where you stand: for an admin, the organization's balance and auto reload; for a member, their
|
|
189
|
+
allowance and whether the organization's credits are fine, low or out; for everyone, this month's spending against
|
|
190
|
+
the monthly limit and spending by category and by model.
|
|
116
191
|
|
|
117
192
|
## Tools
|
|
118
193
|
|
|
119
194
|
| Tool | What it does |
|
|
120
195
|
| --- | --- |
|
|
121
|
-
| `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole task
|
|
122
|
-
| `get_job` `{id, wait_seconds?}` | A job's status, open question
|
|
123
|
-
| `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. |
|
|
124
|
-
| `list_jobs` `{status?, limit?}` | Your recent jobs with their cost; `[replay]` marks recorded ones. |
|
|
125
|
-
| `follow_up` `{id, text, model?, region?, files?, wait?}` | Carry on in the same session: same browser while it is kept, same sign-ins, what earlier turns found. `
|
|
126
|
-
| `rerun_job` `{id, wait?}` | Run the same task with the same settings
|
|
127
|
-
| `answer_job` `{id, question_id, answer}` | Answer a job's question: yes
|
|
128
|
-
| `message_job` `{id, text}` | Pass on what the person says while a job runs ("take the cheaper one", a detail it asked for). It reads the message before its next step
|
|
129
|
-
| `take_control` `{id}` / `hand_back` `{id}` | Pause a job and get a link to drive its browser yourself, then let it carry on from
|
|
196
|
+
| `browser_task` `{task, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?, max_steps?, pre_approved?, files?, wait?, wait_seconds?}` | Run a whole web task, however many sites and steps. Waits up to `wait_seconds` (default 120) and returns the result, or the job id if it is still running (it carries on; `get_job` waits again). `wait: false` returns the id at once. `model`: `gpt-6-luna` (the default), `auto` (Haiku does the task, Sonnet checks it), or one model for every step: `opus`, `sonnet`, `haiku`, `gpt-5-mini` or `gpt-5-nano`. `quality` (`auto`, `economy`, `accurate`) instead of one model; `model` wins. `region`: the country to browse from (`"us"`, `"in"`). `start_url`: the page to open first. `sites`: further sites whose saved logins the task may use. `login`: which of your accounts on those sites. `stealth` and `solve`: on by default; `false` turns them off for this run. `max_steps`: browser actions across the run. `pre_approved` (`{actions: [pay, delete, send, transfer, cancel], max_amount?, currency?}`): only with the person's say-so, final steps that run without asking. `files`: up to 10 attachments (`{name, type?, data}` in base64, 25 MB each). |
|
|
197
|
+
| `get_job` `{id, wait_seconds?}` | A job's status, its open question with the link to answer it, the result, the cost so far, the live-view link while it runs, and the session's files. `wait_seconds` waits for it to finish or need you first. |
|
|
198
|
+
| `get_file` `{id, file_id}` | One of the session's files, attached or downloaded. Up to 5 MB comes back in the result (an image as an image, text as text); larger files are linked in the app. |
|
|
199
|
+
| `list_jobs` `{status?, limit?}` | Your recent jobs, newest first, with their cost; `[replay]` marks recorded ones. `status`: `queued`, `running`, `needs_input`, `done`, `failed` or `cancelled`. |
|
|
200
|
+
| `follow_up` `{id, text, model?, region?, files?, wait?, wait_seconds?}` | Carry on in the same session: the same browser while it is kept, the same sign-ins, what earlier turns found ("now also…", "open the second one", "try again with…"). `model` changes this turn's model (`auto` routes again). `region` runs the turn from another country, in a new browser session there. |
|
|
201
|
+
| `rerun_job` `{id, wait?, wait_seconds?}` | Run the same task again with the same settings, as a new job. |
|
|
202
|
+
| `answer_job` `{id, question_id, answer}` | Answer a job's question: `yes`, `no`, `done` (handled in the browser), `cancel`, or text. The id is in the job's `Question …` line, which also says what answer it takes. Codes and passwords go on the answer page, never here. |
|
|
203
|
+
| `message_job` `{id, text}` | Pass on what the person says while a job runs ("take the cheaper one", a detail it asked for), in their words. It reads the message before its next step, and the person's newest words win over the task; sent while the job waits on a question, it answers it. |
|
|
204
|
+
| `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 where you left it. |
|
|
130
205
|
| `cancel_job` `{id}` | Stop a job. Cancelling a tool call that is waiting on a job stops the job too. |
|
|
131
|
-
| `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). |
|
|
132
|
-
| `list_saved_tasks` | Your saved tasks,
|
|
133
|
-
| `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run a saved task, with optional changes for this run only. |
|
|
134
|
-
| `save_task` `{name, task? \| from_job?,
|
|
135
|
-
| `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task
|
|
206
|
+
| `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) when one was recorded. |
|
|
207
|
+
| `list_saved_tasks` | Your saved tasks: id, name, settings, how often and when they last ran, and what their last run needed. |
|
|
208
|
+
| `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?, wait_seconds?}` | Run a saved task with its saved settings, with optional changes for this run only. |
|
|
209
|
+
| `save_task` `{name, task? \| from_job?, start_url?, region?, sites?, login?, stealth?, solve?, model?, quality?}` | Save a task to run again here or in the app: give the task and settings, or `from_job` to save a job's task with the settings it ran with. |
|
|
210
|
+
| `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task, change its task, or change only the settings given. |
|
|
136
211
|
| `delete_saved_task` `{id}` | Delete a saved task. Its past runs stay in your history. |
|
|
137
|
-
| `delete_session` `{id}` | Delete a session from your history: it no longer shows or opens anywhere; its record and cost are kept for billing. Logins, saved tasks and spending stay. |
|
|
138
|
-
| `list_logins` | Sites
|
|
139
|
-
| `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings: residential IP (auto
|
|
140
|
-
| `get_usage` `{days?}` | Your
|
|
212
|
+
| `delete_session` `{id}` | Delete a session from your history: it no longer shows or opens anywhere; its record and cost are kept for billing. Logins, saved tasks and spending stay. Only with the person's say-so. |
|
|
213
|
+
| `list_logins` | Sites with saved logins: which accounts, whether a password and authenticator key are stored, what recent runs met there. Never a password or code. Logins are added in the app. |
|
|
214
|
+
| `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` | Your sites and their settings, and change one site's: residential IP (`auto`, `always` or `never`), stealth browsing, CAPTCHA solving. A change applies to every later task on that site. |
|
|
215
|
+
| `get_usage` `{days?}` | Your organization's credits as your role sees them (an admin: its balance and auto reload; a member: whether it is fine, low, out or at its limit), what is left of your allowance (or the key's), this month's spending against the organization's monthly limit, and the last `days` (default 30) of spending by category (model, residential IP, browser, CAPTCHA) and by model. |
|
|
216
|
+
|
|
217
|
+
## What a job returns
|
|
218
|
+
|
|
219
|
+
A finished job starts with `SUCCESS`, `PARTLY DONE` or `NOT DONE`. One that did not fully pass lists what of the task
|
|
220
|
+
is done, what is not (each with its evidence) and why it stopped. A job still running says `Still running after
|
|
221
|
+
120 s; the job carries on`, and your agent waits again with `get_job`. A job that needs a person shows the question,
|
|
222
|
+
a `Question <id>` line saying how to answer it, and the answer link.
|
|
223
|
+
|
|
224
|
+
## Whole tasks or steps?
|
|
225
|
+
|
|
226
|
+
Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return flight
|
|
227
|
+
on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy order and add it
|
|
228
|
+
to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the start, carries what
|
|
229
|
+
each site gives to the next and checks the end result. Split it yourself only where a step is not browser work (your
|
|
230
|
+
own code, files, an API) or needs your own decision between steps; then send each browser step with the values it
|
|
231
|
+
needs written in, or use `follow_up` to stay in the same browser and sign-ins. Say in the task what may be completed
|
|
232
|
+
without asking ("pay with my saved card", "go ahead and submit"); anything else that is final waits for a yes.
|
|
141
233
|
|
|
142
234
|
## Tasks that name no site
|
|
143
235
|
|
|
144
236
|
Send them as they are: "the best free resource to learn linear algebra", "research Postgres vs MySQL for a startup".
|
|
145
|
-
pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with
|
|
146
|
-
|
|
147
|
-
|
|
237
|
+
pilotfish searches the web first and answers from what it read, every fact linked to its page, in seconds and with no
|
|
238
|
+
browser. When the answer needs a site (a fare for a date, a table to book, your own account), the browser starts on
|
|
239
|
+
the site the search found; a price or availability for particular dates is always read on the site itself.
|
|
148
240
|
|
|
149
241
|
## When the person says more mid-task
|
|
150
242
|
|
|
151
243
|
Your agent reads what the person types only between tool calls, so `browser_task`, `follow_up` and `get_job` return
|
|
152
244
|
within two minutes by default while the task carries on. Anything the person says meanwhile (a correction, a detail,
|
|
153
245
|
the answer to the task's question) goes to the task with `message_job`, in their words, and the agent keeps waiting
|
|
154
|
-
with `get_job`.
|
|
155
|
-
|
|
156
|
-
## Whole tasks or steps?
|
|
157
|
-
|
|
158
|
-
Send the whole web task in one `browser_task`, however many sites and steps it has: "find the cheapest return
|
|
159
|
-
flight on MakeMyTrip, then book a hotel near the beach for those dates on Booking.com", "read my last Swiggy
|
|
160
|
-
order and add it to my Splitwise group". pilotfish splits it into parts, asks for every sign-in it needs at the
|
|
161
|
-
start, carries what each site gives to the next (the flight's dates into the hotel search) and checks the end
|
|
162
|
-
result. Split it yourself only where a step is not browser work (your own code, files, an API) or needs your own
|
|
163
|
-
decision between steps; then send each browser step as its own `browser_task` with the values it needs written
|
|
164
|
-
in, or use `follow_up` to stay in the same browser and sign-ins. Say what may be completed without asking ("pay
|
|
165
|
-
with my saved card", "go ahead and submit"); anything else that is final waits for your yes.
|
|
246
|
+
with `get_job`.
|
|
166
247
|
|
|
167
|
-
## When a job needs
|
|
248
|
+
## When a job needs a person
|
|
168
249
|
|
|
169
|
-
A one-time code, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that
|
|
170
|
-
pilotfish's answer page
|
|
171
|
-
browser live and lets
|
|
250
|
+
A one-time code with no saved source, a CAPTCHA it could not clear, a sign-in or a payment to approve: clients that
|
|
251
|
+
support it open pilotfish's answer page, and other clients get the link in the tool result. The answer page shows the
|
|
252
|
+
browser live and lets the person take over, so they can type a code or sign in right there. Codes and passwords never
|
|
253
|
+
pass through the agent.
|
|
172
254
|
|
|
173
255
|
## Pricing
|
|
174
256
|
|
|
175
|
-
Pay as you go from prepaid credit:
|
|
176
|
-
price plus 20%, and CAPTCHAs per solve. Each task shows its
|
|
177
|
-
[pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume
|
|
178
|
-
[talk to us](https://pilotfish.gai.ventures/contact).
|
|
257
|
+
Pay as you go from the organization's prepaid credit: browser time at $0.02 per browser-hour (billed in whole minutes),
|
|
258
|
+
residential traffic at $4 per GB, models at their token price plus 20%, and CAPTCHAs per solve. Each task shows its
|
|
259
|
+
cost as it runs. Full prices: [pilotfish.gai.ventures/pricing](https://pilotfish.gai.ventures/pricing). For volume
|
|
260
|
+
pricing or your own proxies, [talk to us](https://pilotfish.gai.ventures/contact).
|
|
179
261
|
|
|
180
262
|
## Settings
|
|
181
263
|
|
|
182
|
-
Only for this package. Clients that connect to the URL need none.
|
|
264
|
+
Only for this package (the relay). Clients that connect to the URL need none.
|
|
183
265
|
|
|
184
266
|
| Variable | Default | Meaning |
|
|
185
267
|
| --- | --- | --- |
|
|
186
|
-
| `PILOTFISH_KEY` | |
|
|
268
|
+
| `PILOTFISH_KEY` | | One of your organization's API keys (`pf_…`). Required. |
|
|
187
269
|
| `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API, or its `/mcp` URL. |
|
|
188
270
|
|
|
271
|
+
## Troubleshooting
|
|
272
|
+
|
|
273
|
+
- **401 Unauthorized:** the key was revoked or rotated, or your organization was deleted. Ask an admin for a current
|
|
274
|
+
key (**Org settings → API keys**), or sign in from your client instead.
|
|
275
|
+
- **Codex stops the call after a minute:** keep `tool_timeout_sec = 180` as above; the task itself carries on.
|
|
276
|
+
- **`npx` fails, or the relay won't start:** check `node --version` is 22 or newer; on Windows, start it through
|
|
277
|
+
`cmd /c` as above.
|
|
278
|
+
- **A task is refused:** the reason and whom to ask are in the result; the table under "Organizations, members and
|
|
279
|
+
money" above lists each one.
|
|
280
|
+
|
|
189
281
|
## License
|
|
190
282
|
|
|
191
283
|
This relay is MIT licensed. The pilotfish service is covered by its
|
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.
|
|
13
|
+
var VERSION = true ? "0.1.22" : "0.0.0-dev";
|
|
14
14
|
|
|
15
15
|
// packages/mcp-managed/dist/bridge.js
|
|
16
16
|
var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
|
|
@@ -23,9 +23,9 @@ function endpointOf(url = DEFAULT_URL) {
|
|
|
23
23
|
function checkKey(key) {
|
|
24
24
|
const k = (key ?? "").trim();
|
|
25
25
|
if (!k)
|
|
26
|
-
throw new Error("PILOTFISH_KEY is not set:
|
|
26
|
+
throw new Error("PILOTFISH_KEY is not set: use one of your organization's API keys (an admin makes them in the pilotfish app: Org settings \u2192 API keys).");
|
|
27
27
|
if (!/^pf_[A-Za-z0-9_-]{16,}$/.test(k))
|
|
28
|
-
throw new Error("PILOTFISH_KEY does not look like a pilotfish
|
|
28
|
+
throw new Error("PILOTFISH_KEY does not look like a pilotfish API key (pf_...). Copy it again from Org settings \u2192 API keys.");
|
|
29
29
|
return k;
|
|
30
30
|
}
|
|
31
31
|
function remoteTransport(o) {
|
|
@@ -34,7 +34,7 @@ function remoteTransport(o) {
|
|
|
34
34
|
function explain(e) {
|
|
35
35
|
const m = e instanceof Error ? e.message : String(e);
|
|
36
36
|
if (/\b401\b|unauthori[sz]ed/i.test(m))
|
|
37
|
-
return "pilotfish refused the MCP key (revoked, mistyped, or
|
|
37
|
+
return "pilotfish refused the MCP key (revoked, rotated, mistyped, or its organization was deleted). Ask an admin of your organization for a current one (Org settings \u2192 API keys).";
|
|
38
38
|
if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT/i.test(m))
|
|
39
39
|
return `Cannot reach pilotfish (${m}). Check PILOTFISH_URL and your connection.`;
|
|
40
40
|
return `pilotfish: ${m}`;
|
|
@@ -97,7 +97,7 @@ replays) as an MCP server over stdio.
|
|
|
97
97
|
pilotfish-mcp-managed --version print the version
|
|
98
98
|
|
|
99
99
|
Environment:
|
|
100
|
-
PILOTFISH_KEY your
|
|
100
|
+
PILOTFISH_KEY one of your organization's API keys (pf_...): pilotfish app \u2192 Org settings \u2192 API keys
|
|
101
101
|
PILOTFISH_URL the pilotfish API (default ${DEFAULT_URL})`;
|
|
102
102
|
async function main() {
|
|
103
103
|
const { values } = parseArgs({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gaiventures/pilotfish-mcp-managed",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.22",
|
|
4
4
|
"description": "Whole browser tasks done in pilotfish's cloud for any MCP agent, signed in with your saved logins. mcprush.com-37c48d491684ec6011385ea5",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|