feat(skills): support MCP-first execution and clarify CLI fallback hierarchy

[TTTT-T]

Summary

This PR updates the core Firecrawl skills to support MCP-first execution while keeping the CLI as a clean fallback, resolving an issue where coding agents in MCP-enabled environments falsely report Firecrawl as unavailable or attempt unauthorized npx installations when the local firecrawl binary is not on PATH.

Changes

1. Execution Hierarchy: Added explicit guidance in skills/firecrawl/SKILL.md and skills/firecrawl/rules/install.md establishing the priority order:
   • MCP First: Use exposed native Firecrawl MCP tools (firecrawl_search, firecrawl_scrape, firecrawl_crawl, firecrawl_map, firecrawl_agent, etc.) directly when available.
   • CLI Fallback: Use firecrawl CLI commands when running in standard terminal / CLI environments.
   • Disambiguation: Clarified that a missing local CLI binary on PATH does not mean Firecrawl is unavailable if MCP tools are configured.
   • Safety Boundary: Explicitly instructed agents not to perform unauthorized background npx firecrawl-cli init or npm installs.
2. Tool Mappings: Added dual MCP / CLI quick-start references to skills/firecrawl/SKILL.md overview table and individual skill documents (firecrawl-search, firecrawl-scrape, firecrawl-map, firecrawl-crawl, firecrawl-agent, firecrawl-interact, firecrawl-parse, firecrawl-monitor, firecrawl-download).
3. Frontmatter Cleanup: Removed restrictive allowed-tools: [Bash(firecrawl *), Bash(npx firecrawl-cli *)] from skill frontmatter (matching the pattern previously adopted in firecrawl-developer-index and firecrawl-research-index) so agent harnesses can invoke native MCP tools without restriction.

Verification

• Ran pnpm test (all 23 test suites / 426 unit tests passing).
• Ran pnpm format:check (all TypeScript and Markdown files formatted via Prettier).

---

Summary by cubic

Determines Firecrawl execution priority as MCP-first with CLI fallback in the core skill docs, so coding agents in MCP-enabled environments no longer report Firecrawl as unavailable or run unauthorized installs when the local firecrawl binary isn't on PATH.

• Adds an execution hierarchy across the skill docs: call native MCP tools first, then CLI, and never install packages unless the user explicitly requested it.
• Removes allowed-tools Bash frontmatter from skill definitions so agent harnesses can invoke MCP tools directly.
• Adds MCP tool references alongside CLI commands in the overview table and individual skill guides.

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

[cubic-dev-ai]

7 issues found across 11 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/firecrawl/rules/install.md">

<violation number="1" location="skills/firecrawl/rules/install.md:16">
P2: Rule 3 forbids running `npx firecrawl-cli init` unless the user explicitly requests it, but the 'Quick Setup (Recommended)' block directly below recommends `npx -y firecrawl-cli@latest init -y --browser` and calls it 'safe to re-run when the CLI is missing' — no user-request condition. A coding agent reading both gets contradictory guidance on when installing is allowed and which command to run ('Command not found' step 3 instead says `npm install -g firecrawl-cli@latest`). Qualify the Quick Setup to require explicit user consent (or reword rule 3) and use a single install command so the docs are internally consistent.</violation>
</file>

<file name="skills/firecrawl-download/SKILL.md">

<violation number="1" location="skills/firecrawl-download/SKILL.md:15">
P2: The MCP-first instruction loses the download skill's core behavior. It tells the agent only to 'extract and save page contents' with `firecrawl_scrape`, but that tool returns content into the conversation and does not write local files or screenshots unless the agent explicitly requests `formats: ["markdown", "screenshot"]` and writes them itself. A user asking to 'download the site' (with screenshots, per the CLI `--screenshot`) in an MCP-first environment gets in-chat content rather than the local `.firecrawl/` file tree the CLI produces. Ask the agent to request the screenshot/markdown formats and save each page to `.firecrawl/`, so the two paths stay equivalent.</violation>
</file>

<file name="skills/firecrawl/SKILL.md">

<violation number="1" location="skills/firecrawl/SKILL.md:13">
P2: When the CLI is absent, MCP-first execution bypasses this skill's required `.firecrawl/` persistence and saved-source citation flow. Document how to save and bounded-read MCP results with host filesystem tools, or make those requirements conditional for MCP execution.</violation>

<violation number="2" location="skills/firecrawl/SKILL.md:13">
P2: On MCP-only hosts, this new route leaves the required search-feedback step pointing at the missing `firecrawl` CLI. Add an MCP branch using `firecrawl_search_feedback` and keep the CLI command for CLI searches.</violation>

<violation number="3" location="skills/firecrawl/SKILL.md:43">
P2: When CLI fallback handles a paper search, this row directs the agent to run `research`, which does not perform a search. Use `research search-papers` in the CLI column.</violation>
</file>

<file name="skills/firecrawl-search/SKILL.md">

<violation number="1" location="skills/firecrawl-search/SKILL.md:15">
P2: In an MCP-only environment, the required feedback step still invokes `firecrawl search-feedback` in the background. Add an MCP branch that calls `firecrawl_search_feedback` and retain the CLI command only for CLI searches.</violation>
</file>

<file name="skills/firecrawl-parse/SKILL.md">

<violation number="1" location="skills/firecrawl-parse/SKILL.md:14">
P2: When the exposed MCP server is hosted remotely, it cannot read a local `filePath` directly. Document the upload-handoff and `uploadRef` flow, or limit this shortcut to local/self-hosted MCP connections.</violation>
</file>

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Rule 3 forbids running npx firecrawl-cli init unless the user explicitly requests it, but the 'Quick Setup (Recommended)' block directly below recommends npx -y firecrawl-cli@latest init -y --browser and calls it 'safe to re-run when the CLI is missing' — no user-request condition. A coding agent reading both gets contradictory guidance on when installing is allowed and which command to run ('Command not found' step 3 instead says npm install -g firecrawl-cli@latest). Qualify the Quick Setup to require explicit user consent (or reword rule 3) and use a single install command so the docs are internally consistent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/rules/install.md, line 16:

<comment>Rule 3 forbids running `npx firecrawl-cli init` unless the user explicitly requests it, but the 'Quick Setup (Recommended)' block directly below recommends `npx -y firecrawl-cli@latest init -y --browser` and calls it 'safe to re-run when the CLI is missing' — no user-request condition. A coding agent reading both gets contradictory guidance on when installing is allowed and which command to run ('Command not found' step 3 instead says `npm install -g firecrawl-cli@latest`). Qualify the Quick Setup to require explicit user consent (or reword rule 3) and use a single install command so the docs are internally consistent.</comment>

<file context>
@@ -9,6 +9,12 @@ description: |
+
+1. **Check for Native MCP Tools First**: Before attempting to install or check the CLI, verify whether Firecrawl MCP tools (e.g. `firecrawl_search`, `firecrawl_scrape`, `firecrawl_crawl`, `firecrawl_map`, etc.) are exposed in your current agent environment. If MCP tools are available, **use them directly** without installing the CLI.
+2. **Missing Local CLI != Firecrawl Unavailable**: If `firecrawl` command is not found on `PATH`, this only means the CLI executable is absent locally; it does not mean Firecrawl functionality is unavailable. Check for MCP tools before reporting failure.
+3. **No Unauthorized Package Installation**: Agents must **not** execute `npx firecrawl-cli init` or install npm packages unless explicitly requested by the user.
+
 ## Quick Setup (Recommended)
</file context>

[cubic-dev-ai]

P2: The MCP-first instruction loses the download skill's core behavior. It tells the agent only to 'extract and save page contents' with firecrawl_scrape, but that tool returns content into the conversation and does not write local files or screenshots unless the agent explicitly requests formats: ["markdown", "screenshot"] and writes them itself. A user asking to 'download the site' (with screenshots, per the CLI --screenshot) in an MCP-first environment gets in-chat content rather than the local .firecrawl/ file tree the CLI produces. Ask the agent to request the screenshot/markdown formats and save each page to .firecrawl/, so the two paths stay equivalent.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-download/SKILL.md, line 15:

<comment>The MCP-first instruction loses the download skill's core behavior. It tells the agent only to 'extract and save page contents' with `firecrawl_scrape`, but that tool returns content into the conversation and does not write local files or screenshots unless the agent explicitly requests `formats: ["markdown", "screenshot"]` and writes them itself. A user asking to 'download the site' (with screenshots, per the CLI `--screenshot`) in an MCP-first environment gets in-chat content rather than the local `.firecrawl/` file tree the CLI produces. Ask the agent to request the screenshot/markdown formats and save each page to `.firecrawl/`, so the two paths stay equivalent.</comment>

<file context>
@@ -13,6 +10,12 @@ allowed-tools:
 
+## Tool Choice & Quick Start
+
+- MCP: Use **`firecrawl_map(url, ...)`** to discover pages and **`firecrawl_scrape(url, ...)`** to extract and save page contents.
+- CLI: **`firecrawl x download <url> [--include-paths <paths>] [--limit <n>] -y`**
+  Command line batch download directly to `.firecrawl/`.
</file context>

Suggested change

	- MCP: Use **`firecrawl_map(url, ...)`** to discover pages and **`firecrawl_scrape(url, ...)`** to extract and save page contents.
	- MCP: Use **`firecrawl_map(url, ...)`** to discover pages, then **`firecrawl_scrape(url, formats: ["markdown", "screenshot"], ...)`** on each page and save the results to local files under `.firecrawl/`.

[cubic-dev-ai]

P2: When CLI fallback handles a paper search, this row directs the agent to run research, which does not perform a search. Use research search-papers in the CLI column.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 43:

<comment>When CLI fallback handles a paper search, this row directs the agent to run `research`, which does not perform a search. Use `research search-papers` in the CLI column.</comment>

<file context>
@@ -30,19 +37,19 @@ Follow this escalation pattern:
+| Need                        | MCP Tool                             | CLI Command           | When                                                            |
+| --------------------------- | ------------------------------------ | --------------------- | --------------------------------------------------------------- |
+| Find pages on a topic       | `firecrawl_search`                   | `search`              | No specific URL yet                                             |
+| Find research papers        | `firecrawl_research_search_papers`   | `research`            | Biomedical/clinical/scientific literature — use the paper index |
+| Answer a coding question    | `firecrawl_developer_search`         | `developer`           | Issues, merged PRs, READMEs, and docs — not a general web page  |
+| Get a page's content        | `firecrawl_scrape`                   | `scrape`              | Have a URL, page is static or JS-rendered                       |
</file context>

Suggested change

	| Find research papers | `firecrawl_research_search_papers` | `research` | Biomedical/clinical/scientific literature — use the paper index |
	| Find research papers | `firecrawl_research_search_papers` | `research search-papers` | Biomedical/clinical/scientific literature — use the paper index |

[cubic-dev-ai]

P2: When the CLI is absent, MCP-first execution bypasses this skill's required .firecrawl/ persistence and saved-source citation flow. Document how to save and bounded-read MCP results with host filesystem tools, or make those requirements conditional for MCP execution.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 13:

<comment>When the CLI is absent, MCP-first execution bypasses this skill's required `.firecrawl/` persistence and saved-source citation flow. Document how to save and bounded-read MCP results with host filesystem tools, or make those requirements conditional for MCP execution.</comment>

<file context>
@@ -2,13 +2,20 @@
+
+Follow this precedence order based on your current execution environment:
+
+1. **MCP First (Recommended)**: If Firecrawl MCP tools (`firecrawl_search`, `firecrawl_scrape`, `firecrawl_map`, `firecrawl_crawl`, `firecrawl_agent`, `firecrawl_interact`, `firecrawl_parse`, `firecrawl_monitor_*`, `firecrawl_developer_search`, `firecrawl_research_*`) are available in the tool catalog, **call the MCP tools directly**.
+2. **CLI Fallback**: If MCP tools are not exposed, check if the `firecrawl` CLI is installed on `PATH` and run CLI commands.
+3. **Missing Local CLI != Unavailable**: If `firecrawl` command is not found on `PATH`, do **not** declare Firecrawl unavailable without checking for exposed MCP tools first. **Do not run unauthorized `npx` commands or install packages silently**.
</file context>

[cubic-dev-ai]

P2: On MCP-only hosts, this new route leaves the required search-feedback step pointing at the missing firecrawl CLI. Add an MCP branch using firecrawl_search_feedback and keep the CLI command for CLI searches.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl/SKILL.md, line 13:

<comment>On MCP-only hosts, this new route leaves the required search-feedback step pointing at the missing `firecrawl` CLI. Add an MCP branch using `firecrawl_search_feedback` and keep the CLI command for CLI searches.</comment>

<file context>
@@ -2,13 +2,20 @@
+
+Follow this precedence order based on your current execution environment:
+
+1. **MCP First (Recommended)**: If Firecrawl MCP tools (`firecrawl_search`, `firecrawl_scrape`, `firecrawl_map`, `firecrawl_crawl`, `firecrawl_agent`, `firecrawl_interact`, `firecrawl_parse`, `firecrawl_monitor_*`, `firecrawl_developer_search`, `firecrawl_research_*`) are available in the tool catalog, **call the MCP tools directly**.
+2. **CLI Fallback**: If MCP tools are not exposed, check if the `firecrawl` CLI is installed on `PATH` and run CLI commands.
+3. **Missing Local CLI != Unavailable**: If `firecrawl` command is not found on `PATH`, do **not** declare Firecrawl unavailable without checking for exposed MCP tools first. **Do not run unauthorized `npx` commands or install packages silently**.
</file context>

[cubic-dev-ai]

P2: In an MCP-only environment, the required feedback step still invokes firecrawl search-feedback in the background. Add an MCP branch that calls firecrawl_search_feedback and retain the CLI command only for CLI searches.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-search/SKILL.md, line 15:

<comment>In an MCP-only environment, the required feedback step still invokes `firecrawl search-feedback` in the background. Add an MCP branch that calls `firecrawl_search_feedback` and retain the CLI command only for CLI searches.</comment>

<file context>
@@ -2,15 +2,20 @@
+
+- MCP: **`firecrawl_search(query, scrapeOptions?, categories?, limit?, sources?, ...)`**
+  Call directly when Firecrawl MCP tools are exposed.
+  Feedback: **`firecrawl_search_feedback(searchId, rating, ...)`**
+- CLI: **`firecrawl search <query> [--scrape] [--json] [-o <path>]`**
+  Fallback when running in a CLI environment.
</file context>

[cubic-dev-ai]

P2: When the exposed MCP server is hosted remotely, it cannot read a local filePath directly. Document the upload-handoff and uploadRef flow, or limit this shortcut to local/self-hosted MCP connections.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-parse/SKILL.md, line 14:

<comment>When the exposed MCP server is hosted remotely, it cannot read a local `filePath` directly. Document the upload-handoff and `uploadRef` flow, or limit this shortcut to local/self-hosted MCP connections.</comment>

<file context>
@@ -2,15 +2,19 @@
+## Tool Choice & Quick Start
+
+- MCP: **`firecrawl_parse(filePath?, formats?, ...)`**
+  Call directly when Firecrawl MCP tools are exposed.
+- CLI: **`firecrawl parse <file> [-o <path>]`**
+  Fallback when running in a CLI environment.
</file context>