mcp-image 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shinsuke Kagawa
+
+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.

package/README.md

@@ -0,0 +1,163 @@
+# MCP Image Generator
+
+A powerful MCP (Model Context Protocol) server that enables AI assistants to generate and edit images using Google's Gemini 2.5 Flash Image API. Seamlessly integrate advanced image generation capabilities into Claude Code, Cursor, and other MCP-compatible AI tools.
+
+## ✨ Features
+
+- **AI-Powered Image Generation**: Create images from text prompts using Gemini 2.5 Flash Image Preview
+- **Image Editing**: Transform existing images with natural language instructions
+- **Advanced Options**: 
+  - Multi-image blending for composite scenes
+  - Character consistency across generations
+  - World knowledge integration for accurate context
+- **Multiple Output Formats**: PNG, JPEG, WebP support
+- **File Output**: Images are saved as files for easy access and integration
+
+## 🔧 Prerequisites
+
+- **Node.js** 20 or higher
+- **Gemini API Key** - Get yours at [Google AI Studio](https://aistudio.google.com/apikey)
+- **Claude Code** or **Cursor** (or any MCP-compatible AI tool)
+- Basic terminal/command line knowledge
+
+## 🚀 Quick Start
+
+### 1. Get Your Gemini API Key
+
+Get your API key from [Google AI Studio](https://aistudio.google.com/apikey)
+
+### 2. MCP Configuration
+
+#### For Claude Code
+
+```bash
+claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image
+```
+
+#### For Cursor
+
+Add to your Cursor settings (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "mcp-image": {
+        "command": "npx",
+        "args": ["-y", "mcp-image"],
+        "env": {
+          "GEMINI_API_KEY": "your_gemini_api_key_here",
+          "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
+        }
+      }
+    }
+  }
+}
+```
+
+⚠️ **Security Note**: Never commit your API key to version control. Keep it secure and use environment-specific configuration.
+
+📁 **Path Requirements**: 
+- `IMAGE_OUTPUT_DIR` must be an absolute path (e.g., `/Users/username/images`, not `./images`)
+- Defaults to `./output` in the current working directory if not specified
+- Directory will be created automatically if it doesn't exist
+
+## 📖 Usage Examples
+
+Once configured, your AI assistant can generate images using natural language:
+
+### Basic Image Generation
+
+```
+"Generate a serene mountain landscape at sunset with a lake reflection"
+```
+
+### Image Editing
+
+```
+"Edit this image to make the person face right"
+(with inputImagePath: "/path/to/image.jpg")
+```
+
+
+### Advanced Features
+
+```
+"Generate a portrait of a medieval knight, maintaining character consistency for future variations"
+(with maintainCharacterConsistency: true)
+```
+
+## 🔧 API Reference
+
+### `generate_image` Tool
+
+The MCP server exposes a single tool for all image operations:
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `prompt` | string | ✅ | Text description or editing instruction |
+| `inputImagePath` | string | ❌ | Absolute path to input image for editing |
+| `fileName` | string | ❌ | Custom filename for output (auto-generated if not specified) |
+| `blendImages` | boolean | ❌ | Enable multi-image blending |
+| `maintainCharacterConsistency` | boolean | ❌ | Maintain character appearance across generations |
+| `useWorldKnowledge` | boolean | ❌ | Use real-world knowledge for context |
+
+#### Response
+
+```json
+{
+  "type": "resource",
+  "resource": {
+    "uri": "file:///path/to/generated/image.png",
+    "name": "image-filename.png",
+    "mimeType": "image/png"
+  },
+  "metadata": {
+    "model": "gemini-2.5-flash-image-preview",
+    "processingTime": 5000,
+    "timestamp": "2024-01-01T12:00:00.000Z"
+  }
+}
+```
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**"API key not found"**
+- Ensure `GEMINI_API_KEY` is set in your environment
+- Verify the API key is valid and has image generation permissions
+
+**"Input image file not found"**
+- Use absolute file paths, not relative paths
+- Ensure the file exists and is accessible
+- Supported formats: PNG, JPEG, WebP (max 10MB)
+
+**"No image data found in Gemini API response"**
+- Try rephrasing your prompt with more specific details
+- Ensure your prompt is appropriate for image generation
+- Check if your API key has sufficient quota
+
+### Performance Tips
+
+- Image generation: 30-60 seconds typical
+- Image editing: 15-45 seconds typical  
+- Use specific, descriptive prompts for better results
+- Consider enabling `useWorldKnowledge` for historical or factual subjects
+
+
+## 💰 Usage Notes
+
+- This MCP server uses the paid Gemini API for image generation
+- Check current pricing and rate limits at [Google AI Studio](https://aistudio.google.com/)
+- Monitor your API usage to avoid unexpected charges
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+**Need help?** [Open an issue](https://github.com/shinpr/mcp-image/issues) or check the [troubleshooting section](#-troubleshooting) above.

package/dist/api/geminiClient.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Gemini API client for image generation
+ * Integrates with Google's Gemini AI API using the official SDK
+ * Supports automatic URL Context processing and feature parameters
+ */
+import type { Result } from '../types/result';
+import type { Config } from '../utils/config';
+import { GeminiAPIError, NetworkError } from '../utils/errors';
+/**
+ * Metadata for generated images
+ */
+export interface GeminiGenerationMetadata {
+    model: string;
+    prompt: string;
+    mimeType: string;
+    timestamp: Date;
+    inputImageProvided: boolean;
+    contextMethod: string;
+    /** Features usage metadata */
+    features?: {
+        blendImages: boolean;
+        maintainCharacterConsistency: boolean;
+        useWorldKnowledge: boolean;
+    };
+}
+/**
+ * Parameters for Gemini API image generation (with processed data)
+ */
+export interface GeminiApiParams {
+    prompt: string;
+    inputImage?: Buffer;
+    blendImages?: boolean;
+    maintainCharacterConsistency?: boolean;
+    useWorldKnowledge?: boolean;
+}
+/**
+ * Result of image generation
+ */
+export interface GeneratedImageResult {
+    imageData: Buffer;
+    metadata: GeminiGenerationMetadata;
+}
+/**
+ * Gemini API client interface
+ */
+export interface GeminiClient {
+    generateImage(params: GeminiApiParams): Promise<Result<GeneratedImageResult, GeminiAPIError | NetworkError>>;
+}
+/**
+ * Creates a new Gemini API client
+ * @param config Configuration containing API key and other settings
+ * @returns Result containing the client or an error
+ */
+export declare function createGeminiClient(config: Config): Result<GeminiClient, GeminiAPIError>;
+//# sourceMappingURL=geminiClient.d.ts.map

package/dist/api/geminiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geminiClient.d.ts","sourceRoot":"","sources":["../../src/api/geminiClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAiD9D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,IAAI,CAAA;IACf,kBAAkB,EAAE,OAAO,CAAA;IAC3B,aAAa,EAAE,MAAM,CAAA;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE;QACT,WAAW,EAAE,OAAO,CAAA;QACpB,4BAA4B,EAAE,OAAO,CAAA;QACrC,iBAAiB,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4BAA4B,CAAC,EAAE,OAAO,CAAA;IACtC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,wBAAwB,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,CACX,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC,CAAA;CACxE;AAwPD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAevF"}

package/dist/api/geminiClient.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Gemini API client for image generation
+ * Integrates with Google's Gemini AI API using the official SDK
+ * Supports automatic URL Context processing and feature parameters
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGeminiClient = createGeminiClient;
+const genai_1 = require("@google/genai");
+const result_1 = require("../types/result");
+const errors_1 = require("../utils/errors");
+/**
+ * URL pattern for automatic URL detection
+ */
+const URL_PATTERN = /https?:\/\/(?:[-\w.])+(?:\.[a-zA-Z]{2,})+(?:\/[-\w._~:\/?#[\]@!$&'()*+,;=]*)?/g;
+/**
+ * Implementation of Gemini API client
+ */
+class GeminiClientImpl {
+    constructor(genai) {
+        this.genai = genai;
+        this.modelName = 'gemini-2.5-flash-image-preview';
+    }
+    async generateImage(params) {
+        try {
+            // Enhance prompt with structured parameters for better accuracy
+            let enhancedPrompt = params.prompt;
+            // Convert MCP parameters to structured prompt instructions
+            if (params.maintainCharacterConsistency) {
+                enhancedPrompt +=
+                    ' [INSTRUCTION: Maintain exact character appearance, including facial features, hairstyle, clothing, and all physical characteristics consistent throughout the image]';
+            }
+            if (params.blendImages) {
+                enhancedPrompt +=
+                    ' [INSTRUCTION: Seamlessly blend multiple visual elements into a natural, cohesive composition with smooth transitions]';
+            }
+            if (params.useWorldKnowledge) {
+                enhancedPrompt +=
+                    ' [INSTRUCTION: Apply accurate real-world knowledge including historical facts, geographical accuracy, cultural contexts, and realistic depictions]';
+            }
+            // Prepare the request content with enhanced prompt
+            const requestContent = [enhancedPrompt];
+            // Add input image if provided
+            if (params.inputImage) {
+                requestContent.push({
+                    inlineData: {
+                        data: params.inputImage.toString('base64'),
+                        mimeType: 'image/jpeg', // Assume JPEG for input images
+                    },
+                });
+            }
+            // Prepare API configuration
+            const config = {};
+            // URL detection is maintained for potential future use
+            // Note: urlContext tool has been removed as it's not supported by the model
+            this.detectUrls(params.prompt);
+            // Note: Feature parameters are now handled via prompt enhancement
+            // The Gemini API does not directly support these as config parameters
+            // Generate content using Gemini API with official URL Context support
+            const response = await this.genai.models.generateContent({
+                model: this.modelName,
+                contents: requestContent,
+                config,
+            });
+            // Extract image data from response
+            if (!response || typeof response !== 'object') {
+                return (0, result_1.Err)(new errors_1.GeminiAPIError('Invalid response from Gemini API', 'The API returned an unexpected response format'));
+            }
+            // Handle different response structures
+            const candidates = response.response?.candidates ||
+                response.candidates;
+            if (!candidates || candidates.length === 0) {
+                return (0, result_1.Err)(new errors_1.GeminiAPIError('No image generated by Gemini API', 'Try rephrasing your prompt or check if the model supports your request type'));
+            }
+            const candidate = candidates[0];
+            if (!candidate) {
+                return (0, result_1.Err)(new errors_1.GeminiAPIError('No candidate found in Gemini API response', 'The API response was malformed. Try again or contact support if the issue persists'));
+            }
+            const parts = candidate.content?.parts;
+            if (!parts || parts.length === 0) {
+                return (0, result_1.Err)(new errors_1.GeminiAPIError('No image data in response from Gemini API', 'The API response was malformed. Try again or contact support if the issue persists'));
+            }
+            // Find the image part with proper type guards
+            const imagePart = parts.find((part) => {
+                const p = part;
+                return p.inlineData?.data;
+            });
+            if (!imagePart?.inlineData) {
+                return (0, result_1.Err)(new errors_1.GeminiAPIError('No image data found in Gemini API response', 'The model may not have generated an image. Try a different prompt'));
+            }
+            // Convert base64 image data to Buffer
+            const imageBuffer = Buffer.from(imagePart.inlineData.data, 'base64');
+            const mimeType = imagePart.inlineData.mimeType || 'image/png';
+            // Create metadata with features information
+            const metadata = {
+                model: this.modelName,
+                prompt: params.prompt, // Original prompt, not enhanced
+                mimeType,
+                timestamp: new Date(),
+                inputImageProvided: !!params.inputImage,
+                contextMethod: 'prompt_only',
+            };
+            // Add features usage information if any features are specified (including false)
+            if (params.blendImages !== undefined ||
+                params.maintainCharacterConsistency !== undefined ||
+                params.useWorldKnowledge !== undefined) {
+                metadata.features = {
+                    blendImages: params.blendImages || false,
+                    maintainCharacterConsistency: params.maintainCharacterConsistency || false,
+                    useWorldKnowledge: params.useWorldKnowledge || false,
+                };
+            }
+            return (0, result_1.Ok)({
+                imageData: imageBuffer,
+                metadata,
+            });
+        }
+        catch (error) {
+            return this.handleError(error, params.prompt);
+        }
+    }
+    handleError(error, prompt) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        // Check if it's a network error
+        if (this.isNetworkError(error)) {
+            return (0, result_1.Err)(new errors_1.NetworkError(`Network error during image generation: ${errorMessage}`, 'Check your internet connection and try again', error instanceof Error ? error : undefined));
+        }
+        // Check if it's an API-specific error
+        if (this.isAPIError(error)) {
+            return (0, result_1.Err)(new errors_1.GeminiAPIError(`Failed to generate image: ${errorMessage}`, this.getAPIErrorSuggestion(errorMessage), this.extractStatusCode(error)));
+        }
+        // Generic API error
+        return (0, result_1.Err)(new errors_1.GeminiAPIError(`Failed to generate image with prompt "${prompt}": ${errorMessage}`, 'Check your API key, quota, and prompt validity. Try again with a different prompt'));
+    }
+    isNetworkError(error) {
+        if (error instanceof Error) {
+            const networkErrorCodes = ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND'];
+            return networkErrorCodes.some((code) => error.message.includes(code) || error.code === code);
+        }
+        return false;
+    }
+    isAPIError(error) {
+        if (error instanceof Error) {
+            const apiErrorKeywords = ['quota', 'rate limit', 'unauthorized', 'forbidden', 'api key'];
+            return apiErrorKeywords.some((keyword) => error.message.toLowerCase().includes(keyword));
+        }
+        return false;
+    }
+    getAPIErrorSuggestion(errorMessage) {
+        const lowerMessage = errorMessage.toLowerCase();
+        if (lowerMessage.includes('quota') || lowerMessage.includes('rate limit')) {
+            return 'You have exceeded your API quota or rate limit. Wait before making more requests or upgrade your plan';
+        }
+        if (lowerMessage.includes('unauthorized') || lowerMessage.includes('api key')) {
+            return 'Check that your GEMINI_API_KEY is valid and has the necessary permissions';
+        }
+        if (lowerMessage.includes('forbidden')) {
+            return 'Your API key does not have permission for this operation';
+        }
+        return 'Check your API configuration and try again';
+    }
+    extractStatusCode(error) {
+        if (error && typeof error === 'object' && 'status' in error) {
+            return typeof error.status === 'number' ? error.status : undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Detect URLs in prompt for automatic URL Context activation
+     * @param prompt The prompt text to analyze
+     * @returns True if URLs are detected, false otherwise
+     */
+    detectUrls(prompt) {
+        return URL_PATTERN.test(prompt);
+    }
+}
+/**
+ * Creates a new Gemini API client
+ * @param config Configuration containing API key and other settings
+ * @returns Result containing the client or an error
+ */
+function createGeminiClient(config) {
+    try {
+        const genai = new genai_1.GoogleGenAI({
+            apiKey: config.geminiApiKey,
+        });
+        return (0, result_1.Ok)(new GeminiClientImpl(genai));
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return (0, result_1.Err)(new errors_1.GeminiAPIError(`Failed to initialize Gemini client: ${errorMessage}`, 'Verify your GEMINI_API_KEY is valid and the @google/genai package is properly installed'));
+    }
+}
+//# sourceMappingURL=geminiClient.js.map

package/dist/api/geminiClient.js.map

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

package/dist/api/urlContextClient.d.ts

@@ -0,0 +1,149 @@
+/**
+ * URL Context API client for processing URLs and extracting context
+ * Uses @google/genai SDK for URL context processing
+ */
+import { type Result } from '../types/result';
+import { NetworkError, URLContextError } from '../utils/errors';
+/**
+ * Response from URL context processing
+ */
+export interface UrlContextResponse {
+    /** Context content extracted from URLs */
+    contextContent: string;
+    /** Combined prompt with context and cleaned original prompt */
+    combinedPrompt: string;
+    /** Additional extracted information */
+    extractedInfo: Record<string, unknown>;
+    /** Success flag */
+    success: boolean;
+}
+/**
+ * Mock interface for text generation (to be replaced with real implementation later)
+ */
+interface TextGenerationClient {
+    generateText(prompt: string): Promise<Result<{
+        text: string;
+    }, Error>>;
+}
+/**
+ * Client for processing URLs and extracting context
+ * Basic implementation for Phase 2 - will be enhanced in later phases
+ */
+export declare class UrlContextClient {
+    private textClient;
+    /**
+     * Maximum number of URLs to process (performance consideration)
+     */
+    private static readonly MAX_URLS;
+    /**
+     * Maximum number of retry attempts
+     */
+    private readonly MAX_RETRIES;
+    /**
+     * Timeout for URL context processing in milliseconds
+     */
+    private readonly TIMEOUT_MS;
+    constructor(textClient: TextGenerationClient);
+    /**
+     * Process multiple URLs and extract context for image generation
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response with combined prompt or error
+     */
+    processUrls(urls: string[], originalPrompt: string): Promise<Result<UrlContextResponse, URLContextError | NetworkError>>;
+    /**
+     * Process URLs with retry mechanism and timeout
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response with retry information
+     */
+    processUrlsWithRetry(urls: string[], originalPrompt: string): Promise<Result<UrlContextResponse, URLContextError | NetworkError>>;
+    /**
+     * Process URLs with timeout protection
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result with timeout protection
+     */
+    private processUrlsWithTimeout;
+    /**
+     * Core URL processing logic without retry/timeout
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Result containing URL context response
+     */
+    private processUrlsCore;
+    /**
+     * Build a context extraction prompt for Gemini API
+     * @param urls Array of URLs to process
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Formatted prompt for context extraction
+     */
+    private buildContextPrompt;
+    /**
+     * Combine URL context with original prompt for image generation
+     * @param contextPrompts Array of context content from URLs
+     * @param originalPrompt Original prompt containing URLs
+     * @param urls Array of processed URLs
+     * @returns Combined prompt for image generation
+     */
+    private combineContextWithPrompt;
+    /**
+     * Remove URLs and clean up common action words from prompt
+     * @param originalPrompt Original prompt containing URLs
+     * @returns Cleaned prompt suitable for final instruction
+     */
+    private cleanPromptFromUrls;
+    /**
+     * Format and clean context content from multiple sources
+     * @param contextPrompts Array of raw context content
+     * @returns Formatted context content
+     */
+    private formatContextContent;
+    /**
+     * Format the final combined prompt with context and instruction sections
+     * @param urls Array of processed URLs
+     * @param contextContent Formatted context content
+     * @param finalPrompt Final instruction prompt
+     * @returns Complete combined prompt
+     */
+    private formatCombinedPrompt;
+    /**
+     * Create a standardized context error from API failure
+     * @param originalError The original error from text generation
+     * @returns Formatted URLContextError
+     */
+    private createContextError;
+    /**
+     * Create appropriate error based on error type
+     * @param error The original error that occurred
+     * @returns Formatted error (NetworkError or URLContextError)
+     */
+    private createProcessingError;
+    /**
+     * Parse extracted information from context content
+     * @param contextContent The context content to parse
+     * @param processedUrlCount Number of URLs that were processed
+     * @returns Structured extracted information
+     */
+    private parseExtractedInfo;
+    /**
+     * Check if an error is network-related
+     * @param error The error to check
+     * @returns True if it's a network error
+     */
+    private isNetworkError;
+    /**
+     * Check if an error is retryable
+     * @param error The error to check
+     * @returns True if the error should trigger a retry
+     */
+    private isRetryableError;
+    /**
+     * Add a delay for exponential backoff
+     * @param ms Milliseconds to delay
+     * @returns Promise that resolves after the delay
+     */
+    private delay;
+}
+export {};
+//# sourceMappingURL=urlContextClient.d.ts.map

package/dist/api/urlContextClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlContextClient.d.ts","sourceRoot":"","sources":["../../src/api/urlContextClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAE/D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAA;IACtB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAA;IACtB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,mBAAmB;IACnB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;GAEG;AACH,UAAU,oBAAoB;IAC5B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,CAAC,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAgBf,OAAO,CAAC,UAAU;IAf9B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAK;IAErC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAI;IAEhC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;gBAEf,UAAU,EAAE,oBAAoB;IAEpD;;;;;OAKG;IACG,WAAW,CACf,IAAI,EAAE,MAAM,EAAE,EACd,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,eAAe,GAAG,YAAY,CAAC,CAAC;IAuBtE;;;;;OAKG;IACG,oBAAoB,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,eAAe,GAAG,YAAY,CAAC,CAAC;IA0DtE;;;;;OAKG;YACW,sBAAsB;IA4BpC;;;;;OAKG;YACW,eAAe;IA2B7B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IAYhC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAkB3B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAoB1B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAqBtB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;OAIG;YACW,KAAK;CAGpB"}