MCP Server for Crawl4AI

Instructions

Implementation Reference

• src/handlers/content-handlers.ts:132-160 (handler)

  The primary handler function for the generate_pdf tool. It calls the underlying service to generate the PDF, validates the response, and formats it as an MCP resource (base64 PDF blob with URI and accompanying text).

  async generatePDF(options: PDFEndpointOptions) {
    try {
      const result: PDFEndpointResponse = await this.service.generatePDF(options);
  
      // Response has { success: true, pdf: "base64string" }
      if (!result.success || !result.pdf) {
        throw new Error('PDF generation failed - no PDF data in response');
      }
  
      return {
        content: [
          {
            type: 'resource',
            resource: {
              uri: `data:application/pdf;name=${encodeURIComponent(new URL(String(options.url)).hostname)}.pdf;base64,${result.pdf}`,
              mimeType: 'application/pdf',
              blob: result.pdf,
            },
          },
          {
            type: 'text',
            text: `PDF generated for: ${options.url}`,
          },
        ],
      };
    } catch (error) {
      throw this.formatError(error, 'generate PDF');
    }
  }

• src/server.ts:837-840 (registration)

  Tool dispatch registration in the MCP server request handler switch statement. Validates input with GeneratePdfSchema and delegates to ContentHandlers.generatePDF.

  case 'generate_pdf':
    return await this.validateAndExecute('generate_pdf', args, GeneratePdfSchema, async (validatedArgs) =>
      this.contentHandlers.generatePDF(validatedArgs),
    );

• src/schemas/validation-schemas.ts:72-78 (schema)

  Zod schema for validating generate_pdf tool inputs (requires URL).

  export const GeneratePdfSchema = createStatelessSchema(
    z.object({
      url: z.string().url(),
      // Only url is supported - output_path not exposed as MCP needs base64 data
    }),
    'generate_pdf',
  );

• src/server.ts:176-189 (registration)

  Tool metadata registration in the MCP list_tools response, including name, description, and input schema definition.

    name: 'generate_pdf',
    description:
      '[STATELESS] Convert webpage to PDF. Returns base64-encoded PDF data. Creates new browser each time. Cannot capture form fills or JS changes. For persistent PDFs use create_session + crawl(session_id, pdf:true).',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'The URL to convert to PDF',
        },
      },
      required: ['url'],
    },
  },

• src/crawl4ai-service.ts:159-175 (helper)

  Underlying service method that makes the HTTP POST request to the Crawl4AI /pdf endpoint to generate the PDF base64 data.

  async generatePDF(options: PDFEndpointOptions): Promise<PDFEndpointResponse> {
    // Validate URL
    if (!validateURL(options.url)) {
      throw new Error('Invalid URL format');
    }
  
    try {
      const response = await this.axiosClient.post('/pdf', {
        url: options.url,
        // output_path is omitted to get base64 response
      });
  
      return response.data;
    } catch (error) {
      return handleAxiosError(error);
    }
  }