开物基模 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

일일 결산 API는 계정 차원의 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/             单元 / 端到端 / 实时集成测试