Firecrawl MCP Effect

耐火材料

一个可自托管、兼容Vercel的MCP（模型上下文协议）服务器，用于 萤火虫，采用严格的TypeScript ES2024构建， 效果TS，以及Bun运行时。

快速入门：

• 添加到克劳德桌面 （或奔跑 ./scripts/setup-claude.sh)
• 添加到LM工作室
• 全部文件 （包括开发人员文档 docs/dev/)

______________________________________________________________________

建筑

firecrawl-mcp/
├── api/                        # Vercel serverless function entrypoints
│   ├── health.ts               # GET /health — LB probe
│   └── mcp.ts                  # POST / — MCP JSON-RPC 2.0 handler
├── src/
│   ├── config/
│   │   └── app-config.ts       # Effect Config — typed secret management
│   ├── errors/
│   │   └── mcp-errors.ts       # Tagged domain errors (Data.TaggedError)
│   ├── services/
│   │   ├── firecrawl-client.ts # Effect Layer wrapping @mendable/firecrawl-js
│   │   └── logger.ts           # Structured JSON logger service
│   ├── api/
│   │   ├── groups/
│   │   │   └── mcp-handler.ts  # MCP JSON-RPC dispatch + web adapter
│   │   └── schemas/
│   │       └── firecrawl-schemas.ts  # Effect Schema types for all tools
│   ├── tools/
│   │   ├── tool-definitions.ts # Static tool metadata (tools/list)
│   │   ├── tool-registry.ts    # Handler map — name -> Effect handler
│   │   └── tool-schemas.ts     # Schema re-exports (avoids circular imports)
│   ├── lib/
│   │   ├── app-layer.ts        # Full Layer DAG composition
│   │   └── utils.ts            # Pure utilities (sanitization, parsing)
│   └── server.ts               # Local Bun dev server
├── .env.example
├── dprint.json
├── package.json
├── tsconfig.json
└── vercel.json

实心对齐

______________________________________________________________________

需求

• 包子 >= 1.1.0
• Firecrawl API密钥 或自托管的Firecrawl实例URL

______________________________________________________________________

运行期模型

Bun是唯一的工具链——安装程序、打包器、测试运行器、开发服务器和 类型检查器主机。Vercel负责运营 _编译输出_ 在Node.js 22下。没有 运行时冲突：源代码永远不会交给Node raw。这 functions 把…的车堵住 vercel.json 故意缺席；Vercel自动检测 api/ 处理人员和 服务捆绑 dist/ 输出。

______________________________________________________________________

本地开发

# Install dependencies
bun install

# Configure environment
cp .env.example .env.local
# Edit .env.local: set FIRECRAWL_API_KEY or FIRECRAWL_API_URL

# Start dev server with hot reload
bun run dev
# Server listens on http://localhost:3000

# Type-check (bun hosts tsc — no separate tsc binary needed)
bun run typecheck

# Format all source files
bun run fmt

# Check formatting without writing (CI)
bun run fmt:check

发送测试请求

# List available tools
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Scrape a page
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "firecrawl_scrape",
      "arguments": {
        "url": "https://example.com",
        "formats": ["markdown"],
        "onlyMainContent": true
      }
    }
  }'

# Export Prometheus metrics
curl -X GET http://localhost:3000/metrics

______________________________________________________________________

Vercel部署

# Install Vercel CLI
bun add -g vercel

# Deploy
vercel

# Set environment variables in Vercel dashboard or via CLI
vercel env add FIRECRAWL_API_KEY

环境变量

______________________________________________________________________

云服务模式

当 CLOUD_SERVICE=true，API密钥是从每个传入请求中读取的，而不是 相比于环境：

POST / HTTP/1.1
x-firecrawl-api-key: fc-your-key-here
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

接受的标头（按优先级顺序）：

1. x-firecrawl-api-key
2. x-api-key
3. Authorization: Bearer

______________________________________________________________________

安全模式

当 SAFE_MODE=true （在以下情况下自动启用 CLOUD_SERVICE=true):

• firecrawl_scrape 条带 actions 涉及用户交互（点击、编写、执行Javascript、生成PDF）
• firecrawl_crawl 剥去 webhook 选项
• firecrawl_browser_execute 返回错误

______________________________________________________________________

可观测性

• 每个回复都包括 X-Request-Id 用于端到端相关性。
• 结构化日志通过经过净化的上游诊断捕获工具故障。
• GET /metrics 公开Prometheus文本度量：

- mcp_requests_total - mcp_request_duration_ms_total - mcp_tool_calls_total - mcp_tool_duration_ms_total

______________________________________________________________________

CI/CD

• CI工作流程(.github/workflows/ci.yml)在PR上运行 main 推送：

- 格式检查 - 类型检查 - 测试 - 烟雾检查

• 依赖关系策略工作流(.github/workflows/dependency-policy.yml)强制执行精确的固定版本并拒绝提交 bun.lock.
• 安全工作流程(.github/workflows/security.yml)跑步 bun audit 以及CodeQL分析。
• Dependabot配置(.github/dependabot.yml)每周管理Bun和GitHub Actions的更新。
• CD工作流程(.github/workflows/deploy.yml)CI成功后部署到Vercel main.

部署所需的存储库机密：

• VERCEL_TOKEN
• VERCEL_ORG_ID
• VERCEL_PROJECT_ID

______________________________________________________________________

添加新工具

1. 添加一个 ToolDefinition 进入 src/tools/tool-definitions.ts
2. 向添加架构 src/api/schemas/firecrawl-schemas.ts
3. 在中重新导出架构 src/tools/tool-schemas.ts
4. 添加一个处理程序函数并将其注册到 src/tools/tool-registry.ts

没有其他文件需要修改。

______________________________________________________________________

效果层DAG

AppConfigLive (Config env)
    |
    +-- AppLoggerLive
    |
    +-- FirecrawlClientLive
         |
         +-- AppLive (merged)
              |
              +-- ManagedRuntime (api/mcp.ts)