@infimind-next/ai-hive-mcp

蜂巢 AI 的本地 MCP 服务，让你在自己的 MCP 客户端里调用文本、图片和视频模型。

安装

使用下面的配置安装 0.6.0。把 <APIKEY> 换成你在蜂巢 AI 网页端「MCP 接入」里生成的 MCP 密钥：

{
  "mcpServers": {
    "ai-hive": {
      "command": "npx",
      "args": ["-y", "@infimind-next/[email protected]"],
      "env": { "AI_HIVE_MCP_KEY": "<APIKEY>" }
    }
  }
}

手动配置也把密钥放在 env 里；--key 仍兼容，但会出现在进程参数中，不建议继续使用。

也可以在终端或 Agent 里运行下面的命令，自动检测本机客户端、写入配置并安装技能：

AI_HIVE_MCP_KEY=<APIKEY> npx -y @infimind-next/ai-hive-mcp@latest setup

setup 会检测 Claude Code、Cursor、Codex、Claude Desktop 和 OpenCode，只写入 ai-hive 这一项，保留你已有的 MCP 配置和已有密钥；密钥以环境变量写入配置文件，不放进启动参数。没有密钥且本机没有登录凭证时会直接失败，不会写入一份不可用的配置。Claude Code 和 Codex 会同时安装技能。重复执行是安全的。常用选项：

• --client cursor,codex：只处理指定客户端。
• --dry-run：只预览，不写文件。
• --skip-skills：只写 MCP 配置，不安装技能。

要求 Node.js >= 20.19.0。默认请求超时为 300 秒，可通过 --timeout-ms 或 AI_HIVE_MCP_TIMEOUT_MS 覆盖；无效值回退为 300 秒。WorkBuddy Connector 的启动与认证命令保持引用 @latest，Connector 和 Skills 版本仍为 1.2.1。

本包通过标准 MCP stdio 与客户端通信，仅保证与支持 MCP 的客户端配合使用。

命令行

没有 MCP 宿主时，也可以用同一个 MCP 密钥直接调用。run 会先读取所选线路的报价再提交，金额单位是蜂蜜；只有充值实付金额才是元。输出默认适合人读，加 --json 返回原始结构：

ai-hive-mcp models --type IMAGE --json     # 筛选模型目录
ai-hive-mcp model <模型 ID> --json          # 查参数与售价
ai-hive-mcp models --type IMAGE --schema-version 2 --json  # 默认查看图片专业版能力
ai-hive-mcp usage --json                    # 查积分与账单汇总
ai-hive-mcp run <模型 ID> "写一句欢迎语"      # 付费文字调用

run 是付费调用，每次都会生成新的 clientRequestId；需要重试同一次请求时改用 MCP 的 chat_text 并复用原标识。

工具

• get_user_info：查询当前用户和普通蜂蜜积分

专属蜂蜜由服务端按实际模型自动选择抵扣，无需新增调用参数。不能仅凭普通蜂蜜积分为 0 拒绝模型调用；只有实际调用返回积分不足时，才使用 rechargeUrl 引导充值并重试。

• list_models：按类型或关键词筛选四字段轻目录，找到候选后用 get_model 读取参数和价格
• get_model：查询单个模型的参数 schema、媒体要求、计费因素和调用示例
• upload_media_from_path：上传本地图片、视频、音频或文档，返回 mediaId
• chat_text：文本对话
• generate_image：图片预检或正式生成
• generate_video：视频预检或正式生成
• get_material_mode：查询认证资格和网页授权入口（可选）
• quote_video_materials：获取素材报价（可选）
• list_generation_tasks：查询当前账号全部入口的图片、视频任务摘要，最新优先
• get_generation_task：按任务 ID 查询状态、结果和费用
• get_billing_summary：查询当前账户全部入口的账单汇总
• list_billing_records：分页查询账单记录
• get_billing_record：按记录 ID 查询账单详情

账单查询

3 个账单工具均为只读，需要所连接服务端支持。查询当前账户在网页、API、MCP 等全部入口的记录，不接受手机号或其他用户 ID。现有模型、任务和账户工具的调用方式不变。

账单单位为 HONEY（蜂蜜虚拟积分），积分数值沿用服务端的 micros 整数字符串，避免精度损失。消费仅指实际结算，预占、释放分别展示，不计入消费。查询某批生成任务时，传入该批的 taskIds，不要用前后积分之差推断批次费用；尚未结算的任务不能当作免费。

get_billing_summary 和 list_billing_records 支持可选 from、to、taskIds、publicModelId、invocationSource。不传时间时由服务端使用北京时间今日；指定时间须成对传入含时区的 ISO 8601 字符串，按左闭右开区间 [from,to) 查询。taskIds 传 1～100 个非空任务 ID。invocationSource 可选 UNKNOWN、WEB、MCP、WORKBUDDY、QWENWORK、DOUBAO_WORK、MIAOSHOU、OPENAPI。

list_billing_records 的 pageSize 默认 20、最多 100，后续分页原样传回 cursor。get_billing_record 接收列表返回的 recordId，例如 charge:<id> 或 reservation:<id>。这些工具不请求活动或公告通知。

认证素材模式

已发布的 0.3.1 提供可选认证工具，其调用契约支持认证版接收普通素材，由服务端按模型 ID 自动识别并校验资格、准备素材，不要求新增参数或先调用报价工具；实际可用性以所连接服务端的响应为准。materialMode、materialQuoteId 与 quote_video_materials 均为可选兼容能力。先用 dryRun: true 预检资格与费用；预检不执行供应商内容审核。资格不足或需要授权时，展示返回的操作链接，或引导查看认证资格指南。用户本人在网页授权，MCP 不能代签；保留用户指定模型，费用变化时重新确认。费用以所选模型的当前报价为准。

0.3.2 活动与公告通知

支持服务端提供的独立充值活动通知。首段文本继续是原业务 JSON，后续文本包含活动摘要、截止时间、充值入口与档位；Agent 按握手中的展示规则简短转达，尊重拒绝促销和严格输出要求。

客户端自动使用可选查询参数请求通知，不增加工具必填参数，不改计费请求或自动重试次数。连接旧服务端且没有通知时正常返回业务结果。旧的 0.3.0/0.3.1 可继续使用新服务端，但不能保证旧 Agent 主动展示活动。支持管理员现有公告策略及无截止时间的公告；发布记录与实测范围见 0.3.2 记录。

调用流程

图片和视频生成固定按 5 步走：

1. 用 list_models 选择模型，记录 publicModelId。
2. 用 get_model 查看参数契约，params 的字段名、类型、枚举值和默认值逐项来自返回的 paramsSchema。
3. 调用 generate_image 或 generate_video 时传 dryRun: true 预检，核对返回的 estimatedReservationMicros 估价（单位：蜂蜜 micros，1,000,000 micros = 1 蜂蜜；只有充值实付金额使用元）。
4. 确认费用后去掉 dryRun 正式生成，params 替换为预检返回的 resolvedParams，并传入预检返回的 pricingSnapshot 和本次调用稳定唯一的 clientRequestId。
5. 用 get_generation_task 查询任务进度、结果和费用，不重复创建任务。

需要找回近期任务时，使用 list_generation_tasks。可选 publicModelId 筛选模型，page 默认 1，pageSize 默认 20、最多 50。返回 {tasks,total,page,pageSize}，按创建时间和任务 ID 倒序；列表仅含任务与子任务 ID、模型、类型、创建时间、批量数量、160 字符以内提示词摘要、状态和进度，完整参数、结果地址及费用见详情。列表是只读工具，不返回公告或消耗通知额度。

详情默认包含 billing：金额单位为蜂蜜，currency=CNY 仅为历史兼容编码，不作为展示币种；公开价格快照、预估金额 estimatedReservationMicros、已入账金额 settledChargeMicros 和 settlementComplete。金额为 micros 字符串；结算未完成时已入账金额尚非最终费用，不能把 0 当免费。billing:null 表示费用暂不可读，任务结果仍可用。关闭通知不影响费用。钱包继续用 get_user_info。

远程 MCP 随服务端部署获得列表能力，本地 MCP 需升级到 0.3.4。新版客户端连接旧服务端不支持的列表端点时，会提示继续按任务 ID 查询。已发布的旧客户端无需修改详情调用即可透传 billing；严格拒绝新增响应字段的自定义消费者需更新响应校验规则。

重试与价格变化

• 传输中断或超时后重试：复用同一个 clientRequestId 和相同业务参数，不会重复扣费。
• 修正参数、积分或媒体问题后重试：必须使用新的 clientRequestId。
• 正式生成提示价格已更新：保持业务参数和原 clientRequestId 不变，重新预检获取最新 pricingSnapshot 后重试。
• 返回 REQUEST_OUTCOME_UNKNOWN：停止自动重试，联系管理员核查。

认证版的用户路径

用户提供普通素材即可，后台自动处理认证。使用对应认证模型与当前价格快照，先 dryRun 预检资格、素材和费用；通过后沿用标准版提交格式，认证字段和专用报价工具都可省略。收到任务 ID 后只查询原任务。

仅缺少授权、充值资格或积分时向用户说明必要操作，并提供认证与充值入口；不擅自换模型提交。费用变化时重新确认，预检通过不代表内容审核通过。

不向用户转述内部参数、错误码、报价与重试机制。客户端可选升级提示默认静默，仅开启 --verbose 时输出维护诊断。

recoveryAction 是给调用端的恢复指引，不要逐字转成用户待办。响应中断用原 clientRequestId 和相同参数恢复；明确失败后再次生成，或改变报价/输入时，使用新请求标识。结果未知时先核查，不自动重建付费任务。

0.4.2 的历史发布物与验证范围见 0.4.2 发布记录。

0.6.0：图片专业版能力协商

list_models / get_model 默认声明 pricingCapabilities: ["image-token-pricing-v1"]，同一图片模型可返回 serviceTiers: ["STANDARD", "PRO"] 和带 serviceTier: "PRO" 的 token 价格快照；generate_image 传 serviceTier: "PRO" 使用该变体。需要隐藏专业版时显式传空数组；旧客户端不传能力字段时继续只看到基础入口。不新增模型 ID，也不新增 V3 路径。

0.6.0 同时放宽文字模型附件能力校验，兼容图片附件数量上限和文档附件上限 20。

0.5.0：按需查询模型

模型查询默认使用 V2：先按类型或关键词读取分页目录，再查询候选模型的参数和价格。已知模型 ID 时可直接查询详情；需要旧格式时显式传 schemaVersion: 1，目录查询传旧 detail 也继续采用旧格式。V2 不与 detail 同传。调用、预检与费用确认规则保持不变，需要所连接服务端支持 V2。

升级后需让客户端实际启动新包并刷新工具说明。使用 @latest 的配置也需要获取并启动新版包；固定旧版本的配置继续使用原发布包。

0.4.2：修正 Codex 技能目录

将 Codex 技能安装到 ~/.agents/skills，与 Codex 的技能发现路径一致；setup 的其他行为、工具名称、入参和返回保持不变。

0.4.1：修正发布说明

0.4.1 仅修正 npm 首页的 README 发布状态文案，功能与 0.4.0 相同。

0.4.0：一条命令接入

新增 setup 命令：检测本机客户端、写入 MCP 配置、安装随包发布的 5 个技能，并用 user-info 验证连接。新增 models、model、usage、run 四个命令行子命令，让没有 MCP 宿主的 Agent 也能选型、试跑和查账。setup 写入的配置统一走 AI_HIVE_MCP_KEY，MCP 服务的启动参数里不再带密钥。

向下兼容：0.3.3 的 12 个工具名称、入参和返回保持不变，0.4.0 只新增 4 个只读工具；server、auth、status、logout 的行为不变。旧服务端不接受 detail 参数时，list_models 会自动去掉它重试一次。账单工具需要服务端已部署账单接口，未部署时会提示到控制台查看，不影响其他工具。

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 回退仍返回兼容活动。

0.3.3：简化提示与报价对象兼容

工具说明精简为用途和必要输入；充值活动仅说明优惠、截止时间和入口。未拥有专属蜂蜜的账户不介绍相关信息。报价支持嵌套对象与 JSON 字符串，沿用服务端校验与原有支付规则。

0.3.4：任务列表与详情费用（随 0.4.0 发布）

新增 list_generation_tasks；现有详情调用默认返回费用，API 与 MCP 使用相同口径。推送、服务端部署和 npm 发布需另行授权。

0.5.0 模型查询默认显式使用 V2，无需启动开关。先按类型或关键词筛选四字段轻目录，找到候选即可 get_model（默认参数与价格）；已知 ID 直接 get_model。仅完整目录需求才继续 nextCursor。正式调用前预检并确认费用，未知提交结果先查询原任务，不自动付费重试。固定旧包保持原行为；使用 @latest 的配置需获取并启动新版包后采用 V2。

订阅资金 V2（仓库实现中，未发布）

chat_text 支持正安全整数 maxOutputTokens 限制输出上限；省略时客户端不补默认字段，保持原请求正文。新工具发现不再提供额外服务档选择，新 Fast、Ultrafast 请求会被拒绝，普通文字请求不增加档位消费倍率。订阅功能由服务端总开关控制，默认关闭；最终可用性以服务器权益、运营许可和已认证线路为准。历史请求按原 ID 和原正文恢复，保留原档位、价格与资金快照，不重新定价。

功能开启且账号有当前订阅时，普通文字请求自动使用订阅，依次消耗「订阅额度 → 适用于该模型的专属蜂蜜 → 普通余额」。普通余额仅在你开启「余额续用」后补足差额；关闭余额续用仍可使用专属蜂蜜。没有当前订阅的普通请求保留原专属蜂蜜和钱包路径；功能关闭时也沿用原路径。显式传入 maxOutputTokens 或 serviceTier: "STANDARD" 的新请求进入订阅资金 V2，由服务端检查可用资金和许可。

文档提取文本参与订阅预占，图片要求已认证的图片输入上界；无认证时拒绝，不静默改走钱包。图片、视频生成仍按原方式计费。服务端的 Chat Completions、Responses、Anthropic Messages 标准端点也接入同一账号的订阅，JSON 和 SSE 均适用；这些端点的参数与幂等规则见 OpenAPI 调用指南。Codex 启动器的订阅适配另行实施和验收。

get_user_info 传 includeSubscriptionUsage=true 可读取版本化订阅用量；省略或 false 保持旧响应，不以钱包余额判断订阅额度。按月购买有效期与周/5 小时额度窗口分离，没有独立月度硬额度。

付费请求重试保持原 clientRequestId 和正文；处于处理中或结果待确认时不得换 ID 重发。此次源码变更没有修改包版本、发布 npm 或切换线上默认协议，不能把仓库版本号当作 registry 当前版本。

文本 RPM 限流以 RATE_LIMITED 结构化错误返回，首次拒绝可附 retryAfterSeconds。原请求 ID 的历史失败重放不重新开始倒计时；客户端不自动重试付费请求，用户确认恢复后再用新 ID 发起。缺少秒数时不推算等待时间。此能力属于仓库源码，尚未发布 npm。