开物基模 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 などのエラーコードを「問題の性質 + 元の意味 + 平易な説明 + 次のステップの案内」の4段構造に内面化します。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/             单元 / 端到端 / 实时集成测试