Printify MCP Server

Implementation Reference

• src/index.ts:558-599 (registration)

  MCP server.tool registration for 'upload_image', including input schema (fileName, url) and handler function that checks client, determines source type, and delegates to uploadImageToPrintify service
  // Upload image tool server.tool( "upload_image", { fileName: z.string().describe("File name"), url: z.string().describe("URL of the image to upload, path to local file, or base64 encoded image data") }, async ({ fileName, url }): Promise<{ content: any[], isError?: boolean }> => { // Import the printify uploader service const { uploadImageToPrintify, determineImageSourceType } = await import('./services/printify-uploader.js'); // Check if client is initialized if (!printifyClient) { return { content: [{ type: "text", text: "Printify API client is not initialized. The PRINTIFY_API_KEY environment variable may not be set." }], isError: true }; } // Log the attempt with limited information for privacy const sourceType = determineImageSourceType(url); const sourcePreview = sourceType === 'url' ? url.substring(0, 30) + '...' : sourceType === 'file' ? url : // Show full file path url.substring(0, 30) + '...'; console.log(`Attempting to upload image: ${fileName} from ${sourceType} source: ${sourcePreview}`); // Call the service const result = await uploadImageToPrintify(printifyClient, fileName, url); // Return the result if (result.success) { return result.response as { content: any[], isError?: boolean }; } else { return result.errorResponse as { content: any[], isError: boolean }; } } );
• src/services/printify-uploader.ts:49-300 (handler)

  Main handler function uploadImageToPrintify that validates shop, handles file/url/base64 sources, verifies files, and calls PrintifyAPI.uploadImage
  export async function uploadImageToPrintify( printifyClient: PrintifyAPI, fileName: string, source: string ) { try { // Validate shop is selected const currentShop = printifyClient.getCurrentShop(); if (!currentShop) { throw new Error('No shop is currently selected. Use the list-shops and switch-shop tools to select a shop.'); } // Determine the source type const sourceType = determineImageSourceType(source); console.log(`Uploading image to Printify from ${sourceType} source`); let image; if (sourceType === 'file') { // Handle file upload const filePath = normalizeFilePath(source); // Validate file exists const fileInfo = getFileInfo(filePath); if (!fileInfo.exists) { throw new Error(`File not found: ${filePath}`); } console.log(`Uploading file to Printify: ${filePath}`); console.log(`File size: ${fileInfo.size} bytes`); // Check file size limits if (fileInfo.size && fileInfo.size > 20 * 1024 * 1024) { // 20MB limit throw new Error(`File is too large (${Math.round(fileInfo.size / (1024 * 1024))}MB). Maximum size is 20MB.`); } // Verify the file exists and is readable before uploading try { // Use dynamic imports for fs and path const fs = await import('fs'); const path = await import('path'); if (fs.existsSync(filePath)) { const stats = fs.statSync(filePath); console.log(`File verification before upload:`); console.log(`- Path: ${filePath}`); console.log(`- Absolute path: ${path.resolve(filePath)}`); console.log(`- Size: ${stats.size} bytes`); console.log(`- Created: ${stats.birthtime}`); console.log(`- Permissions: ${stats.mode.toString(8)}`); try { fs.accessSync(filePath, fs.constants.R_OK); console.log(`- Readable: Yes`); } catch (e: any) { console.log(`- Readable: No - ${e.message || e}`); } // Try to read the first few bytes to verify the file is readable try { const fd = fs.openSync(filePath, 'r'); const buffer = Buffer.alloc(10); const bytesRead = fs.readSync(fd, buffer, 0, 10, 0); fs.closeSync(fd); console.log(`- Read test: Successfully read ${bytesRead} bytes`); } catch (readError: any) { console.error(`- Read test failed: ${readError.message || readError}`); } // Create a debug directory and copy the file there try { const debugDir = path.join(process.cwd(), 'debug'); if (!fs.existsSync(debugDir)) { fs.mkdirSync(debugDir, { recursive: true }); } const debugFilePath = path.join(debugDir, `upload_${Date.now()}_${path.basename(filePath)}`); fs.copyFileSync(filePath, debugFilePath); console.log(`- Debug copy: ${debugFilePath}`); } catch (copyError: any) { console.error(`- Debug copy failed: ${copyError.message || copyError}`); } } else { console.error(`ERROR: File does not exist at upload time: ${filePath}`); throw new Error(`File does not exist at upload time: ${filePath}`); } } catch (verifyError: any) { console.error('Error verifying file before upload:', verifyError); throw new Error(`Failed to verify file before upload: ${verifyError.message || verifyError}`); } // Upload to Printify console.log(`Attempting to upload file to Printify: ${filePath}`); image = await printifyClient.uploadImage(fileName, filePath); console.log(`Upload successful! Image ID: ${image.id}`); console.log(`Preview URL: ${image.preview_url}`); } else { // For URLs and base64 strings, upload directly image = await printifyClient.uploadImage(fileName, source); } console.log(`Image uploaded successfully! ID: ${image.id}`); return { success: true, image, response: formatSuccessResponse( 'Image Uploaded Successfully', { 'Image ID': image.id, 'File Name': image.file_name, 'Dimensions': `${image.width}x${image.height}`, 'Preview URL': image.preview_url }, `You can now use this image ID (${image.id}) when creating a product.\n\n` + `**Example:**\n` + `\`\`\`json\n` + `"print_areas": {\n` + ` "front": { "position": "front", "imageId": "${image.id}" }\n` + `}\n` + `\`\`\`` ) }; } catch (error: any) { console.error('Error uploading image to Printify:', error); // Determine source type for better error messages const sourceType = determineImageSourceType(source); const sourceTypeLabel = sourceType === 'url' ? 'URL' : sourceType === 'file' ? 'file path' : 'base64 string'; // Create appropriate troubleshooting tips based on source type const tips = [ 'Check that your Printify API key is valid', 'Ensure your Printify account is properly connected' ]; if (sourceType === 'url') { tips.push('Make sure the URL is publicly accessible and points directly to an image file'); tips.push('The URL must start with http:// or https://'); } else if (sourceType === 'file') { tips.push('Make sure the file exists and is readable'); tips.push('Check that the path is correct and includes the full path to the file'); tips.push('The file must be a valid image format (PNG, JPEG, SVG)'); tips.push('Recommended resolution for JPEG/PNG files is 300 DPI'); tips.push('Maximum file size is 20MB'); } else { tips.push('Make sure the base64 string is valid and represents an image'); } // Gather as much diagnostic information as possible const diagnosticInfo: any = { FileName: fileName, SourceType: sourceTypeLabel, Source: sourceType === 'url' ? source : (sourceType === 'file' ? source : `${source.substring(0, 30)}...`), CurrentShop: printifyClient.getCurrentShop(), ErrorType: error.constructor.name, ErrorStack: error.stack, ErrorMessage: error.message, CurrentWorkingDirectory: process.cwd(), NodeVersion: process.version, Platform: process.platform, // Add Printify client information PrintifyClientInitialized: !!printifyClient, PrintifyShopId: printifyClient.getCurrentShopId(), PrintifyAvailableShops: printifyClient.getAvailableShops().length }; // Add file-specific diagnostics if it's a file if (sourceType === 'file') { const filePath = normalizeFilePath(source); const fileInfo = getFileInfo(filePath); diagnosticInfo.FileExists = fileInfo.exists; diagnosticInfo.FileSize = fileInfo.exists ? fileInfo.size + ' bytes' : 'N/A'; // Try to get more file details if it exists if (fileInfo.exists) { try { // Use dynamic imports for fs const fsPromise = import('fs'); const pathPromise = import('path'); // Wait for imports to complete const [fsModule, pathModule] = await Promise.all([fsPromise, pathPromise]); const fs = fsModule.default || fsModule; const path = pathModule.default || pathModule; const stats = fs.statSync(filePath); diagnosticInfo.FileCreated = stats.birthtime; diagnosticInfo.FileModified = stats.mtime; diagnosticInfo.FilePermissions = stats.mode.toString(8); diagnosticInfo.AbsolutePath = path.resolve(filePath); // Try to read the first few bytes to verify content try { const buffer = Buffer.alloc(10); const fd = fs.openSync(filePath, 'r'); // Read the first 10 bytes const bytesRead = fs.readSync(fd, buffer, 0, 10, 0); fs.closeSync(fd); diagnosticInfo.FileReadable = true; diagnosticInfo.BytesRead = bytesRead; diagnosticInfo.FileFirstBytes = buffer.toString('hex').substring(0, 20); // Check file signature to determine if it's a valid image const hexSignature = buffer.toString('hex').substring(0, 8).toLowerCase(); let fileType = 'unknown'; // Check common image signatures if (hexSignature.startsWith('89504e47')) { fileType = 'PNG'; } else if (hexSignature.startsWith('ffd8ffe')) { fileType = 'JPEG'; } else if (hexSignature.startsWith('52494646')) { fileType = 'WEBP'; } else if (hexSignature.startsWith('3c737667')) { fileType = 'SVG'; } diagnosticInfo.DetectedFileType = fileType; diagnosticInfo.FileSignature = hexSignature; } catch (readError: any) { diagnosticInfo.FileReadable = false; diagnosticInfo.FileReadError = readError.message || String(readError); } } catch (statError: any) { diagnosticInfo.FileStatError = statError.message || String(statError); } } } // Add error details if available if (error.response) { diagnosticInfo.PrintifyResponseStatus = error.response.status; diagnosticInfo.PrintifyResponseStatusText = error.response.statusText; diagnosticInfo.PrintifyResponseData = error.response.data; diagnosticInfo.PrintifyResponseHeaders = error.response.headers; } return { success: false, error, errorResponse: formatErrorResponse( error, `Printify Upload (${sourceTypeLabel})`, diagnosticInfo, tips ) }; } }
• src/index.ts:561-564 (schema)

  Zod input schema for upload_image tool: fileName (string), url (string supporting URL, local file path, or base64)
  { fileName: z.string().describe("File name"), url: z.string().describe("URL of the image to upload, path to local file, or base64 encoded image data") },
• src/printify-api.ts:478-644 (helper)

  PrintifyAPI.uploadImage low-level helper: handles URL direct upload, file reading+Sharp+base64 conversion, data URL or plain base64 upload to Printify SDK
  async uploadImage(fileName: string, source: string) { try { console.log(`Uploading image ${fileName}`); // If the source starts with http:// or https://, use the URL upload method if (source.startsWith('http://') || source.startsWith('https://')) { console.log(`Uploading from URL: ${source.substring(0, 30)}...`); return await this.client.uploads.uploadImage({ file_name: fileName, url: source }); } // If it's a file path, try to read the file and convert to base64 if (source.startsWith('file://') || source.includes(':\\') || source.includes(':/') || !source.startsWith('data:')) { try { console.log(`Attempting to read file from: ${source}`); // Handle file:// protocol let filePath = source; if (source.startsWith('file:///')) { filePath = source.replace('file:///', ''); } // Handle Windows paths if (filePath.startsWith('/')) { filePath = filePath.substring(1); } console.log(`Normalized file path: ${filePath}`); // Check if file exists if (!fs.existsSync(filePath)) { const error = new Error(`File not found: ${filePath}`); console.error('File not found error:', error); console.error('Current working directory:', process.cwd()); console.error('File path type:', typeof filePath); console.error('Absolute path check:', path.isAbsolute(filePath) ? 'Absolute' : 'Relative'); // Try to list the directory contents if possible try { const dir = path.dirname(filePath); if (fs.existsSync(dir)) { console.error('Directory exists. Contents:', fs.readdirSync(dir)); } else { console.error('Parent directory does not exist:', dir); } } catch (dirError) { console.error('Error checking directory:', dirError); } throw error; } // Get file stats const stats = fs.statSync(filePath); console.log(`File size: ${stats.size} bytes`); if (stats.size === 0) { throw new Error(`File is empty: ${filePath}`); } if (stats.size > 10 * 1024 * 1024) { // 10MB limit throw new Error(`File is too large (${Math.round(stats.size / (1024 * 1024))}MB). Maximum size is 10MB.`); } // Process the image with Sharp console.log('Processing image with Sharp before uploading...'); // Use Sharp directly const sharpInstance = sharp(filePath); const outputFormat = path.extname(filePath).toLowerCase() === '.jpg' || path.extname(filePath).toLowerCase() === '.jpeg' ? 'jpeg' : 'png'; // Convert to the appropriate format if (outputFormat === 'jpeg') { sharpInstance.jpeg({ quality: 100 }); } else { sharpInstance.png({ quality: 100 }); } // Get the buffer const buffer = await sharpInstance.toBuffer(); console.log(`Image processed successfully: ${buffer.length} bytes`); // Determine the MIME type const mimeType = outputFormat === 'jpeg' ? 'image/jpeg' : 'image/png'; // Convert to base64 const base64Data = buffer.toString('base64'); console.log(`Converted to base64 string of length ${base64Data.length}`); // Create data URL with the proper MIME type prefix const dataUrl = `data:${mimeType};base64,${base64Data}`; console.log(`Uploading with data URL (MIME type: ${mimeType})`); try { console.log(`Uploading to Printify with file_name: ${fileName}, contents length: ${base64Data.length}`); // Use the dataUrl instead of just the base64Data const result = await this.client.uploads.uploadImage({ file_name: fileName, contents: dataUrl.split(',')[1] }); console.log('Upload successful, result:', result); return result; } catch (uploadError: any) { console.error('Error during Printify upload:', uploadError); if (uploadError.response) { console.error('Response status:', uploadError.response.status); console.error('Response data:', JSON.stringify(uploadError.response.data, null, 2)); } throw uploadError; } } catch (error: any) { console.error('Error reading file:', error); const errorMessage = error.message || 'Unknown error'; // Create a detailed error message with troubleshooting information let detailedError = `Failed to process file ${source}: ${errorMessage}\n\n`; detailedError += 'Troubleshooting steps:\n'; detailedError += '1. Check if the file exists and is readable\n'; detailedError += '2. Make sure the file is a valid image (PNG, JPEG, etc.)\n'; detailedError += '3. Try using a URL or base64 encoded string instead\n'; detailedError += '\nFile processing details:\n'; detailedError += `- Attempted to read from: ${source}\n`; detailedError += `- Current working directory: ${process.cwd()}\n`; // Add stack trace if (error.stack) { detailedError += `\nStack trace:\n${error.stack}\n`; } throw new Error(detailedError); } } else if (source.startsWith('data:image/')) { // If source is base64 data with data URL prefix // Extract the base64 content const base64Content = source.split(',')[1]; console.log(`Uploading image with base64 data from data URL (length: ${base64Content.length})`); return await this.client.uploads.uploadImage({ file_name: fileName, contents: base64Content }); } else { // Otherwise, assume it's a base64 encoded string without prefix console.log(`Uploading image with base64 data (length: ${source.length})`); return await this.client.uploads.uploadImage({ file_name: fileName, contents: source }); } } catch (error: any) { console.error('Error uploading image:', error); // Add detailed debugging information const debugInfo: any = { fileName, sourceType: typeof source, sourceLength: source.length, currentWorkingDir: process.cwd(), errorMessage: error.message, errorStack: error.stack }; console.error('Detailed upload error information:', JSON.stringify(debugInfo, null, 2)); // If there's a response object, extract and log the full response data if (error.response) { console.error('Response status:', error.response.status); console.error('Response data:', JSON.stringify(error.response.data, null, 2)); // Add the full response data to the debug info debugInfo.responseStatus = error.response.status; debugInfo.responseData = error.response.data; } throw this.enhanceError(error, debugInfo); } }
• src/services/printify-uploader.ts:31-44 (helper)

  determineImageSourceType utility to classify image source as 'url', 'file', or 'base64' for routing logic
  export function determineImageSourceType(source: string): 'url' | 'file' | 'base64' { // Check if it's a URL if (source.startsWith('http://') || source.startsWith('https://')) { return 'url'; } // Check if it's a file path if (source.includes(':\\') || source.includes(':/') || source.startsWith('/') || source.includes('\\')) { return 'file'; } // Otherwise assume it's base64 return 'base64'; }