@infimind-next/ai-hive-mcp 0.2.5 → 0.3.0

package/README.md

@@ -0,0 +1,48 @@
+# @infimind-next/ai-hive-mcp
+
+蜂巢 AI 的本地 MCP 服务，让你在自己的 MCP 客户端里调用文本、图片和视频模型。
+
+## 安装
+
+在 MCP 客户端中加入以下配置，把 `<APIKEY>` 换成你在蜂巢 AI 网页端「MCP 接入」里生成的 API Key：
+
+```json
+{
+  "mcpServers": {
+    "ai-hive": {
+      "command": "npx",
+      "args": ["-y", "@infimind-next/ai-hive-mcp@0.3.0", "--key", "<APIKEY>"]
+    }
+  }
+}
+```
+
+要求 Node.js >= 20.19.0。本包通过标准 MCP stdio 与客户端通信，仅保证与支持 MCP 的客户端配合使用。
+
+## 工具
+
+- `get_user_info`：查询当前用户和余额
+- `list_models`：按 TEXT、IMAGE 或 VIDEO 查询可用模型与公开价格
+- `get_model`：查询单个模型的参数 schema、媒体要求、计费因素和调用示例
+- `upload_media_from_path`：上传本地图片、视频或音频，返回 mediaId
+- `chat_text`：文本对话
+- `generate_image`：图片预检或正式生成
+- `generate_video`：视频预检或正式生成
+- `get_generation_task`：查询生成任务进度和结果
+
+## 调用流程
+
+图片和视频生成固定按 5 步走：
+
+1. 用 `list_models` 选择模型，记录 `publicModelId`。
+2. 用 `get_model` 查看参数契约，`params` 的字段名、类型、枚举值和默认值逐项来自返回的 `paramsSchema`。
+3. 调用 `generate_image` 或 `generate_video` 时传 `dryRun: true` 预检，核对返回的 `estimatedReservationMicros` 估价（单位：人民币 micros，1 元 = 1,000,000 micros）。
+4. 确认费用后去掉 `dryRun` 正式生成，`params` 替换为预检返回的 `resolvedParams`，并传入预检返回的 `pricingSnapshot` 和本次调用稳定唯一的 `clientRequestId`。
+5. 用 `get_generation_task` 查询任务进度和结果，不重复创建任务。
+
+## 重试与价格变化
+
+- 传输中断或超时后重试：复用同一个 `clientRequestId` 和相同业务参数，不会重复扣费。
+- 修正参数、余额或媒体问题后重试：必须使用新的 `clientRequestId`。
+- 正式生成提示价格已更新：保持业务参数和原 `clientRequestId` 不变，重新预检获取最新 `pricingSnapshot` 后重试。
+- 返回 `REQUEST_OUTCOME_UNKNOWN`：停止自动重试，联系管理员核查。

package/dist/api-client.d.ts

@@ -21,11 +21,13 @@ export declare class AiHiveApiClient {
     private readResponse;
     getUserInfo(): Promise<unknown>;
     listModels(input: Record<string, unknown>): Promise<unknown>;
+    getModel(publicModelId: string, routingMode?: string): Promise<unknown>;
     createMediaUpload(input: unknown): Promise<unknown>;
     completeMediaUpload(mediaId: string): Promise<unknown>;
     chatText(input: unknown): Promise<unknown>;
     generateImage(input: unknown): Promise<unknown>;
     generateVideo(input: unknown): Promise<unknown>;
+    private requestGeneration;
     getGenerationTask(input: {
         taskId: string;
     }): Promise<unknown>;

package/dist/api-client.js

@@ -1,4 +1,14 @@
 import { encodeMcpClientInfo, MCP_CLIENT_INFO_HEADER, } from "./client-info.js";
+class AiHiveApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "AiHiveApiError";
+    }
+}
+const GET_MODEL_UNSUPPORTED_MESSAGE = "当前 AI-HIVE 服务端版本不支持 get_model，请先升级服务端后再试";
+const DRY_RUN_UNSUPPORTED_MESSAGE = "当前 AI-HIVE 服务端版本不支持 dryRun，请先升级服务端后再试";
 function formatIssue(value) {
     if (typeof value === "string") {
         return value;
@@ -34,6 +44,15 @@ function errorMessage(body) {
 function timeoutError() {
     return new Error("请求超时，请稍后重试");
 }
+function redactInternalPricing(value) {
+    if (Array.isArray(value)) {
+        return value.map(redactInternalPricing);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => key === "originalMicros" ? [] : [[key, redactInternalPricing(item)]]));
+    }
+    return value;
+}
 async function discardResponseBody(response) {
     try {
         await response.body?.cancel();
@@ -119,18 +138,39 @@ export class AiHiveApiClient {
     async readResponse(response) {
         const body = await response.json().catch(() => ({}));
         if (!response.ok) {
-            throw new Error(errorMessage(body));
+            throw new AiHiveApiError(response.status, errorMessage(body));
         }
         return body;
     }
     getUserInfo() {
         return this.request("/mcp/user-info");
     }
-    listModels(input) {
-        const query = typeof input.modelType === "string"
-            ? `?modelType=${encodeURIComponent(input.modelType)}`
+    async listModels(input) {
+        const query = new URLSearchParams();
+        if (typeof input.modelType === "string") {
+            query.set("modelType", input.modelType);
+        }
+        if (typeof input.detail === "string") {
+            query.set("detail", input.detail);
+        }
+        const serialized = query.toString();
+        return redactInternalPricing(await this.request(`/mcp/models${serialized ? `?${serialized}` : ""}`));
+    }
+    // getModel 与 listModels 的 detail 参数依赖服务端新部署; 旧服务端会 404 或被
+    // strict 入参校验拒绝, 所以 npm 0.3.0 必须在服务端升级之后发布.
+    async getModel(publicModelId, routingMode) {
+        const query = routingMode
+            ? `?${new URLSearchParams({ routingMode }).toString()}`
             : "";
-        return this.request(`/mcp/models${query}`);
+        try {
+            return redactInternalPricing(await this.request(`/mcp/models/${encodeURIComponent(publicModelId)}${query}`));
+        }
+        catch (error) {
+            if (error instanceof AiHiveApiError && error.status === 404) {
+                throw new Error(GET_MODEL_UNSUPPORTED_MESSAGE);
+            }
+            throw error;
+        }
     }
     createMediaUpload(input) {
         return this.request("/mcp/media/upload-token", {
@@ -150,16 +190,29 @@ export class AiHiveApiClient {
         });
     }
     generateImage(input) {
-        return this.request("/mcp/generation/image", {
-            method: "POST",
-            body: JSON.stringify(input),
-        });
+        return this.requestGeneration("/mcp/generation/image", input);
     }
     generateVideo(input) {
-        return this.request("/mcp/generation/video", {
-            method: "POST",
-            body: JSON.stringify(input),
-        });
+        return this.requestGeneration("/mcp/generation/video", input);
+    }
+    async requestGeneration(path, input) {
+        try {
+            return await this.request(path, {
+                method: "POST",
+                body: JSON.stringify(input),
+            });
+        }
+        catch (error) {
+            if (typeof input === "object" &&
+                input !== null &&
+                input.dryRun === true &&
+                error instanceof AiHiveApiError &&
+                error.status === 400 &&
+                /\bdryRun\b/.test(error.message)) {
+                throw new Error(DRY_RUN_UNSUPPORTED_MESSAGE);
+            }
+            throw error;
+        }
     }
     getGenerationTask(input) {
         return this.request(`/mcp/generation/tasks/${encodeURIComponent(input.taskId)}`);

package/dist/local-media.js

@@ -5,6 +5,7 @@ import { mcpCreateMediaUploadOutputSchema, mcpUploadMediaFromPathInputSchema, }
 import { fileTypeFromBuffer } from "file-type";
 const FILE_HEAD_BYTES = 4100;
 const SMALL_MEDIA_LIMIT_BYTES = 10 * 1024 * 1024;
+const IMAGE_LIMIT_BYTES = 30 * 1024 * 1024;
 const AUDIO_LIMIT_BYTES = 15 * 1024 * 1024;
 const VIDEO_LIMIT_BYTES = 100 * 1024 * 1024;
 const EXTENSION_MIME = new Map([
@@ -12,6 +13,12 @@ const EXTENSION_MIME = new Map([
     [".jpg", "image/jpeg"],
     [".jpeg", "image/jpeg"],
     [".webp", "image/webp"],
+    [".bmp", "image/bmp"],
+    [".gif", "image/gif"],
+    [".tif", "image/tiff"],
+    [".tiff", "image/tiff"],
+    [".heic", "image/heic"],
+    [".heif", "image/heif"],
     [".mp3", "audio/mpeg"],
     [".wav", "audio/wav"],
     [".mp4", "video/mp4"],
@@ -47,6 +54,9 @@ function mediaSizeLimit(contentType) {
     if (contentType.startsWith("audio/")) {
         return AUDIO_LIMIT_BYTES;
     }
+    if (contentType.startsWith("image/")) {
+        return IMAGE_LIMIT_BYTES;
+    }
     return SMALL_MEDIA_LIMIT_BYTES;
 }
 function mediaTypeLabel(contentType) {
@@ -56,6 +66,9 @@ function mediaTypeLabel(contentType) {
     if (contentType.startsWith("audio/")) {
         return "音频";
     }
+    if (contentType.startsWith("image/")) {
+        return "图片";
+    }
     return "图片/文档";
 }
 function assertFileSizeAllowed(sizeBytes, contentType) {

package/dist/schemas.d.ts

@@ -56,6 +56,11 @@ export declare const mcpUploadMediaFromPathInputSchema: z.ZodObject<{
 }>;
 export declare const listModelsShape: {
     modelType: z.ZodOptional<z.ZodEnum<["TEXT", "IMAGE", "VIDEO"]>>;
+    detail: z.ZodOptional<z.ZodEnum<["lite", "full"]>>;
+};
+export declare const getModelShape: {
+    publicModelId: z.ZodString;
+    routingMode: z.ZodOptional<z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>>;
 };
 export declare const chatTextShape: {
     publicModelId: z.ZodString;
@@ -63,7 +68,7 @@ export declare const chatTextShape: {
     messages: z.ZodArray<z.ZodObject<{
         role: z.ZodEnum<["system", "user", "assistant"]>;
         content: z.ZodEffects<z.ZodString, string, string>;
-        mediaIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        mediaIds: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
     }, "strict", z.ZodTypeAny, {
         content: string;
         role: "user" | "assistant" | "system";
@@ -71,31 +76,36 @@ export declare const chatTextShape: {
     }, {
         content: string;
         role: "user" | "assistant" | "system";
-        mediaIds?: string[] | undefined;
+        mediaIds?: string[] | null | undefined;
     }>, "many">;
     thinkingEnabled: z.ZodOptional<z.ZodBoolean>;
-    pricingSnapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    clientRequestId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const generateImageShape: {
     publicModelId: z.ZodString;
     routingMode: z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
-    batchSize: z.ZodDefault<z.ZodNumber>;
-    imageMediaIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    pricingSnapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    batchSize: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodNumber, z.ZodNull]>, number, number | null>>;
+    imageMediaIds: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+    params: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>, Record<string, unknown>, Record<string, unknown> | null>>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    clientRequestId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const generateVideoShape: {
     publicModelId: z.ZodString;
     routingMode: z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>;
     prompt: z.ZodEffects<z.ZodString, string, string>;
-    imageMediaIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    videoMediaIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    audioMediaIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    imageMediaIds: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+    videoMediaIds: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
+    audioMediaIds: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodNull]>, string[], string[] | null>>;
     firstFrameMediaId: z.ZodOptional<z.ZodString>;
     lastFrameMediaId: z.ZodOptional<z.ZodString>;
-    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    pricingSnapshot: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    params: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodNull]>, Record<string, unknown>, Record<string, unknown> | null>>;
+    dryRun: z.ZodDefault<z.ZodBoolean>;
+    clientRequestId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const getGenerationTaskShape: {
     taskId: z.ZodString;

package/dist/schemas.js

@@ -11,7 +11,24 @@ const routingModeSchema = z.enum([
     "SUCCESS_FIRST",
 ]);
 const pricingSnapshotSchema = z.record(z.unknown());
-const paramsSchema = z.record(z.unknown()).default({});
+// 宿主常把可选数组/对象字段塞成 null, 归一到默认值避免服务端收到非法请求.
+const nullableMediaIdsSchema = z
+    .union([z.array(mediaIdSchema), z.null()])
+    .transform((value) => value ?? [])
+    .default([]);
+const paramsSchema = z
+    .union([z.record(z.unknown()), z.null()])
+    .transform((value) => value ?? {})
+    .default({});
+// SDK 在 handler 之前先用 zod 校验入参, schema 必须放行畸形快照, server 层才有机会代为归一化.
+const pricingSnapshotInputSchema = z
+    .union([
+    pricingSnapshotSchema,
+    z.array(pricingSnapshotSchema.nullable()),
+    z.string(),
+    z.null(),
+])
+    .optional();
 export const mcpCreateMediaUploadOutputSchema = z
     .object({
     mediaId: mediaIdSchema,
@@ -41,39 +58,60 @@ const messageSchema = z
     .object({
     role: z.enum(["system", "user", "assistant"]),
     content: nonBlankStringSchema,
-    mediaIds: z.array(mediaIdSchema).default([]),
+    mediaIds: nullableMediaIdsSchema,
 })
     .strict();
+// 幂等键供付费调用去重, 空白值等同于没传, 所以沿用 nonBlank 校验但保持 optional.
+const clientRequestIdSchema = z
+    .string()
+    .max(100)
+    .refine((value) => value.trim().length > 0, {
+    message: "Expected non-blank string",
+})
+    .optional();
 export const listModelsShape = {
     modelType: z.enum(["TEXT", "IMAGE", "VIDEO"]).optional(),
+    detail: z.enum(["lite", "full"]).optional(),
+};
+export const getModelShape = {
+    publicModelId: z.string().min(1),
+    routingMode: routingModeSchema.optional(),
 };
 export const chatTextShape = {
     publicModelId: z.string().min(1),
     routingMode: routingModeSchema,
     messages: z.array(messageSchema).min(1),
     thinkingEnabled: z.boolean().optional(),
-    pricingSnapshot: pricingSnapshotSchema,
+    clientRequestId: clientRequestIdSchema,
+    pricingSnapshot: pricingSnapshotInputSchema,
 };
 export const generateImageShape = {
     publicModelId: z.string().min(1),
     routingMode: routingModeSchema,
     prompt: nonBlankStringSchema,
-    batchSize: z.number().int().min(1).max(10).default(1),
-    imageMediaIds: z.array(mediaIdSchema).default([]),
+    batchSize: z
+        .union([z.number().int().min(1).max(10), z.null()])
+        .transform((value) => value ?? 1)
+        .default(1),
+    imageMediaIds: nullableMediaIdsSchema,
     params: paramsSchema,
-    pricingSnapshot: pricingSnapshotSchema,
+    dryRun: z.boolean().default(false),
+    clientRequestId: clientRequestIdSchema,
+    pricingSnapshot: pricingSnapshotInputSchema,
 };
 export const generateVideoShape = {
     publicModelId: z.string().min(1),
     routingMode: routingModeSchema,
     prompt: nonBlankStringSchema,
-    imageMediaIds: z.array(mediaIdSchema).default([]),
-    videoMediaIds: z.array(mediaIdSchema).default([]),
-    audioMediaIds: z.array(mediaIdSchema).default([]),
+    imageMediaIds: nullableMediaIdsSchema,
+    videoMediaIds: nullableMediaIdsSchema,
+    audioMediaIds: nullableMediaIdsSchema,
     firstFrameMediaId: mediaIdSchema.optional(),
     lastFrameMediaId: mediaIdSchema.optional(),
     params: paramsSchema,
-    pricingSnapshot: pricingSnapshotSchema,
+    dryRun: z.boolean().default(false),
+    clientRequestId: clientRequestIdSchema,
+    pricingSnapshot: pricingSnapshotInputSchema,
 };
 export const getGenerationTaskShape = {
     taskId: z.string().min(1),

package/dist/server.d.ts

@@ -4,16 +4,17 @@ import { AiHiveApiClient } from "./api-client.js";
 import { type BearerTokenProvider } from "./auth-token-provider.js";
 import type { McpClientConfig } from "./config.js";
 import { WorkBuddyCredentialStore } from "./workbuddy-credentials.js";
-export declare const SERVER_VERSION = "0.2.5";
+export declare const SERVER_VERSION = "0.3.0";
 declare function content(value: unknown): {
     content: {
         type: "text";
         text: string;
     }[];
 };
-type ApiClientLike = Pick<AiHiveApiClient, "getUserInfo" | "listModels" | "createMediaUpload" | "completeMediaUpload" | "chatText" | "generateImage" | "generateVideo" | "getGenerationTask" | "putUpload">;
+type ApiClientLike = Pick<AiHiveApiClient, "getUserInfo" | "listModels" | "getModel" | "createMediaUpload" | "completeMediaUpload" | "chatText" | "generateImage" | "generateVideo" | "getGenerationTask" | "putUpload">;
 export type ToolDefinition = {
     name: string;
+    description: string;
     schema: z.ZodRawShape;
     handler: (args: Record<string, unknown>) => Promise<ReturnType<typeof content>>;
 };

package/dist/server.js

@@ -1,14 +1,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, listModelsShape, } from "./schemas.js";
+import { chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, getModelShape, listModelsShape, } from "./schemas.js";
 import { z } from "zod";
 import { AiHiveApiClient } from "./api-client.js";
 import { normalizeApiEndpoint, StaticBearerTokenProvider, WorkBuddyTokenProvider, } from "./auth-token-provider.js";
 import { readMcpClientInfo } from "./client-info.js";
 import { uploadMediaFromPath } from "./local-media.js";
 import { WorkBuddyOAuthClient } from "./workbuddy-oauth-client.js";
-export const SERVER_VERSION = "0.2.5";
+export const SERVER_VERSION = "0.3.0";
 const DEPRECATED_ATTACHMENT_IDS_MESSAGE = "attachmentIds 已废弃，请使用 messages[].mediaIds";
+const SNAPSHOT_PARSE_FAILURE_MESSAGE = "pricingSnapshot 格式不正确，应为 list_models 返回的快照对象，也可以省略该字段由客户端自动获取";
+const SNAPSHOT_ARRAY_MISMATCH_MESSAGE = "pricingSnapshot 数组中没有匹配当前模型和 routingMode 的快照，请传入 list_models 返回的对应快照对象，或省略该字段由客户端自动获取";
+const SNAPSHOT_IDENTITY_MISMATCH_MESSAGE = "pricingSnapshot 的 publicModelId 或 routingMode 与请求不一致，请传入 list_models 返回的对应快照对象，或省略该字段由客户端自动获取";
+const MODEL_UNAVAILABLE_MESSAGE = "模型当前不可用或不支持该路由模式，请重新调用 list_models 获取最新模型信息";
 function content(value) {
     return {
         content: [{ type: "text", text: JSON.stringify(value) }],
@@ -19,20 +23,111 @@ function rejectDeprecatedAttachmentIds(args) {
         throw new Error(DEPRECATED_ATTACHMENT_IDS_MESSAGE);
     }
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pickSnapshotForRequest(snapshots, publicModelId, routingMode) {
+    return snapshots.find((item) => isPlainObject(item) &&
+        item.publicModelId === publicModelId &&
+        item.routingMode === routingMode);
+}
+// LLM 回传 pricingSnapshot 时经常漏传或变形(数组/JSON 字符串/null), 由客户端代为归一化,
+// 保证进入付费 API 的请求一定携带服务端期望的单个快照对象.
+async function resolvePricingSnapshot(client, modelType, args) {
+    const requestArgs = { ...args };
+    if (requestArgs.dryRun === false) {
+        delete requestArgs.dryRun;
+    }
+    let snapshot = requestArgs.pricingSnapshot;
+    const isDryRun = args.dryRun === true;
+    const withoutPricingSnapshot = () => {
+        const request = { ...requestArgs };
+        delete request.pricingSnapshot;
+        return request;
+    };
+    const resolveCurrentSnapshot = async () => {
+        const models = await client().listModels({ modelType });
+        const model = Array.isArray(models)
+            ? models.find((item) => isPlainObject(item) && item.publicModelId === args.publicModelId)
+            : undefined;
+        const snapshots = isPlainObject(model) ? model.pricingSnapshot : undefined;
+        const matched = Array.isArray(snapshots)
+            ? pickSnapshotForRequest(snapshots, args.publicModelId, args.routingMode)
+            : undefined;
+        if (!matched) {
+            throw new Error(MODEL_UNAVAILABLE_MESSAGE);
+        }
+        return {
+            ...requestArgs,
+            pricingSnapshot: matched,
+            pricingSnapshotAutoResolved: true,
+        };
+    };
+    if (snapshot === undefined || snapshot === null) {
+        return isDryRun ? withoutPricingSnapshot() : resolveCurrentSnapshot();
+    }
+    if (typeof snapshot === "string") {
+        try {
+            snapshot = JSON.parse(snapshot);
+        }
+        catch {
+            throw new Error(SNAPSHOT_PARSE_FAILURE_MESSAGE);
+        }
+    }
+    if (snapshot === undefined || snapshot === null) {
+        return isDryRun ? withoutPricingSnapshot() : resolveCurrentSnapshot();
+    }
+    if (Array.isArray(snapshot)) {
+        const matched = pickSnapshotForRequest(snapshot, args.publicModelId, args.routingMode);
+        if (!matched) {
+            throw new Error(SNAPSHOT_ARRAY_MISMATCH_MESSAGE);
+        }
+        return { ...requestArgs, pricingSnapshot: matched };
+    }
+    if (isPlainObject(snapshot)) {
+        // 单对象快照同样可能传错模型或档位, 与数组分支一致校验, 避免按错误价格计费;
+        // 键缺失时放行, 由服务端 strict schema 兜底.
+        if ((typeof snapshot.publicModelId === "string" &&
+            snapshot.publicModelId !== args.publicModelId) ||
+            (typeof snapshot.routingMode === "string" &&
+                snapshot.routingMode !== args.routingMode)) {
+            throw new Error(SNAPSHOT_IDENTITY_MISMATCH_MESSAGE);
+        }
+        return { ...requestArgs, pricingSnapshot: snapshot };
+    }
+    // 数字/布尔等原始类型同样是畸形回传, 不能原样透传给付费 API.
+    throw new Error(SNAPSHOT_PARSE_FAILURE_MESSAGE);
+}
+// 幂等键语义写在每个付费工具的描述里, 让宿主在选型阶段就能看到重试规则.
+const CLIENT_REQUEST_ID_NOTE = "付费调用应传入稳定 UUID 作为 clientRequestId 幂等键；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期 pricingSnapshot 时复用原值和相同业务参数。余额、参数、媒体或已缓存的模型调用失败在修正后必须使用新的 clientRequestId；REQUEST_OUTCOME_UNKNOWN 必须停止自动重试并人工核查。";
 export function createToolDefinitions(client) {
     return [
         {
             name: "get_user_info",
+            description: "查询当前用户和余额。",
             schema: {},
             handler: async () => content(await client().getUserInfo()),
         },
         {
             name: "list_models",
+            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型与公开价格。detail 为 lite 时只返回各模型各路由的售价摘要（维度、单位、计费方式、内含数量及 saleMicros），用于快速选型；detail 为 full 时返回完整公开详情。saleMicros 是客户实际结算价，两种结果都不包含内部参考成本。",
             schema: listModelsShape,
             handler: async (args) => content(await client().listModels(args)),
         },
+        {
+            name: "get_model",
+            description: "按 publicModelId 查询单个模型的参数 schema、媒体要求、计费因素和示例；传 routingMode 可获取线路专属契约。",
+            schema: getModelShape,
+            handler: async (args) => {
+                const publicModelId = String(args.publicModelId);
+                return content(typeof args.routingMode === "string"
+                    ? await client().getModel(publicModelId, args.routingMode)
+                    : await client().getModel(publicModelId));
+            },
+        },
         {
             name: "upload_media_from_path",
+            description: "上传本地图片、视频、音频或文档并返回 mediaId。",
             schema: {
                 path: z.string().min(1),
                 filename: z.string().min(1).optional(),
@@ -42,24 +137,35 @@ export function createToolDefinitions(client) {
         },
         {
             name: "chat_text",
+            description: `使用指定模型生成文本。${CLIENT_REQUEST_ID_NOTE}`,
             schema: chatTextShape,
             handler: async (args) => {
                 rejectDeprecatedAttachmentIds(args);
-                return content(await client().chatText(args));
+                const body = await resolvePricingSnapshot(client, "TEXT", args);
+                return content(await client().chatText(body));
             },
         },
         {
             name: "generate_image",
+            description: `创建图片生成任务；dryRun=true 时只校验参数、媒体和预估费用，不创建任务且可省略 pricingSnapshot 与 clientRequestId。${CLIENT_REQUEST_ID_NOTE}`,
             schema: generateImageShape,
-            handler: async (args) => content(await client().generateImage(args)),
+            handler: async (args) => {
+                const body = await resolvePricingSnapshot(client, "IMAGE", args);
+                return content(await client().generateImage(body));
+            },
         },
         {
             name: "generate_video",
+            description: `创建视频生成任务；dryRun=true 时只校验参数、媒体和预估费用，不创建任务且可省略 pricingSnapshot 与 clientRequestId。${CLIENT_REQUEST_ID_NOTE}`,
             schema: generateVideoShape,
-            handler: async (args) => content(await client().generateVideo(args)),
+            handler: async (args) => {
+                const body = await resolvePricingSnapshot(client, "VIDEO", args);
+                return content(await client().generateVideo(body));
+            },
         },
         {
             name: "get_generation_task",
+            description: "查询图片或视频任务状态和结果。",
             schema: getGenerationTaskShape,
             handler: async (args) => content(await client().getGenerationTask({
                 taskId: String(args.taskId),
@@ -107,7 +213,7 @@ export function createServer(input) {
         clientInfoProvider: () => readMcpClientInfo(server),
     });
     for (const tool of createToolDefinitions(client)) {
-        server.tool(tool.name, tool.schema, tool.handler);
+        server.tool(tool.name, tool.description, tool.schema, tool.handler);
     }
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infimind-next/ai-hive-mcp",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "engines": {