firecrawl-mcp 1.3.3 → 1.4.1

package/README.md

@@ -19,9 +19,17 @@ A Model Context Protocol (MCP) server implementation that integrates with FireCr
 
 ## Installation
 
-### Manual Installation
+## Quick Start
+
+### 1. Installation
+
+Choose one of these methods:
 
 ```bash
+# Using npx (recommended)
+npx -y firecrawl-mcp
+
+# Global installation
 npm install -g firecrawl-mcp
 ```
 
@@ -33,6 +41,26 @@ To install FireCrawl for Claude Desktop automatically via [Smithery](https://smi
 npx -y @smithery/cli install @mendableai/mcp-server-firecrawl --client claude
 ```
 
+
+### Running on Cursor
+
+Configuring Cursor 🖥️
+Note: Requires Cursor version 0.45.6+
+
+To configure FireCrawl MCP in Cursor:
+
+1. Open Cursor Settings
+2. Go to Features > MCP Servers 
+3. Click "+ Add New MCP Server"
+4. Enter the following:
+   - Name: "firecrawl-mcp" (or your preferred name)
+   - Type: "command"
+   - Command: `env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp`
+
+Replace `your-api-key` with your FireCrawl API key.
+
+After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use FireCrawl MCP when appropriate, but you can explicitly request it by describing your web scraping needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.
+
 ## Configuration
 
 ### Environment Variables

package/dist/index.js

@@ -492,6 +492,36 @@ const EXTRACT_TOOL = {
         required: ['urls'],
     },
 };
+const DEEP_RESEARCH_TOOL = {
+    name: 'firecrawl_deep_research',
+    description: 'Conduct deep research on a query using web crawling, search, and AI analysis.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'The query to research',
+            },
+            maxDepth: {
+                type: 'number',
+                description: 'Maximum depth of research iterations (1-10)',
+            },
+            timeLimit: {
+                type: 'number',
+                description: 'Time limit in seconds (30-300)',
+            },
+            maxUrls: {
+                type: 'number',
+                description: 'Maximum number of URLs to analyze (1-1000)',
+            },
+            __experimental_streamSteps: {
+                type: 'boolean',
+                description: 'Experimental flag for streaming steps',
+            },
+        },
+        required: ['query'],
+    },
+};
 // Type guards
 function isScrapeOptions(args) {
     return (typeof args === 'object' &&
@@ -672,6 +702,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         CHECK_CRAWL_STATUS_TOOL,
         SEARCH_TOOL,
         EXTRACT_TOOL,
+        DEEP_RESEARCH_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -973,6 +1004,65 @@ ${result.markdown ? `\nContent:\n${result.markdown}` : ''}`)
                     };
                 }
             }
+            case 'firecrawl_deep_research': {
+                if (!args || typeof args !== 'object' || !('query' in args)) {
+                    throw new Error('Invalid arguments for firecrawl_deep_research');
+                }
+                try {
+                    const researchStartTime = Date.now();
+                    server.sendLoggingMessage({
+                        level: 'info',
+                        data: `Starting deep research for query: ${args.query}`,
+                    });
+                    const response = await client.deepResearch(args.query, {
+                        maxDepth: args.maxDepth,
+                        timeLimit: args.timeLimit,
+                        maxUrls: args.maxUrls,
+                    }, 
+                    // Activity callback
+                    (activity) => {
+                        server.sendLoggingMessage({
+                            level: 'info',
+                            data: `Research activity: ${activity.message} (Depth: ${activity.depth})`,
+                        });
+                    }, 
+                    // Source callback
+                    (source) => {
+                        server.sendLoggingMessage({
+                            level: 'info',
+                            data: `Research source found: ${source.url}${source.title ? ` - ${source.title}` : ''}`,
+                        });
+                    });
+                    // Log performance metrics
+                    server.sendLoggingMessage({
+                        level: 'info',
+                        data: `Deep research completed in ${Date.now() - researchStartTime}ms`,
+                    });
+                    if (!response.success) {
+                        throw new Error(response.error || 'Deep research failed');
+                    }
+                    // Format the results
+                    const formattedResponse = {
+                        finalAnalysis: response.data.finalAnalysis,
+                        activities: response.activities,
+                        sources: response.sources,
+                        currentDepth: response.currentDepth,
+                        maxDepth: response.maxDepth,
+                        summaries: response.summaries || [],
+                    };
+                    return {
+                        content: [{ type: 'text', text: formattedResponse.finalAnalysis }],
+                        isError: false,
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: 'text', text: errorMessage }],
+                        isError: true,
+                    };
+                }
+            }
             default:
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/dist/jest.setup.js

@@ -0,0 +1,58 @@
+import { jest } from '@jest/globals';
+// Set test timeout
+jest.setTimeout(30000);
+// Create mock responses
+const mockSearchResponse = {
+    success: true,
+    data: [
+        {
+            url: 'https://example.com',
+            title: 'Test Page',
+            description: 'Test Description',
+            markdown: '# Test Content',
+            actions: null,
+        },
+    ],
+};
+const mockBatchScrapeResponse = {
+    success: true,
+    id: 'test-batch-id',
+};
+const mockBatchStatusResponse = {
+    success: true,
+    status: 'completed',
+    completed: 1,
+    total: 1,
+    creditsUsed: 1,
+    expiresAt: new Date(),
+    data: [
+        {
+            url: 'https://example.com',
+            title: 'Test Page',
+            description: 'Test Description',
+            markdown: '# Test Content',
+            actions: null,
+        },
+    ],
+};
+// Create mock instance methods
+const mockSearch = jest.fn().mockImplementation(async () => mockSearchResponse);
+const mockAsyncBatchScrapeUrls = jest
+    .fn()
+    .mockImplementation(async () => mockBatchScrapeResponse);
+const mockCheckBatchScrapeStatus = jest
+    .fn()
+    .mockImplementation(async () => mockBatchStatusResponse);
+// Create mock instance
+const mockInstance = {
+    apiKey: 'test-api-key',
+    apiUrl: 'test-api-url',
+    search: mockSearch,
+    asyncBatchScrapeUrls: mockAsyncBatchScrapeUrls,
+    checkBatchScrapeStatus: mockCheckBatchScrapeStatus,
+};
+// Mock the module
+jest.mock('@mendable/firecrawl-js', () => ({
+    __esModule: true,
+    default: jest.fn().mockImplementation(() => mockInstance),
+}));