@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.
- package/README.md +103 -84
- package/cli.js +1 -1
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,80 +1,84 @@
|
|
|
1
1
|
# pilotfish MCP (managed)
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)
|
|
8
4
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
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
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
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
|
|
45
|
+
claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp
|
|
55
46
|
```
|
|
56
47
|
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
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
|
-
{
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
95
|
+
### Check a key
|
|
92
96
|
|
|
93
|
-
|
|
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
|
-
```
|
|
98
|
-
|
|
99
|
+
```sh
|
|
100
|
+
PILOTFISH_KEY=pf_YOUR_KEY npx -y @gaiventures/pilotfish-mcp-managed --check
|
|
99
101
|
```
|
|
100
102
|
|
|
101
|
-
|
|
103
|
+
In Windows PowerShell: `$env:PILOTFISH_KEY = "pf_YOUR_KEY"; npx -y @gaiventures/pilotfish-mcp-managed --check`.
|
|
102
104
|
|
|
103
|
-
|
|
105
|
+
## MCP keys
|
|
104
106
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
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
|
|
115
|
-
| `get_job` `{id, wait_seconds?}` |
|
|
116
|
-
| `get_file` `{id, file_id}` | One of the session's files
|
|
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.
|
|
119
|
-
| `rerun_job` `{id, wait?}` |
|
|
120
|
-
| `answer_job` `{id, question_id, answer}` | yes
|
|
121
|
-
| `message_job` `{id, text}` | Steer a running job ("
|
|
122
|
-
| `take_control` `{id}` / `hand_back` `{id}` | Pause a
|
|
123
|
-
| `cancel_job` `{id}` | Stop a job. Cancelling a
|
|
124
|
-
| `get_replay` `{id}` | The job's
|
|
125
|
-
| `list_saved_tasks` | Your saved tasks
|
|
126
|
-
| `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run
|
|
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
|
|
129
|
-
| `delete_saved_task` `{id}` | Delete a saved task
|
|
130
|
-
| `delete_session` `{id}` | Delete a session from history: its turns,
|
|
131
|
-
| `list_logins` | Sites
|
|
132
|
-
| `get_settings` / `update_site_settings` `{site, residential?, stealth?, solve?}` |
|
|
133
|
-
| `get_usage` `{days?}` | Your credit balance
|
|
134
|
-
|
|
135
|
-
When a job needs you
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
|
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.
|
|
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.
|
|
4
|
-
"description": "
|
|
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
|
-
"
|
|
37
|
+
"web-automation",
|
|
35
38
|
"claude-code",
|
|
36
39
|
"codex",
|
|
37
40
|
"cursor"
|