fix(mcp): put keyless account recovery in the agent-readable message

[Max17190]

Why

Agents read content[0].text (=== structuredContent.message). Keyless quota, blocked-tool, and ineligible-access recoveries previously told the agent to keep using keyless tools or wait, so the account-attachment steps never reached that path.

Summary

• Put both attachment routes in the shared keyless recovery message: create a key at https://www.firecrawl.dev/signin, then set Authorization: Bearer YOUR_API_KEY on https://mcp.firecrawl.dev/v2/mcp or use https://mcp.firecrawl.dev/v2/mcp-oauth.
• Apply that copy to KEYLESS_QUOTA_EXHAUSTED, KEYLESS_LIMIT_REACHED, KEYLESS_TOOL_NOT_AVAILABLE, and KEYLESS_ACCESS_NOT_AVAILABLE.
• Drop available_tools and next_actions (including continue_keyless) on those codes so the agent is not sent back into Search/Scrape/Parse.
• Keep retry_after_seconds on structuredContent when Core sends it; do not put a wait in the message.
• Leave CREDENTIAL_INVALID, KEYLESS_ELIGIBILITY_UNAVAILABLE, KEYLESS_OPTION_NOT_AVAILABLE, and initialize / KEYLESS_PROFILE_INSTRUCTIONS unchanged. The result stays a 200 isError tool result.

Test plan

• npm test
• Keyless Search/Scrape/Parse 429 returns isError: true with the quota message and content[0].text === structuredContent.message
• retry_after_seconds is present only when the API body includes it
• Keyless firecrawl_crawl (and other account-only tools) returns KEYLESS_TOOL_NOT_AVAILABLE with no available_tools / continue_keyless
• Ineligible keyless IP returns KEYLESS_ACCESS_NOT_AVAILABLE with the same Fix
• Invalid API key recovery and eligibility-unavailable retry guidance are unchanged

---

Summary by cubic

Put keyless account recovery instructions in the agent-readable message and simplify invalid-credential recoveries. This stops agents from looping on free-tier tools and removes human-reconnect prompts.

• For KEYLESS_QUOTA_EXHAUSTED, KEYLESS_LIMIT_REACHED, KEYLESS_TOOL_NOT_AVAILABLE, and KEYLESS_ACCESS_NOT_AVAILABLE: the message tells the user to create a Firecrawl API key at https://www.firecrawl.dev/signin and either set Authorization: Bearer YOUR_API_KEY on https://mcp.firecrawl.dev/v2/mcp or use https://mcp.firecrawl.dev/v2/mcp-oauth. Do not return available_tools or next_actions; keep docs_url and include retry_after_seconds only when provided. Result remains a 200 isError tool result.
• For CREDENTIAL_INVALID and OAUTH_CONNECTION_INVALID: return a short diagnostic (“The Firecrawl API key is invalid or revoked.” / “This Firecrawl account connection is no longer valid.”) and omit next_actions; no human-in-chat guidance. KEYLESS_ELIGIBILITY_UNAVAILABLE stays a retry-later recovery.
• Tests add a helper to assert content[0].text equals structuredContent.message, expect no available_tools/next_actions on keyless and invalid-credential recoveries, validate retry_after_seconds passthrough, and confirm account-only tools do not execute under keyless.

^{Written for commit 990a2b4. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

No issues found across 2 files

<sub>Auto-approved: Focused bug fix: keyless recovery messages now instruct the agent to attach a key instead of continuing free-tier tools; tests pin the new message contract and dropped fields. No operational, security, or contract expansion beyond the intended correction.

Re-trigger cubic</sub>