@gaiventures/pilotfish-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gAI Ventures
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# pilotfish MCP
 
-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.
+A real Chromium on your own machine for any [MCP](https://modelcontextprotocol.io) agent: Claude Code, OpenAI
+Codex CLI, Cursor, Claude Desktop, VS Code, or your own client. **No account and no API key.** Your agent's own
+model reads each page and decides every step; pilotfish carries out the action, checks it, and reports what
+changed.
+
+- **Ref-based tools that prove each action.** `browser_click {ref: "e12"}` refuses (obscured, stale, not
+  visible) rather than clicking the wrong thing, and every action returns evidence of what changed.
+- **Cheap to read.** Compact snapshots of the visible screen, only the lines that changed when the agent has
+  seen the page a moment ago, and `browser_query` for just the values it needs (read-only JavaScript).
+- **People stay in the loop.** A sign-in, a one-time code or a CAPTCHA comes back as `NEEDS A PERSON`: you do
+  it in the browser window, the agent calls `browser_resume` and carries on. Nothing tries to get past it.
+- **Secrets never reach the model.** Values in `PILOTFISH_SECRETS` are typed as `{{name}}` placeholders and
+  masked in every result.
+- **Local.** A fresh browser on your machine and your own IP; nothing is kept when it closes. Cookie banners
+  are rejected and ads and trackers blocked before the agent sees the page.
+
+## Requirements
+
+- Node.js 22 or newer
+- Google Chrome (or another Chromium browser such as Microsoft Edge or Chromium). Set `PILOTFISH_CHROME` to use
+  a specific one.
+
+## Setup
+
+**Claude Code**
+
+```sh
+claude mcp add pilotfish -- npx -y @gaiventures/pilotfish-mcp
+```
+
+On native Windows (not WSL): `claude mcp add pilotfish -- cmd /c npx -y @gaiventures/pilotfish-mcp`.
+Settings go before the `--` as `-e NAME=value`, e.g. `-e PILOTFISH_HEADLESS=1`.
+
+**OpenAI Codex CLI** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.pilotfish]
+command = "npx"
+args = ["-y", "@gaiventures/pilotfish-mcp"]
+# browser_resume waits up to 300 s for you; Codex's default per-call limit is 60 s.
+tool_timeout_sec = 330
+# Optional settings:
+# env = { PILOTFISH_HEADLESS = "1", PILOTFISH_ALLOWED_HOSTS = "example.com,*.example.com" }
+```
+
+**Cursor, Claude Desktop, Windsurf and other MCP clients** (Cursor: `~/.cursor/mcp.json` or `.cursor/mcp.json`;
+Claude Desktop: `claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "pilotfish": {
+      "command": "npx",
+      "args": ["-y", "@gaiventures/pilotfish-mcp"],
+      "env": {
+        "PILOTFISH_SECRETS": "{\"shop_password\": {\"value\": \"...\", \"allowedHosts\": [\"shop.example.com\"]}}"
+      }
+    }
+  }
+}
+```
+
+`env` is optional; leave it out when you set nothing. To pin a version, use `@gaiventures/pilotfish-mcp@0.1.0`.
+
+The browser opens in a window of its own on your desktop, where you sign in or solve a CAPTCHA when a page
+needs a person (`PILOTFISH_HEADLESS=1` hides it; on a Linux machine with no display it is hidden already).
+
+**Streamable HTTP** (one browser shared by every client that connects; binds to 127.0.0.1):
+
+```sh
+npx -y @gaiventures/pilotfish-mcp --http --port 8931     # http://127.0.0.1:8931/mcp
+claude mcp add --transport http pilotfish http://127.0.0.1:8931/mcp
+```
+
+Clients that take a URL instead of a command (`"url": "http://127.0.0.1:8931/mcp"`) connect the same way. A
+loopback server answers only loopback `Host` headers (DNS rebinding). Set `PILOTFISH_MCP_TOKEN` to require
+`Authorization: Bearer <token>`; serving on any other address needs it.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `browser_navigate` `{url, snapshot?}` | Open an http(s) URL. Returns evidence and the visible screen as a snapshot, with counts of what is above and below. `snapshot: false` leaves the screen out (what happened and the counts only): only for a page the same reply reads with `browser_query` and the agent will not act on. |
+| `browser_snapshot` `{whole_page?}` | The page as a compact tree with refs (`[e12]<button>Search`): three screens around the viewport, or everything with `whole_page`. Each word once: no closing tags, an element's text not repeated on the lines under it, link targets as paths, no generated ids; every word and ref is kept. |
+| `browser_click` `{ref}` | Click by ref; refuses (obscured, stale, not visible) rather than clicking the wrong thing. |
+| `browser_type` `{ref, text, submit?}` | Replace a field's text; `{{name}}` placeholders type configured secrets. |
+| `browser_select` `{ref, values}` | Pick `<select>` option(s) by label or value. |
+| `browser_press` `{key}` | A key or shortcut (`Enter`, `Escape`, `Control+a`). |
+| `browser_scroll` `{direction}` | Scroll about one screen; returns the screen it shows. |
+| `browser_actions` `{actions}` | Up to 10 steps in one call (`click`, `type`, `select`, `press`, `scroll`, `wait` by ref), e.g. a form's fields then submit; each goes through the same checks as its own tool. Stops at the first that fails or after one that moves the page to another address. |
+| `browser_query` `{expression}` | Read just the values you need with a read-only JavaScript expression (JSON, at most 4,000 characters): a results list, prices, counts. It runs in a world of its own where clicks, typing, submits and network writes are refused. The cheapest way to read. |
+| `browser_find` `{query}` | Refs of the elements on the whole page that match the words, best first; partial matches are marked. Several targets can be separated by commas. |
+| `browser_get_text` `{max_chars?, selector?}` | Readable text of the whole page (PDFs too), or of the first element matching `selector` (`main`, `#results`), secrets masked, up to `max_chars` (default 20,000). |
+| `browser_screenshot` `{}` | JPEG of the viewport (off when secrets are configured: the image could show them). |
+| `browser_wait` `{seconds}` | Wait 0.5–10 s, then return what changed. Actions already wait for the requests they start. |
+| `browser_resume` `{timeout_s?}` | After a result said NEEDS A PERSON and you were asked: waits (default 300 s) until the page has moved on, then returns it. |
+| `browser_tabs` `{switch_to?}` | List open tabs; `switch_to: "t2"` makes another tab current. |
+| `browser_close` `{}` | Close the browser; the next call starts a fresh one. Not needed at the end of a task: the browser closes when the client disconnects. |
+
+**Each screen once.** The agent's model keeps every result in its context, and a new token costs it far more than
+one it re-reads (a prompt-cache write against a read). So an action on a page the agent was shown a few results back
+(at most 8) returns only the lines that changed (`CHANGES ONLY since the page snapshot N browser results back`), each
+under its unchanged parent line marked `~ `, with what is gone listed by ref. Refs are stable across snapshots, so the
+lines not repeated still work; a change of more than half of the screen gets the whole screen, and
+`browser_snapshot` always does.
+
+**Pages only a person can pass.** After every acting tool the page is classified. A sign-in with no credentials, a
+one-time code or 2FA prompt, a device approval, a sign-in link, a passkey, 3-D Secure or a CAPTCHA adds a
+`NEEDS A PERSON (…)` block to the result: what the page needs, and that you should do it in the pilotfish browser
+window; the agent then calls `browser_resume`. Nothing tries to get past it (no passwords or codes it was not given,
+no CAPTCHA solving). A client that supports elicitation asks you itself and the call goes on when you are done. A
+browser check that clears by itself is waited out first (up to 12 s). `BLOCKED:` (the site refused this browser) and
+`STOP:` (a never-automate site's bot check) mean nobody can fix it from the window.
+
+**Confirmations.** Irreversible-looking actions (pay, place an order, send, delete) need your yes. A client with
+elicitation asks you; without it such actions are refused with that reason, never read as a "no".
+
+## Settings
+
+All optional. No API key is read: the server works the same with none set.
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `PILOTFISH_HEADLESS` | `0` where a window can be shown (Windows, macOS, Linux with a display), else `1` | `1` hides the browser window; sign-ins and CAPTCHAs then cannot be done by hand. |
+| `PILOTFISH_ALLOWED_HOSTS` | any public host | Comma-separated hostname globs (`example.com,*.example.com`) the browser may visit and act on. |
+| `PILOTFISH_ALLOW_PRIVATE` | `0` | `1` allows localhost and private networks (development). |
+| `PILOTFISH_SECRETS` | | JSON: `{"name": "value"}` or `{"name": {"value"?, "totp"?, "allowedHosts"?}}`, typed as `{{name}}`; a `totp` seed (base32) types the current 2FA code. Values never reach a model, a result or an error message. |
+| `PILOTFISH_INTERVENTION_TIMEOUT_MS` | `180000` | How long a call waits for your answer to a question asked in the client. |
+| `PILOTFISH_ALLOW_SCREENSHOTS` | on without secrets | `1` allows screenshots even with secrets configured. |
+| `PILOTFISH_CHROME` | auto-detect | The browser executable. |
+| `PILOTFISH_MCP_TOKEN` | | HTTP mode: the required bearer token. |
+
+## What it connects to
+
+Only the sites your agent opens, and the public ad-block lists (EasyList, EasyPrivacy, uBlock Origin filters),
+fetched about once a week and cached in `~/.pilotfish/adblock`. No telemetry, no pilotfish servers, no model
+providers.
+
+For saved logins, sessions you can come back to, a cloud browser and whole tasks run for you, see the hosted
+pilotfish app: https://pilotfish.gai.ventures (and its MCP,
+[`@gaiventures/pilotfish-mcp-managed`](https://www.npmjs.com/package/@gaiventures/pilotfish-mcp-managed)).
+
+## License
+
+MIT