开物基模 MCP 服务（kwjm-mcp）

基于 开物基模 (kwjm.com) API 的 MCP 服务。让任何一种支持 MCP 的 Agent 工具只需配置一次平台 API Key，即可调用 文本 / 图像 / 视频 模型，且清楚看到每个模型的可用范围与能力边界。

平台本质：开物基模是 AI 模型聚合代理（API Provider）。你持有平台令牌后，即可通过本服务调用各模型族（OpenAI、Seed/Seedance、DeepSeek、Qwen、Gemini、Anthropic、快手可灵等）。

---

特性

• 一次配置，到处可用：设置 KWJM_API_KEY 即可调用模型；再配置非密钥字段 KWJM_API_KEY_ID，即可把默认日结查询精确绑定到当前成员 Key。
• 能力发现：list_models / get_model_capabilities 让 Agent 在调用前看到每个模型的 modality、家族、选择层级、别名、能力边界。
• 多模态调用：文本（OpenAI /v1/chat/completions 与 Anthropic /v1/messages）、图像（/v1/images/generations、/v1/images/edits）、视频（异步任务含 /v1、/v2、/v3 与 kling 专属端点）。
• 防误判规则（核心设计）：
  • 默认/备选/非指明不调用分级：default 同类任务优先、fallback 备选、off-by-default 仅显式指名，绝不默认触碰未知模型。
  • 歧义问询：指明模型但存在版本/同名歧义（如 deepseek 家族）时，返回候选清单，交用户或 Agent 依据准确上下文选定，不擅自猜测。
  • 实时精确 ID 优先：/v1/models 返回的精确 ID 是最终请求值；别名仅作为辅助入口，不能覆盖同名实时 ID。例如 kw-video-v2* 必须原样传给平台。
  • Seedance 语义锁定：用户说 Seedance 2.0 时，对应 kw-video-v2、kw-video-v2-fast、kw-video-v2-mini 三档候选，最匹配 kw-video-v2，但需确认后再调用；用户说 Seedance 2.5 时，对应 kw-video-v2.5。
  • 同类工作默认决策：同类任务由 Agent 依据上下文决定使用哪个 default 模型，不强制每次问询。
• 能力边界预检 + 主动拦截：validate_request 在调用前校验用户输入（参考图数量上限、尺寸/分辨率/比例/时长枚举、必现错误），越界时主动提醒并给修正建议；suggest_model 按任务给出默认/备选/非指明分级。
• 错误码「说人话」：401/403/429/500/503 等错误码内化为「问题性质 + 原版含义 + 通俗解释 + 下一步引导」四段结构，Agent 不再只吐状态码，而是用普通人听得懂的话解释「发生了什么、为什么、该怎么办」。

---

快速开始

1. 安装

npm install -g kwjm-mcp

也可以不全局安装，直接让 MCP 客户端通过 npx 启动：

npx -y kwjm-mcp

2. 配置 API Key

在任何 MCP 客户端的 server 配置里，通过 env 传入令牌：

环境变量	必填	说明
KWJM_API_KEY	是	开物基模平台令牌（控制台 → API令牌）
KWJM_API_KEY_ID	日结必填	当前令牌的数字 ID；仅用于 get_current_key_daily_cost 精确过滤，不是密钥

API Base URL 固定为官方 https://kwjm.com，不接受环境变量覆盖，避免 bearer token 被误发到其他来源。

3. 以 npx 作为 server 命令示例

npx -y kwjm-mcp
# 源码开发：npm install && npm run build && node dist/index.js

---

工具总览

工具	说明	端点
list_models	列出全部模型与能力元数据（modality/层级/别名）	registry
get_model_capabilities	单模型能力深挖与别名解析	registry
refresh_models	调 /v1/models 实时并入 registry，未知模型标为非指明不调用	GET /v1/models
chat_completions	OpenAI 兼容文本生成	POST /v1/chat/completions
messages	Anthropic Messages 文本生成（claude 系）	POST /v1/messages
generate_image	文生图（端点随模型分派：/v1/images/generations、-gp 异步、DashScope、gemini）	分派
edit_image	图生图/编辑	POST /v1/images/edits
generate_video	文/图/参考生视频，端点随模型族分派（/v1、/v3、/v2、DashScope、kling）	分派
get_video_result	轮询视频/图像任务结果（queryPath 随模型族）	分派
get_current_key_daily_cost	默认查询当前 KWJM_API_KEY_ID 的日结成本；日期缺省为平台定义的前一天	GET /api/v1/user/statistics/day/keys
get_account_daily_costs	仅在显式传入 all_keys=true 时查询同账户全部 Key 日结	GET /api/v1/user/statistics/day/keys
get_wallet_balance	查询当前账户钱包余额	GET /api/v1/user/wallet

能力原子化（内化真实文档）

模型能力表已基于平台 62 个 API 文档页逐条内化，覆盖真实端到端体系：

• 文本：/v1/chat/completions、/v1/responses、/v1/messages（gpt-5.2/5.4、deepseek-v3.2、qwen3、doubao-seed、gemini、claude 系列）
• 图像：/v1/images/generations、/v1/images/edits、/v1/images/generations/tasks（异步，-gp 后缀）、DashScope 等效、gemini generateContent
• 视频（多端点体系，异步任务轮询）：
  • /v1/videos/generations（doubao-seedance、wan 系列）
  • /v3/contents/generations/tasks（kw-video-v2* 精确模型与 dreamina-seedance 兼容模型）
  • /v1/videos/text2video|image2video|video2video|reference（kling 系列）
  • /v1/videos/create（veo3.1、sora-2-sp）、/v1/videos（sora-2）
  • /v2/video_generation（MiniMax-H3）、DashScope /api/v1/services/aigc/video-generation/video-synthesis（wan2.7）
• 精确 ID 规则：kw-video-v2、kw-video-v2-fast、kw-video-v2-mini、kw-video-v2.5 均为独立平台 ID，不映射为 dreamina ID。自然语言 Seedance 2.0 返回前三者候选并推荐 kw-video-v2；自然语言 Seedance 2.5 映射到 kw-video-v2.5。

关于选择规则（很重要）

• 默认模型：文本 gpt-5.2-pro-2025-12-11；图像 gpt-image-2；视频 kw-video-v2。同类任务不指名时由 Agent 默认采用。
• 歧义：入参命中多个候选（如 wan、kling 等多版本家族）→ 工具返回候选清单，需确定后再调用。
• Seedance 2.0：视为 kw-video-v2、kw-video-v2-fast、kw-video-v2-mini 三档候选；默认建议 kw-video-v2，但调用前必须让用户确认具体档位。
• Seedance 2.5：视为 kw-video-v2.5。
• 非指明不调用：claude-opus-4-8、gpt-image-2-gp（异步）、grok-imagine 等已标记的模型，未显式指名(explicit: true)不会调用。

---

测试

npm test          # 单元 + 端到端（无需平台 key；e2e 验证防误判规则在协议层生效）
npm run test:live # 只读实时模型校验；不会触发生成
npm run test:live:text
KWJM_LIVE_COST_ACK=image npm run test:live:image
KWJM_LIVE_COST_ACK=video npm run test:live:video
KWJM_LIVE_COST_ACK=video-reference npm run test:live:video-reference

日结接口只提供账户维度的 Key 列表；因此默认的当前成员查询必须用 KWJM_API_KEY_ID 做精确绑定。get_account_daily_costs 还要求显式传入 all_keys=true，避免普通成本查询意外扩展到同账户其他成员。

---

Agent 接入指南

• Codex
• Claude Code
• OpenCode
• zcode
• Cursor
• Hermes Agent
• OpenClaw
• Trae
• Workbuddy

---

设计文档

• 设计 spec
• 1.0 发布收口审计

目录结构

src/
  core/
    types.ts      类型：能力/层级/别名
    registry.ts   策展能力表 + 选择规则 + 别名映射 + refresh 合并
    client.ts     HTTP 封装（鉴权/错误归一化）
  handlers/
    result.ts     MCP 结果/错误封装
    guard.ts      防误判守卫（歧义/off-by-default）
    discovery.ts  list_models / get_model_capabilities / refresh_models
    text.ts       chat_completions / messages
    image.ts      generate_image / edit_image
    video.ts      generate_video / get_video_result
    usage.ts      当前 Key / 全账户日结与钱包查询
  index.ts        MCP Server 引导
test/             单元 / 端到端 / 实时集成测试