image-vision-mcp 1.0.0

package/dist/services/image.d.ts

@@ -0,0 +1,19 @@
+import type { ImageLoadResult } from "../types.js";
+export declare function isHttpUrl(input: string): boolean;
+export interface UrlCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * 校验图片 URL 是否安全（防止 SSRF 访问内网/元数据服务）
+ *
+ * 默认拒绝：loopback、私网、链路本地、CGNAT、已知元数据 hostname。
+ * 如需访问内网图片服务，设置环境变量 ALLOW_PRIVATE_NETWORK_IMAGES=1
+ */
+export declare function isAllowedUrl(url: string): UrlCheckResult;
+export declare function detectMimeTypeFromPath(filePath: string): string;
+export declare function detectMimeTypeFromContentType(contentType: string | undefined): string;
+export declare function imageBufferToDataUrl(buffer: Buffer, mimeType: string): string;
+export declare function loadLocalImage(filePath: string): Promise<ImageLoadResult>;
+export declare function downloadImage(url: string): Promise<ImageLoadResult>;
+export declare function loadImageAsDataUrl(input: string): Promise<ImageLoadResult>;

package/dist/services/image.js

@@ -0,0 +1,216 @@
+import fs from "fs/promises";
+import path from "path";
+import { URL } from "url";
+import net from "net";
+import http from "http";
+import https from "https";
+import dns from "dns";
+import axios from "axios";
+import { SUPPORTED_MIME_TYPES, IMAGE_DOWNLOAD_TIMEOUT_MS, IMAGE_MAX_SIZE_BYTES, } from "../constants.js";
+export function isHttpUrl(input) {
+    return /^https?:\/\//i.test(input);
+}
+// ────────────────────── SSRF 防护 ──────────────────────
+const BLOCKED_HOSTNAMES = new Set([
+    "localhost",
+    "ip6-localhost",
+    "ip6-loopback",
+    "metadata.google.internal", // GCP 元数据
+    "metadata", // 一些云环境的简写
+]);
+function isPrivateIPv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+        return false;
+    }
+    const [a, b] = parts;
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local（含 AWS/GCP 元数据）
+    if (a === 0)
+        return true; // 0.0.0.0/8
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    return false;
+}
+function isPrivateIPv6(ip) {
+    const lower = ip.toLowerCase();
+    if (lower === "::1")
+        return true; // loopback
+    if (lower === "::")
+        return true; // 未指定
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true; // fc00::/7 ULA
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") ||
+        lower.startsWith("fea") || lower.startsWith("feb"))
+        return true; // fe80::/10 link-local
+    return false;
+}
+/**
+ * 校验图片 URL 是否安全（防止 SSRF 访问内网/元数据服务）
+ *
+ * 默认拒绝：loopback、私网、链路本地、CGNAT、已知元数据 hostname。
+ * 如需访问内网图片服务，设置环境变量 ALLOW_PRIVATE_NETWORK_IMAGES=1
+ */
+export function isAllowedUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { allowed: false, reason: "URL 解析失败" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { allowed: false, reason: `不允许的协议: ${parsed.protocol}` };
+    }
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, ""); // 去掉 IPv6 方括号
+    if (BLOCKED_HOSTNAMES.has(hostname.toLowerCase())) {
+        return { allowed: false, reason: `不允许的 hostname: ${hostname}` };
+    }
+    if (net.isIPv4(hostname)) {
+        if (isPrivateIPv4(hostname)) {
+            return { allowed: false, reason: `不允许的内网 IP: ${hostname}` };
+        }
+    }
+    else if (net.isIPv6(hostname)) {
+        if (isPrivateIPv6(hostname)) {
+            return { allowed: false, reason: `不允许的内网 IP: ${hostname}` };
+        }
+    }
+    return { allowed: true };
+}
+function isPrivateIP(ip) {
+    if (net.isIPv4(ip))
+        return isPrivateIPv4(ip);
+    if (net.isIPv6(ip))
+        return isPrivateIPv6(ip);
+    return false;
+}
+/**
+ * 创建安全的 DNS lookup 函数：解析后校验所有 IP，拒绝内网地址。
+ *
+ * 防止 DNS rebinding 攻击：攻击者控制域名，第一次解析返回公网 IP 通过校验，
+ * 第二次解析返回内网 IP 绕过校验。本函数返回第一个校验过的 IP，强制 axios
+ * 用这个 IP 连接，不再重新解析。
+ */
+function createSafeLookup(allowPrivate) {
+    return (hostname, options, callback) => {
+        const lookupOpts = { ...options, all: true };
+        dns.lookup(hostname, lookupOpts, (err, addresses) => {
+            if (err) {
+                callback(err, "", 0);
+                return;
+            }
+            const list = (addresses || []);
+            if (list.length === 0) {
+                callback(new Error(`DNS 解析无结果: ${hostname}`), "", 0);
+                return;
+            }
+            if (!allowPrivate) {
+                for (const addr of list) {
+                    if (isPrivateIP(addr.address)) {
+                        callback(new Error(`域名 ${hostname} 解析到内网 IP: ${addr.address}`), "", 0);
+                        return;
+                    }
+                }
+            }
+            const first = list[0];
+            callback(null, first.address, first.family);
+        });
+    };
+}
+export function detectMimeTypeFromPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return SUPPORTED_MIME_TYPES[ext] ?? "image/jpeg";
+}
+export function detectMimeTypeFromContentType(contentType) {
+    if (!contentType)
+        return "image/jpeg";
+    const base = contentType.split(";")[0].trim().toLowerCase();
+    const known = ["image/jpeg", "image/png", "image/gif", "image/webp", "image/bmp"];
+    return known.includes(base) ? base : "image/jpeg";
+}
+export function imageBufferToDataUrl(buffer, mimeType) {
+    return `data:${mimeType};base64,${buffer.toString("base64")}`;
+}
+export async function loadLocalImage(filePath) {
+    let stats;
+    try {
+        stats = await fs.stat(filePath);
+    }
+    catch (err) {
+        throw new Error(`无法访问本地文件: ${filePath} (${err.message})`);
+    }
+    if (!stats.isFile()) {
+        throw new Error(`路径不是文件: ${filePath}`);
+    }
+    const buffer = await fs.readFile(filePath);
+    const mimeType = detectMimeTypeFromPath(filePath);
+    return {
+        dataUrl: imageBufferToDataUrl(buffer, mimeType),
+        mimeType,
+        sizeBytes: buffer.length,
+    };
+}
+export async function downloadImage(url) {
+    // SSRF 防护：默认拒绝内网/loopback/元数据地址
+    const allowPrivateRaw = (process.env.ALLOW_PRIVATE_NETWORK_IMAGES || "").toLowerCase();
+    const allowPrivate = allowPrivateRaw === "1" || allowPrivateRaw === "true";
+    if (!allowPrivate) {
+        const check = isAllowedUrl(url);
+        if (!check.allowed) {
+            throw new Error(`${check.reason}（如需访问内网图片，设置环境变量 ALLOW_PRIVATE_NETWORK_IMAGES=1）`);
+        }
+    }
+    try {
+        // 自定义 DNS 解析：校验所有解析到的 IP，防止 DNS rebinding 绕过 SSRF 防护。
+        // 通过 httpAgent/httpsAgent 传入，axios 会把它们传给底层 http.request。
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const safeLookup = createSafeLookup(allowPrivate);
+        const httpAgent = new http.Agent({ lookup: safeLookup });
+        const httpsAgent = new https.Agent({ lookup: safeLookup });
+        const config = {
+            responseType: "arraybuffer",
+            timeout: IMAGE_DOWNLOAD_TIMEOUT_MS,
+            maxContentLength: IMAGE_MAX_SIZE_BYTES,
+            maxRedirects: 5,
+            httpAgent,
+            httpsAgent,
+        };
+        const response = await axios.get(url, config);
+        const buffer = Buffer.from(response.data);
+        const contentType = response.headers?.["content-type"];
+        const mimeType = detectMimeTypeFromContentType(typeof contentType === "string" ? contentType : undefined);
+        return {
+            dataUrl: imageBufferToDataUrl(buffer, mimeType),
+            mimeType,
+            sizeBytes: buffer.length,
+        };
+    }
+    catch (err) {
+        if (err instanceof axios.AxiosError) {
+            if (err.response) {
+                throw new Error(`下载图片失败: HTTP ${err.response.status} ${err.response.statusText} - ${url}`);
+            }
+            if (err.code === "ECONNABORTED") {
+                throw new Error(`下载图片超时 (${IMAGE_DOWNLOAD_TIMEOUT_MS}ms): ${url}`);
+            }
+            throw new Error(`下载图片失败: ${err.message} - ${url}`);
+        }
+        throw new Error(`下载图片失败: ${err.message} - ${url}`);
+    }
+}
+export async function loadImageAsDataUrl(input) {
+    if (isHttpUrl(input)) {
+        return downloadImage(input);
+    }
+    return loadLocalImage(input);
+}
+//# sourceMappingURL=image.js.map

package/dist/services/image.js.map

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

package/dist/services/moonshot.d.ts

@@ -0,0 +1,9 @@
+import type { MoonshotChatResponse, MoonshotMessage } from "../types.js";
+export interface CallMoonshotParams {
+    apiKey: string;
+    model?: string;
+    messages: MoonshotMessage[];
+    maxTokens?: number;
+}
+export declare function handleMoonshotError(error: unknown): string;
+export declare function callMoonshot(params: CallMoonshotParams): Promise<MoonshotChatResponse>;

package/dist/services/moonshot.js

@@ -0,0 +1,71 @@
+import axios, { AxiosError } from "axios";
+import { API_BASE_URL, DEFAULT_MODEL, REQUEST_TIMEOUT_MS } from "../constants.js";
+export function handleMoonshotError(error) {
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            const errMsg = data?.error?.message;
+            switch (status) {
+                case 401:
+                    return `Error: Moonshot API 鉴权失败 (401)。请检查 MOONSHOT_API_KEY 是否正确。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+                case 403:
+                    return `Error: Moonshot API 拒绝访问 (403)。可能是 API key 无权限调用该模型。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+                case 404:
+                    return `Error: Moonshot API 模型不存在 (404)。请检查模型名是否正确 (当前: ${DEFAULT_MODEL})。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+                case 429:
+                    return `Error: Moonshot API 限流 (429)。请稍后重试。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+                case 500:
+                case 502:
+                case 503:
+                    return `Error: Moonshot API 服务端错误 (${status})。请稍后重试。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+                default:
+                    return `Error: Moonshot API 请求失败 (HTTP ${status})。${errMsg ? ` 详情: ${errMsg}` : ""}`;
+            }
+        }
+        if (error.code === "ECONNABORTED") {
+            return `Error: Moonshot API 请求超时 (${REQUEST_TIMEOUT_MS}ms)。请稍后重试。`;
+        }
+        if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED") {
+            return `Error: 无法连接 Moonshot API (${error.code})。请检查网络。`;
+        }
+    }
+    return `Error: 调用 Moonshot API 时发生意外错误: ${error instanceof Error ? error.message : String(error)}`;
+}
+const MAX_RETRIES = 2;
+const INITIAL_RETRY_DELAY_MS = 1000;
+export async function callMoonshot(params) {
+    const { apiKey, model = DEFAULT_MODEL, messages, maxTokens = 2048 } = params;
+    if (!apiKey) {
+        throw new Error("MOONSHOT_API_KEY 未设置");
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            const response = await axios.post(`${API_BASE_URL}/chat/completions`, {
+                model,
+                messages,
+                max_tokens: maxTokens,
+            }, {
+                timeout: REQUEST_TIMEOUT_MS,
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+            });
+            return response.data;
+        }
+        catch (err) {
+            lastError = err;
+            // 仅对 429 限流重试，指数退避：1s, 2s
+            if (err instanceof AxiosError && err.response?.status === 429 && attempt < MAX_RETRIES) {
+                const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=moonshot.js.map

package/dist/services/moonshot.js.map

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

package/dist/tools/describeClipboard.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDescribeClipboardTool(server: McpServer, getApiKey: () => string): void;

package/dist/tools/describeClipboard.js

@@ -0,0 +1,106 @@
+import { DescribeClipboardInputSchema } from "../schemas.js";
+import { DEFAULT_MODEL, CHARACTER_LIMIT } from "../constants.js";
+import { readClipboardImage } from "../services/clipboard.js";
+import { callMoonshot, handleMoonshotError } from "../services/moonshot.js";
+export function registerDescribeClipboardTool(server, getApiKey) {
+    server.registerTool("kimi_describe_clipboard", {
+        title: "Kimi 识别剪贴板图片",
+        description: `使用 Moonshot Kimi 视觉模型 (kimi-k2.6) 识别剪贴板中的图片并返回文本描述。
+
+直接从系统剪贴板读取图片，无需提供文件路径或 URL。
+跨平台支持: Windows (PowerShell)、macOS (pngpaste/osascript)、Linux (xclip/xsel)。
+
+Args:
+  - prompt (string, 可选): 询问图片的问题或识图指令，默认 "请详细描述这张图片的内容。"。最长 4000 字符
+  - max_tokens (number, 可选): 返回描述的最大 token 数，1-8192，默认 2048
+
+Returns:
+  文本内容，包含图片描述和 token 使用情况元信息。
+
+Usage:
+  1. 用户先复制一张图片到剪贴板 (Ctrl+C)
+  2. 调用此工具即可自动从剪贴板读取并识别
+
+Examples:
+  - 描述剪贴板截图: (无参数，使用默认 prompt)
+  - 提取剪贴板图片中的文字: prompt="请提取图片中的所有文字"
+  - 识别剪贴板中的图表: prompt="图表中显示的数据是什么"
+
+Error Handling:
+  - "剪贴板中没有图片": 请先复制一张图片到剪贴板
+  - "不支持的平台": 当前操作系统不支持
+  - "Moonshot API 鉴权失败 (401)": API key 错误
+  - "Moonshot API 限流 (429)": 请求过于频繁，请稍后重试`,
+        inputSchema: DescribeClipboardInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        const apiKey = getApiKey();
+        // 1. 从剪贴板读取图片
+        let imageResult;
+        try {
+            imageResult = await readClipboardImage();
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: 读取剪贴板图片失败 - ${err.message}`,
+                    },
+                ],
+            };
+        }
+        // 2. 构造 Moonshot 请求
+        const content = [
+            { type: "image_url", image_url: { url: imageResult.dataUrl } },
+            { type: "text", text: params.prompt },
+        ];
+        const messages = [{ role: "user", content }];
+        // 3. 调用 Moonshot API
+        let response;
+        try {
+            response = await callMoonshot({
+                apiKey,
+                model: DEFAULT_MODEL,
+                messages,
+                maxTokens: params.max_tokens,
+            });
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: handleMoonshotError(err) }],
+            };
+        }
+        // 4. 提取描述
+        const description = response.choices?.[0]?.message?.content ?? "";
+        if (!description) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: Moonshot API 返回空内容。完整响应: ${JSON.stringify(response)}`,
+                    },
+                ],
+            };
+        }
+        // 5. 构造输出
+        const meta = [
+            `模型: ${response.model}`,
+            `图片大小: ${(imageResult.sizeBytes / 1024).toFixed(2)} KB (${imageResult.mimeType})`,
+            `Token 使用: ${response.usage?.total_tokens ?? "未知"} (prompt: ${response.usage?.prompt_tokens ?? "?"}, completion: ${response.usage?.completion_tokens ?? "?"})`,
+        ].join("\n");
+        let text = `${description}\n\n---\n${meta}`;
+        if (text.length > CHARACTER_LIMIT) {
+            text = text.slice(0, CHARACTER_LIMIT) + `\n\n[已截断，原文长度 ${text.length} 字符]`;
+        }
+        return {
+            content: [{ type: "text", text }],
+        };
+    });
+}
+//# sourceMappingURL=describeClipboard.js.map

package/dist/tools/describeClipboard.js.map

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

package/dist/tools/describeImage.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDescribeImageTool(server: McpServer, getApiKey: () => string): void;

package/dist/tools/describeImage.js

@@ -0,0 +1,105 @@
+import { DescribeImageInputSchema } from "../schemas.js";
+import { DEFAULT_MODEL, CHARACTER_LIMIT } from "../constants.js";
+import { loadImageAsDataUrl } from "../services/image.js";
+import { callMoonshot, handleMoonshotError } from "../services/moonshot.js";
+export function registerDescribeImageTool(server, getApiKey) {
+    server.registerTool("kimi_describe_image", {
+        title: "Kimi 识图",
+        description: `使用 Moonshot Kimi 视觉模型 (kimi-k2.6) 识别图片并返回文本描述。
+
+支持输入本地图片路径或 http(s):// 图片 URL。MCP 内部会自动将图片转换为 base64 后调用 Moonshot API（Moonshot 不支持直接传 URL）。
+
+Args:
+  - image (string, 必填): 图片路径或 URL。
+    - 本地路径示例: "C:/Users/user/screenshot.png" 或 "/tmp/img.jpg"
+    - URL 示例: "https://example.com/img.png"
+  - prompt (string, 可选): 询问图片的问题或识图指令，默认 "请详细描述这张图片的内容。"。最长 4000 字符
+  - max_tokens (number, 可选): 返回描述的最大 token 数，1-8192，默认 2048
+
+Returns:
+  文本内容，包含图片描述和 token 使用情况元信息。
+
+Examples:
+  - 描述本地截图: image="C:/Users/user/screenshot.png"
+  - 描述网络图片: image="https://example.com/chart.png", prompt="图表中显示的数据是什么"
+  - 提取文字 (OCR): image="C:/Users/user/document.jpg", prompt="请提取图片中的所有文字"
+  - 识别物体: image="C:/Users/user/photo.jpg", prompt="图片里有哪些物体"
+
+Error Handling:
+  - "无法访问本地文件": 文件路径错误或无权限
+  - "下载图片失败": URL 无法访问或超时
+  - "Moonshot API 鉴权失败 (401)": API key 错误
+  - "Moonshot API 限流 (429)": 请求过于频繁，请稍后重试`,
+        inputSchema: DescribeImageInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (params) => {
+        const apiKey = getApiKey();
+        // 1. 加载图片为 data URL
+        let imageResult;
+        try {
+            imageResult = await loadImageAsDataUrl(params.image);
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: 加载图片失败 - ${err.message}`,
+                    },
+                ],
+            };
+        }
+        // 2. 构造 Moonshot 请求
+        const content = [
+            { type: "image_url", image_url: { url: imageResult.dataUrl } },
+            { type: "text", text: params.prompt },
+        ];
+        const messages = [{ role: "user", content }];
+        // 3. 调用 Moonshot API
+        let response;
+        try {
+            response = await callMoonshot({
+                apiKey,
+                model: DEFAULT_MODEL,
+                messages,
+                maxTokens: params.max_tokens,
+            });
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: handleMoonshotError(err) }],
+            };
+        }
+        // 4. 提取描述
+        const description = response.choices?.[0]?.message?.content ?? "";
+        if (!description) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: Moonshot API 返回空内容。完整响应: ${JSON.stringify(response)}`,
+                    },
+                ],
+            };
+        }
+        // 5. 构造输出
+        const meta = [
+            `模型: ${response.model}`,
+            `图片大小: ${(imageResult.sizeBytes / 1024).toFixed(2)} KB (${imageResult.mimeType})`,
+            `Token 使用: ${response.usage?.total_tokens ?? "未知"} (prompt: ${response.usage?.prompt_tokens ?? "?"}, completion: ${response.usage?.completion_tokens ?? "?"})`,
+        ].join("\n");
+        let text = `${description}\n\n---\n${meta}`;
+        if (text.length > CHARACTER_LIMIT) {
+            text = text.slice(0, CHARACTER_LIMIT) + `\n\n[已截断，原文长度 ${text.length} 字符]`;
+        }
+        return {
+            content: [{ type: "text", text }],
+        };
+    });
+}
+//# sourceMappingURL=describeImage.js.map

package/dist/tools/describeImage.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+export interface MoonshotImageContent {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export interface MoonshotTextContent {
+    type: "text";
+    text: string;
+}
+export type MoonshotContent = MoonshotImageContent | MoonshotTextContent;
+export interface MoonshotMessage {
+    role: "user" | "assistant" | "system";
+    content: string | MoonshotContent[];
+}
+export interface MoonshotChoice {
+    index: number;
+    message: {
+        role: string;
+        content: string;
+    };
+    finish_reason: string;
+}
+export interface MoonshotUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface MoonshotChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: MoonshotChoice[];
+    usage: MoonshotUsage;
+}
+export interface ImageLoadResult {
+    dataUrl: string;
+    mimeType: string;
+    sizeBytes: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}