Image Analysis MCP Server

Instructions

Implementation Reference

• src/index.ts:130-159 (handler)

  Main execution logic for the 'analyze_image_from_path' tool. Validates input, performs path security check, reads and encodes the image file to base64, verifies MIME type, and calls the GPT analysis helper.
  } else if (toolName === 'analyze_image_from_path') { if (!isValidAnalyzeImagePathArgs(args)) { throw new McpError( ErrorCode.InvalidParams, 'Invalid arguments for analyze_image_from_path: imagePath (string) is required' ); } const imagePath = args.imagePath; // Basic security check: prevent absolute paths trying to escape common roots (adjust as needed) // This is a VERY basic check and might need refinement based on security requirements. if (path.isAbsolute(imagePath) && !imagePath.startsWith(process.cwd()) && !imagePath.startsWith(os.homedir()) && !imagePath.startsWith('/mnt/')) { // Allow relative paths, paths within cwd, home, or WSL mounts. Adjust if needed. console.warn(`Potential unsafe path access attempt blocked: ${imagePath}`); throw new McpError(ErrorCode.InvalidParams, 'Invalid or potentially unsafe imagePath provided.'); } const resolvedPath = path.resolve(imagePath); // Resolve relative paths if (!fs.existsSync(resolvedPath)) { throw new McpError(ErrorCode.InvalidParams, `File not found at path: ${resolvedPath}`); } const imageDataBuffer = fs.readFileSync(resolvedPath); const base64String = imageDataBuffer.toString('base64'); const mimeType = mime.lookup(resolvedPath) || 'application/octet-stream'; // Detect MIME type or default if (!mimeType.startsWith('image/')) { throw new McpError(ErrorCode.InvalidParams, `File is not an image: ${mimeType}`); } analysis = await this.analyzeImageWithGpt4({ type: 'base64', data: base64String, mimeType: mimeType });
• src/index.ts:96-105 (schema)

  Input schema definition for the 'analyze_image_from_path' tool, specifying the required 'imagePath' parameter.
  inputSchema: { type: 'object', properties: { imagePath: { type: 'string', description: 'Local file path of the image to analyze (must be accessible from the server execution environment)', }, }, required: ['imagePath'], },
• src/index.ts:93-106 (registration)

  Tool registration in the ListToolsRequestSchema handler, including name, description, and schema.
  { name: 'analyze_image_from_path', description: 'Loads an image from a local file path and analyzes its content using GPT-4o-mini. AI assistants need to provide a valid path for the server execution environment (e.g., Linux path if the server is running on WSL).', inputSchema: { type: 'object', properties: { imagePath: { type: 'string', description: 'Local file path of the image to analyze (must be accessible from the server execution environment)', }, }, required: ['imagePath'], }, },
• src/index.ts:40-45 (helper)

  Type guard helper for validating the arguments passed to the 'analyze_image_from_path' tool.
  const isValidAnalyzeImagePathArgs = ( args: any ): args is { imagePath: string } => // New type guard for path tool typeof args === 'object' && args !== null && typeof args.imagePath === 'string';
• src/index.ts:210-246 (helper)

  Shared helper method for analyzing images (URL or base64 data URI) using GPT-4o-mini OpenAI API.
  private async analyzeImageWithGpt4( imageData: { type: 'url', data: string } | { type: 'base64', data: string, mimeType: string } ): Promise<string> { try { let imageInput: any; if (imageData.type === 'url') { imageInput = { type: 'image_url', image_url: { url: imageData.data } }; } else { // Construct data URI for OpenAI API imageInput = { type: 'image_url', image_url: { url: `data:${imageData.mimeType};base64,${imageData.data}` } }; } const response = await openai.chat.completions.create({ model: 'gpt-4o-mini', messages: [ { role: 'system', content: 'Analyze the image content in detail and provide an explanation in English.', }, { role: 'user', content: [ { type: 'text', text: 'Please analyze the following image and explain its content in detail.' }, imageInput, // Use the constructed image input ], }, ], max_tokens: 1000, }); return response.choices[0]?.message?.content || 'Could not retrieve analysis results.'; } catch (error) { console.error('OpenAI API error:', error); throw new Error(`OpenAI API error: ${error instanceof Error ? error.message : String(error)}`); } }