# 🚀 MCPO - MCP Pollinations Proxy

A Docker-containerized MCP (Model Context Protocol) proxy that combines **mcpo** CLI tool with **Pollinations MCP** server, providing AI image, text, audio, and vision generation capabilities through standard REST endpoints.

## 🌟 Features

### 🎨 Multimodal AI Capabilities
- **Image Generation**: Create stunning images from text prompts with 1024x1024 default resolution
- **Image-to-Image**: Transform existing images using text descriptions  
- **Vision Analysis**: Analyze, describe, compare images and extract text (OCR)
- **Text Generation**: Simple and advanced text generation with system prompts
- **Text-to-Speech**: Convert text to speech with multiple voice options
- **Audio Generation**: Create contextual audio responses

### 🔧 Technical Features
- **OpenAPI REST Endpoints**: Standard HTTP/REST interface for all MCP capabilities
- **Docker Containerized**: Easy deployment and consistent environment
- **Real-time Processing**: Direct API integration with Pollinations services
- **Multiple Model Support**: Access various AI models for different tasks

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose
- Port 7777 available

### Installation & Usage

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd mcpo
   ```

2. **Build and run the container**
   ```bash
   docker-compose build
   docker-compose up
   ```

3. **Access the service**
   - Service runs on: `http://localhost:7777`
   - OpenAPI docs: `http://localhost:7777/docs`
   - API endpoints: `http://localhost:7777/api/...`

### Development Commands

```bash
# Build the container
docker-compose build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs

# Stop the service
docker-compose down
```

## 🎯 API Endpoints

The service exposes Pollinations MCP server functionality through REST endpoints:

### 🖼️ Image Generation
- `POST /api/generateImage` - Generate image from text prompt
- `POST /api/generateImageUrl` - Get image generation URL
- `POST /api/generateImageToImage` - Transform image with text prompt
- `GET /api/listImageModels` - List available image models

### 📝 Text Generation  
- `POST /api/generateText` - Simple text generation
- `POST /api/generateAdvancedText` - Advanced text with system prompts
- `GET /api/listTextModels` - List available text models

### 👁️ Vision & Analysis
- `POST /api/analyzeImageFromUrl` - Analyze image from URL
- `POST /api/analyzeImageFromData` - Analyze base64 image data
- `POST /api/compareImages` - Compare two images
- `POST /api/extractTextFromImage` - OCR text extraction

### 🎵 Audio Generation
- `POST /api/sayText` - Text-to-speech conversion
- `POST /api/respondAudio` - Generate contextual audio responses
- `GET /api/listAudioVoices` - List available voices

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────┐    ┌─────────────────────┐
│   Client App    │───▶│  MCPO Proxy  │───▶│  Pollinations API   │
│   (HTTP/REST)   │    │  (Port 7777) │    │  (MCP Protocol)     │
└─────────────────┘    └──────────────┘    └─────────────────────┘
```

### Container Stack
- **Base**: Node.js 18 Alpine Linux  
- **Python**: Installed for mcpo CLI tool
- **Port**: 7777 exposed for HTTP access
- **Host**: Configured to bind to 0.0.0.0

### Service Flow
1. Container starts with `mcpo` CLI tool
2. `mcpo` proxies the `pollinations-model-context-protocol` MCP server
3. MCP server capabilities become available via OpenAPI endpoints
4. External applications use standard HTTP/REST calls

## 📁 Project Structure

```
mcpo/
├── docker-compose.yml          # Docker compose configuration
├── Dockerfile                  # Container definition
├── CLAUDE.md                   # Development instructions
├── pollinations-mcp-src/       # MCP server source code
│   ├── src/
│   │   ├── services/
│   │   │   ├── imageService.js     # Image generation & transformation
│   │   │   ├── textService.js      # Text generation (simple & advanced)
│   │   │   ├── audioService.js     # Text-to-speech & audio
│   │   │   ├── visionService.js    # Image analysis & OCR
│   │   │   ├── authService.js      # Authentication
│   │   │   └── resourceService.js  # Resource management
│   │   ├── utils/
│   │   │   ├── coreUtils.js        # Core utilities
│   │   │   ├── polyfills.js        # Node.js polyfills
│   │   │   └── schemaUtils.js      # Schema validation
│   │   └── index.js                # Main MCP server
│   └── pollinations-mcp.js         # Entry point
└── README.md                    # This file
```

## 🔧 Configuration

### Default Settings
- **Image Resolution**: 1024x1024 pixels
- **Image Quality**: Private=true, NoLogo=true, Enhance=true
- **Text Generation**: OpenAI-compatible models
- **Audio Format**: MP3 with Alloy voice
- **Vision Models**: GPT-4o for image analysis

### Environment Variables
The container automatically configures the MCP proxy without additional environment variables needed.

## 🎨 Usage Examples

### Image Generation
```bash
curl -X POST http://localhost:7777/api/generateImage \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset",
    "options": {
      "width": 1024,
      "height": 1024,
      "model": "flux"
    }
  }'
```

### Vision Analysis
```bash
curl -X POST http://localhost:7777/api/analyzeImageFromUrl \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/image.jpg",
    "prompt": "What do you see in this image?"
  }'
```

### Text-to-Speech
```bash
curl -X POST http://localhost:7777/api/sayText \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test of text to speech",
    "voice": "alloy",
    "format": "mp3"
  }'
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Pollinations.AI](https://pollinations.ai) for the amazing AI APIs
- [Model Context Protocol](https://github.com/modelcontextprotocol) for the MCP standard
- [mcpo](https://github.com/mcpo-tools/mcpo) CLI tool for MCP to OpenAPI conversion

## 🔗 Links

- [Pollinations API Documentation](https://github.com/pollinations/pollinations/blob/master/APIDOCS.md)
- [Docker Hub](https://hub.docker.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

---

**Built with ❤️ using Docker, Node.js, and Python**