🚀 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

   git clone <repository-url>
   cd mcpo
   

2. Build and run the container

   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

# 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

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

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

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 file for details.

🙏 Acknowledgments

• Pollinations.AI for the amazing AI APIs
• Model Context Protocol for the MCP standard
• mcpo CLI tool for MCP to OpenAPI conversion

🔗 Links

• Pollinations API Documentation
• Docker Hub
• Model Context Protocol

---

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