`feat: Add optional authentication support and related changes`

.gitignore

@@ -66,6 +66,7 @@ pids
 .env.test.local
 .env.production.local
 .env.local
+mcp.json
 
 # parcel-bundler cache
 .cache

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to the MCPollinations will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.2] - `2025-07-25`
+
+### Added
+- **Optional Authentication Support**: Added support for optional `token` and `referrer` parameters to access enhanced Pollinations API features
+  - Environment variable support: `POLLINATIONS_TOKEN` and `POLLINATIONS_REFERRER`
+  - MCP configuration file support with new `auth` section
+  - Authorization header (`Bearer token`) and Referer header support in all API requests
+  - Backward compatible - free tier continues to work without authentication
+- Enhanced MCP configuration generator with authentication prompts
+- Updated example-mcp.json to include auth section template
+- Comprehensive documentation updates for authentication setup
+- **Windows Path Guidance**: Added documentation for Windows users to use absolute paths for reliable file saving
+
+### Changed
+- All service functions now accept optional `authConfig` parameter
+- MCP server now reads and passes authentication configuration to services
+- Configuration generator includes new authentication configuration section
+
+### Fixed
+- Improved file path handling documentation for Windows compatibility
+
 ## [1.0.7] - `2025-04-08`
 
 ### Added

LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Pink Pixel
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

README.md

@@ -82,6 +82,8 @@ node /path/to/MCPollinations/generate-mcp-config.js
 
 2. Follow the prompts to customize your configuration or use the defaults.
    - Set custom output and temporary directories (defaults to relative paths for portability)
+     - **Windows users**: Consider using absolute paths (e.g., `C:\Users\YourName\Pictures\MCPollinations`) for more reliable file saving
+   - **Configure optional authentication** (token and referrer for enhanced access)
    - Configure default parameters for image generation (with a list of available models, dimensions, etc.)
    - Configure default parameters for text generation (with a list of available models)
    - Configure default parameters for audio generation (voice)
@@ -94,6 +96,41 @@ After integration, you can use commands like:
 
 "Generate an image of a sunset over the ocean using MCPollinations"
 
+## Authentication (Optional)
+
+MCPollinations supports optional authentication to provide access to more models and better rate limits. The server works perfectly without authentication (free tier), but users with API tokens can get enhanced access.
+
+### Configuration Methods
+
+**Method 1: Environment Variables (Recommended for security)**
+```bash
+# Set environment variables before running the server
+export POLLINATIONS_TOKEN="your-api-token"
+export POLLINATIONS_REFERRER="https://your-domain.com"
+
+# Then run the server
+npx @pinkpixel/mcpollinations
+```
+
+**Method 2: MCP Configuration File**
+When generating your MCP configuration, you'll be prompted for optional authentication settings:
+```json
+{
+  "mcpollinations": {
+    "auth": {
+      "token": "your-api-token",
+      "referrer": "https://your-domain.com"
+    }
+  }
+}
+```
+
+### Authentication Parameters
+
+- **`token`** (optional): Your Pollinations API token for enhanced access
+- **`referrer`** (optional): Your domain/application referrer URL
+
+Both parameters are completely optional. Leave them empty or unset to use the free tier.
 
 ## Troubleshooting
 
@@ -193,6 +230,8 @@ When using Claude or another application with the MCP server:
 
 3. If Claude Desktop launches the MCP server automatically, images will be saved in Claude Desktop's working directory (typically in an application data folder).
 
+**💡 Windows Users**: For reliable file saving on Windows, use absolute paths in your MCP configuration instead of relative paths (e.g., `C:\Users\YourName\Pictures\MCPollinations` instead of `./mcpollinations-output`). Relative paths may not resolve as expected depending on the working directory context.
+
 ### Finding Your Generated Images
 
 - The response from Claude after generating an image includes the full file path where the image was saved

example-mcp.json

@@ -8,6 +8,10 @@
     "resources": {
       "output_dir": "./mcpollinations-output"
     },
+    "auth": {
+      "token": "",
+      "referrer": ""
+    },
     "default_params": {
       "image": {
         "model": "flux",

generate-mcp-config.js

@@ -19,6 +19,10 @@ const defaultConfig = {
     "resources": {
       "output_dir": "./mcpollinations-output",
     },
+    "auth": {
+      "token": "",
+      "referrer": ""
+    },
     "default_params": {
       "image": {
         "model": "flux",
@@ -93,6 +97,31 @@ async function generateMcpConfig() {
       config[configKey].resources.output_dir = outputDir;
     }
 
+    // Authentication configuration
+    console.log('\nAuthentication Configuration (Optional):');
+    console.log('These settings are optional and provide access to more models and better rate limits.');
+    console.log('Leave empty to use the free tier.');
+    console.log('Note: You can also set these via environment variables POLLINATIONS_TOKEN and POLLINATIONS_REFERRER');
+
+    const authToken = await prompt('API Token (optional): ');
+    if (authToken && authToken.trim()) {
+      config[configKey].auth.token = authToken.trim();
+    } else {
+      delete config[configKey].auth.token;
+    }
+
+    const authReferrer = await prompt('Referrer URL (optional): ');
+    if (authReferrer && authReferrer.trim()) {
+      config[configKey].auth.referrer = authReferrer.trim();
+    } else {
+      delete config[configKey].auth.referrer;
+    }
+
+    // Remove auth section entirely if both fields are empty
+    if (!config[configKey].auth.token && !config[configKey].auth.referrer) {
+      delete config[configKey].auth;
+    }
+
     // Default parameters customization
     console.log('\nDefault Parameters:');
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinkpixel/mcpollinations",
-  "version": "1.0.8",
+  "version": "1.1.2",
   "description": "Model Context Protocol (MCP) server for the Pollinations APIs with image saving functionality.",
   "type": "module",
   "bin": {

pollinations-mcp-server.js

@@ -102,11 +102,30 @@ import player from 'play-sound';
 // Create audio player instance
 const audioPlayer = player({});
 
+// Read authentication configuration from environment variables
+// These are optional - the server works without them (free tier)
+const authConfig = {
+  token: process.env.POLLINATIONS_TOKEN || null,
+  referrer: process.env.POLLINATIONS_REFERRER || null
+};
+
+// Only create authConfig object if we have at least one auth parameter
+const finalAuthConfig = (authConfig.token || authConfig.referrer) ? authConfig : null;
+
+if (finalAuthConfig) {
+  console.error('Auth configuration loaded:', {
+    hasToken: !!finalAuthConfig.token,
+    hasReferrer: !!finalAuthConfig.referrer
+  });
+} else {
+  console.error('Running in free tier mode (no auth configuration)');
+}
+
 // Create the server instance
 const server = new Server(
   {
     name: '@pinkpixel/mcpollinations',
-    version: '1.0.8',
+    version: '1.1.2',
   },
   {
     capabilities: {
@@ -135,7 +154,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === 'generateImageUrl') {
     try {
       const { prompt, model = 'flux', seed, width = 1024, height = 1024, enhance = true, safe = false } = args;
-      const result = await generateImageUrl(prompt, model, seed, width, height, enhance, safe);
+      const result = await generateImageUrl(prompt, model, seed, width, height, enhance, safe, finalAuthConfig);
       return {
         content: [
           { type: 'text', text: JSON.stringify(result, null, 2) }
@@ -152,7 +171,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   } else if (name === 'generateImage') {
     try {
       const { prompt, model = 'flux', seed, width = 1024, height = 1024, enhance = true, safe = false, outputPath = './mcpollinations-output', fileName = '', format = 'png' } = args;
-      const result = await generateImage(prompt, model, seed, width, height, enhance, safe, outputPath, fileName, format);
+      const result = await generateImage(prompt, model, seed, width, height, enhance, safe, outputPath, fileName, format, finalAuthConfig);
 
       // Prepare the response content
       const content = [
@@ -186,7 +205,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   } else if (name === 'respondAudio') {
     try {
       const { prompt, voice, seed, voiceInstructions } = args;
-      const result = await respondAudio(prompt, voice, seed, voiceInstructions);
+      const result = await respondAudio(prompt, voice, seed, voiceInstructions, finalAuthConfig);
 
       // Save audio to a temporary file
       const tempDir = os.tmpdir();
@@ -274,7 +293,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   } else if (name === 'respondText') {
     try {
       const { prompt, model = "openai", seed } = args;
-      const result = await respondText(prompt, model, seed);
+      const result = await respondText(prompt, model, seed, finalAuthConfig);
       return {
         content: [
           { type: 'text', text: result }

src/services/audioService.js

@@ -11,9 +11,10 @@
  * @param {string} [voice="alloy"] - Voice to use for audio generation. Available options: "alloy", "echo", "fable", "onyx", "nova", "shimmer", "coral", "verse", "ballad", "ash", "sage", "amuch", "dan"
  * @param {number} [seed] - Seed for reproducible results
  * @param {string} [voiceInstructions] - Additional instructions for voice character/style
+ * @param {Object} [authConfig] - Optional authentication configuration {token, referrer}
  * @returns {Promise<Object>} - Object containing the base64 audio data, mime type, and metadata
  */
-export async function respondAudio(prompt, voice = "alloy", seed, voiceInstructions) {
+export async function respondAudio(prompt, voice = "alloy", seed, voiceInstructions, authConfig = null) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('Prompt is required and must be a string');
   }
@@ -41,8 +42,20 @@ export async function respondAudio(prompt, voice = "alloy", seed, voiceInstructi
   url += `?${queryString}`;
 
   try {
+    // Prepare fetch options with optional auth headers
+    const fetchOptions = {};
+    if (authConfig) {
+      fetchOptions.headers = {};
+      if (authConfig.token) {
+        fetchOptions.headers['Authorization'] = `Bearer ${authConfig.token}`;
+      }
+      if (authConfig.referrer) {
+        fetchOptions.headers['Referer'] = authConfig.referrer;
+      }
+    }
+
     // Fetch the audio from the URL
-    const response = await fetch(url);
+    const response = await fetch(url, fetchOptions);
 
     if (!response.ok) {
       throw new Error(`Failed to generate audio: ${response.statusText}`);

src/services/imageService.js

@@ -14,10 +14,11 @@
  * @param {number} [height=1024] - Height of the generated image
  * @param {boolean} [enhance=true] - Whether to enhance the prompt using an LLM before generating
  * @param {boolean} [safe=false] - Whether to apply content filtering
+ * @param {Object} [authConfig] - Optional authentication configuration {token, referrer}
  * @returns {Object} - Object containing the image URL and metadata
  * @note Always includes nologo=true and private=true parameters
  */
-export async function generateImageUrl(prompt, model = 'flux', seed = Math.floor(Math.random() * 1000000), width = 1024, height = 1024, enhance = true, safe = false) {
+export async function generateImageUrl(prompt, model = 'flux', seed = Math.floor(Math.random() * 1000000), width = 1024, height = 1024, enhance = true, safe = false, authConfig = null) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('Prompt is required and must be a string');
   }
@@ -81,20 +82,33 @@ export async function generateImageUrl(prompt, model = 'flux', seed = Math.floor
  * @param {string} [outputPath='./mcpollinations-output'] - Directory path where to save the image
  * @param {string} [fileName] - Name of the file to save (without extension)
  * @param {string} [format='png'] - Image format to save as (png, jpeg, jpg, webp)
+ * @param {Object} [authConfig] - Optional authentication configuration {token, referrer}
  * @returns {Promise<Object>} - Object containing the base64 image data, mime type, metadata, and file path if saved
  * @note Always includes nologo=true and private=true parameters
  */
-export async function generateImage(prompt, model = 'flux', seed = Math.floor(Math.random() * 1000000), width = 1024, height = 1024, enhance = true, safe = false, outputPath = './mcpollinations-output', fileName = '', format = 'png') {
+export async function generateImage(prompt, model = 'flux', seed = Math.floor(Math.random() * 1000000), width = 1024, height = 1024, enhance = true, safe = false, outputPath = './mcpollinations-output', fileName = '', format = 'png', authConfig = null) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('Prompt is required and must be a string');
   }
 
   // First, generate the image URL
-  const urlResult = await generateImageUrl(prompt, model, seed, width, height, enhance, safe);
+  const urlResult = await generateImageUrl(prompt, model, seed, width, height, enhance, safe, authConfig);
 
   try {
+    // Prepare fetch options with optional auth headers
+    const fetchOptions = {};
+    if (authConfig) {
+      fetchOptions.headers = {};
+      if (authConfig.token) {
+        fetchOptions.headers['Authorization'] = `Bearer ${authConfig.token}`;
+      }
+      if (authConfig.referrer) {
+        fetchOptions.headers['Referer'] = authConfig.referrer;
+      }
+    }
+
     // Fetch the image from the URL
-    const response = await fetch(urlResult.imageUrl);
+    const response = await fetch(urlResult.imageUrl, fetchOptions);
 
     if (!response.ok) {
       throw new Error(`Failed to generate image: ${response.statusText}`);

src/services/textService.js

@@ -10,9 +10,10 @@
  * @param {string} prompt - The text prompt to generate a response for
  * @param {string} [model="openai"] - Model to use for text generation. Available options: "openai", "anthropic", "mistral", "llama", "gemini"
  * @param {number} [seed] - Seed for reproducible results (default: random)
+ * @param {Object} [authConfig] - Optional authentication configuration {token, referrer}
  * @returns {Promise<string>} - The generated text response
  */
-export async function respondText(prompt, model = "openai", seed = Math.floor(Math.random() * 1000000)) {
+export async function respondText(prompt, model = "openai", seed = Math.floor(Math.random() * 1000000), authConfig = null) {
   if (!prompt || typeof prompt !== 'string') {
     throw new Error('Prompt is required and must be a string');
   }
@@ -34,8 +35,20 @@ export async function respondText(prompt, model = "openai", seed = Math.floor(Ma
   }
 
   try {
+    // Prepare fetch options with optional auth headers
+    const fetchOptions = {};
+    if (authConfig) {
+      fetchOptions.headers = {};
+      if (authConfig.token) {
+        fetchOptions.headers['Authorization'] = `Bearer ${authConfig.token}`;
+      }
+      if (authConfig.referrer) {
+        fetchOptions.headers['Referer'] = authConfig.referrer;
+      }
+    }
+
     // Fetch the text from the URL
-    const response = await fetch(url);
+    const response = await fetch(url, fetchOptions);
 
     if (!response.ok) {
       throw new Error(`Failed to generate text: ${response.statusText}`);