@lutery/vision-mcp 1.0.0

package/dist/tools/vision-tool.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Vision Tool
+ *
+ * @description MCP 视觉分析工具，提供统一的图片分析接口
+ */
+import { z } from 'zod';
+import { ModelConfig } from '../config/model-config.js';
+/**
+ * 工具参数 Schema
+ */
+export declare const VisionToolInputSchema: z.ZodObject<{
+    /**
+     * 图片输入：支持 URL、base64(data URL) 或本地路径
+     * @example "https://example.com/image.jpg"
+     * @example "data:image/jpeg;base64,/9j/4AAQ..."
+     * @example "/path/to/local/image.png"
+     */
+    image: z.ZodString;
+    /**
+     * 分析提示词：描述要执行的分析任务
+     * @example "Describe this UI design and extract all components"
+     * @example "Detect objects and provide their coordinates"
+     * @example "Extract text using OCR"
+     */
+    prompt: z.ZodString;
+    /**
+     * 输出格式：可选，指定为 "text" 或 "json"
+     * @default "text"
+     */
+    output_format: z.ZodDefault<z.ZodOptional<z.ZodEnum<["text", "json"]>>>;
+    /**
+     * 系统提示词模板：可选，指定使用的模板
+     * @default auto-detected based on prompt
+     * @example "ui-analysis"
+     * @example "object-detection"
+     */
+    template: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    image: string;
+    prompt: string;
+    output_format: "text" | "json";
+    template?: string | undefined;
+}, {
+    image: string;
+    prompt: string;
+    output_format?: "text" | "json" | undefined;
+    template?: string | undefined;
+}>;
+export type VisionToolInput = z.infer<typeof VisionToolInputSchema>;
+/**
+ * 工具响应格式
+ */
+export interface VisionToolResponse {
+    content: string;
+    format: 'text' | 'json';
+    metadata: {
+        modelType: string;
+        modelName: string;
+        imageFormat: string;
+        processingTimeMs: number;
+        imageSize: number;
+    };
+}
+/**
+ * 视觉工具类
+ */
+export declare class VisionTool {
+    private modelConfig;
+    private adapter;
+    constructor(config?: ModelConfig);
+    /**
+     * 创建模型适配器（使用 registry）
+     */
+    private createAdapter;
+    /**
+     * 执行视觉分析
+     */
+    analyze(input: VisionToolInput): Promise<VisionToolResponse>;
+    /**
+     * 构建元数据
+     */
+    private buildMetadata;
+    /**
+     * 获取工具信息
+     */
+    getToolInfo(): {
+        modelConfig: ModelConfig;
+    };
+}
+export declare function getVisionTool(config?: ModelConfig): VisionTool;
+//# sourceMappingURL=vision-tool.d.ts.map

package/dist/tools/vision-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-tool.d.ts","sourceRoot":"","sources":["../../src/tools/vision-tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAwC,MAAM,2BAA2B,CAAC;AAQ9F;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;OAGG;;IAGH;;;;;OAKG;;;;;;;;;;;;EAEM,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,OAAO,CAAqB;gBAExB,MAAM,CAAC,EAAE,WAAW;IAgBhC;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACU,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA2EzE;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACI,WAAW,IAAI;QACpB,WAAW,EAAE,WAAW,CAAC;KAC1B;CAKF;AAOD,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,CAK9D"}

package/dist/tools/vision-tool.js

@@ -0,0 +1,167 @@
+/**
+ * Vision Tool
+ *
+ * @description MCP 视觉分析工具，提供统一的图片分析接口
+ */
+import { z } from 'zod';
+import { loadModelConfig, validateModelConfig } from '../config/model-config.js';
+import { normalizeImageInput } from '../utils/image-input.js';
+import { ModelConfigError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { buildPrompt } from '../prompts/system.js';
+import { registry } from '../providers/provider-registry.js';
+/**
+ * 工具参数 Schema
+ */
+export const VisionToolInputSchema = z.object({
+    /**
+     * 图片输入：支持 URL、base64(data URL) 或本地路径
+     * @example "https://example.com/image.jpg"
+     * @example "data:image/jpeg;base64,/9j/4AAQ..."
+     * @example "/path/to/local/image.png"
+     */
+    image: z.string().describe('Image URL, base64 data URL, or local file path'),
+    /**
+     * 分析提示词：描述要执行的分析任务
+     * @example "Describe this UI design and extract all components"
+     * @example "Detect objects and provide their coordinates"
+     * @example "Extract text using OCR"
+     */
+    prompt: z.string().describe('Analysis prompt describing the task'),
+    /**
+     * 输出格式：可选，指定为 "text" 或 "json"
+     * @default "text"
+     */
+    output_format: z.enum(['text', 'json']).optional().default('text').describe('Output format preference'),
+    /**
+     * 系统提示词模板：可选，指定使用的模板
+     * @default auto-detected based on prompt
+     * @example "ui-analysis"
+     * @example "object-detection"
+     */
+    template: z.string().optional().describe('System prompt template to use')
+}).strict();
+/**
+ * 视觉工具类
+ */
+export class VisionTool {
+    modelConfig;
+    adapter;
+    constructor(config) {
+        // 加载配置
+        this.modelConfig = config || loadModelConfig();
+        // 验证配置
+        validateModelConfig(this.modelConfig);
+        // 创建适配器
+        this.adapter = this.createAdapter(this.modelConfig);
+        logger.info('Vision tool initialized', {
+            modelType: this.modelConfig.type,
+            modelName: this.modelConfig.name
+        });
+    }
+    /**
+     * 创建模型适配器（使用 registry）
+     */
+    createAdapter(config) {
+        const provider = registry.get(config.type);
+        if (!provider) {
+            throw new ModelConfigError(`Unsupported model type: ${config.type}`);
+        }
+        return provider.createAdapter(config);
+    }
+    /**
+     * 执行视觉分析
+     */
+    async analyze(input) {
+        const startTime = Date.now();
+        const requestId = Math.random().toString(36).substring(7);
+        logger.logRequest('Vision analysis started', {
+            requestId,
+            modelType: this.modelConfig.type,
+            imageInputLength: input.image.length,
+            hasTemplate: !!input.template
+        });
+        try {
+            // 1. 规范化图片输入
+            logger.debug('Normalizing image input', { requestId });
+            const normalizedImage = await normalizeImageInput(input.image);
+            logger.debug('Image normalized successfully', {
+                requestId,
+                type: normalizedImage.type,
+                mimeType: normalizedImage.mimeType,
+                dataLength: normalizedImage.dataUrl.length
+            });
+            // 2. 构建完整提示词
+            logger.debug('Building prompt', { requestId });
+            const fullPrompt = buildPrompt(input.template, input.prompt);
+            logger.debug('Prompt built', {
+                requestId,
+                promptLength: fullPrompt.length,
+                templateUsed: input.template || 'auto-detected'
+            });
+            // 3. 调用视觉模型
+            logger.logRequest('Calling vision model', {
+                requestId,
+                modelType: this.modelConfig.type,
+                modelName: this.modelConfig.name
+            });
+            const modelResponse = await this.adapter.analyzeWithResponse(normalizedImage.dataUrl, fullPrompt);
+            // 4. 构建响应
+            const response = {
+                content: modelResponse.content,
+                format: input.output_format,
+                metadata: {
+                    modelType: this.modelConfig.type,
+                    modelName: this.modelConfig.name,
+                    imageFormat: normalizedImage.mimeType,
+                    processingTimeMs: Date.now() - startTime,
+                    imageSize: normalizedImage.dataUrl.length
+                }
+            };
+            logger.logRequest('Vision analysis completed', {
+                requestId,
+                processingTimeMs: response.metadata.processingTimeMs,
+                outputLength: response.content.length
+            });
+            return response;
+        }
+        catch (error) {
+            logger.error('Vision analysis failed', error, {
+                requestId,
+                processingTimeMs: Date.now() - startTime
+            });
+            throw error;
+        }
+    }
+    /**
+     * 构建元数据
+     */
+    buildMetadata(normalizedImage, startTime) {
+        return {
+            modelType: this.modelConfig.type,
+            modelName: this.modelConfig.name,
+            imageFormat: normalizedImage.mimeType,
+            processingTimeMs: Date.now() - startTime,
+            imageSize: normalizedImage.dataUrl.length
+        };
+    }
+    /**
+     * 获取工具信息
+     */
+    getToolInfo() {
+        return {
+            modelConfig: this.modelConfig
+        };
+    }
+}
+/**
+ * 创建工具实例（单例模式）
+ */
+let toolInstance;
+export function getVisionTool(config) {
+    if (!toolInstance) {
+        toolInstance = new VisionTool(config);
+    }
+    return toolInstance;
+}
+//# sourceMappingURL=vision-tool.js.map

package/dist/tools/vision-tool.js.map

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

package/dist/utils/data-url-parser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Data URL Parser Utility
+ *
+ * @description 解析 data URL 格式，将 data:image/png;base64,... 拆解为 mimeType 和 base64 data
+ * 用于 Claude API 适配器，因为 Claude 需要单独的 media_type 和 base64 data 字段
+ */
+/**
+ * 解析后的 data URL 结构
+ */
+export interface ParsedDataUrl {
+    mimeType: string;
+    data: string;
+}
+/**
+ * 解析 data URL
+ * @param dataUrl - data:image/png;base64,iVBORw0KG...
+ * @returns { mimeType, data }
+ * @throws {Error} 如果 data URL 格式无效
+ */
+export declare function parseDataUrl(dataUrl: string): ParsedDataUrl;
+/**
+ * 检查是否为 data URL
+ * @param value - 待检查的字符串
+ * @returns 是否为 data URL
+ */
+export declare function isDataUrl(value: string): boolean;
+//# sourceMappingURL=data-url-parser.d.ts.map

package/dist/utils/data-url-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-url-parser.d.ts","sourceRoot":"","sources":["../../src/utils/data-url-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAuC3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/utils/data-url-parser.js

@@ -0,0 +1,53 @@
+/**
+ * Data URL Parser Utility
+ *
+ * @description 解析 data URL 格式，将 data:image/png;base64,... 拆解为 mimeType 和 base64 data
+ * 用于 Claude API 适配器，因为 Claude 需要单独的 media_type 和 base64 data 字段
+ */
+/**
+ * 解析 data URL
+ * @param dataUrl - data:image/png;base64,iVBORw0KG...
+ * @returns { mimeType, data }
+ * @throws {Error} 如果 data URL 格式无效
+ */
+export function parseDataUrl(dataUrl) {
+    if (!dataUrl.startsWith('data:')) {
+        throw new Error('Invalid data URL: must start with "data:"');
+    }
+    // 格式：data:image/png;base64,iVBORw0KG...
+    // 或：data:image/png;charset=utf-8;base64,iVBORw0KG...（带 charset）
+    const commaIndex = dataUrl.indexOf(',');
+    if (commaIndex === -1) {
+        throw new Error('Invalid data URL: missing comma separator');
+    }
+    const metaPart = dataUrl.substring(5, commaIndex); // "data:" 之后，"," 之前
+    const dataPart = dataUrl.substring(commaIndex + 1);
+    // 新增：验证 dataPart 非空
+    if (!dataPart) {
+        throw new Error('Invalid data URL: empty data part');
+    }
+    // 解析 meta 部分：image/png;base64 或 image/png;charset=utf-8;base64
+    const metaParts = metaPart.split(';');
+    const mimeType = metaParts[0];
+    if (!mimeType?.startsWith('image/')) {
+        throw new Error(`Invalid MIME type in data URL: ${mimeType}`);
+    }
+    // 修复：使用 includes 查找 base64，而不是假设 position [1]
+    // 这样可以处理带 charset 的 data URL，如：data:image/png;charset=utf-8;base64,...
+    if (!metaParts.includes('base64')) {
+        throw new Error('Invalid data URL: missing base64 encoding');
+    }
+    return {
+        mimeType,
+        data: dataPart
+    };
+}
+/**
+ * 检查是否为 data URL
+ * @param value - 待检查的字符串
+ * @returns 是否为 data URL
+ */
+export function isDataUrl(value) {
+    return value.startsWith('data:image/');
+}
+//# sourceMappingURL=data-url-parser.js.map

package/dist/utils/data-url-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-url-parser.js","sourceRoot":"","sources":["../../src/utils/data-url-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,wCAAwC;IACxC,gEAAgE;IAChE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAExC,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,oBAAoB;IACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IAEnD,oBAAoB;IACpB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,+DAA+D;IAC/D,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAE9B,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,8CAA8C;IAC9C,uEAAuE;IACvE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,QAAQ;KACf,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AACzC,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vision MCP Error Types
+ *
+ * @description 统一错误处理系统，提供清晰的错误分类和信息
+ */
+export declare enum VisionMCPErrorCode {
+    INVALID_INPUT = "INVALID_INPUT",
+    MODEL_CONFIG_ERROR = "MODEL_CONFIG_ERROR",
+    IMAGE_LOAD_ERROR = "IMAGE_LOAD_ERROR",
+    MODEL_API_ERROR = "MODEL_API_ERROR",
+    TIMEOUT_ERROR = "TIMEOUT_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+export interface VisionMCPErrorOptions {
+    message: string;
+    code: VisionMCPErrorCode;
+    details?: Record<string, any>;
+    cause?: unknown;
+}
+export declare class VisionMCPError extends Error {
+    readonly code: VisionMCPErrorCode;
+    readonly details?: Record<string, any>;
+    readonly timestamp: Date;
+    constructor({ message, code, details, cause }: VisionMCPErrorOptions);
+    toJSON(): {
+        error: {
+            message: string;
+            code: VisionMCPErrorCode;
+            details: {
+                [x: string]: any;
+            };
+            timestamp: string;
+        };
+    };
+}
+export declare class InvalidInputError extends VisionMCPError {
+    constructor(message: string, details?: Record<string, any>, cause?: unknown);
+}
+export declare class ModelConfigError extends VisionMCPError {
+    constructor(message: string, details?: Record<string, any>, cause?: unknown);
+}
+export declare class ImageLoadError extends VisionMCPError {
+    constructor(message: string, details?: Record<string, any>, cause?: unknown);
+}
+export declare class ModelAPIError extends VisionMCPError {
+    constructor(message: string, details?: Record<string, any>, cause?: unknown);
+}
+export declare class TimeoutError extends VisionMCPError {
+    constructor(message: string, details?: Record<string, any>, cause?: unknown);
+}
+/**
+ * 将未知错误转换为 VisionMCPError
+ */
+export declare function toVisionMCPError(error: unknown, context?: string): VisionMCPError;
+/**
+ * 将错误映射为 MCP 工具响应格式
+ */
+export declare function toMCPErrorResponse(error: VisionMCPError): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oBAAY,kBAAkB;IAC5B,aAAa,kBAAkB;IAC/B,kBAAkB,uBAAuB;IACzC,gBAAgB,qBAAqB;IACrC,eAAe,oBAAoB;IACnC,aAAa,kBAAkB;IAC/B,aAAa,kBAAkB;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAE,kBAAkB,CAAC;IACzC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9C,SAAgB,SAAS,EAAE,IAAI,CAAC;gBAEpB,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,qBAAqB;IAiBpE,MAAM;;;;;;;;;;CAaP;AAED,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO;CAS5E;AAED,qBAAa,gBAAiB,SAAQ,cAAc;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO;CAS5E;AAED,qBAAa,cAAe,SAAQ,cAAc;gBACpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO;CAS5E;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO;CAS5E;AAED,qBAAa,YAAa,SAAQ,cAAc;gBAClC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO;CAS5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CA+BjF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc;;;;;;EAUvD"}

package/dist/utils/errors.js

@@ -0,0 +1,146 @@
+/**
+ * Vision MCP Error Types
+ *
+ * @description 统一错误处理系统，提供清晰的错误分类和信息
+ */
+export var VisionMCPErrorCode;
+(function (VisionMCPErrorCode) {
+    VisionMCPErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    VisionMCPErrorCode["MODEL_CONFIG_ERROR"] = "MODEL_CONFIG_ERROR";
+    VisionMCPErrorCode["IMAGE_LOAD_ERROR"] = "IMAGE_LOAD_ERROR";
+    VisionMCPErrorCode["MODEL_API_ERROR"] = "MODEL_API_ERROR";
+    VisionMCPErrorCode["TIMEOUT_ERROR"] = "TIMEOUT_ERROR";
+    VisionMCPErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(VisionMCPErrorCode || (VisionMCPErrorCode = {}));
+export class VisionMCPError extends Error {
+    code;
+    details;
+    timestamp;
+    constructor({ message, code, details, cause }) {
+        super(message);
+        this.name = 'VisionMCPError';
+        this.code = code;
+        this.details = details;
+        this.timestamp = new Date();
+        if (cause) {
+            this.cause = cause;
+        }
+        // 保持正确的错误堆栈
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, VisionMCPError);
+        }
+    }
+    toJSON() {
+        // 从错误响应中移除堆栈跟踪（仅保留在日志中）
+        const { stack, ...detailsWithoutStack } = this.details || {};
+        return {
+            error: {
+                message: this.message,
+                code: this.code,
+                details: detailsWithoutStack,
+                timestamp: this.timestamp.toISOString()
+            }
+        };
+    }
+}
+export class InvalidInputError extends VisionMCPError {
+    constructor(message, details, cause) {
+        super({
+            message: `Invalid input: ${message}`,
+            code: VisionMCPErrorCode.INVALID_INPUT,
+            details,
+            cause
+        });
+        this.name = 'InvalidInputError';
+    }
+}
+export class ModelConfigError extends VisionMCPError {
+    constructor(message, details, cause) {
+        super({
+            message: `Model configuration error: ${message}`,
+            code: VisionMCPErrorCode.MODEL_CONFIG_ERROR,
+            details,
+            cause
+        });
+        this.name = 'ModelConfigError';
+    }
+}
+export class ImageLoadError extends VisionMCPError {
+    constructor(message, details, cause) {
+        super({
+            message: `Failed to load image: ${message}`,
+            code: VisionMCPErrorCode.IMAGE_LOAD_ERROR,
+            details,
+            cause
+        });
+        this.name = 'ImageLoadError';
+    }
+}
+export class ModelAPIError extends VisionMCPError {
+    constructor(message, details, cause) {
+        super({
+            message: `Model API error: ${message}`,
+            code: VisionMCPErrorCode.MODEL_API_ERROR,
+            details,
+            cause
+        });
+        this.name = 'ModelAPIError';
+    }
+}
+export class TimeoutError extends VisionMCPError {
+    constructor(message, details, cause) {
+        super({
+            message: `Request timeout: ${message}`,
+            code: VisionMCPErrorCode.TIMEOUT_ERROR,
+            details,
+            cause
+        });
+        this.name = 'TimeoutError';
+    }
+}
+/**
+ * 将未知错误转换为 VisionMCPError
+ */
+export function toVisionMCPError(error, context) {
+    if (error instanceof VisionMCPError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        // 堆栈跟踪只记录在日志中，不包含在错误详情中
+        const details = {
+            originalError: error.name
+        };
+        // 仅当 LOG_LEVEL 为 debug 时才包含堆栈跟踪
+        if (process.env.LOG_LEVEL === 'debug') {
+            details.stack = error.stack;
+        }
+        return new VisionMCPError({
+            message: context ? `${context}: ${error.message}` : error.message,
+            code: VisionMCPErrorCode.UNKNOWN_ERROR,
+            details,
+            cause: error
+        });
+    }
+    return new VisionMCPError({
+        message: context || 'An unknown error occurred',
+        code: VisionMCPErrorCode.UNKNOWN_ERROR,
+        details: {
+            error: String(error)
+        }
+    });
+}
+/**
+ * 将错误映射为 MCP 工具响应格式
+ */
+export function toMCPErrorResponse(error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(error.toJSON(), null, 2)
+            }
+        ],
+        isError: true
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/image-input.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Image Input Normalization Utility
+ *
+ * @description 统一处理图片输入：支持 URL、base64(data URL) 和本地路径
+ */
+/**
+ * 图片输入类型
+ */
+export type ImageInputType = 'url' | 'base64' | 'local';
+/**
+ * 规范化后的图片输入格式（总是转换为 base64 data URL）
+ */
+export interface NormalizedImageInput {
+    type: ImageInputType;
+    originalInput: string;
+    dataUrl: string;
+    mimeType: string;
+}
+/**
+ * 检测输入类型
+ */
+export declare function detectInputType(input: string): ImageInputType;
+/**
+ * 从文件扩展名获取 MIME 类型
+ */
+export declare function getMimeTypeFromFileName(filename: string): string;
+/**
+ * 从 data URL 提取 MIME 类型
+ */
+export declare function getMimeTypeFromDataUrl(dataUrl: string): string;
+/**
+ * 检测 URL 是否指向图片文件
+ */
+export declare function isImageUrl(url: string): boolean;
+/**
+ * 规范化图片输入为统一的 data URL 格式
+ */
+export declare function normalizeImageInput(input: string): Promise<NormalizedImageInput>;
+/**
+ * 获取图片大小信息（用于日志）
+ */
+export declare function getImageSizeInfo(dataUrl: string): {
+    size: number;
+};
+//# sourceMappingURL=image-input.d.ts.map

package/dist/utils/image-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-input.d.ts","sourceRoot":"","sources":["../../src/utils/image-input.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAyBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAa7D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYhE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoB9D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAY/C;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuCtF;AAkKD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAalE"}