# OpenCode TokenRhythm Image MCP

适配 [opencode](https://opencode.ai) 的 [基元律动 (TokenRhythm)](https://tokenrhythm.studio) **图片生成** MCP 服务器。

通过 MCP 协议让 opencode 直接调用 TokenRhythm 的图片生成模型（`qwen-image-2.0`、`wan2.7-image`），生成并保存图片到本地磁盘。

## 特性

- 纯 Python 标准库实现 MCP stdio 协议，**零第三方依赖**（要求 Python 3.8+）
- 内置两个工具：
  - `generate_image` — 生成图片并保存到本地，返回本地路径与远程 URL
  - `list_image_models` — 列出可用的图片生成模型
- 图片默认保存到 `~/Pictures/opencode-tokenrhythm/`
- API Key 通过环境变量传入，不写入代码

## 图片生成模型

| 模型 | 说明 | 价格 |
|------|------|------|
| `qwen-image-2.0` | 阿里云通义千问图片生成 | ¥0.20/张 |
| `wan2.7-image` | 阿里云万相图片生成 | ¥0.20/张 |

## 安装

### 1. 下载服务器

将 `server.py` 放到本地任意目录，例如：

```
C:\Users\<用户名>\.config\opencode\mcp\server.py
```

### 2. 设置环境变量

设置 `TOKENRHYTHM_API_KEY` 为你的 TokenRhythm API Key（在 [tokenrhythm.studio](https://tokenrhythm.studio) 注册后获取）：

```powershell
# Windows（用户级）
[Environment]::SetEnvironmentVariable("TOKENRHYTHM_API_KEY", "sk_xxx", "User")
```

```bash
# Linux / macOS
export TOKENRHYTHM_API_KEY=sk_xxx
```

可选环境变量：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `TOKENRHYTHM_API_KEY` | (无) | 必填，TokenRhythm API Key |
| `TOKENRHYTHM_BASE_URL` | `https://tokenrhythm.studio/v1` | API 基础地址 |
| `TOKENRHYTHM_OUTPUT_DIR` | `~/Pictures/opencode-tokenrhythm` | 图片保存目录 |

### 3. 在 opencode 中注册 MCP

编辑 `opencode.json`（全局：`~/.config/opencode/opencode.json`；或项目：`.opencode/opencode.json`）：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tokenrhythm-image": {
      "type": "local",
      "command": ["python", "C:\\Users\\<用户名>\\.config\\opencode\\mcp\\server.py"],
      "enabled": true,
      "environment": {
        "TOKENRHYTHM_API_KEY": "{env:TOKENRHYTHM_API_KEY}"
      }
    }
  }
}
```

### 4. 重启 opencode

保存配置后**重启 opencode**，在对话中即可使用 `generate_image` 工具生成图片。

## 手动测试

不启动 opencode，直接通过 stdio 验证：

```powershell
$env:TOKENRHYTHM_API_KEY = "sk_xxx"
python server.py
```

然后在另一终端发送 MCP JSON-RPC 消息，或参考 `test/` 目录。

## 工具说明

### generate_image

生成图片。参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | string | 是 | 图片描述 |
| `model` | string | 否 | `qwen-image-2.0`（默认）或 `wan2.7-image` |
| `n` | integer | 否 | 生成数量，1-4，默认 1 |
| `size` | string | 否 | 尺寸，如 `1024x1024` |

### list_image_models

列出 TokenRhythm 图片生成模型及当前 `/v1/models` 返回的模型列表。

## 相关链接

- [TokenRhythm API 文档](https://tokenrhythm.studio/docs/api-integration)
- [TokenRhythm 模型列表](https://tokenrhythm.studio/models)
- [OpenCode MCP 文档](https://opencode.ai/docs/mcp-servers)