Fix all PR #82 issues: Update to Firecrawl v3 API

[devin-ai-integration]

Fix all PR #82 issues: Update to Firecrawl v3 API

Summary

This PR comprehensively addresses all issues identified in PR #82 by updating the codebase from Firecrawl v2 to v3 API. This is a major breaking change that involves updating method signatures, response handling, and tool implementations.

Key Changes:

• Updated package dependency to @mendable/firecrawl-js ^3.1.0
• Migrated all API calls to v3 structure (scrapeUrl → scrape, asyncCrawlUrl → crawl, etc.)
• Removed success/error field handling (v3 throws exceptions instead)
• Fixed screenshot format from string to object format
• Added missing firecrawl_deep_research tool implementation
• Updated all tests and Jest setup for v3 compatibility
• Fixed CI test configuration with --passWithNoTests flag

Review & Testing Checklist for Human

⚠️ HIGH RISK - API Version Upgrade

• Test real API calls end-to-end with actual Firecrawl v3 API (not just mocks) for scrape, crawl, search, and map operations
• Verify error handling works correctly without success/error fields - test rate limiting, invalid URLs, and API failures
• Test screenshot functionality with the new object format { type: "screenshot", fullPage, quality, viewport }
• Validate all tool implementations including the new firecrawl_deep_research tool work as expected
• Check response parsing for edge cases where response structure might vary from mocks

Recommended Test Plan:

1. Start the MCP server locally and connect a client
2. Test each tool with real URLs and verify expected outputs
3. Intentionally trigger errors (invalid API key, rate limits) to verify error handling
4. Test with various content types and formats to ensure robustness

---

Diagram

%%{ init : { "theme" : "default" }}%%
graph TD
    Package["package.json<br/>Updated deps"]:::major-edit
    MainCode["src/index.ts<br/>Core server logic"]:::major-edit
    Tests["src/index.test.ts<br/>Unit tests"]:::major-edit
    JestSetup["jest.setup.ts<br/>Test configuration"]:::major-edit
    
    Package --> MainCode
    MainCode --> |"API calls"| FirecrawlV3["Firecrawl v3 API<br/>External service"]:::context
    MainCode --> |"Tool implementations"| Tools["MCP Tools<br/>(scrape, crawl, search, etc.)"]:::context
    Tests --> MainCode
    JestSetup --> Tests
    
    subgraph Legend
        L1["Major Edit"]:::major-edit
        L2["Minor Edit"]:::minor-edit  
        L3["Context/No Edit"]:::context
    end

classDef major-edit fill:#90EE90
classDef minor-edit fill:#87CEEB  
classDef context fill:#FFFFFF

Loading

Notes

• Critical Change: This PR removes the success/error field handling that was used in v2, as v3 API throws exceptions instead. This is a fundamental change in error handling approach.
• Type Safety: Used any typing in several places to handle inconsistent v3 response structures - this trades type safety for compatibility.
• Testing Gap: Local tests pass but use mocks that may not perfectly match real v3 API behavior, especially for error scenarios.
• All lint checks pass and build is successful, but real-world testing is essential given the scope of API changes.

Session Info:

• Link to Devin run: https://app.devin.ai/sessions/5df8bf3c208149f79f741442ea5b7be4
• Requested by: @nickscamara

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring