tokenhub-aigc-model

README.md

# TokenHub AIGC Model — MCP Server

通过 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 调用 TokenHub 大模型服务平台能力的 MCP Server。客户在任何支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor / 各类 AI IDE）中配置 TokenHub API Key，即可用自然语言调用文生图、图生图、可灵（Kling）视频生成等能力。

## 对话式选模型

**不需要在配置里改模型**。MCP 内置模型注册表，AI 会先通过 `tokenhub_list_models` 查询可用模型，再按你对话中指定的模型调用对应工具并构建请求：

> 用户：**"用 kling-video-v3 生成一个海边日落的视频"**
> → AI 查模型注册表 → 调用 `tokenhub_kling_text_to_video(model="kling-video-v3", ...)` → 返回 task_id → 轮询 `tokenhub_kling_get_task` 直到拿到视频

`TOKENHUB_MODEL` 环境变量仅作为**兜底默认值**（不传 model 时使用），日常使用建议直接对话指定模型。

---

## 快速开始

### 方式一：stdio（本地接入，推荐先用这个）

在 MCP 客户端配置中新增一个命令类型的 MCP Server：

| 客户端 | 配置位置 |
| --- | --- |
| WorkBuddy | `~/.workbuddy/mcp.json`，然后「连接器管理 → 自定义连接器 → 信任」 |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | Settings → MCP → Add new MCP server |

```json
{
  "mcpServers": {
    "tokenhub": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tokenhub-aigc-model"],
      "env": {
        "TOKENHUB_API_KEY": "你的 TokenHub API Key",
        "TOKENHUB_BASE_URL": "https://tokenhub.tencentmaas.com",
        "TOKENHUB_TIMEOUT_MS": "120000"
      },
      "description": "TokenHub 生图/生视频 MCP"
    }
  }
}
```

> `TOKENHUB_MODEL` 可不配：默认在对话中指定模型；不指定时生图用 `custom-model-og-v2`、视频用 `kling-video-v3`。
>
> ⚠️ **超时配置**：`TOKENHUB_TIMEOUT_MS`（毫秒）为单次请求超时，默认 `120000`（120 秒）。**文生图/图生图为同步接口**，高画质/大尺寸下生成耗时可能较长；若日志出现"请求超时"，请调大该值（如 `300000`）。

### 方式二：Streamable HTTP（远程部署）

```json
{
  "mcpServers": {
    "tokenhub": {
      "url": "https://你的服务域名/mcp",
      "headers": { "x-mcp-auth-token": "部署时设置的 MCP_AUTH_TOKEN" }
    }
  }
}
```

---

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `TOKENHUB_API_KEY` | 是（调用时报错） | - | TokenHub 控制台获取的 API Key，请求头 `Authorization: Bearer <key>` |
| `TOKENHUB_BASE_URL` | 否 | `https://tokenhub.tencentmaas.com` | 站点域名（见下），末尾无需斜杠 |
| `TOKENHUB_MODEL` | 否 | `custom-model-og-v2` | **兜底默认模型**：仅当调用不传 model 时生效。推荐在对话中直接指定模型 |
| `TOKENHUB_TIMEOUT_MS` | 否 | `120000` | **单次请求超时（毫秒）**。生图为同步接口，高画质/大尺寸生成耗时长，超时请调大（如 `300000`）；非法值自动回退默认 |
| `MCP_AUTH_TOKEN` | 否（HTTP 模式建议） | - | HTTP 模式可选鉴权，设置后 /mcp 请求必须携带 `x-mcp-auth-token` 请求头 |

### 站点域名

TokenHub 按地域分站部署，不同站点的客户需填写对应域名。默认是国内站广州：

| 站点 | 域名（示例） |
| --- | --- |
| 国内站 · 广州 | `https://tokenhub.tencentmaas.com`（默认） |
| 其他站点（国内新加坡 / 国际站广州、新加坡、美西等） | 请联系 TokenHub 商务/技术支持获取对应域名，填入 `TOKENHUB_BASE_URL` 或单次调用传 `base_url` |

---

## 工具总览

| 工具 | 能力 | 适用模型 | 文档 |
| --- | --- | --- | --- |
| `tokenhub_list_models` | 查询可用模型注册表（对话式选模型的入口） | - | - |
| `tokenhub_generate_image` | 文生图（同步） | custom-model-og-v2 | [docs/og-image.md](docs/og-image.md) |
| `tokenhub_edit_image` | 图生图 / 图片编辑（同步） | custom-model-og-v2 | [docs/og-image.md](docs/og-image.md) |
| `tokenhub_kling_text_to_video` | 可灵文生视频（异步提交） | kling-video-v3 等 4 款 | [docs/kling.md](docs/kling.md) |
| `tokenhub_kling_image_to_video` | 可灵图生视频（异步提交） | kling-video-v3 等 4 款 | [docs/kling.md](docs/kling.md) |
| `tokenhub_kling_get_task` | 可灵任务查询 / 轮询 | 所有 kling 视频任务 | [docs/kling.md](docs/kling.md) |

---

## 模型列表总表

> **以 `tokenhub_list_models` 实时返回为准**，下表为当前注册内容（v0.3.0）。

| 模型 | 厂商 | 能力 | 可用工具 | 文档 |
| --- | --- | --- | --- | --- |
| custom-model-og-v2 | og-image | 文生图 / 图生图 | generate_image, edit_image | [docs/og-image.md](docs/og-image.md) |
| kling-video-v3（默认） | kling | 文生视频 / 图生视频 | kling_text_to_video, kling_image_to_video (+ get_task 轮询) | [docs/kling.md](docs/kling.md) |
| kling-video-v3-turbo | kling | 文生视频 / 图生视频 | 同上 | [docs/kling.md](docs/kling.md) |
| kling-video-v2.6 | kling | 文生视频 / 图生视频 | 同上 | [docs/kling.md](docs/kling.md) |
| kling-video-v2.5-turbo | kling | 文生视频 / 图生视频 | 同上 | [docs/kling.md](docs/kling.md) |

---

## WorkBuddy 对话示例

### 示例 1：文生图（og-image，同步）

> **用户**：画一只在竹林中跳舞的小猫，2048x2048
>
> **AI**（内部动作）：`tokenhub_list_models` → 发现 custom-model-og-v2 → 调用 `tokenhub_generate_image({ model: "custom-model-og-v2", prompt: "一只在竹林中跳舞的小猫", size: "2048x2048" })`
>
> **AI 返回**：图片 URL + request_id + token 用量

### 示例 2：可灵文生视频（异步两段式）

> **用户**：用 kling-video-v3 生成 5 秒 16:9 的视频：黄昏海滩上女孩看日落
>
> **AI**（内部动作）：`tokenhub_list_models` → 调用 `tokenhub_kling_text_to_video({ model: "kling-video-v3", prompt: "黄昏海滩上女孩看日落", settings: { aspect_ratio: "16:9", duration: 5 } })`
>
> **AI 返回**：`task_id: 251435731-WandVideo-xxxx`，并说明：*"任务已提交，视频生成需要几分钟，我可以帮你持续查询进度。"*
>
> **用户**：查询进度
>
> **AI**（内部动作）：`tokenhub_kling_get_task({ task_id: "251435731-WandVideo-xxxx" })` → status=processing → 回复：*"正在生成中，约 3~5 秒后再查一次。"*
>
> **用户**：再查一下
>
> **AI**（内部动作）：`tokenhub_kling_get_task(...)` → status=succeeded → 返回视频地址：*"生成完成！视频链接：https://...mp4（临时链接，请及时保存）"*

### 示例 3：可灵图生视频

> **用户**：用这张图作为首帧，让画面中的猫转头，模型用 kling-video-v3
>
> **AI**（内部动作）：`tokenhub_list_models` → 调用 `tokenhub_kling_image_to_video({ model: "kling-video-v3", contents: [{ type: "prompt", text: "让画面中的猫自然转头" }, { type: "first_frame", url: "https://...jpg" }] })` → 拿 task_id → 轮询 `tokenhub_kling_get_task` → 返回视频

---

## 错误处理

- 工具调用失败返回 `isError: true`，错误信息包含 `status`、上游错误 `code`、`request_id`。
- **HTTP 200 但业务 `code != 0`**（可灵等统一外壳接口）：同样按错误透传 `code` 与 `message`。
- 出现权限/限流/参数错误时，**请保留 `request_id`** 提交给 TokenHub 技术支持定位。
- 未配置 `TOKENHUB_API_KEY` 时，工具调用直接返回明确提示（server 可正常启动，`tokenhub_list_models` 不受影响）。

---

## HTTP 模式部署（远程）

```bash
# 本地启动（默认 stdio）
npx -y tokenhub-aigc-model

# HTTP 模式
TOKENHUB_API_KEY=xxx MCP_AUTH_TOKEN=部署密钥 \
  npx -y tokenhub-aigc-model --transport=http --port=3000 --host=127.0.0.1
```

端点：
- `POST /mcp`、`GET /mcp`：MCP 协议入口
- `GET /health`：健康检查

部署到公网时务必：
1. 设置 `MCP_AUTH_TOKEN`，或在前置网关/反向代理（如 EdgeOne、CLB、Nginx）做鉴权；
2. 使用 HTTPS；
3. `base_url` 支持单次覆盖，仅建议在可信环境下开放。

---

## 开发与发布

```bash
npm install        # 安装依赖
npm run build      # TypeScript 构建到 dist/
npm test           # 单元测试 + stdio/HTTP 冒烟测试（共 37 个用例）
npm pack --dry-run # 查看发布内容
```

发布到 npmjs（当前 registry 若是腾讯镜像，需显式指定）：

```bash
npm run build
npm test
npm version 0.3.0   # 升版本（或手改 package.json）
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.3.0 && git push --tags
```

---

## ⚠️ 重要提醒

1. **开白**：TokenHub 模型多为白名单制，需联系 TokenHub 产品/后台人员提交 UIN 和 Appid 开白后方可使用；未开白调用会返回权限错误（保留 request_id 排查）。
2. **API Key**：请在 [TokenHub 控制台](https://console.cloud.tencent.com/tokenhub/apikey) 为对应模型创建专属 Key；Key 只在创建时展示一次，请妥善保存。
3. **计费**：TokenHub 按 Token 计费（约 10 元/百万 token），小时结算。生视频单次任务消耗远高于生图（可达数十万 token），请商务及时为客户申请折扣。
4. **同步生图超时**：文生图/图生图为同步接口，单次请求可能耗时较长（默认超时 120 秒）。如遇"请求超时"，请在 MCP 配置中调大 `TOKENHUB_TIMEOUT_MS`（如 `300000`）。
5. **视频临时链接**：`tokenhub_kling_get_task` 返回的视频地址为临时链接（约 12 小时有效），请及时下载转存。

---

## License

[Apache-2.0](./LICENSE)

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Scored 2026-08-23 09:35 across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one generates an image purely from text, while the other edits/generates from 1-16 input images with optional masking. There is no realistic confusion between them.

Naming Consistency5/5

Both tools follow the same tokenhub_<verb>_image pattern with static verb prefixes: edit and generate. The naming convention is consistent and predictable.

Tool Count4/5

With only two tools, the server is slightly thin, but each tool covers a distinct core task in the image-generation domain. The focused scope makes the small count reasonable.

Completeness4/5

The two primary workflows—text-to-image generation and image editing/reinpainting—are covered, and the synchronous design avoids needing result-status tools. A minor gap is the lack of model-list or capability-discovery tooling, but agents can still complete the core tasks.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers