Review: agent-browser-plugin-firecrawl (full repo)

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: node --test

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.env
+.env.*
+*.log
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rakshith Ramprakash
+
+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.

README.md

@@ -0,0 +1,184 @@
+# agent-browser-plugin-firecrawl
+
+A [agent-browser](https://github.com/vercel-labs/agent-browser) plugin that integrates [Firecrawl](https://firecrawl.dev). It speaks the `agent-browser.plugin.v1` stdio protocol and exposes Firecrawl two ways:
+
+- **`browser.provider`** — launches a Firecrawl **cloud browser session** and returns its CDP WebSocket URL, so agent-browser drives Firecrawl's managed Chrome (proxies, anti-bot, persistent login profiles, live view). Firecrawl becomes a remote browser backend, peer to Browserbase/Browserless/Kernel.
+- **`command.run`** — calls Firecrawl's **scrape / search / crawl / map** endpoints directly, without launching a browser session.
+
+## Requirements
+
+- Node.js ≥ 18 (uses the built-in `fetch`).
+- A Firecrawl API key in the `FIRECRAWL_API_KEY` environment variable. Get one at [firecrawl.dev](https://www.firecrawl.dev/).
+
+> Never put the API key in `agent-browser.json` `args`. agent-browser reads it from the plugin's environment.
+
+## Install
+
+From GitHub (current):
+
+```bash
+agent-browser plugin add rakshith48/agent-browser-plugin-firecrawl
+```
+
+From npm (once published):
+
+```bash
+agent-browser plugin add agent-browser-plugin-firecrawl
+```
+
+`plugin add` runs the package once, reads its `plugin.manifest`, and writes the config to `./agent-browser.json` (use `--global` for `~/.agent-browser/config.json`). Verify:
+
+```bash
+agent-browser plugin list
+agent-browser plugin show firecrawl
+```
+
+## Use it
+
+### As a browser provider
+
+```bash
+export FIRECRAWL_API_KEY=fc-...
+agent-browser --provider firecrawl open https://example.com
+agent-browser snapshot
+agent-browser click @e2
+agent-browser close
+```
+
+agent-browser asks the plugin for a session (`POST /v2/browser`), connects to the returned `cdpUrl`, and drives it with its full command surface. On `close` (or a failed connect) the plugin deletes the session (`DELETE /v2/browser/{id}`).
+
+### As scrape/search/crawl/map commands
+
+```bash
+agent-browser plugin run firecrawl firecrawl.scrape --payload '{"url":"https://example.com","formats":["markdown"]}'
+agent-browser plugin run firecrawl firecrawl.search --payload '{"query":"firecrawl agent browser","limit":5}'
+agent-browser plugin run firecrawl firecrawl.crawl  --payload '{"url":"https://docs.example.com"}'
+agent-browser plugin run firecrawl firecrawl.map    --payload '{"url":"https://example.com"}'
+```
+
+The `--payload` JSON is forwarded as the request body to the matching Firecrawl `/v2` endpoint; the Firecrawl response is returned under `data`.
+
+## Configuration
+
+`plugin add` writes this for you, but you can edit `agent-browser.json` manually:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "firecrawl",
+      "command": "agent-browser-plugin-firecrawl",
+      "capabilities": [
+        "browser.provider",
+        "command.run",
+        "firecrawl.scrape",
+        "firecrawl.search",
+        "firecrawl.crawl",
+        "firecrawl.map"
+      ]
+    }
+  ]
+}
+```
+
+> When added from GitHub, `plugin add` instead writes `"command": "npx"` with `"args": ["-y", "github:rakshith48/agent-browser-plugin-firecrawl"]`. The npm-installed form above uses the global `bin`.
+
+### Environment variables
+
+The plugin reuses Firecrawl's standard env vars — the **same ones the Firecrawl CLI and SDK use** — so if Firecrawl is already set up in your shell, the plugin works with no extra config.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `FIRECRAWL_API_KEY` | yes\* | — | Firecrawl API key (`fc-...`). Authenticates the plugin to the Firecrawl API. |
+| `FIRECRAWL_API_URL` | no | `https://api.firecrawl.dev` | Override for self-hosted Firecrawl (no key required for local instances). |
+| `FIRECRAWL_PROFILE_NAME` | no | — | Persistent browser profile to load (cookies/localStorage/login state). |
+| `FIRECRAWL_PROFILE_SAVE_CHANGES` | no | `true` | Save browser state back to the profile on close. Set `false`/`0` for read-only. |
+
+\* Not required when `FIRECRAWL_API_URL` points at a self-hosted instance.
+
+### Two auth layers
+
+- **API auth (plugin → Firecrawl):** the `FIRECRAWL_API_KEY` env var — same convention as the built-in Browserbase/Browserless/Kernel providers.
+- **Browser auth (session → target site):** Firecrawl **persistent profiles**. Set `FIRECRAWL_PROFILE_NAME` (or pass `profile` in the launch request) to log in once and reuse the session:
+
+  ```bash
+  # First run: log in, state is saved to the profile
+  FIRECRAWL_PROFILE_NAME=my-app agent-browser --provider firecrawl open https://app.example.com/login
+  # ... drive the login with agent-browser, then close ...
+
+  # Later runs: already authenticated
+  FIRECRAWL_PROFILE_NAME=my-app FIRECRAWL_PROFILE_SAVE_CHANGES=false \
+    agent-browser --provider firecrawl open https://app.example.com/dashboard
+  ```
+
+### Browser session options
+
+The `browser.launch` request forwards these fields (when present) to `POST /v2/browser`: `ttl`, `activityTtl`, `streamWebView`, and `profile` (`{ name, saveChanges }`). If the request has no `profile`, the `FIRECRAWL_PROFILE_NAME` env var is used.
+
+## Policy gating
+
+Each capability is a policy action `plugin:firecrawl:<capability>`:
+
+```bash
+agent-browser --confirm-actions plugin:firecrawl:browser.provider --provider firecrawl open https://example.com
+```
+
+## Develop & test
+
+### Unit tests (no API key, no network)
+
+Hermetic tests spawn the bin and mock the Firecrawl API on localhost — they cover the protocol paths and the `browser.launch` request mapping:
+
+```bash
+npm test          # node --test
+```
+
+Quick manual checks:
+
+```bash
+npm run manifest  # prints the plugin manifest
+echo '{"protocol":"agent-browser.plugin.v1","type":"firecrawl.scrape","capability":"command.run","request":{"url":"https://example.com","formats":["markdown"]}}' \
+  | FIRECRAWL_API_KEY=fc-... node bin/plugin.js
+```
+
+### End-to-end (real Firecrawl + agent-browser)
+
+```bash
+# 0. prerequisites
+npm install -g agent-browser
+export FIRECRAWL_API_KEY=fc-...
+
+# 1. install + inspect the plugin
+agent-browser plugin add rakshith48/agent-browser-plugin-firecrawl
+agent-browser plugin list
+agent-browser plugin show firecrawl
+
+# 2. browser.provider — drive Firecrawl's cloud browser
+agent-browser --provider firecrawl open https://example.com
+agent-browser get title
+agent-browser snapshot -i          # note the @e refs, then click one
+agent-browser click @e2
+agent-browser get url              # should have navigated
+agent-browser close
+
+# 3. command.run — scrape / search / crawl / map
+agent-browser plugin run firecrawl firecrawl.scrape --payload '{"url":"https://example.com","formats":["markdown"]}'
+agent-browser plugin run firecrawl firecrawl.search --payload '{"query":"firecrawl","limit":3}'
+
+# 4. persistent profile — log in once, reuse
+FIRECRAWL_PROFILE_NAME=my-app agent-browser --provider firecrawl open https://app.example.com/login
+# ...drive the login with snapshot/click/fill, then close to save state...
+agent-browser close
+FIRECRAWL_PROFILE_NAME=my-app FIRECRAWL_PROFILE_SAVE_CHANGES=false \
+  agent-browser --provider firecrawl open https://app.example.com/dashboard
+agent-browser close
+
+# 5. confirm no sessions leaked
+curl -s "https://api.firecrawl.dev/v2/browser?status=active" -H "Authorization: Bearer $FIRECRAWL_API_KEY"
+```
+
+> `snapshot` refs (`@e1`, `@e2`, …) are assigned per snapshot — always take a fresh snapshot in the current session before clicking a ref.
+
+## License
+
+MIT