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

package/README.md

@@ -30,6 +30,10 @@
 - `generate_video`：视频预检或正式生成
 - `get_generation_task`：查询生成任务进度和结果
 
+### 认证素材模式
+
+0.3.1 增加可选的 `get_material_mode`（查询资格与网页授权入口）、`quote_video_materials`（冻结素材并报价），以及 `generate_video` 的 `materialMode` / `materialQuoteId` 字段。这些工具不是生成前置要求；旧版 0.3.0 也可直接使用认证模型。实际发布版本以 npm registry 为准。用户必须登录网页明确授权，MCP 不能代签；确认报价后按认证版模型单价按生成时长计费，认证服务费已内嵌其中，不再另收素材服务费。
+
 ## 调用流程
 
 图片和视频生成固定按 5 步走：
@@ -46,3 +50,14 @@
 - 修正参数、余额或媒体问题后重试：必须使用新的 `clientRequestId`。
 - 正式生成提示价格已更新：保持业务参数和原 `clientRequestId` 不变，重新预检获取最新 `pricingSnapshot` 后重试。
 - 返回 `REQUEST_OUTCOME_UNKNOWN`：停止自动重试，联系管理员核查。
+
+
+### 认证版的用户路径
+
+用户提供普通素材即可，后台自动处理认证。使用对应认证模型与当前价格快照，先 dryRun 预检资格、素材和费用；通过后沿用标准版提交格式，认证字段和专用报价工具都可省略。收到任务 ID 后只查询原任务。
+
+仅缺少授权、充值资格或余额时向用户说明必要操作，并提供[认证与充值入口](https://ai-hive.iclip.cn/certified-materials#guide)；不擅自换模型提交。费用变化时重新确认，预检通过不代表内容审核通过。
+
+更新信息仅在用户询问或与当前任务有关时介绍，不向用户转述内部参数、错误码、报价与重试机制。客户端可选升级提示默认静默，仅开启 `--verbose` 时输出维护诊断。技术维护记录见仓库 `docs/openapi/technical-changelog.md`。
+
+`recoveryAction` 是给调用端的恢复指引，不要逐字转成用户待办。响应中断用原 `clientRequestId` 和相同参数恢复；明确失败后再次生成，或改变报价/输入时，使用新请求标识。结果未知时先核查，不自动重建付费任务。

package/dist/api-client.d.ts

@@ -1,5 +1,6 @@
 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;
 type AiHiveApiClientInput = {
     endpoint: string;
@@ -7,19 +8,42 @@ type AiHiveApiClientInput = {
     timeoutMs: number;
     fetchImpl?: FetchImpl;
     clientInfoProvider?: () => McpClientInfo | undefined;
+    updateNotifier?: UpdateNotifier;
 };
+export declare class AiHiveApiError extends Error {
+    readonly status: number | undefined;
+    readonly details?: {
+        errorCode: string;
+        message: string;
+        helpUrl?: string;
+        actionUrl?: string;
+        retryable?: boolean;
+        recoveryAction?: string;
+    } | undefined;
+    constructor(status: number | undefined, message: string, details?: {
+        errorCode: string;
+        message: string;
+        helpUrl?: string;
+        actionUrl?: string;
+        retryable?: boolean;
+        recoveryAction?: string;
+    } | undefined);
+}
 export declare class AiHiveApiClient {
     private readonly endpoint;
     private readonly tokenProvider;
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly clientInfoProvider?;
+    private readonly updateNotifier?;
     constructor(input: AiHiveApiClientInput);
     private withTimeout;
     private request;
     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>;

package/dist/api-client.js

@@ -1,9 +1,12 @@
 import { encodeMcpClientInfo, MCP_CLIENT_INFO_HEADER, } from "./client-info.js";
-class AiHiveApiError extends Error {
+import { LATEST_CLIENT_VERSION_HEADER, } from "./update-notifier.js";
+export class AiHiveApiError extends Error {
     status;
-    constructor(status, message) {
+    details;
+    constructor(status, message, details) {
         super(message);
         this.status = status;
+        this.details = details;
         this.name = "AiHiveApiError";
     }
 }
@@ -41,8 +44,25 @@ function errorMessage(body) {
     }
     return "请求失败";
 }
+class AiHiveTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AiHiveTimeoutError";
+    }
+}
+// timeoutError 被 request/putUpload 共用, 覆盖只读接口与大文件上传,
+// 文案必须保持通用: 这里只描述状态, 付费调用专属的幂等恢复口径
+// 在 chatText/requestGeneration 处用 PAID_TIMEOUT_MESSAGE 替换.
+const GENERIC_TIMEOUT_MESSAGE = "等待响应超时，服务端可能仍在处理，请稍后重试";
+// 付费调用超时后服务端可能仍在生成(最终成功则已扣费), MCP/OpenAPI 没有
+// "查询会话结果"的能力, 唯一安全的恢复手段是幂等重调; 改参数重发会被当成
+// 新请求再次扣费, 与"同 prompt 提交 4 次扣 4 次"的客诉同因.
+const PAID_TIMEOUT_MESSAGE = "等待响应超时，服务端可能仍在生成，也可能已完成并扣费。请复用同一 clientRequestId 和相同业务参数重新调用，由服务端幂等去重并返回首次结果；修正参数后必须更换新的 clientRequestId";
 function timeoutError() {
-    return new Error("请求超时，请稍后重试");
+    return new AiHiveTimeoutError(GENERIC_TIMEOUT_MESSAGE);
+}
+function isTimeoutError(error) {
+    return error instanceof AiHiveTimeoutError;
 }
 function redactInternalPricing(value) {
     if (Array.isArray(value)) {
@@ -67,12 +87,14 @@ export class AiHiveApiClient {
     timeoutMs;
     fetchImpl;
     clientInfoProvider;
+    updateNotifier;
     constructor(input) {
         this.endpoint = input.endpoint.replace(/\/+$/, "");
         this.tokenProvider = input.tokenProvider;
         this.timeoutMs = input.timeoutMs;
         this.fetchImpl = input.fetchImpl ?? fetch;
         this.clientInfoProvider = input.clientInfoProvider;
+        this.updateNotifier = input.updateNotifier;
     }
     async withTimeout(operation) {
         const controller = new AbortController();
@@ -117,6 +139,9 @@ export class AiHiveApiClient {
                     response = await this.send(path, init, signal, refreshedToken);
                 }
             }
+            // 只看最终响应的版本头; 401 重试前的旧响应已废弃, 不重复参与判断.
+            // headers 用可选链访问, 兼容测试中的极简 fetch stub.
+            this.updateNotifier?.notifyIfOutdated(response.headers?.get(LATEST_CLIENT_VERSION_HEADER) ?? null);
             return this.readResponse(response);
         });
     }
@@ -138,13 +163,42 @@ export class AiHiveApiClient {
     async readResponse(response) {
         const body = await response.json().catch(() => ({}));
         if (!response.ok) {
-            throw new AiHiveApiError(response.status, errorMessage(body));
+            const message = errorMessage(body);
+            const details = body &&
+                typeof body === "object" &&
+                typeof body.errorCode === "string" &&
+                body.errorCode.startsWith("ASSET_")
+                ? {
+                    errorCode: body.errorCode,
+                    message,
+                    retryable: body.retryable === true,
+                    ...(typeof body.recoveryAction === "string"
+                        ? { recoveryAction: body.recoveryAction }
+                        : {}),
+                    ...(typeof body.helpUrl === "string"
+                        ? { helpUrl: body.helpUrl }
+                        : {}),
+                    ...(typeof body.actionUrl === "string"
+                        ? { actionUrl: body.actionUrl }
+                        : {}),
+                }
+                : undefined;
+            throw new AiHiveApiError(response.status, message, details);
         }
         return body;
     }
     getUserInfo() {
         return this.request("/mcp/user-info");
     }
+    getMaterialMode() {
+        return this.request("/mcp/material-mode");
+    }
+    quoteVideoMaterials(input) {
+        return this.request("/mcp/generation/video/material-quote", {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+    }
     async listModels(input) {
         const query = new URLSearchParams();
         if (typeof input.modelType === "string") {
@@ -183,11 +237,19 @@ export class AiHiveApiClient {
             method: "POST",
         });
     }
-    chatText(input) {
-        return this.request("/mcp/chat/text", {
-            method: "POST",
-            body: JSON.stringify(input),
-        });
+    async chatText(input) {
+        try {
+            return await this.request("/mcp/chat/text", {
+                method: "POST",
+                body: JSON.stringify(input),
+            });
+        }
+        catch (error) {
+            if (isTimeoutError(error)) {
+                throw new Error(PAID_TIMEOUT_MESSAGE);
+            }
+            throw error;
+        }
     }
     generateImage(input) {
         return this.requestGeneration("/mcp/generation/image", input);
@@ -203,6 +265,9 @@ export class AiHiveApiClient {
             });
         }
         catch (error) {
+            if (isTimeoutError(error)) {
+                throw new Error(PAID_TIMEOUT_MESSAGE);
+            }
             if (typeof input === "object" &&
                 input !== null &&
                 input.dryRun === true &&

package/dist/cli.js

@@ -295,8 +295,10 @@ async function runMcp(config, dependencies) {
     try {
         const resolved = await resolveServerAuth(config, dependencies.createStore(config.credentialsFile));
         await dependencies.runServer({
+            ...(config.verbose ? { verbose: true } : {}),
             ...resolved,
             timeoutMs: config.timeoutMs,
+            webOrigin: config.webOrigin,
         });
         return 0;
     }

package/dist/config.js

@@ -1,6 +1,10 @@
 import { resolveWorkBuddyCredentialsFile } from "./workbuddy-credentials.js";
 const DEFAULT_ENDPOINT = "https://ai-hive.iclip.cn/api";
 const DEFAULT_WEB_ORIGIN = "https://ai-hive.iclip.cn";
+// 文本对话由上游同步返回, 长推理模型实测可达 157s+ (gpt-6/claude-sonnet 系列).
+// 旧默认 120s 会在服务端仍在生成时先断开客户端连接, 用户看到"超时失败"、
+// 服务端却成功扣费. 现取 300s, 仍小于网关 600s 读超时, 留足余量.
+const DEFAULT_TIMEOUT_MS = 300_000;
 const CLI_COMMANDS = new Set([
     "server",
     "auth",
@@ -46,7 +50,9 @@ export function parseConfig(input) {
         values.set(name, value);
         index += 1;
     }
-    const timeoutMs = Number.parseInt(values.get("timeout-ms") ?? input.env.AI_HIVE_MCP_TIMEOUT_MS ?? "120000", 10);
+    const timeoutMs = Number.parseInt(values.get("timeout-ms") ??
+        input.env.AI_HIVE_MCP_TIMEOUT_MS ??
+        String(DEFAULT_TIMEOUT_MS), 10);
     const endpointOverride = values.get("endpoint") ?? input.env.AI_HIVE_API_ENDPOINT;
     return {
         command,
@@ -58,7 +64,9 @@ export function parseConfig(input) {
         key: values.get("key") ?? input.env.AI_HIVE_MCP_KEY ?? null,
         credentialsFile: values.get("credentials-file") ??
             resolveWorkBuddyCredentialsFile(input.env),
-        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 120000,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0
+            ? timeoutMs
+            : DEFAULT_TIMEOUT_MS,
         verbose: flags.has("verbose") || input.env.AI_HIVE_MCP_VERBOSE === "true",
     };
 }

package/dist/schemas.d.ts

@@ -94,6 +94,8 @@ export declare const generateImageShape: {
     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: {
+    materialMode: z.ZodOptional<z.ZodEnum<["standard", "certified"]>>;
+    materialQuoteId: z.ZodOptional<z.ZodString>;
     publicModelId: z.ZodString;
     routingMode: z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>;
     prompt: z.ZodEffects<z.ZodString, string, string>;

package/dist/schemas.js

@@ -100,6 +100,8 @@ export const generateImageShape = {
     pricingSnapshot: pricingSnapshotInputSchema,
 };
 export const generateVideoShape = {
+    materialMode: z.enum(["standard", "certified"]).optional(),
+    materialQuoteId: z.string().min(1).optional(),
     publicModelId: z.string().min(1),
     routingMode: routingModeSchema,
     prompt: nonBlankStringSchema,

package/dist/server.d.ts

@@ -4,14 +4,14 @@ 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.0";
+export declare const SERVER_VERSION = "0.3.1";
 declare function content(value: unknown): {
     content: {
         type: "text";
         text: string;
     }[];
 };
-type ApiClientLike = Pick<AiHiveApiClient, "getUserInfo" | "listModels" | "getModel" | "createMediaUpload" | "completeMediaUpload" | "chatText" | "generateImage" | "generateVideo" | "getGenerationTask" | "putUpload">;
+type ApiClientLike = Pick<AiHiveApiClient, "getUserInfo" | "getMaterialMode" | "quoteVideoMaterials" | "listModels" | "getModel" | "createMediaUpload" | "completeMediaUpload" | "chatText" | "generateImage" | "generateVideo" | "getGenerationTask" | "putUpload">;
 export type ToolDefinition = {
     name: string;
     description: string;
@@ -24,14 +24,23 @@ export type ResolvedServerAuth = {
     tokenProvider: BearerTokenProvider;
 };
 export declare function resolveServerAuth(config: McpClientConfig, store: WorkBuddyCredentialStore): Promise<ResolvedServerAuth>;
+/**
+ * 与 @ai-hive/contracts 的 buildMcpServerInstructions 内容对应;
+ * mcp-client 独立发布不依赖 contracts, 修改时两边同步.
+ */
+export declare function buildServerInstructions(webOrigin?: string): string;
 export declare function createServer(input: {
     endpoint: string;
     tokenProvider: BearerTokenProvider;
     timeoutMs: number;
+    webOrigin?: string;
+    verbose?: boolean;
 }): McpServer;
 export declare function runServer(input: {
     endpoint: string;
     tokenProvider: BearerTokenProvider;
     timeoutMs: number;
+    webOrigin?: string;
+    verbose?: boolean;
 }): Promise<void>;
 export {};

package/dist/server.js

@@ -2,12 +2,13 @@ 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";
 import { z } from "zod";
-import { AiHiveApiClient } from "./api-client.js";
+import { AiHiveApiClient, AiHiveApiError } from "./api-client.js";
 import { normalizeApiEndpoint, StaticBearerTokenProvider, WorkBuddyTokenProvider, } from "./auth-token-provider.js";
 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.0";
+export const SERVER_VERSION = "0.3.1";
 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 返回的对应快照对象，或省略该字段由客户端自动获取";
@@ -100,11 +101,14 @@ async function resolvePricingSnapshot(client, modelType, args) {
 }
 // 幂等键语义写在每个付费工具的描述里, 让宿主在选型阶段就能看到重试规则.
 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 [
         {
             name: "get_user_info",
-            description: "查询当前用户和余额。",
+            description: "查询当前用户、余额，以及官网地址和充值入口；余额不足时引导用户打开 rechargeUrl 完成充值后重试。",
             schema: {},
             handler: async () => content(await client().getUserInfo()),
         },
@@ -137,7 +141,7 @@ export function createToolDefinitions(client) {
         },
         {
             name: "chat_text",
-            description: `使用指定模型生成文本。${CLIENT_REQUEST_ID_NOTE}`,
+            description: `使用指定模型生成文本。${LONG_RUNNING_NOTE}${CLIENT_REQUEST_ID_NOTE}`,
             schema: chatTextShape,
             handler: async (args) => {
                 rejectDeprecatedAttachmentIds(args);
@@ -156,13 +160,43 @@ export function createToolDefinitions(client) {
         },
         {
             name: "generate_video",
-            description: `创建视频生成任务；dryRun=true 时只校验参数、媒体和预估费用，不创建任务且可省略 pricingSnapshot 与 clientRequestId。${CLIENT_REQUEST_ID_NOTE}`,
+            description: `认证版接收普通素材，服务端按模型 ID 自动校验资格和准备素材。提交前先用 dryRun=true 做只读预检，不用真实付费提交试探资格。materialMode、materialQuoteId 和专用报价工具均为可选兼容能力；正式提交使用当前 pricingSnapshot 和稳定 clientRequestId。资格不足时明确说明差额或待授权事项，并在回复中展示返回的 helpUrl 或 actionUrl 为可点击链接；未返回链接时使用 https://ai-hive.iclip.cn/certified-materials#guide。保留用户指定模型，不擅自切换模型或继续付费提交。认证服务已包含在模型价格中；费用变化时重新确认。收到任务 ID 后查询原任务，不重复创建。dryRun 不创建任务、不冻结素材、不预占或扣费，也不执行供应商内容审核。${CLIENT_REQUEST_ID_NOTE}`,
             schema: generateVideoShape,
             handler: async (args) => {
                 const body = await resolvePricingSnapshot(client, "VIDEO", args);
                 return content(await client().generateVideo(body));
             },
         },
+        {
+            name: "get_material_mode",
+            description: "查询认证版服务状态、授权与累计充值资格。已满足条件时直接继续；仅未授权时请用户本人打开 actionUrl 阅读并同意，不得代替用户授权。累计充值资格与钱包余额分别检查。",
+            schema: {},
+            handler: async () => content(await client().getMaterialMode()),
+        },
+        {
+            name: "quote_video_materials",
+            description: "上传普通素材后，由调用端用与生成相同的模型、参数及媒体 ID 获取报价，包含参考图片、视频、首帧和尾帧。无需用户手动认证素材。认证服务已包含在模型价格中，不另收素材费；向用户说明必要费用，费用或计费条件变化时重新确认。此工具可选，返回 id 可用作 materialQuoteId；未提供报价时服务端自动准备。显式报价过期时保留原素材重新获取。",
+            schema: {
+                publicModelId: generateVideoShape.publicModelId,
+                routingMode: generateVideoShape.routingMode,
+                prompt: generateVideoShape.prompt,
+                imageMediaIds: generateVideoShape.imageMediaIds,
+                videoMediaIds: generateVideoShape.videoMediaIds,
+                audioMediaIds: generateVideoShape.audioMediaIds,
+                firstFrameMediaId: generateVideoShape.firstFrameMediaId,
+                lastFrameMediaId: generateVideoShape.lastFrameMediaId,
+                pricingSnapshot: generateVideoShape.pricingSnapshot,
+                params: generateVideoShape.params,
+            },
+            handler: async (args) => {
+                const body = await resolvePricingSnapshot(client, "VIDEO", {
+                    ...args,
+                    dryRun: true,
+                });
+                delete body.dryRun;
+                return content(await client().quoteVideoMaterials(body));
+            },
+        },
         {
             name: "get_generation_task",
             description: "查询图片或视频任务状态和结果。",
@@ -204,16 +238,57 @@ export async function resolveServerAuth(config, store) {
         }),
     };
 }
+/**
+ * 与 @ai-hive/contracts 的 buildMcpServerInstructions 内容对应;
+ * mcp-client 独立发布不依赖 contracts, 修改时两边同步.
+ */
+export function buildServerInstructions(webOrigin) {
+    const lines = [
+        "AI Hive 是统一的大模型调用平台，按钱包余额扣费。",
+        "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 后查询原任务，不重复创建。",
+        "latestChange、changelog 和升级信息仅在用户主动询问或与当前任务直接相关时介绍。对用户只说明实际能力、费用、限制、结果和必要操作，不转述字段名、错误码、报价 ID、幂等机制、版本适配或内部排查过程；技术字段和 recoveryAction 供调用端处理，不能替代用户操作说明。用户明确排查接入问题时可以解释所需技术细节。",
+        "先用 get_user_info 查询余额；返回里带官网地址和充值入口，余额不足时引导用户打开 rechargeUrl 充值后重试。",
+        "调用 chat_text、generate_image、generate_video 前，用 get_model 确认参数契约；正式调用必须传稳定的 clientRequestId 幂等键，修正参数后换新值。",
+        "chat_text 同步返回，长推理模型单次可能耗时 1-3 分钟，客户端超时应设为 300 秒以上；等待超时只代表本端不再等待，服务端可能仍在生成，也可能已完成并扣费，超时后复用同一 clientRequestId 和相同业务参数重新调用即可取回首次结果，修正参数后换新值。",
+    ];
+    lines.push(webOrigin
+        ? `产品更新见 ${webOrigin}/changelog。`
+        : "产品更新见官网更新日志页。");
+    return lines.join("\n");
+}
 export function createServer(input) {
-    const server = new McpServer({ name: "ai-hive", version: SERVER_VERSION });
+    // instructions 随 initialize 握手注入宿主上下文, 是裸 MCP 缺少技能时的基础知识来源.
+    const server = new McpServer({ name: "ai-hive", version: SERVER_VERSION }, { instructions: buildServerInstructions(input.webOrigin) });
+    const updateNotifier = createUpdateNotifier({
+        currentVersion: SERVER_VERSION,
+        enabled: input.verbose === true,
+        endpoint: input.endpoint,
+    });
     const client = () => new AiHiveApiClient({
         endpoint: input.endpoint,
         tokenProvider: input.tokenProvider,
         timeoutMs: input.timeoutMs,
         clientInfoProvider: () => readMcpClientInfo(server),
+        updateNotifier,
     });
     for (const tool of createToolDefinitions(client)) {
-        server.tool(tool.name, tool.description, tool.schema, tool.handler);
+        server.tool(tool.name, tool.description, tool.schema, async (args) => {
+            try {
+                return await tool.handler(args);
+            }
+            catch (error) {
+                if (error instanceof AiHiveApiError && error.details)
+                    return {
+                        isError: true,
+                        structuredContent: error.details,
+                        content: [
+                            { type: "text", text: JSON.stringify(error.details) },
+                        ],
+                    };
+                throw error;
+            }
+        });
     }
     return server;
 }

package/dist/update-notifier.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 与服务端 contracts 的 LATEST_CLIENT_VERSION_HEADER 保持一致;
+ * mcp-client 独立发布到 npm, 不依赖 @ai-hive/contracts, 常量需手工同步.
+ */
+export declare const LATEST_CLIENT_VERSION_HEADER = "x-ai-hive-latest-client-version";
+export type UpdateNotifier = {
+    notifyIfOutdated(latestVersion: string | null): void;
+};
+/**
+ * 仅显式开启维护诊断时, 按服务端响应头在 stderr 一次性提醒可选升级.
+ * 只写 stderr, 不碰 stdout 的 MCP 协议通道; 提醒过就不再重复, 避免刷屏.
+ */
+export declare function createUpdateNotifier(input: {
+    enabled?: boolean;
+    currentVersion: string;
+    endpoint: string;
+    write?: (line: string) => void;
+}): UpdateNotifier;
+/** 只比较 x.y.z 数字段; 非数字段按 0 处理, 不被预发布标签绊倒. */
+export declare function compareVersions(a: string, b: string): number;

package/dist/update-notifier.js

@@ -0,0 +1,46 @@
+/**
+ * 与服务端 contracts 的 LATEST_CLIENT_VERSION_HEADER 保持一致;
+ * mcp-client 独立发布到 npm, 不依赖 @ai-hive/contracts, 常量需手工同步.
+ */
+export const LATEST_CLIENT_VERSION_HEADER = "x-ai-hive-latest-client-version";
+/**
+ * 仅显式开启维护诊断时, 按服务端响应头在 stderr 一次性提醒可选升级.
+ * 只写 stderr, 不碰 stdout 的 MCP 协议通道; 提醒过就不再重复, 避免刷屏.
+ */
+export function createUpdateNotifier(input) {
+    const write = input.write ?? ((line) => console.error(line));
+    let notified = false;
+    return {
+        notifyIfOutdated(latestVersion) {
+            if (!input.enabled || notified || !latestVersion) {
+                return;
+            }
+            if (compareVersions(latestVersion, input.currentVersion) <= 0) {
+                return;
+            }
+            notified = true;
+            write(`[ai-hive-mcp] 新版本 ${latestVersion} 已发布（当前 ${input.currentVersion}），新工具和改进见更新日志：${changelogUrl(input.endpoint)}。升级命令：npm install -g @infimind-next/ai-hive-mcp@latest`);
+        },
+    };
+}
+/** 只比较 x.y.z 数字段; 非数字段按 0 处理, 不被预发布标签绊倒. */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    for (let index = 0; index < 3; index += 1) {
+        const diff = (pa[index] ?? 0) - (pb[index] ?? 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+/** API 与站点同域部署, 由 endpoint 推导更新日志页; 推导失败时回退正式环境. */
+function changelogUrl(endpoint) {
+    try {
+        return `${new URL(endpoint).origin}/changelog`;
+    }
+    catch {
+        return "https://ai-hive.iclip.cn/changelog";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infimind-next/ai-hive-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "engines": {
@@ -12,13 +12,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "lint": "eslint \"src/**/*.ts\"",
-    "prepack": "pnpm run build",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "file-type": "^21.3.4",
@@ -29,5 +22,11 @@
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run"
   }
-}
+}