---
slug: "ariedotme-pi-firecrawl-web"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ariedotme/pi-firecrawl-web@main/README.md"
repo: "https://github.com/ariedotme/pi-firecrawl-web"
source_file: "README.md"
branch: "main"
---
# pi-firecrawl-web

A small Pi TypeScript extension that registers LLM-callable web tools powered only by [Firecrawl](https://firecrawl.dev):

- `web_search` — search the web with Firecrawl Search.
- `fetch_content` — scrape and clean one URL with Firecrawl Scrape.
- `extract_structured` — extract structured JSON from one or more URLs with Firecrawl Extract.

It validates URL protocols, avoids logging secrets, caps search defaults for agent-friendly credit usage, and returns human-readable text plus structured `details`.

## Install locally

```bash
npm install
pi -e ./index.ts
```

## Install as a Pi package

If published to npm:

```bash
pi install npm:pi-firecrawl-web
```

## Configure Firecrawl

### Firecrawl Cloud

For Firecrawl Cloud, leave `FIRECRAWL_BASE_URL` unset and provide an API key:

```bash
export FIRECRAWL_API_KEY=***
```

### Firecrawl self-hosted without authentication

Point the extension at your server and omit the key:

```bash
export FIRECRAWL_BASE_URL=http://localhost:3002
unset FIRECRAWL_API_KEY
```

No `Authorization` header is sent when `FIRECRAWL_API_KEY` is absent.

### Firecrawl self-hosted with authentication

Set both variables:

```bash
export FIRECRAWL_BASE_URL=https://firecrawl.example.com
export FIRECRAWL_API_KEY=***
```

When the key is present, the SDK sends `Authorization: Bearer <key>`.

You may also configure the extension directly:

```json
{
  "firecrawlBaseUrl": "https://firecrawl.example.com",
  "firecrawlApiKey": "fc-..."
}
```

The extension never hardcodes or prints the API key. API keys are optional for self-hosted Firecrawl deployments that do not require authentication.

## Slash command

```text
/firecrawl-status
```

Shows the base URL, whether authentication is configured, and which tools were registered, without revealing the key.

## Usage examples

```js
web_search({ query: "latest React compiler docs", limit: 5 })

web_search({ query: "OpenAI reasoning models", includeContent: true })

fetch_content({ url: "https://docs.firecrawl.dev", formats: ["markdown"] })

extract_structured({
  urls: ["https://example.com"],
  prompt: "Extract pricing plans",
  schema: {
    type: "object",
    properties: {
      plans: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            price: { type: "string" },
            features: { type: "array", items: { type: "string" } }
          }
        }
      }
    }
  }
})
```

## Tool notes

### `web_search`

Parameters include `query`, `limit` (default 5, max 20), `sources`, `categories`, domain filters, country/location, and optional scraped content (`markdown` or `summary`). Results are normalized as `query`, `web`, `news`, and `images` in `details.normalized`.

### `fetch_content`

Supports `markdown`, `summary`, `html`, `rawHtml`, `links`, `images`, `screenshot`, `json`, `question`, and `highlights`. Visible output is truncated when large, but `json` output is returned compactly without cutting through the JSON text.

### `extract_structured`

Requires either `prompt` or `schema`. Supports multiple HTTP/HTTPS URLs, optional web search, sources, safe scrape options, and wildcard warnings because `/*` can consume many credits.

## Development

```bash
npm install
npm run typecheck
npm test
```

Manual local load:

```bash
pi -e ./index.ts
```

If `FIRECRAWL_API_KEY` is unavailable, run the mock tests; they validate URL/domain guards, response formatting, and friendly missing-key behavior without calling Firecrawl.