mcp-hydrocoder-image 1.0.0

package/dist/utils/logger.js

@@ -0,0 +1,186 @@
+/**
+ * Logger utility for structured logging with sensitive data filtering
+ * Provides consistent logging format across the application
+ */
+import * as crypto from 'node:crypto';
+/**
+ * Logger class for structured logging with sensitive data protection
+ */
+export class Logger {
+    constructor() {
+        this.sensitivePatterns = [
+            /GEMINI_API_KEY=([^\s]+)/gi,
+            /api[_-]?key[^\s]*[:=]\s*([^\s]+)/gi,
+            /password[^\s]*[:=]\s*([^\s]+)/gi,
+            /bearer\s+([a-zA-Z0-9\-._~+/]+=*)/gi,
+            /secret[^\s]*[:=]\s*([^\s]+)/gi,
+            /token[^\s]*[:=]\s*([^\s]+)/gi,
+        ];
+        this.urlPatterns = [
+            /(https?:\/\/[^\s]+)/gi, // URLs - separate to handle differently
+        ];
+        this.filterPatterns = [
+            /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g, // Credit card numbers
+            /\b\d{3}-\d{2}-\d{4}\b/g, // SSN
+            /\b(?:\+?1[-.]?)?\(?\d{3}\)?[-.]?\d{3}[-.]?\d{4}\b/g, // Phone numbers
+            /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/gi, // Emails
+        ];
+        this.keyBasedSensitivePatterns = [
+            /api[_-]?key/i,
+            /gemini[_-]?api[_-]?key/i,
+            /secret/i,
+            /password/i,
+            /token/i,
+            /credential/i,
+            /bearer/i,
+        ];
+        // Initialize session ID once per logger instance
+        this.currentSessionId = this.generateId();
+    }
+    /**
+     * Log a debug message (only in development mode)
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    debug(context, message, metadata) {
+        if (process.env['NODE_ENV'] === 'production')
+            return;
+        this.writeLog('debug', context, message, metadata);
+    }
+    /**
+     * Log an info message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    info(context, message, metadata) {
+        this.writeLog('info', context, message, metadata);
+    }
+    /**
+     * Log a warning message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param metadata Optional metadata object
+     */
+    warn(context, message, metadata) {
+        this.writeLog('warn', context, message, metadata);
+    }
+    /**
+     * Log an error message
+     * @param context Context or module where the log originates
+     * @param message Log message
+     * @param error Optional error object
+     * @param metadata Optional metadata object
+     */
+    error(context, message, error, metadata) {
+        const enhancedMetadata = {
+            ...metadata,
+            ...(error && {
+                errorName: error.name,
+                errorMessage: this.sanitizeString(error.message),
+                errorStack: process.env['NODE_ENV'] !== 'production' ? error.stack : undefined,
+            }),
+        };
+        this.writeLog('error', context, message, enhancedMetadata);
+    }
+    /**
+     * Core log writing method with structured format
+     */
+    writeLog(level, context, message, metadata) {
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            level,
+            context,
+            message: this.sanitizeString(message),
+            ...(metadata && { metadata: this.sanitizeMetadata(metadata) }),
+            traceId: this.getCurrentTraceId(),
+            sessionId: this.getCurrentSessionId(),
+        };
+        // JSON format structured log output
+        const logOutput = JSON.stringify(logEntry);
+        // For MCP servers, ALL logs must go to stderr
+        // stdout is reserved for JSON-RPC messages only
+        console.error(logOutput);
+    }
+    /**
+     * Sanitize string content by redacting sensitive information
+     * @param input String to sanitize
+     * @returns Sanitized string
+     */
+    sanitizeString(input) {
+        let sanitized = input;
+        // Redact sensitive data patterns (API keys, passwords, etc.)
+        for (const pattern of this.sensitivePatterns) {
+            sanitized = sanitized.replace(pattern, (match, group1) => match.replace(group1, '[REDACTED]'));
+        }
+        // Additional broad filter for API key-like strings in text
+        // Remove any reference to API key terms even in plain text
+        sanitized = sanitized.replace(/\bapi[_-]?key\b/gi, '[REDACTED]');
+        sanitized = sanitized.replace(/\bgemini[_-]?api[_-]?key\b/gi, '[REDACTED]');
+        // Remove long alphanumeric strings that might be API keys or secrets
+        sanitized = sanitized.replace(/\b[A-Za-z0-9]{20,}\b/g, '[REDACTED]');
+        // Redact URLs with specific label
+        for (const pattern of this.urlPatterns) {
+            sanitized = sanitized.replace(pattern, '[URL_REDACTED]');
+        }
+        // Filter personal information patterns
+        for (const pattern of this.filterPatterns) {
+            sanitized = sanitized.replace(pattern, '[FILTERED]');
+        }
+        return sanitized;
+    }
+    /**
+     * Sanitize metadata by redacting sensitive information
+     * @param metadata Metadata object to sanitize
+     * @returns Sanitized metadata object
+     */
+    sanitizeMetadata(metadata) {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            if (this.isSensitiveKey(key)) {
+                sanitized[key] = '[REDACTED]';
+            }
+            else if (typeof value === 'string') {
+                sanitized[key] = this.sanitizeString(value);
+            }
+            else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                sanitized[key] = this.sanitizeMetadata(value);
+            }
+            else {
+                sanitized[key] = value;
+            }
+        }
+        return sanitized;
+    }
+    /**
+     * Check if a key contains sensitive information
+     * @param key Object key to check
+     * @returns True if the key contains sensitive information
+     */
+    isSensitiveKey(key) {
+        return this.keyBasedSensitivePatterns.some((pattern) => pattern.test(key));
+    }
+    /**
+     * Generate unique ID for trace/session tracking
+     */
+    generateId() {
+        return crypto.randomUUID().substring(0, 8);
+    }
+    /**
+     * Get or generate current trace ID
+     */
+    getCurrentTraceId() {
+        if (!this.currentTraceId) {
+            this.currentTraceId = this.generateId();
+        }
+        return this.currentTraceId;
+    }
+    /**
+     * Get current session ID
+     */
+    getCurrentSessionId() {
+        return this.currentSessionId;
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/security.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Security Manager for file path validation and sanitization
+ * Provides protection against path traversal, null byte injection, and other security threats
+ */
+import { type Result } from '../types/result.js';
+import { SecurityError } from './errors.js';
+/**
+ * Security manager for handling file path validation and sanitization
+ */
+export declare class SecurityManager {
+    private readonly allowedBasePaths;
+    /**
+     * Sanitize and validate file path for security
+     * @param inputPath File path to sanitize
+     * @returns Result containing sanitized path or security error
+     */
+    sanitizeFilePath(inputPath: string): Result<string, SecurityError>;
+    /**
+     * Validate image file extension
+     * @param filePath File path to validate
+     * @returns Result indicating validation success or security error
+     */
+    validateImageFile(filePath: string): Result<void, SecurityError>;
+    /**
+     * Validate directory path for security
+     * @param dirPath Directory path to validate
+     * @returns Result indicating validation success or security error
+     */
+    validateDirectoryPath(dirPath: string): Result<void, SecurityError>;
+    /**
+     * Generate secure temporary file path
+     * @param baseName Base name for the temporary file
+     * @param extension File extension (with dot)
+     * @returns Secure temporary file path
+     */
+    generateSecureTempPath(baseName: string, extension: string): string;
+    /**
+     * Check if a path is within allowed directories
+     * @param targetPath Path to check
+     * @returns True if path is within allowed directories
+     */
+    isPathAllowed(targetPath: string): boolean;
+    /**
+     * Sanitize filename by removing dangerous characters
+     * @param filename Filename to sanitize
+     * @returns Sanitized filename
+     */
+    sanitizeFilename(filename: string): string;
+}
+//# sourceMappingURL=security.d.ts.map

package/dist/utils/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/utils/security.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAMhC;IAED;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAwBlE;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAYhE;;;;OAIG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC;IAUnE;;;;;OAKG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQnE;;;;OAIG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAK1C;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAuB3C"}

package/dist/utils/security.js

@@ -0,0 +1,116 @@
+/**
+ * Security Manager for file path validation and sanitization
+ * Provides protection against path traversal, null byte injection, and other security threats
+ */
+import * as path from 'node:path';
+import { Err, Ok } from '../types/result.js';
+import { SecurityError } from './errors.js';
+/**
+ * Security manager for handling file path validation and sanitization
+ */
+export class SecurityManager {
+    constructor() {
+        this.allowedBasePaths = [
+            process.cwd(),
+            path.resolve(process.env['IMAGE_OUTPUT_DIR'] || './output'),
+            path.resolve('./temp'),
+            path.resolve('./tmp'),
+            '/tmp',
+        ];
+    }
+    /**
+     * Sanitize and validate file path for security
+     * @param inputPath File path to sanitize
+     * @returns Result containing sanitized path or security error
+     */
+    sanitizeFilePath(inputPath) {
+        // Null byte attack prevention
+        if (inputPath.includes('\0')) {
+            return Err(new SecurityError('Null byte detected in file path'));
+        }
+        // Path traversal attack prevention
+        if (inputPath.includes('..')) {
+            return Err(new SecurityError('Path traversal attempt detected'));
+        }
+        // Resolve and validate absolute path
+        const resolvedPath = path.resolve(inputPath);
+        const isAllowed = this.allowedBasePaths.some((basePath) => resolvedPath.startsWith(path.resolve(basePath)));
+        if (!isAllowed) {
+            return Err(new SecurityError('File path outside allowed directories'));
+        }
+        return Ok(resolvedPath);
+    }
+    /**
+     * Validate image file extension
+     * @param filePath File path to validate
+     * @returns Result indicating validation success or security error
+     */
+    validateImageFile(filePath) {
+        // Allowed image file extensions
+        const allowedExtensions = ['.png', '.jpg', '.jpeg', '.webp'];
+        const extension = path.extname(filePath).toLowerCase();
+        if (!allowedExtensions.includes(extension)) {
+            return Err(new SecurityError(`Unsupported file extension: ${extension}`));
+        }
+        return Ok(undefined);
+    }
+    /**
+     * Validate directory path for security
+     * @param dirPath Directory path to validate
+     * @returns Result indicating validation success or security error
+     */
+    validateDirectoryPath(dirPath) {
+        // Use same security checks as file path validation
+        const pathValidation = this.sanitizeFilePath(dirPath);
+        if (!pathValidation.success) {
+            return pathValidation;
+        }
+        return Ok(undefined);
+    }
+    /**
+     * Generate secure temporary file path
+     * @param baseName Base name for the temporary file
+     * @param extension File extension (with dot)
+     * @returns Secure temporary file path
+     */
+    generateSecureTempPath(baseName, extension) {
+        const timestamp = Date.now();
+        const randomSuffix = Math.random().toString(36).substring(2, 8);
+        const secureFilename = `${baseName}-${timestamp}-${randomSuffix}${extension}`;
+        return path.join('/tmp', secureFilename);
+    }
+    /**
+     * Check if a path is within allowed directories
+     * @param targetPath Path to check
+     * @returns True if path is within allowed directories
+     */
+    isPathAllowed(targetPath) {
+        const resolvedPath = path.resolve(targetPath);
+        return this.allowedBasePaths.some((basePath) => resolvedPath.startsWith(path.resolve(basePath)));
+    }
+    /**
+     * Sanitize filename by removing dangerous characters
+     * @param filename Filename to sanitize
+     * @returns Sanitized filename
+     */
+    sanitizeFilename(filename) {
+        // Remove null bytes and path separators
+        let sanitized = filename.replace(/[\0/\\]/g, '');
+        // Remove control characters (ASCII 0-31 and 127) by filtering each character
+        sanitized = sanitized
+            .split('')
+            .filter((char) => {
+            const code = char.charCodeAt(0);
+            return code > 31 && code !== 127;
+        })
+            .join('');
+        // Trim whitespace and dots (to prevent hidden files and relative paths)
+        sanitized = sanitized.replace(/^\.+|\.+$/g, '').trim();
+        // Ensure filename is not empty after sanitization
+        if (sanitized.length === 0) {
+            sanitized = `secure-file-${Date.now()}`;
+        }
+        return sanitized;
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/utils/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/utils/security.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "mcp-hydrocoder-image",
+  "version": "1.0.0",
+  "description": "MCP server for AI image generation with multi-image support",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-hydrocoder-image": "./dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "image-generation",
+    "generative-ai",
+    "image-editing",
+    "prompt-enhancement",
+    "gemini",
+    "google-ai",
+    "nano-banana",
+    "claude-code",
+    "cursor",
+    "codex",
+    "typescript",
+    "agent-skills",
+    "skills"
+  ],
+  "author": "Shinsuke Kagawa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ynzys/mcp-banana.git"
+  },
+  "files": [
+    "dist/**/*",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/__tests__",
+    "!dist/tests",
+    "bin",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "link": "npm run build && npm link",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:summary": "node scripts/show-coverage.js",
+    "test:coverage:clean": "rm -rf coverage .vitest-cache",
+    "test:coverage:fresh": "npm run test:coverage:clean && npm run test:coverage",
+    "test:watch": "vitest",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
+    "lint": "biome lint src",
+    "lint:fix": "biome lint --write src",
+    "check": "biome check src",
+    "check:fix": "biome check --write src",
+    "check:deps": "madge --circular --extensions ts src",
+    "check:all": "npm run check && npm run lint && npm run format:check && npm run check:deps && npm run build && npm run test",
+    "cleanup:processes": "bash ./scripts/cleanup-test-processes.sh",
+    "test:safe": "npm test && npm run cleanup:processes"
+  },
+  "dependencies": {
+    "@google/genai": "^1.42.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^25.3.5",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "madge": "^8.0.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "biome check --write --no-errors-on-unmatched",
+      "biome format --write --no-errors-on-unmatched"
+    ]
+  }
+}

package/skills/image-generation/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: image-generation
+description: Enhances image generation prompts using Subject-Context-Style structure and best practices. Use this skill when generating images, creating illustrations, photos, visual assets, editing images, or crafting prompts for image generation.
+---
+
+# Image Generation Prompt Best Practices
+
+## Prompt Structure
+
+Enhance every image generation prompt around three core elements:
+
+### 1. SUBJECT (What)
+
+The main focus of the image.
+
+- Physical characteristics: textures, materials, colors, scale
+- Actions, poses, expressions if applicable
+- Distinctive features that define the subject
+
+### 2. CONTEXT (Where/When)
+
+The environment and conditions.
+
+- Setting, background, spatial relationships (foreground, midground, background)
+- Time of day, weather, atmospheric conditions
+- Mood and emotional tone of the scene
+
+### 3. STYLE (How)
+
+The visual treatment.
+
+- Artistic or photographic approach: reference specific artists, movements, or styles
+- Lighting design: direction, quality, color temperature, shadows
+- Camera/lens choices: specify focal length, aperture, and shooting angle when photographic
+
+## Core Principles
+
+- **Preserve intent** — Enrich the user's original vision, never override it
+- **Positive descriptions only** — Describe what should be present; rephrase any exclusion as an inclusion
+- **Specific over vague** — "golden hour sunlight at 15° angle" beats "nice lighting"
+- **Natural flow** — Weave elements into a single flowing description, not a bullet list
+
+## Enhancement Patterns
+
+### Hyper-Specific Details
+
+Add concrete visual details where the user left gaps:
+
+- Lighting → direction, quality, color temperature, shadow behavior
+- Textures → surface materials, weathering, reflectivity
+- Atmosphere → particulates, humidity, depth haze
+- Scale → relative sizes, distances, proportions
+
+### Camera Control Terminology
+
+When a photographic look is appropriate:
+
+- Lens type: "shot with 85mm portrait lens", "wide-angle 24mm"
+- Aperture: "shallow depth of field at f/1.8", "deep focus at f/11"
+- Angle: "low angle emphasizing height", "bird's eye view"
+- Motion: "motion blur on the paws", "frozen mid-action"
+
+### Atmospheric Enhancement
+
+Convey mood through environmental details:
+
+- Emotional tone: "serene", "ominous", "jubilant"
+- Light quality: "dappled shadows", "harsh midday sun", "soft diffused overcast"
+- Weather/air: "morning mist", "dust particles in a sunbeam"
+
+### Text in Images
+
+When the image should contain readable text (signs, labels, titles, typography):
+
+- Specify the exact text content in quotes: `"OPEN 24 HOURS" in bold sans-serif`
+- Describe visual treatment: font style, weight, size relative to the scene
+- Define placement and integration: "centered on the storefront awning", "hand-lettered on the chalkboard"
+
+## Feature Patterns
+
+### Character Consistency
+
+When the same character must be recognizable across multiple images:
+
+- Include **at least 3 recognizable visual markers** (distinctive scar, signature clothing, unique hairstyle, characteristic accessory)
+- Use anchoring words: "distinctive", "signature", "always wears", "always has"
+- Be specific: "round tortoiseshell glasses" not just "glasses"
+
+### Compositional Integration (Multi-Element Blending)
+
+When combining multiple visual elements in one scene:
+
+- Define spatial relationships with proportions: "foreground (40% of frame)", "midground", "background"
+- Use integration language: "seamlessly blending", "harmoniously composed", "naturally integrated"
+- Specify relative scale and interaction between elements
+
+### Real-World Accuracy
+
+When depicting real places, cultures, or historical elements:
+
+- Use specific terminology: "traditional Edo-period architecture", "authentic Moroccan zellige tilework"
+- Include culturally accurate details
+- Reference geographical or historical specifics
+
+### Purpose-Driven Enhancement
+
+Tailor the prompt to the intended use:
+
+| Purpose | Emphasis |
+|---------|----------|
+| Product photo | Clean background, studio lighting, commercial appeal |
+| UI mockup | Flat design elements, consistent spacing, screen-appropriate |
+| Presentation slide | Bold composition, clear focal point, text-friendly layout |
+| Social media | Eye-catching, vibrant, crop-friendly aspect ratio |
+| Book/album cover | Typography space, dramatic mood, symbolic elements |
+
+## Image Editing
+
+When modifying an existing image:
+
+- **Preserve** the original's core characteristics: color palette, lighting style, composition
+- Use anchoring phrases: "maintain the existing...", "preserve the original...", "keep the same..."
+- Be specific about what to change vs what to keep unchanged
+- Describe modifications relative to the existing image, not from scratch
+
+## Example
+
+**Input:** "A happy dog in a park"
+
+**Enhanced:** "Golden retriever mid-leap catching a red frisbee, ears flying, tongue out in joy, in a sunlit urban park. Soft morning light filtering through oak trees creates dappled shadows on emerald grass. Background shows families on picnic blankets, slightly out of focus. Shot from low angle emphasizing the dog's athletic movement, with motion blur on the paws suggesting speed."
+