MCPO - MCP Pollinations Proxy

🚀 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

Clone the repository
git clone <repository-url> cd mcpo
Build and run the container
docker-compose build docker-compose up
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

Container starts with mcpo CLI tool
mcpo proxies the pollinations-model-context-protocol MCP server
MCP server capabilities become available via OpenAPI endpoints
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

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

MCPO - MCP Pollinations Proxy