PollinationServiceGateway: Multimodal API Conduit

This entry defines an implementation of the Model Context Protocol (MCP) server, facilitating interaction with the underlying Pollinations ecosystem for generating diverse AI-driven content.

Core Capabilities

• Fabricate graphical assets accessible via direct URLs, derived from descriptive textual inputs.
• Produce visual artifacts and deliver them either as embedded base64 strings or persist them to the filesystem (supporting PNG, JPEG, JPG, and WebP; default format is PNG).
• Synthesize textual responses corresponding to textual stimuli.
• Render auditory sequences based on textual instructions.
• Provide utility functions to catalog the currently accessible models for image and text creation.
• Operation requires zero pre-configuration or API key submission.
• Maintains a minimal operational footprint; lightweight and straightforward.
• Adheres strictly to the Model Context Protocol (MCP) specification.

Infrastructure Prerequisites

• Runtime Environment: Node.js must be at version 14.0.0 or newer.
• For optimal execution speed, version 16.0.0 or later is advised.
• Environments below Node.js 16 necessitate an external AbortController shim.

Initial Deployment Pathways

Installation via Smithery Automation

For automated integration with Claude Desktop environments using Smithery:

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

The most expedient method for activating the MCP server:

bash

Direct execution via npx (no persistent installation needed)

npx @pinkpixel/mcpollinations

If a persistent global utility is preferred:

bash

Global package acquisition

npm install -g @pinkpixel/mcpollinations

Server invocation

mcpollinations

Alternatively

npx @pinkpixel/mcpollinations

Alternatively, source code retrieval:

bash

Clone the repository source

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

Launch the server instance

mcpollinations

Or use npx variant

npx @pinkpixel/mcpollinations

Or direct script execution

node /path/to/MCPollinations/pollinations-mcp-server.js

MCP Integration Sequence

To establish connectivity with client applications supporting the Model Context Protocol (MCP):

1. Invoke the configuration file generation utility:

bash

If globally installed

npx @pinkpixel/mcpollinations generate-config

Or execute via node

node /path/to/MCPollinations/generate-mcp-config.js

Expedited MCP Configuration (Environment Variables)

If manual configuration is preferred over the generator, incorporate this structure into your client's MCP manifest:

{ "mcpollinations": { "command": "npx", "args": ["-y", "@pinkpixel/mcpollinations"], "env": { "token": "YOUR_TOKEN_OPTIONAL", "referrer": "your-app-or-domain-optional", "IMAGE_MODEL": "flux", "IMAGE_WIDTH": "1024", "IMAGE_HEIGHT": "1024", "IMAGE_ENHANCE": "true", "IMAGE_SAFE": "false", "TEXT_MODEL": "openai", "TEXT_TEMPERATURE": "0.7", "TEXT_TOP_P": "0.9", "TEXT_SYSTEM": "", "AUDIO_VOICE": "alloy", "OUTPUT_DIR": "./mcpollinations-output" } } }

1. Refine settings or accept defaults through the subsequent prompts.

   • Designate a storage location for outputs (relative paths are advisable for portability).
     • Windows Users: Absolute paths (e.g., C:\Users\YourName\Pictures\MCPollinations) are recommended for robust file persistence.
   • Configure optional credentials (token, referrer) within the env block.
   • Establish default specification sets for image generation (including model selection, dimensionality, etc.).
   • Establish default specification sets for text generation (including model selection).
   • Establish default specification sets for audio rendering (including voice selection).

2. Transfer the resulting mcp.json file into your host application's designated MCP settings location.

3. Re-initialize the client application.

Post-integration, invocations resemble:

"Construct a visual representation of a twilight scene over the sea utilizing the MCPollinations adapter"

Credential Handling (Non-Mandatory)

MCPollinations supports optional authentication to unlock supplementary models and higher transaction quotas. The service operates fully on the complimentary tier without credentials, but possessing an API key grants access to premium features.

Configuration Modalities

Method 1: Runtime Environment Variables (Security Preferred) bash

Set variables prior to server initiation

export POLLINATIONS_TOKEN="your-api-token" export POLLINATIONS_REFERRER="https://your-domain.com"

Then launch the server

npx @pinkpixel/mcpollinations

Method 2: MCP Configuration File (env section) When crafting the MCP configuration, inject credentials into the env block so the MCP client propagates them as environment variables to the server process:

{ "mcpollinations": { "command": "npx", "args": ["-y", "@pinkpixel/mcpollinations"], "env": { "token": "your-api-token", "referrer": "your-app-or-domain" } } }

Note: The server recognizes POLLINATIONS_TOKEN and POLLINATIONS_REFERRER as equivalents. Utilizing token and referrer within the env block is the standard MCP practice.

Authentication Parameters

• token (Optional): Your authorized token for the Pollinations API, granting elevated access.
• referrer (Optional): The domain or application identifier reporting the request source.

Both parameters are optional; omit them or leave them blank to utilize the standard public access tier.

Utilizing Configured Settings

The PollinationServiceGateway prioritizes default parameters specified in your MCP configuration's env block. When instructing an AI agent to perform a generation task:

• Your established defaults (models, output directories, parameters) are applied automatically.
• To override: Explicitly command the AI to use alternative parameters in the instruction:
• "Render an image using the kontext mechanism"
• "Archive this visual output in my Documents folder"
• "Employ a creativity factor (temperature) of 1.2 for this text generation"

Instructional Examples: - ✅ "Produce a seaside vista" → Deploys your configured model and storage path. - ✅ "Produce a seaside vista employing the flux model" → Overrides only the model specification. - ✅ "Produce a seaside vista and designate the C:\Visuals path for storage" → Overrides only the output location.

This logic ensures user preferences remain dominant unless specifically overridden for a singular operation.

Debugging and Error Resolution

Handling "AbortController is not defined"

If this exception surfaces during MCP server startup:

ReferenceError: AbortController is not defined

This typically indicates execution on a Node.js version predating 16.0.0. Recommended remediation steps:

1. Update Node.js (Highest Recommendation):

2. Migrate to Node.js version 16.0.0 or newer.

3. Utilize Global Installation Method:

4. Ensure the package is the latest version globally: bash npm install -g @pinkpixel/mcpollinations # Relaunch using npx npx @pinkpixel/mcpollinations

5. Manual Dependency Installation:

6. If the built-in polyfill fails to initialize correctly: bash npm install node-abort-controller

Verifying Node.js Version

Confirm your current environment version:

bash node --version

If the output is below 16.0.0, upgrading is suggested for maximal compatibility.

Available Toolsets

The MCP server exposes the following functional interfaces:

Visual Asset Creation Tools

1. generateImageUrl - Constructs a direct URL pointing to a newly generated image based on text input.
2. generateImage - Creates an image, transmits it as base64 data, and optionally saves the physical file (default format PNG).
3. editImage - NEW! Facilitates modification or refinement of extant imagery via textual directives.
4. generateImageFromReference - NEW! Generates novel imagery leveraging existing visuals as stylistic or compositional anchors.
5. listImageModels - Retrieves a catalog of currently supported image generation algorithms.

Textual & Auditory Synthesis Tools

1. respondText - Produces textual output conforming to prompt criteria, supporting parameter tuning.
2. respondAudio - Renders an audio clip derived from a text prompt (voice selection customizable).
3. listTextModels - Retrieves a catalog of currently supported text synthesis models.
4. listAudioVoices - Retrieves a catalog of all available vocal profiles for audio rendering.

Text Synthesis Specifics

Supported Configuration Parameters

The respondText utility allows granular control via several parameters:

• model: Selection from the available text models (consult listTextModels for the current inventory).
• temperature (Range 0.0 to 2.0): Influences the stochastic nature of the output.
• Lower spectrum (0.1–0.7) $\rightarrow$ tighter focus, more predictable results.
• Higher spectrum (0.8–2.0) $\rightarrow$ increased originality and deviation.
• top_p (Range 0.0 to 1.0): Governs output diversity through nucleus sampling methodology.
• Lower values $\rightarrow$ favors the most probable tokens.
• Higher values $\rightarrow$ incorporates a wider selection of potential tokens.
• system: A foundational directive used to shape the model's persona, operational constraints, or required response format.

Customizing Text Generation Flow

javascript // Illustrative options structure for respondText const configuration = { model: "openai", // Algorithm selection temperature: 0.7, // Balanced randomness profile top_p: 0.9, // High allowance for token diversity system: "Your role is to act as a lucid explainer, prioritizing clarity and brevity in all responses." };

Configuration Examples (MCP Environment Defaults)

Inject these settings into the env block of your MCP configuration to establish persistent defaults for the server:

{ "mcpollinations": { "env": { "TEXT_MODEL": "openai", "TEXT_TEMPERATURE": "0.7", "TEXT_TOP_P": "0.9", "TEXT_SYSTEM": "You are a helpful coding assistant." } } }

Image-to-Image Manipulation Capabilities (New Features)

PollinationServiceGateway now includes sophisticated image-to-image processing tools accessible via two dedicated functions:

editImage Function

Ideal for targeted alterations of existing visual data: - Element Subtraction: "erase the canine from this photograph" - Element Addition: "insert avian life into this panorama" - Scene Replacement: "substitute the existing backdrop with a mountainous terrain" - Aesthetic Shifts: "apply a high-contrast lighting scheme"

generateImageFromReference Function

Excellent for stylistic translation and generating conceptually similar new assets: - Style Transfer: "render this photograph in the style of Impressionism" - Format Conversion: "transform this rendering into a cel-shaded cartoon look" - Conceptual Variation: "engineer a cyberpunk rendition of this scene" - Artistic Rendering: "represent this using charcoal sketch aesthetics"

Supported Underlying Models

• kontext: Optimized algorithm specifically tuned for sequential image manipulation.
• nanobanana: Novel Google architecture supporting bidirectional (text-to-image and image-to-image) tasks.
• seedream: Novel ByteDance architecture supporting bidirectional (text-to-image and image-to-image) tasks.

Multi-reference inputs: Both editImage and generateImageFromReference accept either a singular imageUrl or an ordered collection (array) of URLs. The server serializes arrays into the API's expected comma-delimited image parameter. Sequence importance: kontext prioritizes the initial reference; nanobanana handles up to approximately 4 references effectively; seedream supports a maximum of 10 references.

Crucial Caveat: These functions mandate publicly resolvable HTTP(S) URLs for input imagery. Local file references, direct uploads, or embedded data URLs are unsupported by this server component. If local assets are required, they must first be hosted externally (e.g., temporary hosting, cloud storage, or a raw link in a repository) before passing the resultant URL to the tool.

Operational Example

javascript // Modifying an existing asset const modificationResult = await editImage( "recolor the walls to a deep sapphire tone", "https://externalsite.com/original.png", "nanobanana" // Options: "kontext", "nanobanana", "seedream" );

// Creating a derivative based on reference const derivativeResult = await generateImageFromReference( "apply a heavy oil-paint texture", "https://externalsite.com/source_photo.jpg", "seedream" // Options: "kontext", "nanobanana", "seedream" );

Image Synthesis Specifics

Default Output Configuration

When invoking the generateImage tool:

• Files are written to the filesystem by default, using the PNG encoding standard.
• The default persistence location is the execution directory of the MCP server process.
• The 'flux' algorithm is utilized as the standard model selection.
• A unique, randomly generated seed is assigned to every invocation (ensuring output variance).
• Base64 encoded visual data is always transmitted back to the caller, irrespective of file saving status.

Customizing Visual Generation

javascript // Parameter structure example for generateImage const generationSettings = { // Model choice (defaults to 'flux') // Valid algorithms: "flux", "turbo", "kontext", "nanobanana", "seedream" model: "flux",

// Dimensional attributes width: 1024, height: 1024,

// Generation controls seed: 12345, // Fixed value for deterministic output (default is dynamic random value) enhance: true, // Pre-process prompt via LLM for refinement (default is true) safe: false, // Content moderation filter status (default is off)

// Filesystem persistence controls saveToFile: true, // Inhibits disk write if set to false outputPath: "/path/where/to/store", // Specify a custom destination directory fileName: "my_unique_asset_name", // Base name, extension is handled separately format: "png" // Permissible extensions: png, jpeg, jpg, or webp };

Output File Location Management

When an application (like Claude) interacts with the MCP server:

1. Persistence Location: Images are archived in the working directory actively used by the MCP server instance, not the client application's installation path.

2. Manual Server Startup: If launched manually from a specific directory, files populate that location by default.

3. Automated Client Launch: If the client (e.g., Claude Desktop) initiates the server, assets reside in the client's designated operational folder (often buried within application support data).

💡 Windows User Advisory: To guarantee predictable file storage on Windows systems, configure the outputPath parameter in your MCP settings using absolute directory paths (e.g., C:\Users\YourName\Pictures\MCPollinations) rather than relative notations (e.g., ./mcpollinations-output). Relative resolution can vary based on the launching context.

Locating Generated Artwork

• The textual response delivered by Claude following asset creation includes the complete filesystem path where the artifact was saved.
• The outputPath parameter allows for mapping outputs to familiar locations like 'Downloads' or 'Pictures'.
• Recommended practice: Instruct Claude to route outputs to a readily accessible folder.

Guaranteed Unique Naming Convention

The MCP server employs robust safeguards to prevent data loss via accidental file overwrites:

1. Default Naming Scheme: Filenames typically incorporate:
2. A sanitized prefix of the input prompt (first 20 characters).
3. A high-precision timestamp.

4. A randomly generated numerical suffix.

5. User-Specified Filenames: If a base name is provided, collision avoidance is still active:

6. If a file with the exact specified name exists, an automatic numeric sequence marker is appended.
7. Example progression: scene.png, scene_1.png, scene_2.png, etc.

This design ensures that repeated generations using the same prompt or base name will always result in new, distinct files.

Accessing Base64 Payloads

The base64 encoded visual stream is always returned by the tool, even if the file is simultaneously saved to disk. This data is immediately useful for:

• Embedding directly into HTML structures (<img src="data:image/png;base64,..." />).
• Seamless forwarding to other dependent services or APIs.
• In-memory processing without requiring filesystem interaction.
• Rendering within client interfaces that recognize Data URIs.

Developer Interface

To incorporate this functionality within a custom Node.js project:

bash

Installation as a project dependency

npm install @pinkpixel/mcpollinations

Import statements

import { generateImageUrl, generateImage, repsondText, respondAudio, listTextModels, listImageModels, listAudioVoices } from '@pinkpixel/mcpollinations';

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface implemented as a JavaScript object. Its primary purpose is to facilitate the transmission of HTTP requests from a web browser environment back to a remote web server. This capability allows web-based applications to initiate server communication asynchronously after the initial page load, subsequently receiving data without reloading the entire view. XMLHttpRequest forms a foundational component of Asynchronous JavaScript and XML (Ajax) programming paradigms. Before Ajax gained prominence, server interaction was primarily managed through traditional hyperlink navigation or form submissions, actions which typically resulted in complete page replacement.