TokenHub AIGC Model — MCP Server

通过 MCP（Model Context Protocol） 调用 TokenHub 大模型服务平台生图能力的 MCP Server。客户在任何支持 MCP 的客户端（WorkBuddy / Claude Desktop / Cursor / 各类 AI IDE）中配置 TokenHub API Key，即可直接用自然语言调用文生图、图生图/图片编辑接口。

当前内置样例模型：custom-model-og-v2（GPT 系生图模型，同步返回）。

---

功能特性

• 两个工具
  • tokenhub_generate_image：文生图（POST /v1/wand/og-image/generation，同步返回）
  • tokenhub_edit_image：图生图/图片编辑（POST /v1/wand/og-image/edits，同步返回，支持 1-16 张输入图、mask 局部重绘）
• 双传输
  • stdio（默认）：本地客户端直接接入，零部署
  • streamable-http：部署成远程端点，供外部客户/团队远程接入
• 灵活配置：API Key、站点域名、模型名均可通过环境变量配置；单次调用可覆盖域名/模型（切换站点或模型无需改配置）

---

快速开始

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

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

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

{
  "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_MODEL": "custom-model-og-v2"
      },
      "description": "TokenHub 生图 MCP"
    }
  }
}

配置后即可对话：「帮我画一只在竹林中跳舞的小猫，2048x2048」。

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

{
  "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	默认模型名，单次调用可覆盖
MCP_AUTH_TOKEN	否（HTTP 模式建议）	-	HTTP 模式可选鉴权，设置后 /mcp 请求必须携带 x-mcp-auth-token 请求头

站点域名

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

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

---

工具参数说明

tokenhub_generate_image（文生图）

参数	必填	说明
prompt	是	文本描述，最大 32000 字符
base_url / model	否	单次覆盖站点域名 / 模型名
size	否	生成尺寸 宽x高，如 2048x2048。约束：单边≤3840px、宽高为 16 的倍数、长短边比≤3:1、总像素 655360~8294400
quality	否	auto / high / medium / low
n	否	生成数量 1-10，默认 1
background	否	opaque / auto
output_format	否	png / jpeg
output_compression	否	JPEG 压缩级别 0-100（仅 jpeg）
response_format	否	url（默认）/ b64_json

tokenhub_edit_image（图生图/编辑）

共享上文大部分参数，额外：

参数	必填	说明
images	是	输入图 1-16 张，[{ "image_url": "https://... 或 data:image/png;base64,..." }]，png/jpg
mask	否	局部重绘蒙版，尺寸需与输入图一致
background	否	额外支持 transparent

返回：图片 URL 列表、request_id（排查问题用）、total_tokens（计费用）；response_format=b64_json 时附带 base64 图片块供直接展示。

---

错误处理

• 工具调用失败返回 isError: true，错误信息包含 status、上游错误 code、request_id。
• 出现权限/限流/参数错误时，请保留 request_id 提交给 TokenHub 技术支持定位。
• 未配置 TOKENHUB_API_KEY 时，工具调用直接返回明确提示（server 可正常启动）。

---

HTTP 模式部署（远程）

# 本地启动（默认 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 支持单次覆盖，仅建议在可信环境下开放。

---

开发与发布

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

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

npm run build
npm version patch
npm publish --access public --registry=https://registry.npmjs.org
git tag v0.1.0 && git push --tags

---

⚠️ 重要提醒

1. 开白：custom-model-og-v2 为测试模型，需联系 TokenHub 产品/后台人员提交 UIN 和 Appid 开白后方可使用；未开白调用会返回权限错误。
2. API Key：请在 TokenHub 控制台 为对应模型创建专属 Key；Key 只在创建时展示一次，请妥善保存。
3. 计费：TokenHub 按 Token 计费（约 10 元/百万 token），小时结算。n>1 或多张输入图会显著放大消耗，请商务及时为客户申请折扣。
4. 费用公式（人民币）：文本输入 token×3.35 + 文本缓存输入×0.8375 + 图片输入×5.36 + 图片缓存输入×1.34 + 输出图片×20.1 = 单次任务 token 消耗（换算系数与汇率有关，当前系数 6.7）。

---

License

Apache-2.0