# gcv-kie-mcp

MCP-сервер для [kie.ai](https://kie.ai): 12 инструментов для генерации
изображений, видео и музыки с оценкой стоимости до запуска и лимитами расхода.

```bash
claude mcp add gcv-kie -s user -e KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp
```

Требуется Node ≥ 20. Работает с любым MCP-клиентом: Claude Code, Claude Desktop,
Codex, Cursor, Antigravity, Windsurf.

---

## Зачем

Прямой доступ агента к платному API опасен: списание происходит в момент
создания задачи, до того как станет ясно, что результат получится. Сервер
закрывает это:

- **Цены живые.** Прайс запрашивается у kie.ai при обращении и **не хранится на
  диске** — устаревшая цена не может пережить перезапуск и тихо испортить смету
- **Оценка до запуска.** `kie_estimate` считает стоимость по этому прайсу. Цены
  нет — инструмент возвращает `known: false`, а не догадку
- **Лимит на вызов.** `maxCostCredits` отклоняет генерацию при превышении
- **Защита от повтора.** Одинаковый вызов в пределах суток не создаёт вторую
  задачу
- **Журнал трат.** `kie_ledger` показывает, что и сколько стоило

Описание `kie_generate` явно требует предварительных `kie_catalog_show`,
`kie_estimate` и согласия пользователя на сумму — это видит модель, а не только
человек в документации.

---

## Инструменты

| Инструмент | Что делает | Тратит деньги |
|---|---|---|
| `kie_doctor` | Ключ, связь, состояние каталога, курс | нет |
| `kie_balance` | Остаток на счету | нет |
| `kie_catalog_list` | Модели с ценами и лимитами | нет |
| `kie_catalog_show` | Карточка модели: схема `input`, лимиты, цена | нет |
| `kie_catalog_refresh` | Принудительно перечитать и цены, и схемы моделей | нет |
| `kie_catalog_set` | Записать модель вручную, если автоматика её не нашла | нет |
| `kie_estimate` | Оценка стоимости | нет |
| `kie_generate` | Создать генерацию и забрать результат | **да** |
| `kie_status` | Состояние задачи по `taskId` | нет |
| `kie_wait` | Дождаться завершения задачи | нет |
| `kie_upload` | Залить файл, получить URL для референса | нет |
| `kie_ledger` | Журнал трат | нет |

---

## Подключение

### Claude Code

Все оболочки Claude Code читают общий конфиг — достаточно одной регистрации из
любого терминала:

```bash
claude mcp add gcv-kie -s user -e KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp
```

`-e` передаёт ключ переменной окружения дочернего процесса: она не видна в
списке процессов ОС. `-s user` — сервер доступен из любого проекта, `-s local` —
только из текущего.

```bash
claude mcp get gcv-kie
```

Ожидается `Status: ✔ Connected`.

### Claude Desktop

**Расширение `.mcpb`** — ключ вводится в форме при установке и хранится в
системном хранилище учётных данных, а не в открытом файле. Готовый файл
приложен к каждому [релизу](https://github.com/extreez/MCP-KIE/releases):
скачать и открыть двойным кликом либо перетащить в окно приложения.

Собрать самому:

```bash
git clone https://github.com/extreez/MCP-KIE.git && cd MCP-KIE && npm run mcpb
```

**Ручной JSON** — в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gcv-kie": {
      "command": "npx",
      "args": ["-y", "gcv-kie-mcp"],
      "env": { "KIE_API_KEY": "sk-your-key" }
    }
  }
}
```

Ключ здесь лежит открытым текстом — расширение безопаснее.

### Codex

```bash
codex mcp add gcv-kie --env KIE_API_KEY=sk-your-key -- npx -y gcv-kie-mcp
```

Либо в `~/.codex/config.toml`:

```toml
[mcp_servers.gcv-kie]
command = "npx"
args = ["-y", "gcv-kie-mcp"]
env = { KIE_API_KEY = "sk-your-key" }
```

Проверка: `codex mcp list`, подробнее — `codex mcp get gcv-kie`.

### Antigravity

Конфиг общий для IDE, CLI и SDK: `~/.gemini/config/mcp_config.json`, в проекте —
`.agents/mcp_config.json`. Через интерфейс: «…» над панелью агента → MCP Servers
→ Manage MCP Servers → View raw config.

```json
{
  "mcpServers": {
    "gcv-kie": {
      "command": "npx",
      "args": ["-y", "gcv-kie-mcp"],
      "env": { "KIE_API_KEY": "sk-your-key" }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` глобально или `.cursor/mcp.json` в проекте — формат тот же.

### Windsurf

`~/.codeium/windsurf/mcp_config.json` — формат тот же.

### Другой клиент

JSON-RPC 2.0 через stdio, поддерживаемые версии протокола: `2025-06-18`,
`2025-03-26`, `2024-11-05`.

```bash
npx -y gcv-kie-mcp
```

Проверить без клиента:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y gcv-kie-mcp
```

---

## Ключ доступа

Берётся на https://kie.ai/api-key

Порядок поиска:

```
.env проекта → KIE_API_KEY → ~/.gcv/config.json → аргумент --api-key
```

Сервер не печатает значение ключа — только источник и маску (`sk-1…9f2c`).

> Аргумент `--api-key` виден в списке процессов ОС. В конфигах клиентов
> используйте `env`.

---

## Откуда берутся цены

Прайс запрашивается у kie.ai при обращении к каталогу и живёт только в памяти
процесса. На диск он не попадает — поэтому смета не может быть построена по
цене месячной давности.

Схемы моделей (поля `input`, лимиты, допустимые значения) кэшируются на 30 дней
в `~/.gcv/cache/kie/specs.json`. Они описывают устройство модели, а не деньги, и
меняются примерно раз в релиз. Цен в этом файле нет.

Что это значит на практике:

| Когда | Сколько ждать |
|---|---|
| Первое обращение после установки | около минуты — читаются схемы всех моделей |
| Первое обращение в новой сессии | около 5 секунд — только прайс |
| Последующие в той же сессии | мгновенно, прайс держится минуту |

`kie_catalog_refresh` нужен редко: цены и так живые. Он полезен, когда появилась
новая модель или её параметры выглядят неверно — тогда перечитываются и схемы.

## Первый запуск

```
подбери модель для обложки и посчитай, сколько выйдет 3 варианта
```

Агент вызовет `kie_catalog_list` → `kie_catalog_show` → `kie_estimate` и покажет
смету. `kie_generate` — только после подтверждения суммы.

Первый вызов займёт около минуты: читаются схемы моделей. Дальше быстро.

---

## Что модель принимает на вход

`kie_catalog_show` возвращает `limits.inputFiles` — **полный** список файловых
входов модели, включая картинки:

```jsonc
"limits": {
  "refField": "reference_image_urls",
  "maxRefs": 4,
  "inputFiles": [
    { "name": "first_frame_url",      "kind": "image", "maxItems": 1, "role": "start-frame" },
    { "name": "last_frame_url",       "kind": "image", "maxItems": 1, "role": "end-frame" },
    { "name": "reference_image_urls", "kind": "image", "maxItems": 4, "role": "primary" }
  ]
}
```

`refField` — не отдельный ответ, а **указатель** на запись с `role: "primary"`.
`modes` на вопрос «что можно приложить» не отвечает: `wan/2-7-image-to-video`
числится `image-to-video`, то есть моделью создания, и при этом принимает ролик
для продолжения в `first_clip_url`.

Как класть файлы в `kie_generate` и `kie_estimate`:

| Аргумент | Куда уходит |
|---|---|
| `refs` | в `limits.refField` — запись с `role: "primary"` |
| `videos` | в запись с `kind: "video"` |
| `audios` | в запись с `kind: "audio"` |
| `files` | в названное поле: `{"last_frame_url": "./end.png", "mask_url": "./mask.png"}` |

Первые три покрывают главный вход каждого вида. Всё остальное — конечный кадр,
маска, второй референс — адресуется через `files` по имени поля из
`inputFiles`. Поля, которого у модели нет, отклоняется **до** создания задачи:
kie.ai лишнее поле принимает, деньги списывает и файл игнорирует.

---

## Цена-диапазон

У части моделей стоимость зависит от разрешения или наличия видео на входе.
`kie_estimate` пытается свести диапазон к точному числу по тем же параметрам,
что пойдут в генерацию:

| Поле ответа | Смысл |
|---|---|
| `priceBasis: "exact"` | Цена сведена к одному числу |
| `resolvedBy` | По каким параметрам удалось сузить |
| `missingFields` | Какого параметра не хватает, чтобы сузить |
| `isRange: true` | Диапазон окончательный, сузить нечем |

Лимит `maxCostCredits` и проверка баланса считают по верхней границе.

---

## Файлы на диске

| Путь | Что |
|---|---|
| `~/.gcv/config.json` | Конфиг, права 600 |
| `~/.gcv/cache/kie/specs.json` | Схемы моделей, 30 дней. **Цен здесь нет** |
| `~/.gcv/cache/kie/overrides.json` | Модели, записанные через `kie_catalog_set` |
| `~/.gcv/ledger.jsonl` | Журнал трат, только дозапись |
| `~/.gcv/idempotency.json` | Защита от двойной оплаты: ключ → taskId |
| `~/.gcv/output/` | Результаты по умолчанию |

Цены на диске не хранятся нигде.

Расположение переопределяется переменной `GCV_HOME`.

---

## Доработка под себя

Пакет публикуется с исходниками, без сборки и минификации.

```bash
git clone https://github.com/extreez/MCP-KIE.git
cd MCP-KIE
```

Запустить свою копию, не устанавливая:

```bash
node mcp/server.mjs
```

Подключить свою копию в клиент — вместо `npx -y gcv-kie-mcp` укажите
`node /path/to/MCP-KIE/mcp/server.mjs`.

| Файл | За что отвечает |
|---|---|
| `mcp/server.mjs` | Протокол и описания инструментов |
| `src/catalog.mjs` | Живые цены, кэш схем. **Только здесь**, у CLI он другой |
| `src/api.mjs` | HTTP-вызовы kie.ai |
| `src/registry.mjs` | Разбор прайса, сведение цены к точной |
| `src/generate.mjs` | Preflight, оценка, запуск, опрос, скачивание |
| `src/ledger.mjs` | Журнал трат и защита от повтора |
| `mcpb/build.mjs` | Сборка расширения для Claude Desktop |

Остальное содержимое `src/` общее с
[CLI](https://github.com/extreez/gcv-kie-cli): логика одна, обёрток две.
Источник правды — репозиторий CLI, здесь лежит копия, чтобы пакет ставился одной
командой. Если правите ядро — правьте там, сюда переносите скриптом:

```bash
node sync-src.mjs --check
```

```bash
node sync-src.mjs --from ~/src/gcv-kie-cli
```

Скрипт намеренно не трогает `catalog.mjs`: у CLI он кэширует каталог на диске,
здесь — тянет цены живьём. Правки в `mcp/server.mjs` и `src/catalog.mjs` —
только здесь.

Добавили инструмент — добавьте его и в список `tools` в `mcpb/build.mjs`: этот
список показывается в диалоге установки расширения до первого запуска сервера.
CI сверяет оба списка.

Проверка после правок:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp/server.mjs
```

[Issues и PR](https://github.com/extreez/MCP-KIE/issues) приветствуются.
Требование к изменениям: `kie_generate` остаётся единственным инструментом,
который тратит деньги, а лимиты не отключаются ради удобства.

---

## Смежные инструменты

| Инструмент | Назначение |
|---|---|
| [gcv-kie](https://github.com/extreez/gcv-kie-cli) | Те же операции из терминала, плюс `pick`, `prices`, `schema`, `jobs`, `spend` |
| [gcv-creative](https://github.com/extreez/gcv-creative) | Скиллы для агента: пайплайн от брифа до галереи |

CLI и MCP-сервер делят один каталог, конфиг и журнал трат — можно ставить оба.

---

MIT © Leonid Kamenik