# kelivo-image-mcp

一个远程 MCP 服务，让 Kelivo 里的普通聊天模型通过调用工具来生图。图片会被服务自己托管一份，并以 Markdown 直链返回，这样模型可以把它写进回复正文，客户端就能直接铺开显示，而不是折叠在「工具调用」卡片里。

两套后端：

| 后端 | 工具 | 说明 |
| --- | --- | --- |
| OpenAI 兼容中转站 | `generate_image` | grok-imagine / gpt-image / dall-e / flux 等，快，不消耗点数 |
| Nai2API 工作台 | `nai_options` `nai_prompt_convert` `nai_generate` `nai_balance` | NovelAI 4.5，质量高，按画幅消耗点数 |

同时实现两种传输方式，兼容大多数 MCP 客户端：

- 旧版 HTTP+SSE：`GET /sse` + `POST /messages`
- Streamable HTTP：`POST /mcp`

实际上 `/`、`/mcp`、`/sse` 三个路径都能用，GET 当 SSE、POST 当 Streamable HTTP，自动判断。

## 环境变量

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `MCP_AUTH_TOKEN` | 是 | 自定义密码，防止别人拿到 URL 白嫖你的额度 |
| `RELAY_API_KEY` | 用中转站生图则必填 | 中转站 key |
| `RELAY_BASE_URL` | 否 | 默认 `https://us.shapi.vip` |
| `DEFAULT_IMAGE_MODEL` | 否 | 默认 `grok-imagine-image` |
| `NAI_TOKEN` | 用 NAI 生图则必填 | `STA1N-` 开头的密钥 |
| `NAI_BASE_URL` | 否 | 默认 `https://nai.sta1n.cn` |
| `RETURN_IMAGE_BLOCK` | 否 | 设为 `1` 时额外返回 MCP 原生图片块 |
| `PUBLIC_BASE_URL` | 否 | 覆盖自动识别的对外地址 |

## 部署（Render，手机可完成）

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/1906777392-star/kelivo-image-mcp)

部署完得到形如 `https://kelivo-image-mcp.onrender.com` 的地址。访问根路径可以看到版本号和各项配置是否就绪。

## 在 Kelivo 里接入

添加远程 MCP，URL 填：

```
https://<你的域名>.onrender.com/mcp?token=<你的 MCP_AUTH_TOKEN>
```

然后用一个支持工具调用的聊天模型，开启这个 MCP。

## NAI 生图的选项流程

`nai_generate` 的参数都有默认值，但站点选项较多，推荐让模型先调 `nai_options` 把选项列成编号列表给用户挑：

- **风格预设 preset**：`fresh` 韩漫小清新 / `anime` 动漫同人 / `2.5d` 2.5D唯美 / `galgame` GalGame风 / `custom` 自定义
- **画幅 size**：竖图 / 横图 / 方图（各 1 点），2K 系列 15 点，4K 系列 25 点
- **采样器 sampler**：`k_dpmpp_2m_sde` 等 6 种
- **参数**：steps 1-28、scale 1-20、cfg 0-1
- **数量 n**：1 / 2 / 4

单次消耗超过 4 点时，`nai_generate` 不会直接扣费，而是返回一条提示要求模型先向用户说明总消耗，用户同意后再带 `confirmed=true` 调用。中文描述可以先用 `nai_prompt_convert` 转成英文 tag，这一步不消耗点数。

## 说明

- 所有 key 只放在环境变量里，不写进代码。
- 不设 `MCP_AUTH_TOKEN` 的话，任何拿到 URL 的人都能调用并消耗你的额度。
- 图片存在内存里，最多 60 张、保留 12 小时；Render 免费实例休眠或重新部署后图片链接会失效，想长期保存请及时下载。
- Render 免费实例闲置 15 分钟休眠，唤醒约需 1 分钟，所以第一次生图可能偏慢。
- 仓库里的 `main.ts` 是早期的 Deno 版本，功能较旧，仅作保留。