开物基模 MCP Service (kwjm-mcp)

Based on the 开物基模 (kwjm.com) API, this is an MCP service. Any MCP-capable Agent tool only needs to configure the platform API Key once to call text / image / video models, and can clearly see the available scope and capability boundaries of each model.

Platform essence: 开物基模 is an AI model aggregation proxy (API Provider). Once you hold a platform token, you can use this service to call various model families (OpenAI, Seed/Seedance, DeepSeek, Qwen, Gemini, Anthropic, 快手可灵, etc.).

Features

• Configure once, use everywhere: Set KWJM_API_KEY to call models; additionally configure the non-secret field KWJM_API_KEY_ID to bind the default daily settlement query precisely to the current member Key.

• Capability discovery: list_models / get_model_capabilities let the Agent see each model's modality, family, selection tier, aliases, and capability boundaries before calling.

• Multimodal calls: text (OpenAI /v1/chat/completions and Anthropic /v1/messages), image (/v1/images/generations, /v1/images/edits), video (async tasks including /v1, /v2, /v3 and kling-specific endpoints).

• Misjudgment prevention rules (core design):

  • Default / fallback / off-by-default tiers: default is preferred for the same kind of task, fallback is the backup, and off-by-default is only called when explicitly named—never touch unknown models by default.

  • Ambiguity query: when a model is specified but version/name ambiguity exists (e.g., the deepseek family), return a candidate list and let the user or Agent choose based on accurate context; do not guess.

  • Real-time exact ID priority: the exact ID returned by /v1/models is the final request value; aliases are only auxiliary entry points and cannot override same-name real-time IDs. For example, kw-video-v2* must be passed to the platform as-is.

  • Default decision for same-kind tasks: for the same kind of task, the Agent decides which default model to use based on context, without forcing a query every time.

• Capability boundary pre-check + proactive interception: validate_request validates user input before calling (reference image count upper limit, size/resolution/aspect-ratio/duration enums, and required error cases), proactively warns and gives correction suggestions when out of bounds; suggest_model provides default/fallback/off-by-default tiers by task.

• Human-readable error codes: error codes such as 401/403/429/500/503 are internalized into a four-part structure of 'problem nature + original meaning + plain explanation + next-step guidance'. The Agent no longer just outputs status codes, but explains in plain language what happened, why, and what to do.

Quick Start

1. Install

npm install -g kwjm-mcp

You can also skip global installation and let the MCP client start via npx:

npx -y kwjm-mcp

2. Configure API Key

In any MCP client's server configuration, pass the token via env:

The API Base URL is fixed to the official https://kwjm.com and does not accept environment variable overrides, so the bearer token will not be accidentally sent to other sources.

3. Example using npx as the server command

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

Tools Overview

Capability Atomization (Internalizing Real Documentation)

The model capability table is internalized item by item from the platform's 62 API documentation pages, covering the real end-to-end system:

• Text: /v1/chat/completions, /v1/responses, /v1/messages (gpt-5.2/5.4, deepseek-v3.2, qwen3, doubao-seed, gemini, Claude family)

• Image: /v1/images/generations, /v1/images/edits, /v1/images/generations/tasks (async, -gp suffix), DashScope equivalent, gemini generateContent

• Video (multi-endpoint system, async task polling):

  • /v1/videos/generations (doubao-seedance, wan series)

  • /v3/contents/generations/tasks (kw-video-v2* exact models and dreamina-seedance compatible models)

  • /v1/videos/text2video|image2video|video2video|reference (kling series)

  • /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)

• Exact ID rule: kw-video-v2, kw-video-v2-fast, kw-video-v2-mini, kw-video-v2.5 are independent platform IDs and are not mapped to dreamina IDs.

About Selection Rules (Important)

• Default models: text gpt-5.2-pro-2025-12-11; image gpt-image-2; video kw-video-v2. When a same-kind task is not specified, the Agent uses them by default.

• Ambiguity: when the input matches multiple candidates (e.g., the wan, kling families with multiple versions) → the tool returns a candidate list; call only after confirmation.

• Off-by-default: marked models such as claude-opus-4-8, gpt-image-2-gp (async), grok-imagine are not called unless explicitly specified (explicit: true).

Testing

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

The daily settlement interface only provides Key lists at the account level; therefore, the default current-member query must use KWJM_API_KEY_ID for precise binding. get_account_daily_costs also requires explicitly passing all_keys=true to prevent ordinary cost queries from accidentally expanding to other members of the same account.

Agent Integration Guide

• Codex

• Claude Code

• OpenCode

• zcode

• Cursor

• Hermes Agent

• OpenClaw

• Trae

• Workbuddy

Design Documents

• Design spec

• 1.0 release closure audit

Directory Structure

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/             单元 / 端到端 / 实时集成测试