feat: add firecrawl_ask + firecrawl_docs_search tools

[devhims]

Summary

Two new MCP tools wrap the customer-facing /v2/support/* endpoints exposed at api.firecrawl.dev (which proxies to the support-agent service):

Tool	Use when
firecrawl_ask	Debugging — a firecrawl_* call failed, returned an empty result, or behaved unexpectedly. The AI support agent inspects job logs + account state + docs and returns a diagnosis with machine-readable fixParameters you can apply directly.
firecrawl_docs_search	Learning — "how do I…" questions about Firecrawl features, parameters, endpoints, status codes, billing. Returns a docs-grounded answer with citations.

Both auth automatically with the per-session FIRECRAWL_API_KEY — same as every other tool, calls are team-scoped server-side.

Why this matters for agents

Today, when a firecrawl_scrape/firecrawl_crawl/etc. call fails or returns weird output, agents typically:

1. Apologize and tell the user to file a support ticket, or
2. Guess at fixes based on stale training data and burn credits on retries.

After this PR, the right move is firecrawl_ask — the support agent inspects the actual run's logs, often validates a fix against the live API, and returns the corrected parameters as JSON the calling agent can apply directly. The tool descriptions push agents toward this loop explicitly:

Best for: Debugging a failing or unexpected Firecrawl call. Use this WHENEVER another firecrawl_* tool returns an error, an empty result, or output that doesn't match what the user asked for — instead of guessing or apologizing, call firecrawl_ask first and apply the suggested fix.

firecrawl_docs_search solves the parallel problem on the learning side — instead of returning out-of-date answers from training data when the user asks "how do webhooks work in Firecrawl?", agents now have a tool that grounds the answer in the current docs.

Implementation

src/index.ts:

• New callSupportEndpoint(session, endpoint, body) helper near the existing asText() utility — POSTs directly to /v2/support/* with the session's API key (the SDK doesn't expose these yet). Defaults to https://api.firecrawl.dev but honors FIRECRAWL_API_URL when set, so self-hosted-with-proxy deployments work.
• Two new server.addTool({...}) registrations after firecrawl_interact_stop:
  • firecrawl_ask — schema: question (1-8000 chars, required) + optional rationale (1-2000), jobId, context. Mirrors the upstream AskRequestSchema post-cleanup (no model / maxSteps / firecrawlApi* knobs).
  • firecrawl_docs_search — schema: question (1-8000 chars, required) only.
• Both tools use the existing readOnlyHint: true, openWorldHint: false annotations and the same Best-for / Not-recommended / Common-mistakes / Recipe / Returns description pattern as firecrawl_scrape and firecrawl_search.

README.md:

• Quick Reference Table — add ask and docs_search rows.
• Available Tools — full sections (Ability to override RATE_LIMIT when connecting to a local firecrawl instance #11 ask, Feature/remove rate limit #12 docs_search), renumbering the subsequent deprecated browser tools to Feature/remove rate limit #13–Rename package references from firecrawl-mcp to mcp-server-firecrawl #16.

Testing the change

After this lands, in any MCP client (Claude Desktop, Cursor, etc.):

firecrawl_ask({
  "question": "scrape of https://example.com returned empty markdown",
  "rationale": "User wants to scrape example.com to feed an LLM summarization pipeline.",
  "jobId": "scrape-abc-123-def"
})

Should return a { requestId, answer, confidence, fixParameters, validation, … } envelope from the support agent within ~15-30 seconds.

firecrawl_docs_search({
  "question": "how do I verify webhook signatures?"
})

Should return { answer, evidence: [{ pathOrUrl, reason }], … } with citations to the relevant docs pages.

Test plan

• Build clean: pnpm install && pnpm build
• firecrawl_ask returns a valid envelope when called with a real failing job id from the user's team
• firecrawl_docs_search returns docs-grounded results with citations
• Both tools surface clear errors when FIRECRAWL_API_KEY is missing
• FIRECRAWL_API_URL override is honored (self-hosted proxy scenario)

Companion changes

• firecrawl-web#2096 — uses /v2/support/ask from the playground Debug Issue modal.
• support-agent#4 — tightens the customer-facing AskRequestSchema (drops model, maxSteps, firecrawlApi*).
• firecrawl-docs#917 — keeps /support/* out of the Elixir SDK source-of-truth.

🤖 Generated with Claude Code