@gaiventures/pilotfish-mcp-managed 0.0.0-stage → 0.1.1

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 (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +114 -2
  3. package/cli.js +133 -0
  4. package/package.json +41 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gAI Ventures
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,115 @@
1
- # Temporary Holding Version
1
+ # pilotfish MCP (managed)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Your [pilotfish](https://pilotfish.gai.ventures) account as an [MCP](https://modelcontextprotocol.io) server, for
4
+ any agent: Claude Code, OpenAI Codex CLI, Cursor, Claude Desktop, VS Code, or your own client. Everything the
5
+ pilotfish app does, as tools. Tasks run in pilotfish's cloud browser **as you**:
6
+
7
+ - your saved logins and site profiles (sign-ins persist across runs);
8
+ - saved tasks, and sessions you can carry on with follow-ups;
9
+ - residential IPs, stealth browsing and CAPTCHA handling, on by default with per-site settings;
10
+ - live view and take control, replays, and spending.
11
+
12
+ **Everything runs in pilotfish's cloud.** This package is only a small relay for agents that can start a
13
+ **stdio** server and nothing else. It forwards MCP messages to pilotfish's hosted endpoint,
14
+ `https://pilotfish-be.gai.ventures/mcp`, with your key. Agents that speak Streamable HTTP connect to that
15
+ endpoint directly and need no package at all.
16
+
17
+ For a browser on your own machine with no account and no key, use
18
+ [`@gaiventures/pilotfish-mcp`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp) instead.
19
+
20
+ ## Credentials
21
+
22
+ Sign in to the pilotfish app and open **Connect an agent** (`https://pilotfish.gai.ventures/#/connect`):
23
+
24
+ - **No key (OAuth):** Claude.ai, Claude Desktop and Claude Code sign in by themselves. Give them the endpoint
25
+ URL; they open pilotfish's sign-in and a consent page.
26
+ - **An MCP key (`pf_…`):** *Create key*. Each key can be shown again, copied, rotated or revoked there. Make one
27
+ per agent. A key acts as you, and stops working if you leave the workspace.
28
+
29
+ ## Connect
30
+
31
+ **Claude Code** (with a key; drop `--header` to sign in with OAuth instead):
32
+
33
+ ```sh
34
+ claude mcp add --transport http pilotfish https://pilotfish-be.gai.ventures/mcp --header "Authorization: Bearer pf_YOUR_KEY"
35
+ ```
36
+
37
+ **Claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector →
38
+ `https://pilotfish-be.gai.ventures/mcp` → sign in.
39
+
40
+ **Cursor, Windsurf, VS Code and other clients that take a URL** (`mcp.json`):
41
+
42
+ ```json
43
+ { "mcpServers": { "pilotfish": { "url": "https://pilotfish-be.gai.ventures/mcp", "headers": { "Authorization": "Bearer pf_YOUR_KEY" } } } }
44
+ ```
45
+
46
+ **OpenAI Codex CLI** (`~/.codex/config.toml`), through this package:
47
+
48
+ ```toml
49
+ [mcp_servers.pilotfish]
50
+ command = "npx"
51
+ args = ["-y", "@gaiventures/pilotfish-mcp-managed"]
52
+ env = { PILOTFISH_KEY = "pf_YOUR_KEY" }
53
+ # browser_task waits up to 600 s for a result by default; Codex's default per-call limit is 60 s.
54
+ tool_timeout_sec = 660
55
+ ```
56
+
57
+ **Any stdio-only agent**, through this package:
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "pilotfish": {
63
+ "command": "npx",
64
+ "args": ["-y", "@gaiventures/pilotfish-mcp-managed"],
65
+ "env": { "PILOTFISH_KEY": "pf_YOUR_KEY" }
66
+ }
67
+ }
68
+ }
69
+ ```
70
+
71
+ Check a key without an agent: `PILOTFISH_KEY=pf_... npx -y @gaiventures/pilotfish-mcp-managed --check` prints the
72
+ endpoint and the tools, or why the key was refused.
73
+
74
+ ## Settings
75
+
76
+ For this package (an agent that connects to the URL needs none of them).
77
+
78
+ | Variable | Default | Meaning |
79
+ | --- | --- | --- |
80
+ | `PILOTFISH_KEY` | | Your MCP key (`pf_…`). Required for this package. |
81
+ | `PILOTFISH_URL` | `https://pilotfish-be.gai.ventures` | The pilotfish API (or its `/mcp` URL). |
82
+
83
+ ## Tools
84
+
85
+ | Tool | What it does |
86
+ | --- | --- |
87
+ | `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. |
88
+ | `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. |
89
+ | `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. |
90
+ | `list_jobs` `{status?, limit?}` | Your recent jobs with cost; `[replay]` marks recorded ones. |
91
+ | `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). |
92
+ | `rerun_job` `{id, wait?}` | The same task with the same settings, as a new job. |
93
+ | `answer_job` `{id, question_id, answer}` | yes / no / done / cancel / text. Never codes or passwords: those go on the answer page. |
94
+ | `message_job` `{id, text}` | Steer a running job ("use the cheaper one"); read before its next step. |
95
+ | `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. |
96
+ | `cancel_job` `{id}` | Stop a job. Cancelling a waiting tool call cancels its job too. |
97
+ | `get_replay` `{id}` | The job's step timeline with timings and obstacles, and a link to its replay video (MP4, valid 1 hour). |
98
+ | `list_saved_tasks` | Your saved tasks: settings, runs, last run, what the last run needed. |
99
+ | `run_saved_task` `{id, extra_instructions?, start_url?, region?, sites?, stealth?, solve?, wait?}` | Run one, with optional tweaks for this run only. |
100
+ | `save_task` `{name, task? \| from_job?, …settings}` | Save a task, or a job's task with the settings it ran with. |
101
+ | `update_saved_task` `{id, name?, task?, …settings}` | Rename a saved task, change its task, or change only the settings given. |
102
+ | `delete_saved_task` `{id}` | Delete a saved task (its runs stay in history). |
103
+ | `delete_session` `{id}` | Delete a session from history: its turns, events, replay and files (logins, saved tasks and spending stay). |
104
+ | `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. |
105
+ | `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. |
106
+ | `get_usage` `{days?}` | This month's spend against your limits; the period by category and by model. |
107
+
108
+ When a job needs you (a code, a CAPTCHA it could not clear, a sign-in, approving a payment), a client with
109
+ URL-mode elicitation opens pilotfish's answer page for you; other clients get the link in the tool result, with the
110
+ job's watch-only live view. The answer page itself shows the live view with control, so a code, a sign-in or a
111
+ CAPTCHA can be handled there. Codes and passwords never pass through the agent.
112
+
113
+ ## License
114
+
115
+ MIT (this relay). The pilotfish service is subject to its own terms.
package/cli.js ADDED
@@ -0,0 +1,133 @@
1
+ #!/usr/bin/env node
2
+
3
+ // packages/mcp-managed/dist/cli.js
4
+ import { parseArgs } from "node:util";
5
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
6
+
7
+ // packages/mcp-managed/dist/bridge.js
8
+ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
9
+ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
10
+ import { isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
11
+ var DEFAULT_URL = "https://pilotfish-be.gai.ventures";
12
+ function endpointOf(url = DEFAULT_URL) {
13
+ const u = new URL(url);
14
+ if (!/\/mcp\/?$/.test(u.pathname))
15
+ u.pathname = `${u.pathname.replace(/\/$/, "")}/mcp`;
16
+ return u;
17
+ }
18
+ function checkKey(key) {
19
+ const k = (key ?? "").trim();
20
+ if (!k)
21
+ throw new Error("PILOTFISH_KEY is not set: create an MCP key in the pilotfish app (Settings \u2192 Connect an agent).");
22
+ if (!/^pf_[A-Za-z0-9_-]{16,}$/.test(k))
23
+ throw new Error("PILOTFISH_KEY does not look like a pilotfish MCP key (pf_...). Copy it again from Settings \u2192 Connect an agent.");
24
+ return k;
25
+ }
26
+ function remoteTransport(o) {
27
+ return new StreamableHTTPClientTransport(endpointOf(o.url), { requestInit: { headers: { authorization: `Bearer ${o.key}` } } });
28
+ }
29
+ function explain(e) {
30
+ const m = e instanceof Error ? e.message : String(e);
31
+ if (/\b401\b|unauthori[sz]ed/i.test(m))
32
+ return "pilotfish refused the MCP key (revoked, mistyped, or you left the workspace). Create a new one in the pilotfish app: Settings \u2192 Connect an agent.";
33
+ if (/fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT/i.test(m))
34
+ return `Cannot reach pilotfish (${m}). Check PILOTFISH_URL and your connection.`;
35
+ return `pilotfish: ${m}`;
36
+ }
37
+ async function relay(local, o) {
38
+ const remote = remoteTransport(o);
39
+ const initIds = /* @__PURE__ */ new Set();
40
+ let closed = false;
41
+ const close = async () => {
42
+ if (closed)
43
+ return;
44
+ closed = true;
45
+ await remote.terminateSession().catch(() => void 0);
46
+ await Promise.all([remote.close().catch(() => void 0), local.close().catch(() => void 0)]);
47
+ };
48
+ local.onmessage = (m) => {
49
+ if (isJSONRPCRequest(m) && m.method === "initialize")
50
+ initIds.add(m.id);
51
+ remote.send(m).catch((e) => {
52
+ o.log?.(explain(e));
53
+ if (isJSONRPCRequest(m))
54
+ void local.send({ jsonrpc: "2.0", id: m.id, error: { code: -32e3, message: explain(e) } }).catch(() => void 0);
55
+ });
56
+ };
57
+ remote.onmessage = (m) => {
58
+ if (isJSONRPCResultResponse(m) && initIds.delete(m.id)) {
59
+ const v = m.result.protocolVersion;
60
+ if (typeof v === "string")
61
+ remote.setProtocolVersion(v);
62
+ }
63
+ void local.send(m).catch((e) => o.log?.(`relay to client: ${e instanceof Error ? e.message : String(e)}`));
64
+ };
65
+ remote.onerror = (e) => o.log?.(explain(e));
66
+ local.onerror = (e) => o.log?.(`client transport: ${e.message}`);
67
+ local.onclose = () => void close();
68
+ remote.onclose = () => void close();
69
+ await remote.start();
70
+ await local.start();
71
+ return { close };
72
+ }
73
+ async function check(o) {
74
+ const client = new Client({ name: "pilotfish-mcp-managed-check", version: "0.0.1" });
75
+ try {
76
+ await client.connect(remoteTransport(o));
77
+ const tools = (await client.listTools()).tools.map((t) => t.name);
78
+ return { server: `${client.getServerVersion()?.name ?? "?"} ${client.getServerVersion()?.version ?? ""}`.trim(), tools };
79
+ } catch (e) {
80
+ throw new Error(explain(e));
81
+ } finally {
82
+ await client.close().catch(() => void 0);
83
+ }
84
+ }
85
+
86
+ // packages/mcp-managed/dist/cli.js
87
+ var USAGE = `pilotfish-mcp-managed \u2014 your pilotfish account (saved tasks, logins, cloud browser, stealth,
88
+ replays) as an MCP server over stdio.
89
+
90
+ pilotfish-mcp-managed relay stdio to pilotfish's hosted MCP endpoint
91
+ pilotfish-mcp-managed --check connect once with the key, list the tools, exit
92
+
93
+ Environment:
94
+ PILOTFISH_KEY your MCP key (pf_...): pilotfish app \u2192 Settings \u2192 Connect an agent
95
+ PILOTFISH_URL the pilotfish API (default ${DEFAULT_URL})`;
96
+ async function main() {
97
+ const { values } = parseArgs({ options: { check: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } } });
98
+ if (values.help)
99
+ return void process.stderr.write(`${USAGE}
100
+ `);
101
+ let key;
102
+ try {
103
+ key = checkKey(process.env["PILOTFISH_KEY"]);
104
+ } catch (e) {
105
+ process.stderr.write(`pilotfish-mcp-managed: ${e.message}
106
+ `);
107
+ process.exit(2);
108
+ }
109
+ const url = process.env["PILOTFISH_URL"]?.trim() || DEFAULT_URL;
110
+ const log = (m) => void process.stderr.write(`pilotfish-mcp-managed: ${m}
111
+ `);
112
+ if (values.check) {
113
+ try {
114
+ const r = await check({ url, key });
115
+ process.stderr.write(`OK: ${endpointOf(url).href} (${r.server}), ${r.tools.length} tools: ${r.tools.join(", ")}
116
+ `);
117
+ process.exit(0);
118
+ } catch (e) {
119
+ log(e.message);
120
+ process.exit(1);
121
+ }
122
+ }
123
+ const bridge = await relay(new StdioServerTransport(), { url, key, log });
124
+ const shutdown = () => void bridge.close().finally(() => process.exit(0));
125
+ process.stdin.on("end", shutdown);
126
+ process.on("SIGINT", shutdown);
127
+ process.on("SIGTERM", shutdown);
128
+ }
129
+ main().catch((e) => {
130
+ process.stderr.write(`pilotfish-mcp-managed: ${e instanceof Error ? e.stack ?? e.message : String(e)}
131
+ `);
132
+ process.exit(1);
133
+ });
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@gaiventures/pilotfish-mcp-managed",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Your pilotfish account for any MCP agent: tasks in pilotfish's cloud browser, saved logins, replays.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": {
8
+ "pilotfish-mcp-managed": "cli.js"
9
+ },
10
+ "files": [
11
+ "cli.js",
12
+ "README.md",
13
+ "LICENSE"
14
+ ],
15
+ "engines": {
16
+ "node": ">=22"
17
+ },
18
+ "dependencies": {
19
+ "@modelcontextprotocol/sdk": "^1.32.1"
20
+ },
21
+ "mcpName": "io.github.gAI-ventures/pilotfish-managed",
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "git+https://github.com/gAI-ventures/pilotfish.git",
25
+ "directory": "packages/mcp-managed"
26
+ },
27
+ "homepage": "https://pilotfish.gai.ventures",
28
+ "keywords": [
29
+ "mcp",
30
+ "mcp-server",
31
+ "model-context-protocol",
32
+ "browser-automation",
33
+ "cloud-browser",
34
+ "pilotfish",
35
+ "claude-code",
36
+ "codex",
37
+ "cursor"
38
+ ],
39
+ "publishConfig": {
40
+ "access": "public",
41
+ "provenance": false
42
+ }
43
+ }