开物基模 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* 必须原样传给平台。

  • 同类工作默认决策：同类任务由 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 传入令牌：

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

3. 以 npx 作为 server 命令示例

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

工具总览

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

模型能力表已基于平台 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。

关于选择规则（很重要）

• 默认模型：文本 gpt-5.2-pro-2025-12-11；图像 gpt-image-2；视频 kw-video-v2。同类任务不指名时由 Agent 默认采用。

• 歧义：入参命中多个候选（如 wan、kling 等多版本家族）→ 工具返回候选清单，需确定后再调用。

• 非指明不调用：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/             单元 / 端到端 / 实时集成测试