MCP-сервис 开物基模 (kwjm-mcp)

На основе API 开物基模 (kwjm.com) — MCP-сервис. Позволяет любому агенту, поддерживающему MCP, вызывать модели текст / изображение / видео, настроив ключ API платформы всего один раз, и при этом наглядно видеть доступную область и границы возможностей каждой модели.

Суть платформы: 开物基模 — это агрегатор-прокси AI-моделей (API Provider). Имея токен платформы, вы можете через этот сервис вызывать различные семейства моделей (OpenAI, Seed/Seedance, DeepSeek, Qwen, Gemini, Anthropic, 快手可灵 и др.).

Характеристики

• Одна настройка — доступно везде: задайте KWJM_API_KEY и вызывайте модели; дополнительно укажите не-секретное поле KWJM_API_KEY_ID, чтобы привязать запрос дневной сводки по умолчанию к текущему ключу участника.

• Обнаружение возможностей: list_models / get_model_capabilities позволяют агенту перед вызовом увидеть модальность, семейство, уровень выбора, алиасы и границы возможностей каждой модели.

• Мультимодальные вызовы: текст (OpenAI /v1/chat/completions и Anthropic /v1/messages), изображения (/v1/images/generations, /v1/images/edits), видео (асинхронные задачи, включая /v1, /v2, /v3 и отдельные эндпоинты kling).

• Правила защиты от ошибочных вызовов (ключевая особенность):

  • Уровни «по умолчанию / запасной / не вызывать без указания»: default — приоритет для однотипных задач, fallback — запасной, off-by-default — только при явном указании; неизвестные модели никогда не вызываются по умолчанию.

  • Запрос при неоднозначности: если модель указана, но существует неоднозначность версии/имени (например, семейство deepseek), возвращается список кандидатов, и пользователь или агент выбирает на основе точного контекста; сервис не угадывает самостоятельно.

  • Приоритет точного ID из реального времени: точный ID, возвращённый /v1/models, является финальным значением запроса; алиасы служат только вспомогательным входом и не могут переопределять актуальный ID с тем же именем. Например, kw-video-v2* должен передаваться на платформу как есть.

  • Решение по умолчанию для однотипных задач: для однотипных задач агент сам решает, какую модель default использовать, исходя из контекста; обязательный опрос при каждом вызове не требуется.

• Предварительная проверка границ возможностей + активная блокировка: validate_request проверяет пользовательский ввод перед вызовом (лимит количества референсных изображений, перечисление размеров/разрешений/пропорций/длительности, обязательные ошибки) и при выходе за границы активно предупреждает и даёт рекомендации по исправлению; suggest_model выдаёт уровни default/fallback/off-by-default для задачи.

• Коды ошибок «человеческим языком»: коды ошибок 401/403/429/500/503 и другие преобразуются в четырёхчастную структуру «характер проблемы + исходное значение + простое объяснение + инструкция по следующему шагу». Агент больше не выдаёт просто код статуса, а объясняет понятным обычному человеку языком: «что произошло, почему и что делать».

Быстрый старт

1. Установка

npm install -g kwjm-mcp

Можно также не устанавливать глобально, а запускать напрямую через npx в MCP-клиенте:

npx -y kwjm-mcp

2. Настройка API-ключа

В конфигурации сервера любого MCP-клиента передайте токен через env:

API Base URL зафиксирован на официальном https://kwjm.com и не переопределяется через переменные окружения, чтобы bearer-токен не был случайно отправлен в другие источники.

3. Пример команды server с npx

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 платформы и не сопоставляются с ID dreamina.

О правилах выбора (важно)

• Модели по умолчанию: текст — gpt-5.2-pro-2025-12-11; изображение — gpt-image-2; видео — kw-video-v2. При однотипных задачах агент использует их по умолчанию, если модель не указана явно.

• Неоднозначность: если входящие параметры соответствуют нескольким кандидатам (например, многочисленные версии семейств 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

Интерфейс дневной сводки предоставляет список ключей только на уровне аккаунта; поэтому запрос текущего участника по умолчанию должен быть точно привязан через KWJM_API_KEY_ID. get_account_daily_costs также требует явной передачи all_keys=true, чтобы обычный запрос стоимости случайно не распространялся на других участников того же аккаунта.

Руководство по подключению агентов

• Codex

• Claude Code

• OpenCode

• zcode

• Cursor

• Hermes Agent

• OpenClaw

• Trae

• Workbuddy

Дизайн-документация

• Дизайн-спецификация

• Аудит финализации релиза 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/             单元 / 端到端 / 实时集成测试