Christmas MCP Image Describe

A Model Context Protocol (MCP) server that analyzes images using OpenAI's GPT-4o Vision API and provides structured metadata to help make automatic decisions about image placement in website projects.

Features

• 🖼️ Image Analysis: Analyzes images using OpenAI GPT-4o Vision API
• 🎯 Smart Placement: Suggests optimal HTML/CSS placement for images
• 🏷️ Semantic Tags: Generates relevant semantic tags for content organization
• ♿ Accessibility: Provides appropriate alt text for screen readers
• 🔄 Batch Processing: Analyze multiple images at once
• 🛠️ MCP Integration: Works seamlessly with VS Code and other MCP clients

Installation

npm install christmas-mcp-image-describe

Setup

1. Get OpenAI API Credentials

You'll need:

• An OpenAI API key
• (Optional) An OpenAI Project ID

2. Configure Environment Variables

export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_PROJECT="your-openai-project-id"  # optional

3. Configure MCP Client

Add to your MCP configuration (e.g., VS Code settings). Choose one of these options:

Option 1: Direct file path (Recommended)

{
  "mcpServers": {
    "christmas-mcp-image-describe": {
      "command": "node",
      "args": ["./node_modules/christmas-mcp-image-describe/mcp-server.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_PROJECT": "your-openai-project-id-here"
      }
    }
  }
}

Option 2: Using npm script

{
  "mcpServers": {
    "christmas-mcp-image-describe": {
      "command": "npm",
      "args": ["start"],
      "cwd": "./node_modules/christmas-mcp-image-describe",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_PROJECT": "your-openai-project-id-here"
      }
    }
  }
}

Option 3: Debug mode (for troubleshooting)

{
  "mcpServers": {
    "christmas-mcp-image-describe": {
      "command": "node",
      "args": ["./node_modules/christmas-mcp-image-describe/debug.js"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_PROJECT": "your-openai-project-id-here"
      }
    }
  }
}

Usage

As MCP Server

The server provides two tools:

analyze_image

Analyzes a single image and returns structured metadata.

Parameters:

• imagePath (required): Path to the local image file
• context (optional): Context like "about section" or "homepage hero"
• apiKey (required): OpenAI API key
• project (optional): OpenAI project ID

analyze_images_batch

Analyzes multiple images in batch.

Parameters:

• images (required): Array of image objects with path and optional context
• apiKey (required): OpenAI API key
• project (optional): OpenAI project ID

As Node.js Library

import { analyzeImage, analyzeImages } from 'christmas-mcp-image-describe';

// Analyze a single image
const result = await analyzeImage(
  './images/hero.jpg',
  'homepage hero',
  'your-openai-api-key',
  'your-project-id'  // optional
);

console.log(result);
// {
//   "description": "Team of engineers working together",
//   "placement": "section.about.team",
//   "tags": ["team", "engineer", "office"],
//   "alt": "Engineers collaborating at desk"
// }

// Analyze multiple images
const images = [
  { path: './images/hero.jpg', context: 'homepage hero' },
  { path: './images/team.jpg', context: 'about section' }
];

const results = await analyzeImages(images, 'your-openai-api-key');
console.log(results);

Command Line Interface

# Basic usage
npx christmas-mcp-image-describe ./image.jpg

# With context
npx christmas-mcp-image-describe ./hero.png "homepage hero"

# With API key as argument
npx christmas-mcp-image-describe ./team.jpg "about section" sk-your-api-key

Output Format

The analyzer returns a structured JSON object:

{
  "description": "Brief description of the image content",
  "placement": "Suggested HTML/CSS selector (e.g., 'section.hero', 'header.logo')",
  "tags": ["array", "of", "semantic", "tags"],
  "alt": "Accessibility-friendly alt text"
}

Placement Examples

• header.logo - Company logo
• section.hero - Hero/banner images
• section.about.team - Team photos
• section.testimonials - Customer testimonial images
• article.product - Product showcase images
• footer.contact - Contact section images
• aside.sidebar - Sidebar content

API Reference

analyzeImage(imagePath, context, apiKey, project)

Analyzes a single image file.

Parameters:

• imagePath (string): Absolute or relative path to image
• context (string, optional): Context for better analysis
• apiKey (string): OpenAI API key
• project (string, optional): OpenAI project ID

Returns: Promise<Object> - Analysis result

Throws: Error if file not found, API key missing, or API call fails

analyzeImages(images, apiKey, project)

Analyzes multiple images in batch.

Parameters:

• images (Array): Array of {path, context?} objects
• apiKey (string): OpenAI API key
• project (string, optional): OpenAI project ID

Returns: Promise<Array> - Array of results with success/error status

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• BMP (.bmp)
• TIFF (.tiff, .tif)

Development

Setup Development Environment

git clone <repository>
cd christmas-mcp-image-describe
npm install

Running Tests

npm test          # Run tests once
npm run test:watch # Run tests in watch mode

Running Examples

# Set up environment variables first
export OPENAI_API_KEY="your-key"
export OPENAI_PROJECT="your-project"

# Run CLI example
npm run example ./path/to/image.jpg "context description"

Project Structure

christmas-mcp-image-describe/
├── src/
│   └── imageAnalyzer.js     # Core analysis logic
├── example/
│   ├── cli.js              # Command line interface
│   └── usage.js            # Usage examples
├── test/
│   └── imageAnalyzer.test.js # Test suite
├── index.js                # Main library export
├── mcp-server.js           # MCP server entry point
├── mcp.json               # MCP configuration
└── package.json           # Package configuration

Error Handling

The library provides detailed error messages for common issues:

• Missing API Key: "OpenAI API key is required"
• File Not Found: "Image file not found: [path]"
• Invalid File Type: "Invalid image file type: [type]"
• API Errors: "OpenAI API error: [status] - [message]"

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: Create an issue
• Documentation: README.md

Changelog

v1.0.0

• Initial release
• Image analysis with GPT-4o Vision API
• MCP server implementation
• Batch processing support
• CLI interface
• Comprehensive test suite