MCP Server for Crawl4AI

Instructions

Implementation Reference

• src/handlers/session-handlers.ts:3-167 (handler)

  Full implementation of SessionHandlers class. The manageSession method (lines 4-28) is the entry point for the 'manage_session' tool, dispatching based on action to private methods that handle session creation (including optional initial crawl), clearing, and listing active sessions with metadata.
  export class SessionHandlers extends BaseHandler { async manageSession(options: { action: 'create' | 'clear' | 'list'; session_id?: string; initial_url?: string; browser_type?: string; }) { switch (options.action) { case 'create': return this.createSession({ session_id: options.session_id, initial_url: options.initial_url, browser_type: options.browser_type, }); case 'clear': if (!options.session_id) { throw new Error('session_id is required for clear action'); } return this.clearSession({ session_id: options.session_id }); case 'list': return this.listSessions(); default: // This should never happen due to TypeScript types, but handle it for runtime safety throw new Error(`Invalid action: ${(options as { action: string }).action}`); } } private async createSession(options: { session_id?: string; initial_url?: string; browser_type?: string }) { try { // Generate session ID if not provided const sessionId = options.session_id || `session-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`; // Store session info locally this.sessions.set(sessionId, { id: sessionId, created_at: new Date(), last_used: new Date(), initial_url: options.initial_url, metadata: { browser_type: options.browser_type || 'chromium', }, }); // If initial_url provided, make first crawl to establish session if (options.initial_url) { try { await this.axiosClient.post( '/crawl', { urls: [options.initial_url], browser_config: { headless: true, browser_type: options.browser_type || 'chromium', }, crawler_config: { session_id: sessionId, cache_mode: 'BYPASS', }, }, { timeout: 30000, // 30 second timeout for initial crawl }, ); // Update last_used const session = this.sessions.get(sessionId); if (session) { session.last_used = new Date(); } } catch (error) { // Session created but initial crawl failed - still return success console.error(`Initial crawl failed for session ${sessionId}:`, error); } } return { content: [ { type: 'text', text: `Session created successfully:\nSession ID: ${sessionId}\nBrowser: ${options.browser_type || 'chromium'}\n${options.initial_url ? `Pre-warmed with: ${options.initial_url}` : 'Ready for use'}\n\nUse this session_id with the crawl tool to maintain state across requests.`, }, ], // Include all session parameters for easier programmatic access session_id: sessionId, browser_type: options.browser_type || 'chromium', initial_url: options.initial_url, created_at: this.sessions.get(sessionId)?.created_at.toISOString(), }; } catch (error) { throw this.formatError(error, 'create session'); } } private async clearSession(options: { session_id: string }) { try { // Remove from local store const deleted = this.sessions.delete(options.session_id); // Note: The actual browser session in Crawl4AI will be cleaned up // automatically after inactivity or when the server restarts return { content: [ { type: 'text', text: deleted ? `Session cleared successfully: ${options.session_id}` : `Session not found: ${options.session_id}`, }, ], }; } catch (error) { throw this.formatError(error, 'clear session'); } } private async listSessions() { try { // Return locally stored sessions const sessions = Array.from(this.sessions.entries()).map(([id, info]) => { const ageMinutes = Math.floor((Date.now() - info.created_at.getTime()) / 60000); const lastUsedMinutes = Math.floor((Date.now() - info.last_used.getTime()) / 60000); return { session_id: id, created_at: info.created_at.toISOString(), last_used: info.last_used.toISOString(), age_minutes: ageMinutes, last_used_minutes_ago: lastUsedMinutes, initial_url: info.initial_url, browser_type: info.metadata?.browser_type || 'chromium', }; }); if (sessions.length === 0) { return { content: [ { type: 'text', text: 'No active sessions found.', }, ], }; } const sessionList = sessions .map( (session) => `- ${session.session_id} (${session.browser_type}, created ${session.age_minutes}m ago, last used ${session.last_used_minutes_ago}m ago)`, ) .join('\n'); return { content: [ { type: 'text', text: `Active sessions (${sessions.length}):\n${sessionList}`, }, ], }; } catch (error) { throw this.formatError(error, 'list sessions'); } } }
• src/schemas/validation-schemas.ts:150-164 (schema)

  Zod schema for input validation of manage_session tool. Uses discriminatedUnion on 'action' field to validate parameters for 'create', 'clear', or 'list' operations.
  export const ManageSessionSchema = z.discriminatedUnion('action', [ z.object({ action: z.literal('create'), session_id: z.string().optional(), initial_url: z.string().url().optional(), browser_type: z.enum(['chromium', 'firefox', 'webkit']).optional(), }), z.object({ action: z.literal('clear'), session_id: z.string(), }), z.object({ action: z.literal('list'), }), ]);
• src/server.ts:750-789 (registration)

  Registration of 'manage_session' tool in the ListTools response, including name, detailed description, and inputSchema matching the Zod schema.
  { name: 'manage_session', description: '[SESSION MANAGEMENT] Unified tool for managing browser sessions. Supports three actions:\n\n' + '• CREATE: Start a persistent browser session that maintains state across calls\n' + '• CLEAR: Remove a session from local tracking\n' + '• LIST: Show all active sessions with age and usage info\n\n' + 'USAGE EXAMPLES:\n' + '1. Create session: {action: "create", session_id: "my-session", initial_url: "https://example.com"}\n' + '2. Clear session: {action: "clear", session_id: "my-session"}\n' + '3. List sessions: {action: "list"}\n\n' + 'Browser sessions maintain ALL state (cookies, localStorage, page) across multiple crawl calls. Essential for: forms, login flows, multi-step processes, maintaining state across operations.', inputSchema: { // Anthropic/Claude tools require top-level schemas to be a plain object without oneOf/allOf/anyOf type: 'object', properties: { action: { type: 'string', description: 'Action to perform: create, clear, or list', enum: ['create', 'clear', 'list'], }, session_id: { type: 'string', description: 'Session identifier. Required for action="clear". Optional for create (auto-generated if omitted).', }, initial_url: { type: 'string', description: 'URL to load when creating session (action="create").', }, browser_type: { type: 'string', enum: ['chromium', 'firefox', 'webkit'], description: 'Browser engine for the session (action="create").', default: 'chromium', }, }, required: ['action'], }, },
• src/server.ts:885-888 (registration)

  Dispatch handler in the CallToolRequest switch statement that validates arguments using ManageSessionSchema and executes this.sessionHandlers.manageSession.
  case 'manage_session': return await this.validateAndExecute('manage_session', args, ManageSessionSchema, async (validatedArgs) => this.sessionHandlers.manageSession(validatedArgs), );
• src/server.ts:84-84 (registration)

  Instantiation of SessionHandlers class instance (this.sessionHandlers) in the server constructor, passing service, axiosClient, and sessions Map.
  this.sessionHandlers = new SessionHandlers(this.service, this.axiosClient, this.sessions);