# MCP Clipboard Image Server

A Model Context Protocol (MCP) server that enables **Claude Code** to paste images directly from your system clipboard for instant analysis and processing.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-blue)](https://claude.ai/code)

## Features

- 🖼️ Paste images directly from clipboard (Ctrl+C/Cmd+C → MCP tool)
- 🔄 Cross-platform support (Windows, macOS, Linux)
- 📁 Automatic temporary file creation with accessible paths
- 🎨 Support for multiple image formats (PNG, JPEG, GIF, BMP, TIFF)
- ⚡ Format conversion capabilities
- 🛡️ Robust error handling and user feedback
- 🔍 Automatic format detection via magic numbers

## Installation

```bash
npm install
npm run build
```

## Dependencies

- **System Dependencies**: The server requires platform-specific clipboard utilities:
  - **macOS**: Built-in osascript support, optional `pngpaste` for enhanced functionality
  - **Linux**: `xclip` (X11) or `wl-paste` (Wayland)
  - **Windows**: Built-in PowerShell support

### Linux Setup
```bash
# For X11-based systems
sudo apt-get install xclip

# For Wayland-based systems
sudo apt-get install wl-clipboard
```

### macOS Setup (Optional Enhancement)
```bash
# Install pngpaste for better clipboard handling
brew install pngpaste
```

## Usage

## 🚀 Quick Start for Claude Code

### Step 1: Install the Server
```bash
# Clone and build
git clone https://github.com/yourusername/mcp-clipboard-image-server.git
cd mcp-clipboard-image-server
npm install
npm run build
```

### Step 2: Add to Claude Code
Choose one of these methods:

#### Method A: Project-scoped (Recommended)
```bash
claude mcp add clipboard-image -s project -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js
```

#### Method B: User scope (Global - Available everywhere)
```bash
claude mcp add clipboard-image -s user -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js
```

#### Method C: Local scope
```bash
claude mcp add clipboard-image -s local -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js
```

#### Method D: Manual configuration
Create `.mcp.json` in your project root:
```json
{
  "mcpServers": {
    "clipboard-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clipboard-image-server/dist/index.js"],
      "env": {}
    }
  }
}
```

### Step 3: Restart Claude Code
Restart Claude Code to load the new MCP server.

### Step 4: Test it!
1. Copy any image to clipboard
2. In Claude Code, say: **"paste image"**
3. Claude will automatically capture and analyze your image!

## 🎯 Claude Code Usage Examples

### Basic Usage
```
User: paste image
Claude: [Captures image and describes what's in it]

User: paste image and help me debug this error
Claude: [Analyzes screenshot of error and provides solutions]

User: paste image and explain this diagram
Claude: [Interprets technical diagrams, flowcharts, etc.]
```

### Command Shortcuts

#### Claude Code Slash Commands
```bash
# Setup slash commands in Claude Code
./setup-claude-commands.sh

# Now you can use in Claude Code:
/pasteimage             # Paste and analyze image
/pasteimage --debug     # Paste and debug errors  
/pasteimage --explain   # Paste and explain diagrams
/pi                     # Quick shortcut
```

#### Shell Commands  
```bash
# Install shell commands
./install-commands.sh

# Use from terminal:
paste-image --debug     # Paste and debug errors
paste-image --explain   # Paste and explain diagrams
pi                      # Quick alias for paste-image
```

### Advanced Usage
- **Screenshots**: Perfect for debugging UI issues, error messages
- **Diagrams**: Architecture diagrams, flowcharts, wireframes  
- **Code snippets**: Screenshots of code for review and suggestions
- **Data visualizations**: Charts, graphs, analytics dashboards

### Available Tools

#### `paste_image`

Captures an image from the system clipboard and saves it to a temporary file.

**Parameters:**
- `filename` (optional): Custom filename without extension (UUID generated if not provided)
- `format` (optional): Target format - "png", "jpeg", "jpg", "gif", "bmp", "tiff" (preserves original if not specified)

**Usage Examples:**
1. Basic paste: `paste_image`
2. Custom filename: `paste_image({"filename": "screenshot"})`
3. Format conversion: `paste_image({"format": "jpeg"})`
4. Both options: `paste_image({"filename": "diagram", "format": "png"})`

**Returns:**
- Success: File path, format info, and size details
- Error: Helpful troubleshooting information

## 🎯 Slash Commands

After running `./setup-claude-commands.sh`, you can use these slash commands directly in Claude Code:

| Command | Description | Usage |
|---------|-------------|-------|
| `/pasteimage` | Paste and analyze image | `/pasteimage` |
| `/pasteimage --debug` | Paste and debug errors | `/pasteimage --debug` |
| `/pasteimage --explain` | Paste and explain diagrams | `/pasteimage --explain` |
| `/pi` | Quick paste shortcut | `/pi` |
| `/paste-debug` | Paste and debug (alias) | `/paste-debug` |
| `/paste-explain` | Paste and explain (alias) | `/paste-explain` |

### Slash Command Examples:
```
/pasteimage                    → Paste image and analyze
/pasteimage --debug            → Paste image and debug error
/pi                           → Quick paste 
/paste-debug                  → Debug screenshot
```

## Workflow

1. **Copy Image**: Copy any image to clipboard (Ctrl+C/Cmd+C)
2. **Call Tool**: Use `paste_image` tool in Claude Code
3. **Get Path**: Receive temporary file path
4. **Process**: Claude Code can now read and analyze the image

## Error Handling

The server provides comprehensive error handling for:
- No image in clipboard
- Clipboard access permissions
- Unsupported formats
- File system errors
- Platform compatibility issues

## Security Considerations

- Images are saved to system temporary directory
- No network requests or external API calls
- Temporary files use UUID naming to avoid conflicts
- Cross-platform clipboard access uses standard system utilities
- No persistent data storage

## Platform Support

| Platform | Primary Method | Fallback Method | Status |
|----------|---------------|-----------------|--------|
| macOS | osascript | pngpaste | ✅ Supported |
| Linux | xclip | wl-paste | ✅ Supported |
| Windows | PowerShell | - | ✅ Supported |

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Start production server
npm start
```

## Troubleshooting

### Common Issues

1. **"No image found in clipboard"**
   - Ensure an image is actually copied (not just selected)
   - Try copying the image again
   - Some applications may not properly set clipboard data

2. **Clipboard access errors**
   - Check system permissions for clipboard access
   - Ensure required utilities are installed (xclip, wl-paste)
   - Try restarting the MCP server

3. **Platform-specific issues**
   - **Linux**: Install `xclip` or `wl-paste` depending on display server
   - **macOS**: Consider installing `pngpaste` for better compatibility
   - **Windows**: Ensure PowerShell execution policy allows scripts

### Debug Mode

Set environment variable for detailed logging:
```bash
DEBUG=1 node dist/index.js
```

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

For bug reports and feature requests, please use the GitHub issues page.