* add query format support to scrape tool
* bump version to 3.12.0
* prefer markdown over query format in scrape tool description
MCP agents can read and reason over scraped content directly —
the query format is redundant when the agent already has the
scrape result. default guidance now recommends markdown.
Update package version to 3.11.0 and remove the asynchronous agent features from the server API. The firecrawl_agent and firecrawl_agent_status tool registrations (and their detailed usage/polling docs) were deleted from src/index.ts and the usage guidance was simplified to prefer firecrawl_map + scrape (use map when scrape fails). Consumers should stop calling the removed agent endpoints and migrate workflows to map+scrape or other supported tools.
Google Gemini's function calling API rejects tool schemas that use
anyOf alongside other fields. This replaces all z.union() usages with
flat parameter alternatives:
- formats: now a simple string enum array (added 'json' to the enum)
- jsonOptions: new param for JSON extraction prompt/schema
- screenshotOptions: new param for screenshot fullPage/quality/viewport
- parsers: now a simple string enum array
- pdfOptions: new param for PDF maxPages
- webhook (crawl): now a simple string, with separate webhookHeaders
Helper functions (buildFormatsArray, buildParsersArray, buildWebhook,
transformScrapeParams) reassemble the nested format the API expects
from the flat MCP params at execution time.
Closes#164
* init browser
* Bump firecrawl and update session API
Upgrade @mendable/firecrawl-js to 4.13.0-beta.3 and update the session API: rename TTL parameters (ttlTotal -> ttl, ttlWithoutActivity -> activityTtl), adjust documentation and zod schemas/types accordingly, and change the execute-language options by replacing 'js' with 'node' and adding 'bash' (including examples and types).
* Add npm tag logic; update browser execute docs
CI: Change publish workflow to run on pushes to main when package.json changes and keep manual dispatch. Add a step to determine npm tag (beta if version contains "beta", otherwise latest) and pass that tag to pnpm publish. Only run MCP publisher install/login/publish steps when the tag is "latest" to avoid publishing prereleases to the MCP registry.
Code: Update firecrawl_browser_execute docs and parameter ordering in src/index.ts. The description now recommends using bash agent-browser commands by default (with examples and command reference), provides a Python example for Playwright scripting, and adjusts the language enum/default ordering accordingly. These docs clarify usage and preferred workflows for browser automation.
* revert beta release ci back
* update readme
* Update package.json
---------
Co-authored-by: Nicolas <20311743+nickscamara@users.noreply.github.com>
- Enhanced map tool description to highlight its role in finding
specific page URLs when scrape returns empty results
- Added search parameter example showing the recommended workflow
- Removed waitFor from default scrape JSON example (it's optional,
only needed when JS rendering requires extra wait time)
Co-Authored-By: leonardogrig <leo@sideguide.dev>
When scrape returns empty or minimal content from JavaScript-rendered
pages, guide users to try firecrawl_map with a search parameter to
discover the specific page URL before falling back to firecrawl_agent.
This is more efficient than immediately using the agent, as many large
documentation sites spread content across multiple URLs that can be
discovered via map.
Co-Authored-By: leonardogrig <leo@sideguide.dev>
- Scrape tool: Add stronger JSON format guidance with clear decision heuristics
- Scrape tool: Add JavaScript/SPA troubleshooting section (waitFor, URL strategies)
- Scrape tool: Remove references to non-existent batch_scrape (fixes#130)
- Agent tool: Add patient polling guidance (2-3 min minimum, expected wait times)
- Agent status tool: Emphasize not giving up early on polling
- Search tool: Fix sources examples to use object format (fixes#127)
The key changes ensure agents:
1. Use JSON format when extracting specific data points (not markdown)
2. Try waitFor and URL strategies before giving up on JavaScript pages
3. Poll agent status for at least 2-3 minutes before timing out
Co-Authored-By: leonardogrig <leo@sideguide.dev>
Change tool guidance to recommend JSON format by default for scraping.
This prevents context window overflow by extracting only the specific
data needed rather than dumping entire page content.
Changes:
- Update firecrawl_scrape description to prioritize JSON format
- Add branding format example and description
- Change firecrawl_agent to async pattern (returns job ID immediately)
- Agent now uses startAgent() instead of blocking agent() wrapper
- Add polling workflow: start agent → do other work → poll status
- Add comprehensive agent documentation to README
Co-Authored-By: leonardogrig <leo@sideguide.dev>
- Remove outdated 'use extract' recommendation from scrape tool description
- Add Token Limit Issues section explaining how to use JSON format
- Add JSON format example with schema and prompt for structured extraction
This helps users who encounter 'tokens exceeds maximum allowed tokens' errors
by guiding them to use the JSON format which returns only the specific data
they need instead of the full page content.
Co-Authored-By: leonardogrig <leo@sideguide.dev>
Add "enhanced" as a new proxy option in the MCP server. This aligns with the API changes that add "enhanced" as an alias for "stealth".
Co-authored-by: firecrawl-spring[bot] <254786068+firecrawl-spring[bot]@users.noreply.github.com>
Co-authored-by: nickscamara <nick@sideguide.dev>
* feat: add proxy parameter to scrapeParamsSchema
Add support for the 'proxy' parameter with values 'basic', 'stealth',
or 'auto' to enable proxy control for scraping websites with anti-bot
solutions.
This parameter is now available in:
- firecrawl_scrape (direct parameter)
- firecrawl_search (via scrapeOptions)
- firecrawl_crawl (via scrapeOptions)
* Update package.json
---------
Co-authored-by: Nicolas <20311743+nickscamara@users.noreply.github.com>
Introduces an optional 'enterprise' parameter to the search API, allowing users to specify 'zdr' for zero data retention or 'anon' for anonymous mode. Updates documentation to describe these new options.
Introduces two new tools: 'firecrawl_agent' for autonomous web data gathering based on a prompt, and 'firecrawl_agent_status' to check the status of agent jobs. Also updates @mendable/firecrawl-js dependency to version 4.9.3.
mogery