@infimind-next/ai-hive-mcp 0.3.1 → 0.3.3

package/README.md

@@ -11,28 +11,41 @@
   "mcpServers": {
     "ai-hive": {
       "command": "npx",
-      "args": ["-y", "@infimind-next/ai-hive-mcp@0.3.0", "--key", "<APIKEY>"]
+      "args": ["-y", "@infimind-next/ai-hive-mcp@0.3.3", "--key", "<APIKEY>"]
     }
   }
 }
 ```
 
-要求 Node.js >= 20.19.0。本包通过标准 MCP stdio 与客户端通信，仅保证与支持 MCP 的客户端配合使用。
+要求 Node.js >= 20.19.0。默认请求超时为 300 秒，可通过 `--timeout-ms` 或 `AI_HIVE_MCP_TIMEOUT_MS` 覆盖；无效值回退为 300 秒。WorkBuddy Connector 的启动与认证命令保持引用 `@latest`，Connector 和 Skills 版本仍为 1.2.0。
+
+本包通过标准 MCP stdio 与客户端通信，仅保证与支持 MCP 的客户端配合使用。
 
 ## 工具
 
-- `get_user_info`：查询当前用户和余额
+- `get_user_info`：查询当前用户和普通蜂蜜余额
+
+专属蜂蜜由服务端按实际模型自动选择抵扣，无需新增调用参数。不能仅凭普通蜂蜜余额为 0 拒绝模型调用；只有实际调用返回余额不足时，才使用 `rechargeUrl` 引导充值并重试。
+
 - `list_models`：按 TEXT、IMAGE 或 VIDEO 查询可用模型与公开价格
 - `get_model`：查询单个模型的参数 schema、媒体要求、计费因素和调用示例
 - `upload_media_from_path`：上传本地图片、视频或音频，返回 mediaId
 - `chat_text`：文本对话
 - `generate_image`：图片预检或正式生成
 - `generate_video`：视频预检或正式生成
+- `get_material_mode`：查询认证资格和网页授权入口（可选）
+- `quote_video_materials`：获取素材报价（可选）
 - `get_generation_task`：查询生成任务进度和结果
 
 ### 认证素材模式
 
-0.3.1 增加可选的 `get_material_mode`（查询资格与网页授权入口）、`quote_video_materials`（冻结素材并报价），以及 `generate_video` 的 `materialMode` / `materialQuoteId` 字段。这些工具不是生成前置要求；旧版 0.3.0 也可直接使用认证模型。实际发布版本以 npm registry 为准。用户必须登录网页明确授权，MCP 不能代签；确认报价后按认证版模型单价按生成时长计费，认证服务费已内嵌其中，不再另收素材服务费。
+已发布的 0.3.1 提供可选认证工具，其调用契约支持认证版接收普通素材，由服务端按模型 ID 自动识别并校验资格、准备素材，不要求新增参数或先调用报价工具；实际可用性以所连接服务端的响应为准。`materialMode`、`materialQuoteId` 与 `quote_video_materials` 均为可选兼容能力。先用 `dryRun: true` 预检资格与费用；预检不执行供应商内容审核。资格不足或需要授权时，展示返回的操作链接，或引导查看[认证资格指南](https://ai-hive.iclip.cn/certified-materials#guide)。用户本人在网页授权，MCP 不能代签；保留用户指定模型，费用变化时重新确认。费用以所选模型的当前报价为准。
+
+## 0.3.2 活动与公告通知
+
+支持服务端提供的独立充值活动通知。首段文本继续是原业务 JSON，后续文本包含活动摘要、截止时间、充值入口与档位；Agent 按握手中的展示规则简短转达，尊重拒绝促销和严格输出要求。
+
+客户端自动使用可选查询参数请求通知，不增加工具必填参数，不改计费请求或自动重试次数。连接旧服务端且没有通知时正常返回业务结果。旧的 0.3.0/0.3.1 可继续使用新服务端，但不能保证旧 Agent 主动展示活动。支持管理员现有公告策略及无截止时间的公告；发布记录与实测范围见 [0.3.2 记录](../../docs/release/mcp-0.3.2-runbook.md)。
 
 ## 调用流程
 
@@ -51,7 +64,6 @@
 - 正式生成提示价格已更新：保持业务参数和原 `clientRequestId` 不变，重新预检获取最新 `pricingSnapshot` 后重试。
 - 返回 `REQUEST_OUTCOME_UNKNOWN`：停止自动重试，联系管理员核查。
 
-
 ### 认证版的用户路径
 
 用户提供普通素材即可，后台自动处理认证。使用对应认证模型与当前价格快照，先 dryRun 预检资格、素材和费用；通过后沿用标准版提交格式，认证字段和专用报价工具都可省略。收到任务 ID 后只查询原任务。
@@ -61,3 +73,18 @@
 更新信息仅在用户询问或与当前任务有关时介绍，不向用户转述内部参数、错误码、报价与重试机制。客户端可选升级提示默认静默，仅开启 `--verbose` 时输出维护诊断。技术维护记录见仓库 `docs/openapi/technical-changelog.md`。
 
 `recoveryAction` 是给调用端的恢复指引，不要逐字转成用户待办。响应中断用原 `clientRequestId` 和相同参数恢复；明确失败后再次生成，或改变报价/输入时，使用新请求标识。结果未知时先核查，不自动重建付费任务。
+
+当前客户端版本为 0.3.2，已于 2026-10-08 发布。发布物、兼容验证与服务端验收边界见 [0.3.2 发布记录](../../docs/release/mcp-0.3.2-runbook.md)。
+
+### 0.3.2：通知协商与直接上传
+
+0.3.1 保留旧充值活动返回。下面的公告扩展与直接上传工具已包含在 0.3.2 中，需要所连接服务端支持；客户端发布不代表生产服务已部署。
+
+- `create_media_upload`：直接创建上传地址；`complete_media_upload`：直接确认上传完成。两者可在结果中返回通知。
+- 支持通知的查询工具固定声明 `readOnlyHint=false`，因为服务端配置可启用返回状态写入。通知保留条件、截止时间和链接，结合对话转述，同一对话避免机械重复；实际展示由宿主决定。
+- REST 请求级 `X-AI-Hive-Announcements: 1` 启用新的公告扩展；账户 POST 不要求该头。已发布的 0.3.1 不发送新请求头，仍可通过账户 GET 与原有付费请求接收旧充值活动，无需升级客户端或新增参数。SDK 直接工具请求协商，内部价格快照和自动上传初始化关闭；`upload_media_from_path` 展示完整上传完成结果。
+- 正式付费通知请求必须有合法 `clientRequestId`，重放与恢复不重复通知，dryRun 无通知。这些规则已通过本地协议验证；生产服务与真实宿主展示仍需独立验收。
+
+兼容模式（COMPAT）下，账户 GET 和 POST 常驻返回进行中的旧充值活动，不占用模型调用的每日活动通知次数。原有付费请求仍按用户每天首次成功调用返回活动；重放、恢复与 dryRun 不重复通知。管理员启用通知管理（MANAGED）后按入口设置返回；旧客户端保留 `activePromotion` 结构，功能公告通过支持新扩展的客户端返回。
+
+0.3.2 中，CLI login/status 的凭证检查使用账户 GET 并明确发送 `X-AI-Hive-Announcements: 0`，完整验证凭证后仅返回账户核心字段、`activePromotion: null`，不写通知台账、共享次数或最短间隔状态。SDK 的 POST 404/405 后默认 GET 回退仍返回兼容活动。

package/dist/api-client.d.ts

@@ -2,6 +2,9 @@ import type { BearerTokenProvider } from "./auth-token-provider.js";
 import { type McpClientInfo } from "./client-info.js";
 import { type UpdateNotifier } from "./update-notifier.js";
 type FetchImpl = typeof fetch;
+export type AnnouncementOptions = {
+    announcements?: boolean;
+};
 type AiHiveApiClientInput = {
     endpoint: string;
     tokenProvider: BearerTokenProvider;
@@ -42,19 +45,19 @@ export declare class AiHiveApiClient {
     private send;
     private readResponse;
     getUserInfo(): Promise<unknown>;
-    getMaterialMode(): Promise<unknown>;
-    quoteVideoMaterials(input: unknown): 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>;
+    getMaterialMode(options?: AnnouncementOptions): Promise<unknown>;
+    quoteVideoMaterials(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
+    listModels(input: Record<string, unknown>, options?: AnnouncementOptions): Promise<unknown>;
+    getModel(publicModelId: string, routingMode?: string, options?: AnnouncementOptions): Promise<unknown>;
+    createMediaUpload(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
+    completeMediaUpload(mediaId: string, options?: AnnouncementOptions): Promise<unknown>;
+    chatText(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
+    generateImage(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
+    generateVideo(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
     private requestGeneration;
     getGenerationTask(input: {
         taskId: string;
-    }): Promise<unknown>;
+    }, options?: AnnouncementOptions): Promise<unknown>;
     putUpload(input: {
         url: string;
         method: "PUT";

package/dist/api-client.js

@@ -1,5 +1,10 @@
 import { encodeMcpClientInfo, MCP_CLIENT_INFO_HEADER, } from "./client-info.js";
 import { LATEST_CLIENT_VERSION_HEADER, } from "./update-notifier.js";
+function announcementHeaders(options) {
+    return options?.announcements === true
+        ? { "X-AI-Hive-Announcements": "1" }
+        : {};
+}
 export class AiHiveApiError extends Error {
     status;
     details;
@@ -187,19 +192,34 @@ export class AiHiveApiClient {
         }
         return body;
     }
-    getUserInfo() {
-        return this.request("/mcp/user-info");
+    async getUserInfo() {
+        try {
+            return await this.request("/mcp/user-info?include=user-notices", {
+                method: "POST",
+                body: "{}",
+            });
+        }
+        catch (error) {
+            if (error instanceof AiHiveApiError &&
+                (error.status === 404 || error.status === 405)) {
+                return this.request("/mcp/user-info?include=user-notices");
+            }
+            throw error;
+        }
     }
-    getMaterialMode() {
-        return this.request("/mcp/material-mode");
+    getMaterialMode(options) {
+        return this.request("/mcp/material-mode", {
+            headers: announcementHeaders(options),
+        });
     }
-    quoteVideoMaterials(input) {
+    quoteVideoMaterials(input, options) {
         return this.request("/mcp/generation/video/material-quote", {
             method: "POST",
             body: JSON.stringify(input),
+            headers: announcementHeaders(options),
         });
     }
-    async listModels(input) {
+    async listModels(input, options) {
         const query = new URLSearchParams();
         if (typeof input.modelType === "string") {
             query.set("modelType", input.modelType);
@@ -208,16 +228,16 @@ export class AiHiveApiClient {
             query.set("detail", input.detail);
         }
         const serialized = query.toString();
-        return redactInternalPricing(await this.request(`/mcp/models${serialized ? `?${serialized}` : ""}`));
+        return redactInternalPricing(await this.request(`/mcp/models${serialized ? `?${serialized}` : ""}`, { headers: announcementHeaders(options) }));
     }
     // getModel 与 listModels 的 detail 参数依赖服务端新部署; 旧服务端会 404 或被
     // strict 入参校验拒绝, 所以 npm 0.3.0 必须在服务端升级之后发布.
-    async getModel(publicModelId, routingMode) {
+    async getModel(publicModelId, routingMode, options) {
         const query = routingMode
             ? `?${new URLSearchParams({ routingMode }).toString()}`
             : "";
         try {
-            return redactInternalPricing(await this.request(`/mcp/models/${encodeURIComponent(publicModelId)}${query}`));
+            return redactInternalPricing(await this.request(`/mcp/models/${encodeURIComponent(publicModelId)}${query}`, { headers: announcementHeaders(options) }));
         }
         catch (error) {
             if (error instanceof AiHiveApiError && error.status === 404) {
@@ -226,22 +246,25 @@ export class AiHiveApiClient {
             throw error;
         }
     }
-    createMediaUpload(input) {
+    createMediaUpload(input, options) {
         return this.request("/mcp/media/upload-token", {
             method: "POST",
             body: JSON.stringify(input),
+            headers: announcementHeaders(options),
         });
     }
-    completeMediaUpload(mediaId) {
+    completeMediaUpload(mediaId, options) {
         return this.request(`/mcp/media/${encodeURIComponent(mediaId)}/complete`, {
             method: "POST",
+            headers: announcementHeaders(options),
         });
     }
-    async chatText(input) {
+    async chatText(input, options) {
         try {
-            return await this.request("/mcp/chat/text", {
+            return await this.request("/mcp/chat/text?include=user-notices", {
                 method: "POST",
                 body: JSON.stringify(input),
+                headers: announcementHeaders(options),
             });
         }
         catch (error) {
@@ -251,17 +274,18 @@ export class AiHiveApiClient {
             throw error;
         }
     }
-    generateImage(input) {
-        return this.requestGeneration("/mcp/generation/image", input);
+    generateImage(input, options) {
+        return this.requestGeneration("/mcp/generation/image", input, options);
     }
-    generateVideo(input) {
-        return this.requestGeneration("/mcp/generation/video", input);
+    generateVideo(input, options) {
+        return this.requestGeneration("/mcp/generation/video", input, options);
     }
-    async requestGeneration(path, input) {
+    async requestGeneration(path, input, options) {
         try {
-            return await this.request(path, {
+            return await this.request(`${path}?include=user-notices`, {
                 method: "POST",
                 body: JSON.stringify(input),
+                headers: announcementHeaders(options),
             });
         }
         catch (error) {
@@ -279,8 +303,8 @@ export class AiHiveApiClient {
             throw error;
         }
     }
-    getGenerationTask(input) {
-        return this.request(`/mcp/generation/tasks/${encodeURIComponent(input.taskId)}`);
+    getGenerationTask(input, options) {
+        return this.request(`/mcp/generation/tasks/${encodeURIComponent(input.taskId)}?include=user-notices`, { headers: announcementHeaders(options) });
     }
     async putUpload(input) {
         await this.withTimeout(async (signal) => {

package/dist/cli.js

@@ -256,7 +256,10 @@ async function requestUserInfo(endpoint, token, deadlineAt) {
     const timeoutMs = remainingMs(deadlineAt);
     return withDeadline(fetch(`${endpoint.replace(/\/+$/, "")}/mcp/user-info`, {
         method: "GET",
-        headers: { Authorization: `Bearer ${token}` },
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "X-AI-Hive-Announcements": "0",
+        },
         signal: controller.signal,
     }), timeoutMs, () => controller.abort());
 }

package/dist/local-media.js

@@ -115,7 +115,7 @@ export async function uploadMediaFromPath(api, rawInput) {
         filename,
         contentType,
         sizeBytes: stats.size,
-    }));
+    }, { announcements: false }));
     const body = await openAsBlob(input.path, { type: contentType });
     await api.putUpload({
         url: upload.upload.url,
@@ -123,5 +123,5 @@ export async function uploadMediaFromPath(api, rawInput) {
         headers: upload.upload.headers,
         body,
     });
-    return api.completeMediaUpload(upload.mediaId);
+    return api.completeMediaUpload(upload.mediaId, { announcements: true });
 }

package/dist/schemas.d.ts

@@ -20,6 +20,7 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
     expiresAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     mimeType: string;
+    expiresAt: string;
     mediaId: string;
     mediaType: "IMAGE" | "VIDEO" | "AUDIO" | "DOCUMENT";
     sizeBytes: number;
@@ -28,9 +29,9 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
         url: string;
         headers: Record<string, string>;
     };
-    expiresAt: string;
 }, {
     mimeType: string;
+    expiresAt: string;
     mediaId: string;
     mediaType: "IMAGE" | "VIDEO" | "AUDIO" | "DOCUMENT";
     sizeBytes: number;
@@ -39,7 +40,6 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
         url: string;
         headers: Record<string, string>;
     };
-    expiresAt: string;
 }>;
 export declare const mcpUploadMediaFromPathInputSchema: z.ZodObject<{
     path: z.ZodEffects<z.ZodString, string, string>;
@@ -80,7 +80,7 @@ export declare const chatTextShape: {
     }>, "many">;
     thinkingEnabled: z.ZodOptional<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]>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodArray<z.ZodNullable<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const generateImageShape: {
     publicModelId: z.ZodString;
@@ -91,7 +91,7 @@ export declare const generateImageShape: {
     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]>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodArray<z.ZodNullable<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const generateVideoShape: {
     materialMode: z.ZodOptional<z.ZodEnum<["standard", "certified"]>>;
@@ -107,7 +107,7 @@ export declare const generateVideoShape: {
     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]>>;
+    pricingSnapshot: z.ZodOptional<z.ZodUnion<[z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>, z.ZodArray<z.ZodNullable<z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>, "many">, z.ZodString, z.ZodNull]>>;
 };
 export declare const getGenerationTaskShape: {
     taskId: z.ZodString;

package/dist/schemas.js

@@ -10,7 +10,8 @@ const routingModeSchema = z.enum([
     "SPEED_FIRST",
     "SUCCESS_FIRST",
 ]);
-const pricingSnapshotSchema = z.record(z.unknown());
+// 显式开放对象属性, 让宿主原样传递嵌套报价, 严格校验仍由服务端执行.
+const pricingSnapshotSchema = z.object({}).passthrough();
 // 宿主常把可选数组/对象字段塞成 null, 归一到默认值避免服务端收到非法请求.
 const nullableMediaIdsSchema = z
     .union([z.array(mediaIdSchema), z.null()])

package/dist/server.d.ts

@@ -1,22 +1,33 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 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.3.1";
+export declare const SERVER_VERSION = "0.3.3";
 declare function content(value: unknown): {
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent: Record<string, unknown>;
+};
+declare function userInfoContent(value: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
 };
 type ApiClientLike = Pick<AiHiveApiClient, "getUserInfo" | "getMaterialMode" | "quoteVideoMaterials" | "listModels" | "getModel" | "createMediaUpload" | "completeMediaUpload" | "chatText" | "generateImage" | "generateVideo" | "getGenerationTask" | "putUpload">;
 export type ToolDefinition = {
     name: string;
+    title?: string;
     description: string;
     schema: z.ZodRawShape;
-    handler: (args: Record<string, unknown>) => Promise<ReturnType<typeof content>>;
+    annotations?: ToolAnnotations;
+    handler: (args: Record<string, unknown>) => Promise<ReturnType<typeof content> | ReturnType<typeof userInfoContent>>;
 };
 export declare function createToolDefinitions(client: () => ApiClientLike): ToolDefinition[];
 export type ResolvedServerAuth = {

package/dist/server.js

@@ -1,3 +1,4 @@
+import { toolResultContent } from "./user-notices.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, getModelShape, listModelsShape, } from "./schemas.js";
@@ -8,15 +9,29 @@ import { readMcpClientInfo } from "./client-info.js";
 import { createUpdateNotifier } from "./update-notifier.js";
 import { uploadMediaFromPath } from "./local-media.js";
 import { WorkBuddyOAuthClient } from "./workbuddy-oauth-client.js";
-export const SERVER_VERSION = "0.3.1";
+export const SERVER_VERSION = "0.3.3";
 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 获取最新模型信息";
+// 此文案与 @ai-hive/contracts 的 USER_INFO_TOOL_* 常量保持一致; 独立发布的客户端不引入运行依赖.
+const USER_INFO_TOOL_TITLE = "查看蜂巢账户信息";
+const USER_INFO_TOOL_DESCRIPTION = "查看你的蜂巢账户资料、可用余额和充值入口。";
 function content(value) {
+    const result = Array.isArray(value)
+        ? { models: value }
+        : value;
     return {
-        content: [{ type: "text", text: JSON.stringify(value) }],
+        content: toolResultContent(result),
+        structuredContent: result && "userNotices" in result
+            ? Object.fromEntries(Object.entries(result).filter(([key]) => key !== "userNotices"))
+            : result,
+    };
+}
+function userInfoContent(value) {
+    return {
+        ...content(value),
     };
 }
 function rejectDeprecatedAttachmentIds(args) {
@@ -47,7 +62,7 @@ async function resolvePricingSnapshot(client, modelType, args) {
         return request;
     };
     const resolveCurrentSnapshot = async () => {
-        const models = await client().listModels({ modelType });
+        const models = await client().listModels({ modelType }, { announcements: false });
         const model = Array.isArray(models)
             ? models.find((item) => isPlainObject(item) && item.publicModelId === args.publicModelId)
             : undefined;
@@ -99,38 +114,40 @@ async function resolvePricingSnapshot(client, modelType, args) {
     // 数字/布尔等原始类型同样是畸形回传, 不能原样透传给付费 API.
     throw new Error(SNAPSHOT_PARSE_FAILURE_MESSAGE);
 }
-// 幂等键语义写在每个付费工具的描述里, 让宿主在选型阶段就能看到重试规则.
-const CLIENT_REQUEST_ID_NOTE = "付费调用应传入稳定 UUID 作为 clientRequestId 幂等键；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期 pricingSnapshot 时复用原值和相同业务参数。余额、参数、媒体或已缓存的模型调用失败在修正后必须使用新的 clientRequestId；REQUEST_OUTCOME_UNKNOWN 必须停止自动重试并人工核查。";
-// 长耗时提醒同样前置到工具描述: 宿主据此设置超时, 避免"本端超时先断、
-// 服务端跑完仍扣费"被误读成失败扣款.
-const LONG_RUNNING_NOTE = "该调用同步返回，长推理模型单次可能耗时 1-3 分钟，客户端超时应设为 300 秒以上；等待超时只代表本端不再等待，服务端可能仍在生成，也可能已完成并扣费，超时后复用同一 clientRequestId 和相同业务参数重新调用即可取回首次结果，修正参数后换新值。";
 export function createToolDefinitions(client) {
-    return [
+    const definitions = [
         {
             name: "get_user_info",
-            description: "查询当前用户、余额，以及官网地址和充值入口；余额不足时引导用户打开 rechargeUrl 完成充值后重试。",
+            title: USER_INFO_TOOL_TITLE,
+            description: USER_INFO_TOOL_DESCRIPTION,
             schema: {},
-            handler: async () => content(await client().getUserInfo()),
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                openWorldHint: false,
+            },
+            handler: async () => userInfoContent(await client().getUserInfo()),
         },
         {
             name: "list_models",
-            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型与公开价格。detail 为 lite 时只返回各模型各路由的售价摘要（维度、单位、计费方式、内含数量及 saleMicros），用于快速选型；detail 为 full 时返回完整公开详情。saleMicros 是客户实际结算价，两种结果都不包含内部参考成本。",
+            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型及价格；detail=lite 用于选型，detail=full 返回完整信息。",
             schema: listModelsShape,
-            handler: async (args) => content(await client().listModels(args)),
+            annotations: { readOnlyHint: false },
+            handler: async (args) => content(await client().listModels(args, { announcements: true })),
         },
         {
             name: "get_model",
             description: "按 publicModelId 查询单个模型的参数 schema、媒体要求、计费因素和示例；传 routingMode 可获取线路专属契约。",
             schema: getModelShape,
+            annotations: { readOnlyHint: false },
             handler: async (args) => {
                 const publicModelId = String(args.publicModelId);
-                return content(typeof args.routingMode === "string"
-                    ? await client().getModel(publicModelId, args.routingMode)
-                    : await client().getModel(publicModelId));
+                return content(await client().getModel(publicModelId, typeof args.routingMode === "string" ? args.routingMode : undefined, { announcements: true }));
             },
         },
         {
             name: "upload_media_from_path",
+            annotations: { readOnlyHint: false },
             description: "上传本地图片、视频、音频或文档并返回 mediaId。",
             schema: {
                 path: z.string().min(1),
@@ -139,43 +156,68 @@ export function createToolDefinitions(client) {
             },
             handler: async (args) => content(await uploadMediaFromPath(client(), args)),
         },
+        {
+            name: "create_media_upload",
+            description: "为媒体文件创建短期上传地址，按返回的 method 和 headers PUT 原始字节。",
+            schema: {
+                filename: z.string().min(1),
+                contentType: z.string().min(1),
+                sizeBytes: z.number().int().positive(),
+            },
+            annotations: { readOnlyHint: false },
+            handler: async (args) => content(await client().createMediaUpload(args, { announcements: true })),
+        },
+        {
+            name: "complete_media_upload",
+            description: "确认媒体上传完成，返回可用于模型调用的 mediaId。",
+            schema: { mediaId: z.string().min(1) },
+            annotations: { readOnlyHint: false },
+            handler: async (args) => content(await client().completeMediaUpload(String(args.mediaId), {
+                announcements: true,
+            })),
+        },
         {
             name: "chat_text",
-            description: `使用指定模型生成文本。${LONG_RUNNING_NOTE}${CLIENT_REQUEST_ID_NOTE}`,
+            description: "使用指定模型生成文本，返回本次对话结果。",
             schema: chatTextShape,
+            annotations: { readOnlyHint: false },
             handler: async (args) => {
                 rejectDeprecatedAttachmentIds(args);
                 const body = await resolvePricingSnapshot(client, "TEXT", args);
-                return content(await client().chatText(body));
+                return content(await client().chatText(body, { announcements: true }));
             },
         },
         {
             name: "generate_image",
-            description: `创建图片生成任务；dryRun=true 时只校验参数、媒体和预估费用，不创建任务且可省略 pricingSnapshot 与 clientRequestId。${CLIENT_REQUEST_ID_NOTE}`,
+            description: "使用指定模型生成图片；dryRun=true 可先检查输入并预估费用。",
             schema: generateImageShape,
+            annotations: { readOnlyHint: false },
             handler: async (args) => {
                 const body = await resolvePricingSnapshot(client, "IMAGE", args);
-                return content(await client().generateImage(body));
+                return content(await client().generateImage(body, { announcements: true }));
             },
         },
         {
             name: "generate_video",
-            description: `认证版接收普通素材，服务端按模型 ID 自动校验资格和准备素材。提交前先用 dryRun=true 做只读预检，不用真实付费提交试探资格。materialMode、materialQuoteId 和专用报价工具均为可选兼容能力；正式提交使用当前 pricingSnapshot 和稳定 clientRequestId。资格不足时明确说明差额或待授权事项，并在回复中展示返回的 helpUrl 或 actionUrl 为可点击链接；未返回链接时使用 https://ai-hive.iclip.cn/certified-materials#guide。保留用户指定模型，不擅自切换模型或继续付费提交。认证服务已包含在模型价格中；费用变化时重新确认。收到任务 ID 后查询原任务，不重复创建。dryRun 不创建任务、不冻结素材、不预占或扣费，也不执行供应商内容审核。${CLIENT_REQUEST_ID_NOTE}`,
+            description: "使用指定模型生成视频；dryRun=true 可先检查输入并预估费用。",
             schema: generateVideoShape,
+            annotations: { readOnlyHint: false },
             handler: async (args) => {
                 const body = await resolvePricingSnapshot(client, "VIDEO", args);
-                return content(await client().generateVideo(body));
+                return content(await client().generateVideo(body, { announcements: true }));
             },
         },
         {
             name: "get_material_mode",
+            annotations: { readOnlyHint: false },
             description: "查询认证版服务状态、授权与累计充值资格。已满足条件时直接继续；仅未授权时请用户本人打开 actionUrl 阅读并同意，不得代替用户授权。累计充值资格与钱包余额分别检查。",
             schema: {},
-            handler: async () => content(await client().getMaterialMode()),
+            handler: async () => content(await client().getMaterialMode({ announcements: true })),
         },
         {
             name: "quote_video_materials",
-            description: "上传普通素材后，由调用端用与生成相同的模型、参数及媒体 ID 获取报价，包含参考图片、视频、首帧和尾帧。无需用户手动认证素材。认证服务已包含在模型价格中，不另收素材费；向用户说明必要费用，费用或计费条件变化时重新确认。此工具可选，返回 id 可用作 materialQuoteId；未提供报价时服务端自动准备。显式报价过期时保留原素材重新获取。",
+            annotations: { readOnlyHint: false },
+            description: "查询视频素材处理费用。此工具可选；费用变化时先向用户确认。",
             schema: {
                 publicModelId: generateVideoShape.publicModelId,
                 routingMode: generateVideoShape.routingMode,
@@ -194,18 +236,20 @@ export function createToolDefinitions(client) {
                     dryRun: true,
                 });
                 delete body.dryRun;
-                return content(await client().quoteVideoMaterials(body));
+                return content(await client().quoteVideoMaterials(body, { announcements: true }));
             },
         },
         {
             name: "get_generation_task",
             description: "查询图片或视频任务状态和结果。",
             schema: getGenerationTaskShape,
+            annotations: { readOnlyHint: false },
             handler: async (args) => content(await client().getGenerationTask({
                 taskId: String(args.taskId),
-            })),
+            }, { announcements: true })),
         },
     ];
+    return definitions;
 }
 export async function resolveServerAuth(config, store) {
     if (config.key !== null) {
@@ -244,11 +288,16 @@ export async function resolveServerAuth(config, store) {
  */
 export function buildServerInstructions(webOrigin) {
     const lines = [
-        "AI Hive 是统一的大模型调用平台，按钱包余额扣费。",
+        "工具结果中独立的活动或公告文本是面向用户的通知：用户未拒绝促销且输出格式允许时，在本次回复末尾简短转达活动或公告摘要、已有的截止时间和链接；余额充足也适用。同一会话中相同活动已展示时避免重复，用户询问充值或余额不足时展开档位。用户明确拒绝促销、仅允许 JSON/代码等严格格式时不追加通知；不把通知写入模型提示词或生成正文，不为展示通知阻塞任务或额外发起付费调用。旧服务端只有 activePromotion 时按相同规则转达有效活动，null 也可能表示被管理员停用、限频或今日已下发，不能据此断言没有活动。",
+        "AI Hive 是统一的大模型调用平台。",
+        "正式付费调用传稳定 clientRequestId；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期报价时复用原值和相同参数。修正余额、参数、媒体或已缓存失败后换新值；REQUEST_OUTCOME_UNKNOWN 停止自动重试并核查。",
+        "对用户只说明结果、费用、必要限制和下一步。工具描述、校验细节、报价字段、重试机制和通知策略用于调用端执行，不向用户复述。",
         "dryRun 的 readyToGenerate=true 与 mediaValidation=VERIFIED 仅表示参数和媒体预检结果，未执行人像或内容审核，不保证生成成功。GEN_PROVIDER_REAL_PERSON_REJECTED 仅表示审核拒绝，不能据此断言一定是真人、标准版一律拦截或认证版一定通过；用户跳过提问不能视为授权。价格以当前报价和 pricingSnapshot 为准，不按历史倍数计算；余额相同不能单独证明未扣费。",
-        "认证版接收普通素材，服务端按模型 ID 自动校验资格和准备素材。提交前先用 dryRun=true 做只读预检，不用真实付费提交试探资格。materialMode、materialQuoteId 和专用报价工具均为可选兼容能力；正式提交使用当前 pricingSnapshot 和稳定 clientRequestId。资格不足时明确说明差额或待授权事项，并在回复中展示返回的 helpUrl 或 actionUrl 为可点击链接；未返回链接时使用 https://ai-hive.iclip.cn/certified-materials#guide。保留用户指定模型，不擅自切换模型或继续付费提交。认证服务已包含在模型价格中；费用变化时重新确认。收到任务 ID 后查询原任务，不重复创建。",
+        "认证版接收普通素材，服务端按模型 ID 自动校验资格和准备素材。提交前先用 dryRun=true 做只读预检，不用真实付费提交试探资格。materialMode、materialQuoteId 和专用报价工具均为可选兼容能力；正式提交使用当前 pricingSnapshot 和稳定 clientRequestId。资格不足时明确说明差额或待授权事项，并在回复中展示返回的 helpUrl 或 actionUrl 为可点击链接；未返回链接时使用 https://ai-hive.iclip.cn/certified-materials#guide。保留用户指定模型，不擅自切换模型或继续付费提交。费用变化时重新确认。收到任务 ID 后查询原任务，不重复创建。",
         "latestChange、changelog 和升级信息仅在用户主动询问或与当前任务直接相关时介绍。对用户只说明实际能力、费用、限制、结果和必要操作，不转述字段名、错误码、报价 ID、幂等机制、版本适配或内部排查过程；技术字段和 recoveryAction 供调用端处理，不能替代用户操作说明。用户明确排查接入问题时可以解释所需技术细节。",
-        "先用 get_user_info 查询余额；返回里带官网地址和充值入口，余额不足时引导用户打开 rechargeUrl 充值后重试。",
+        "可用 get_user_info 查询蜂蜜余额、官网地址和充值入口。按 get_user_info 返回的 rechargeGuide 说明账户支付方式，不主动介绍账户未拥有的额度。不能仅凭钱包余额为 0 拒绝调用。只有实际调用返回余额不足时，才引导用户打开 rechargeUrl 充值后重试。",
+        "先用 list_models(detail=lite) 选型，再用 get_model 读取所选模型契约。上传前可省略媒体做 dryRun：缺素材不等于参数错误，估价为空时不得当作 0 元或上限。用户接受方案后上传，再带真实媒体预检；同参数同费用不重复确认，费用或条件变化才再确认。正式调用原样回传最后一次预检的 pricingSnapshot，金额保留字符串；仅 materialQuoteId 可自动准备，不能据此省略 pricingSnapshot。",
+        "充值提醒只依据本次返回的 activePromotion；有值时用 title、headline 和 promoTiers 转达本场「限时特惠 · 充值加赠」，金额沿用服务端结果，使用「距本场结束」说明 endsAt，并提供 rechargeUrl 的「立即充值」入口。模型调用返回 null 时不追加活动提醒；get_user_info 返回 null 时不推断具体原因。缓存或幂等重放中的 endsAt 已过期时，先重新查询 get_user_info，以新结果为准，不沿用旧截止时间或推算后续活动。",
         "调用 chat_text、generate_image、generate_video 前，用 get_model 确认参数契约；正式调用必须传稳定的 clientRequestId 幂等键，修正参数后换新值。",
         "chat_text 同步返回，长推理模型单次可能耗时 1-3 分钟，客户端超时应设为 300 秒以上；等待超时只代表本端不再等待，服务端可能仍在生成，也可能已完成并扣费，超时后复用同一 clientRequestId 和相同业务参数重新调用即可取回首次结果，修正参数后换新值。",
     ];
@@ -273,7 +322,7 @@ export function createServer(input) {
         updateNotifier,
     });
     for (const tool of createToolDefinitions(client)) {
-        server.tool(tool.name, tool.description, tool.schema, async (args) => {
+        const handler = async (args) => {
             try {
                 return await tool.handler(args);
             }
@@ -288,7 +337,18 @@ export function createServer(input) {
                     };
                 throw error;
             }
-        });
+        };
+        if (tool.annotations) {
+            server.registerTool(tool.name, {
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.schema,
+                annotations: tool.annotations,
+            }, handler);
+        }
+        else {
+            server.tool(tool.name, tool.description, tool.schema, handler);
+        }
     }
     return server;
 }

package/dist/user-notices.d.ts

@@ -0,0 +1,4 @@
+export declare function toolResultContent(value: unknown): {
+    type: "text";
+    text: string;
+}[];

package/dist/user-notices.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+// 独立 npm 包不能依赖私有 workspace, 与 contracts 的通知文本通过跨包用例校验.
+const noticeSchema = z.object({
+    id: z.string().min(1),
+    revision: z.string().min(1),
+    kind: z.enum(["RECHARGE_PROMOTION", "ANNOUNCEMENT"]),
+    title: z.string().min(1),
+    message: z.string().min(1),
+    details: z.string(),
+    expiresAt: z.string().datetime({ offset: true }).nullable(),
+    action: z
+        .object({
+        label: z.string().min(1),
+        url: z
+            .string()
+            .url()
+            .refine((url) => /^https?:\/\//.test(url)),
+    })
+        .optional(),
+});
+export function toolResultContent(value) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !("userNotices" in value)) {
+        return [{ type: "text", text: JSON.stringify(value) }];
+    }
+    const { userNotices, ...businessResult } = value;
+    const notices = Array.isArray(userNotices)
+        ? userNotices.flatMap((raw) => {
+            const parsed = noticeSchema.safeParse(raw);
+            return parsed.success &&
+                (parsed.data.expiresAt === null ||
+                    new Date(parsed.data.expiresAt).getTime() > Date.now())
+                ? [parsed.data]
+                : [];
+        })
+        : [];
+    return [
+        { type: "text", text: JSON.stringify(businessResult) },
+        ...notices.map((notice) => ({
+            type: "text",
+            text: [
+                `${notice.title}：${notice.message}`,
+                ...(notice.action
+                    ? [`${notice.action.label}：${notice.action.url}`]
+                    : []),
+                ...(notice.details ? [`充值档位：\n${notice.details}`] : []),
+            ].join("\n"),
+        })),
+    ];
+}

package/package.json

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