开物基模 MCP 服务（kwjm-mcp）

Basado en la API de 开物基模 (kwjm.com), este es un servicio MCP. Permite que cualquier herramienta de agente compatible con MCP, con solo configurar una vez la API Key de la plataforma, pueda invocar modelos de texto / imagen / video y ver con claridad el alcance disponible y los límites de capacidad de cada modelo.

Naturaleza de la plataforma: 开物基模 es un proxy agregador de modelos de IA (API Provider). Una vez que tengas el token de la plataforma, puedes invocar las distintas familias de modelos (OpenAI, Seed/Seedance, DeepSeek, Qwen, Gemini, Anthropic, 快手可灵, etc.) a través de este servicio.

Características

• Una configuración, disponible en todas partes: establece KWJM_API_KEY para invocar modelos; además, configura el campo no secreto KWJM_API_KEY_ID para vincular con precisión la consulta diaria por defecto a la Key del miembro actual.

• Descubrimiento de capacidades: list_models / get_model_capabilities permiten que el agente vea, antes de la invocación, la modality, familia, nivel de selección, alias y límites de capacidad de cada modelo.

• Invocación multimodal: texto (OpenAI /v1/chat/completions y Anthropic /v1/messages), imagen (/v1/images/generations, /v1/images/edits), video (tareas asíncronas que incluyen /v1, /v2, /v3 y los endpoints exclusivos de kling).

• Reglas para prevenir errores de interpretación (diseño central):

  • Niveles default/fallback/no invocar sin indicación explícita: default prioridad en tareas del mismo tipo, fallback alternativa, off-by-default solo se invoca si se indica explícitamente; nunca se tocan modelos desconocidos por defecto.

  • Consulta de ambigüedad: cuando se indica un modelo pero existe ambigüedad de versión o de mismo nombre (p. ej., la familia deepseek), se devuelve una lista de candidatos para que el usuario o el agente elija según el contexto preciso, sin adivinar por cuenta propia.

  • Prioridad del ID preciso en tiempo real: el ID exacto devuelto por /v1/models es el valor final de la solicitud; los alias son solo una ayuda de entrada y no pueden anular el ID en tiempo real del mismo nombre. Por ejemplo, kw-video-v2* debe transmitirse tal cual a la plataforma.

  • Decisión por defecto para el mismo tipo de trabajo: en tareas del mismo tipo, el agente decide qué modelo default usar según el contexto; no se fuerza una consulta cada vez.

• Precomprobación de límites de capacidad + bloqueo proactivo: validate_request valida la entrada del usuario antes de la invocación (cantidad máxima de imágenes de referencia, enumeraciones de tamaño/resolución/proporción/duración, errores inevitables); si se excede, avisa de forma proactiva y ofrece sugerencias de corrección; suggest_model entrega los niveles default/alternativo/no invocar según la tarea.

• Códigos de error «en lenguaje humano»: códigos como 401/403/429/500/503 se internalizan en una estructura de cuatro partes («naturaleza del problema + significado original + explicación sencilla + guía del siguiente paso»); el agente ya no se limita a devolver el código de estado, sino que explica «qué pasó, por qué y qué hacer» en palabras que cualquier persona entienda.

Inicio rápido

1. Instalación

npm install -g kwjm-mcp

También puedes evitar la instalación global y simplemente hacer que el cliente MCP lo inicie mediante npx:

npx -y kwjm-mcp

2. Configuración de la API Key

En la configuración del servidor de cualquier cliente MCP, pasa el token mediante env:

La URL base de la API está fijada a la oficial https://kwjm.com y no admite anulación mediante variables de entorno, para evitar que el bearer token se envíe por error a otros orígenes.

3. Ejemplo de comando de servidor con npx

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

Resumen de herramientas

Capacidades atómicas (documentación real internalizada)

La tabla de capacidades de los modelos se ha internalizado punto por punto a partir de las 62 páginas de documentación de la API de la plataforma, cubriendo el verdadero sistema de extremo a extremo:

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

• Imagen: /v1/images/generations, /v1/images/edits, /v1/images/generations/tasks (asíncrono, con sufijo -gp), equivalente DashScope, generateContent de gemini

• Video (sistema de múltiples endpoints, sondeo de tareas asíncronas):

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

  • /v3/contents/generations/tasks (modelos precisos kw-video-v2* y modelos compatibles con dreamina-seedance)

  • /v1/videos/text2video|image2video|video2video|reference (series 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)

• Reglas de ID preciso: kw-video-v2, kw-video-v2-fast, kw-video-v2-mini, kw-video-v2.5 son todos IDs independientes de la plataforma y no se asignan a IDs de dreamina.

Acerca de las reglas de selección (muy importante)

• Modelos por defecto: texto gpt-5.2-pro-2025-12-11; imagen gpt-image-2; video kw-video-v2. Cuando no se indica un modelo para tareas del mismo tipo, el agente los usa por defecto.

• Ambigüedad: si la entrada coincide con varios candidatos (p. ej., familias con varias versiones como wan, kling) → la herramienta devuelve una lista de candidatos y es necesario confirmar antes de invocar.

• No invocar sin indicación explícita: los modelos marcados como claude-opus-4-8, gpt-image-2-gp (asíncrono), grok-imagine, etc., no se invocan si no se indican explícitamente (explicit: true).

Pruebas

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

La API de cierre diario solo ofrece una lista de Keys a nivel de cuenta; por lo tanto, la consulta predeterminada del miembro actual debe vincularse con precisión mediante KWJM_API_KEY_ID. get_account_daily_costs también exige pasar explícitamente all_keys=true, para evitar que una consulta de costos normal se extienda accidentalmente a otros miembros de la misma cuenta.

Guía de integración para agentes

• Codex

• Claude Code

• OpenCode

• zcode

• Cursor

• Hermes Agent

• OpenClaw

• Trae

• Workbuddy

Documentos de diseño

• Especificación de diseño

• Auditoría de cierre del lanzamiento 1.0

Estructura de directorios

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