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 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**