christmas-mcp-image-describe/README.md

MCP server that analyzes images and provides structured metadata for website placement decisions using OpenAI GPT-4o Vision API

# 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

```bash
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

```bash
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)**
```json
{
  "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**
```json
{
  "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)**
```json
{
  "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

```javascript
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

```bash
# 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:

```json
{
  "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

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

### Running Tests

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

### Running Examples

```bash
# 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](https://github.com/Chr1stm4s/christmas-mcp-image-describe/issues)
- Documentation: [README.md](https://github.com/Chr1stm4s/christmas-mcp-image-describe#readme)

## Changelog

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