开物基模 MCP-Dienst（kwjm-mcp）

Ein MCP-Dienst auf Basis der API von 开物基模 (kwjm.com). Jedes MCP-fähige Agent-Tool kann nach nur einmaliger Konfiguration des Plattform-API-Keys Text-/Bild-/Video-Modelle aufrufen und dabei die verfügbaren Bereiche und Fähigkeitsgrenzen jedes Modells klar erkennen.

Plattform-Wesen: 开物基模 ist ein Aggregations-Proxy für KI-Modelle (API Provider). Sobald du ein Plattform-Token besitzt, kannst du über diesen Dienst verschiedene Modellfamilien aufrufen (OpenAI, Seed/Seedance, DeepSeek, Qwen, Gemini, Anthropic, 快手可灵 usw.).

Eigenschaften

• Einmal konfigurieren, überall nutzbar: Mit KWJM_API_KEY können Modelle aufgerufen werden; wird zusätzlich das Nicht-Schlüssel-Feld KWJM_API_KEY_ID konfiguriert, wird die standardmäßige Tagesabrechnungsabfrage exakt an den aktuellen Mitglieds-Key gebunden.

• Fähigkeitserkennung: list_models / get_model_capabilities zeigen dem Agenten vor dem Aufruf jedes Modells dessen Modalität, Familie, Auswahlebene, Aliase und Fähigkeitsgrenzen.

• Multimodale Aufrufe: Text (OpenAI /v1/chat/completions und Anthropic /v1/messages), Bild (/v1/images/generations, /v1/images/edits), Video (asynchrone Aufgaben mit /v1, /v2, /v3 und kling-spezifischen Endpunkten).

• Regeln zur Vermeidung von Fehlentscheidungen (Kerndesign):

  • Stufen „default/fallback/off-by-default“: default bevorzugt für gleichartige Aufgaben, fallback als Alternative, off-by-default nur bei expliziter Angabe – unbekannte Modelle werden niemals standardmäßig berührt.

  • Nachfrage bei Mehrdeutigkeit: Wenn ein Modell angegeben ist, aber Versions-/Namenskonflikte bestehen (z. B. Familie deepseek), wird eine Kandidatenliste zurückgegeben; der Benutzer oder Agent wählt anhand des genauen Kontexts, ohne eigenmächtige Vermutung.

  • Echtzeit-Präzisions-ID bevorzugt: Die von /v1/models zurückgegebene exakte ID ist der endgültige Anforderungswert; Aliase dienen nur als Hilfseinstieg und können eine gleichnamige Echtzeit-ID nicht überschreiben. Beispielsweise muss kw-video-v2* unverändert an die Plattform übergeben werden.

  • Standardentscheidung für gleichartige Aufgaben: Bei gleichartigen Aufgaben entscheidet der Agent anhand des Kontexts, welches default-Modell verwendet wird; eine Rückfrage ist nicht jedes Mal erforderlich.

• Vorabprüfung der Fähigkeitsgrenzen + aktive Blockierung: validate_request validiert vor dem Aufruf die Benutzereingaben (Obergrenze für Referenzbilder, Aufzählungen für Größe/Auflösung/Seitenverhältnis/Dauer, zwingend auftretende Fehler) und weist bei Überschreitung aktiv darauf hin und gibt Korrekturvorschläge; suggest_model liefert je nach Aufgabe die Stufen default/Alternative/off-by-default.

• Fehlercodes „in verständlicher Sprache“: Fehlercodes wie 401/403/429/500/503 werden in eine vierteilige Struktur aus „Problemart + ursprüngliche Bedeutung + allgemeinverständliche Erklärung + nächste Schritte“ überführt. Der Agent spuckt nicht nur Statuscodes aus, sondern erklärt in für Laien verständlichen Worten, „was passiert ist, warum und was zu tun ist“.

Schnellstart

1. Installation

npm install -g kwjm-mcp

Alternativ kann man es ohne globale Installation direkt vom MCP-Client über npx starten:

npx -y kwjm-mcp

2. API-Key konfigurieren

In der Serverkonfiguration eines beliebigen MCP-Clients wird das Token über env übergeben:

Die API-Basis-URL ist fest auf die offizielle https://kwjm.com gesetzt; eine Überschreibung per Umgebungsvariable wird nicht akzeptiert, damit das Bearer-Token nicht versehentlich an andere Quellen gesendet wird.

3. Beispiel mit npx als Serverbefehl

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

Werkzeugübersicht

Fähigkeits-Atomisierung (basierend auf der realen Dokumentation)

Die Modellfähigkeitstabelle wurde Punkt für Punkt aus 62 API-Dokumentationsseiten der Plattform übernommen und deckt das reale Ende-zu-Ende-System ab:

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

• Bild: /v1/images/generations, /v1/images/edits, /v1/images/generations/tasks (asynchron, -gp-Suffix), DashScope-Äquivalent, gemini generateContent

• Video (Multi-Endpunkt-System, asynchrone Aufgaben per Polling):

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

  • /v3/contents/generations/tasks (exakte Modelle kw-video-v2* und dreamina-seedance-kompatible Modelle)

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

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

• Regel für exakte IDs: kw-video-v2, kw-video-v2-fast, kw-video-v2-mini, kw-video-v2.5 sind eigenständige Plattform-IDs und werden nicht auf dreamina-IDs abgebildet.

Über die Auswahlregeln (sehr wichtig)

• Standardmodelle: Text gpt-5.2-pro-2025-12-11; Bild gpt-image-2; Video kw-video-v2. Bei gleichartigen Aufgaben ohne Angabe verwendet der Agent sie standardmäßig.

• Mehrdeutigkeit: Trifft die Eingabe auf mehrere Kandidaten (z. B. wan, kling u. a. Mehrversionsfamilien), gibt das Tool eine Kandidatenliste zurück; erst nach Festlegung sollte aufgerufen werden.

• Ohne Angabe kein Aufruf: Modelle wie claude-opus-4-8, gpt-image-2-gp (asynchron), grok-imagine sind markiert und werden ohne explizite Angabe (explicit: true) nicht aufgerufen.

Tests

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

Die Tagesabrechnungsschnittstelle liefert nur die Key-Liste auf Kontoebene; daher muss die standardmäßige Abfrage des aktuellen Mitglieds mit KWJM_API_KEY_ID exakt gebunden werden. get_account_daily_costs erfordert außerdem die explizite Übergabe von all_keys=true, damit normale Kostenabfragen nicht versehentlich auf andere Mitglieder desselben Kontos ausgeweitet werden.

Integrationsanleitung für Agenten

• Codex

• Claude Code

• OpenCode

• zcode

• Cursor

• Hermes Agent

• OpenClaw

• Trae

• Workbuddy

Design-Dokumente

• Design-Spec

• 1.0-Release-Abschlussaudit

Verzeichnisstruktur

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