Skip to content

OVERVIEW.md

Latest commit

 

History

History
293 lines (222 loc) · 11.4 KB

OVERVIEW.md

File metadata and controls

293 lines (222 loc) · 11.4 KB

MCPollinations Project Overview 🎨✨

Last Updated: September 26, 2025

Project Identity

MCPollinations is a comprehensive Model Context Protocol (MCP) server that enables AI assistants to generate multimodal content through the Pollinations APIs. It serves as a bridge between AI applications and advanced generative AI capabilities for images, text, and audio.

Purpose & Vision

MCPollinations democratizes access to multimodal AI generation by providing:

  • 🖼️ Professional Image Generation - Create high-quality images from text prompts
  • 🎨 Advanced Image Editing - Modify existing images with natural language instructions
  • 📝 Intelligent Text Generation - Generate contextual text responses with fine-tuned parameters
  • 🎵 Voice Synthesis - Convert text to natural-sounding speech with multiple voice options
  • 🔧 MCP Protocol Compliance - Seamless integration with AI applications like Claude Desktop
  • 🎛️ Flexible Configuration - Customizable parameters and optional authentication for enhanced features

Architecture Overview

MCPollinations follows a service-oriented architecture with a thin proxy design, providing minimal abstraction over the Pollinations API while adding valuable MCP protocol compliance and enhanced functionality.

Core Components

MCPollinations/
├── pollinations-mcp-server.js    # 🚀 Main MCP server entry point
├── src/
│   ├── index.js                  # 📦 Service exports and API client
│   ├── schemas.js                # 🔧 Centralized MCP tool definitions
│   └── services/                 # 🎯 Modular service architecture
│       ├── imageService.js       # 🎨 Image generation & editing
│       ├── imageSchema.js        # 📋 Image tool schemas
│       ├── audioService.js       # 🎵 Audio generation
│       ├── audioSchema.js        # 📋 Audio tool schemas
│       ├── textService.js        # 📝 Text generation
│       └── textSchema.js         # 📋 Text tool schemas
├── generate-mcp-config.js        # ⚙️ Interactive configuration generator
└── tests/                        # 🧪 Testing suite
    ├── test-mcp-client.js        # Basic MCP functionality test
    ├── test-image-save.js        # Image saving test
    └── test-list-tools.js        # Tool enumeration test

Design Principles

  1. Service-Schema Pairing: Each service module has a corresponding schema module ensuring consistency between implementation and MCP API contract
  2. Thin Proxy Design: Minimal abstraction over Pollinations API while adding MCP compliance and enhanced features
  3. Modular Architecture: Clear separation of concerns between image, text, and audio services
  4. Configuration-Driven: Comprehensive configuration system supporting various deployment patterns
  5. Error-First Design: Robust error handling with MCP-compliant error responses

Technical Specifications

Runtime Requirements

  • Node.js: Version 14.0.0+ (16.0.0+ recommended for best performance)
  • AbortController: Built-in polyfill for Node.js < 16
  • ES Modules: Project uses "type": "module"

Key Dependencies

  • @modelcontextprotocol/sdk: MCP protocol implementation
  • node-fetch: HTTP client for API requests
  • play-sound: Audio playback functionality
  • node-abort-controller: AbortController polyfill

Authentication Support

  • Optional token-based auth for enhanced API access
  • Environment variables supported:
    • token, referrer (preferred for MCP env)
    • POLLINATIONS_TOKEN, POLLINATIONS_REFERRER (also accepted)
  • Graceful fallback to free tier if unset

Capabilities & Tools

MCPollinations provides 9 specialized MCP tools across three categories:

🎨 Image Generation Tools (5 tools)

  1. generateImageUrl - Generate image URLs from text prompts

    • Models: flux (default), turbo, kontext, nanobanana, seedream
    • Customizable dimensions, seeds, enhancement options

  2. generateImage - Generate images with file saving

    • Returns base64 data AND saves to file (PNG default)
    • Unique filename generation prevents overwrites
    • Supports PNG, JPEG, JPG, WebP formats

  3. editImage ⭐ New in v1.2.0

    • Edit existing images with natural language instructions
    • Perfect for: removing objects, adding elements, changing backgrounds
    • Supports models: kontext (default), nanobanana, seedream

  4. generateImageFromReference ⭐ New in v1.2.0

    • Generate new images using existing images as reference
    • Perfect for: style transfer, artistic interpretations, format changes
    • Supports models: kontext (default), nanobanana, seedream

  5. listImageModels - Enumerate available image generation models

📝 Text Generation Tools (2 tools)

  1. respondText - Advanced text generation with fine-tuning parameters

    • Models: openai (default), and others via listTextModels
    • Parameters: temperature (randomness), top_p (diversity), system prompts
    • Privacy-first: always includes private=true

  2. listTextModels - Dynamic model listing from Pollinations API

🎵 Audio Generation Tools (2 tools)

  1. respondAudio - Text-to-speech generation

    • 13 available voices: alloy, echo, fable, onyx, nova, shimmer, coral, verse, ballad, ash, sage, amuch, dan
    • Customizable voice instructions for character/style
    • Returns base64 audio data

  2. listAudioVoices - Enumerate all available voice options

File Management & Storage

Default Behavior

  • Auto-Save: Images are automatically saved to disk by default
  • Output Directory: ./mcpollinations-output (configurable)
  • Format Support: PNG (default), JPEG, JPG, WebP
  • Unique Naming: Automatic collision avoidance with timestamp and random suffixes

Filename Generation Strategy

// Default pattern
`${sanitized_prompt}_${timestamp}_${random_suffix}.${format}`

// Custom filename collision handling
`${custom_name}.png`     → `${custom_name}_1.png`     → `${custom_name}_2.png`

Cross-Platform Considerations

  • Relative Paths: Default for portability
  • Windows Guidance: Absolute paths recommended for reliability
  • Directory Creation: Automatic recursive directory creation

Configuration & Integration

Installation Methods

  1. Direct Usage (No installation required)

    npx @pinkpixel/mcpollinations

  2. Global Installation

    npm install -g @pinkpixel/mcpollinations
mcpollinations

  3. Smithery Integration (Claude Desktop)

    npx -y @smithery/cli install @pinkpixel-dev/mcpollinations --client claude

  4. Repository Clone (Development)

    git clone https://github.com/pinkpixel-dev/mcpollinations.git

Configuration Generator

The interactive configuration generator (generate-mcp-config.js) outputs an env-only MCP config and provides:

  • ⚙️ Custom output directory (OUTPUT_DIR)
  • 🔐 Optional authentication (token, referrer)
  • 🎛️ Default parameters for image/text/audio via env keys
  • 📁 Platform-specific path guidance

MCP Client Integration

MCPollinations integrates seamlessly with MCP-compatible clients:

{
  "mcpServers": {
    "mcpollinations": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/mcpollinations"],
      "env": {
        "token": "optional-token",
        "referrer": "optional-referrer",
        "OUTPUT_DIR": "./mcpollinations-output"
      }
    }
  }
}

Development Workflow

Quick Development Commands

# Start the MCP server
npm start

# Generate MCP configuration interactively  
npm run generate-config

# Run tests
npm test                    # Basic MCP client test
npm run test:image-save     # Test image saving functionality
npm run test:list-tools     # Test tool listing

# Install globally for system-wide use
npm install -g .

Development Tools & Testing

  • MCP Inspector: Compatible for interactive testing and debugging
  • Test Suite: Comprehensive testing for core functionality
  • Error Handling: Robust error reporting with detailed messages
  • Logging: Structured logging for debugging and monitoring

Adding New Tools

  1. Create service function in appropriate src/services/*Service.js file
  2. Define schema in corresponding src/services/*Schema.js file
  3. Export schema from src/schemas.js
  4. Add tool handler in pollinations-mcp-server.js CallToolRequestSchema handler
  5. Update default configuration in generate-mcp-config.js

Project Status & Evolution

Current Version: 1.3.0 (September 2025)

Recent Breaking Changes:

  • 🚫 Removed gptimage model - No longer supported by Pollinations API
  • 🚫 Removed transparent background support - Feature discontinued
  • ✅ Updated image-to-image operations - Now use kontext model as default

Version History Highlights

  • v1.2.0 (July 2025): Added image-to-image generation tools
  • v1.1.3 (July 2025): Enhanced text generation with fine-tuning parameters
  • v1.1.2 (July 2025): Optional authentication support added
  • v1.0.7 (April 2025): Major update with file saving and comprehensive improvements
  • v1.0.6 (April 2025): Node.js compatibility improvements
  • v1.0.5 (April 2025): Initial public release

Ecosystem Integration

  • ✅ Smithery: Official listing and automated installation
  • ✅ MCP Clients: Full compatibility with Claude Desktop and other MCP clients
  • ✅ CI/CD: GitHub Actions for automated testing and publishing
  • ✅ Docker: Containerization support for deployment flexibility
  • ✅ NPM: Published package for easy distribution

Quality Assurance & Standards

Code Quality

  • 📏 Semantic Versioning: Strict adherence to SemVer principles
  • 📝 Comprehensive Documentation: README, CHANGELOG, CONTRIBUTING guides
  • 🧪 Testing Suite: Automated tests for core functionality
  • 🔍 Error Handling: Robust error management with detailed reporting

Security & Privacy

  • 🔐 Optional Authentication: Token-based enhanced access
  • 🛡️ Privacy-First: Default private=true parameters
  • ⚡ Rate Limiting: Graceful handling of API rate limits
  • 🔒 Secure Defaults: Safe parameter defaults for content filtering

Development Standards

  • 📋 MIT License: Open source with permissive licensing
  • 🌐 Cross-Platform: Linux, Windows, macOS compatibility
  • 📦 Dependency Management: Minimal, well-maintained dependencies
  • 🔄 Backward Compatibility: Careful handling of breaking changes with migration guides

Future Considerations

While no formal roadmap exists, potential areas for future development include:

  • 🔄 Enhanced Model Support: Integration with new Pollinations models as they become available
  • 🎛️ Advanced Configuration: More granular control over generation parameters
  • 📊 Usage Analytics: Optional usage tracking for optimization insights
  • 🌐 Multi-Language Support: Internationalization for broader adoption
  • 🔧 Plugin Architecture: Extensibility for custom functionality

Made with ❤️ by Pink Pixel
"Dream it, Pixel it" ✨