Metadata-Version: 2.4
Name: ownta-mcp
Version: 0.2.0
Summary: OWNTA MCP server (stdio + remote streamable-http): image/video generation, wallet, image ops, read-only skill/library tools, and subject x style prompt composition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.9
Requires-Dist: httpx>=0.27

# ownta-mcp

OWNTA 的 MCP 服务端：把出图、出视频、图像处理、技能与百科只读封装成 Agent 可直接调用的 11 个工具。
两条接入方式——本地 stdio（`pip install ownta-mcp`）或远程 HTTP
（`https://ai.ownta.ai/mcp`，不用装包）。

## 安装

```bash
pip install ownta-mcp
# 或者
uv tool install ownta-mcp
```

需要 Python >= 3.10。装完会得到命令 `ownta-mcp`（也可以 `python -m mcp_server`）。

## 1. 拿一把 Key

登录 <https://ownta.ai> → 设置 → API Key → 新建。

默认 scopes 是五个值：`img.gen`（出图）、`vid.gen`、`llm.chat`、`img.ops`（图像处理）、
`lib.read`。只让 Agent 出图就把 `img.ops` 去掉；Key 建完不能改 scopes，要改只能重建。
存量 Key 会在服务端启动迁移时自动补上 `img.ops` / `lib.read`，不需要重建。

Key 等同账户权限（能出图、能扣点），不要提交进仓库或贴进公开对话。

## 2. 配到客户端

通用形状（Claude Desktop / Cursor 都是 `mcpServers` 这一层）：

```json
{
  "mcpServers": {
    "ownta": {
      "command": "ownta-mcp",
      "env": {
        "OWNTA_GW_API_KEY": "sk-ownta-...",
        "OWNTA_GW_BASE_URL": "https://ai.ownta.ai"
      }
    }
  }
}
```

- Claude Desktop：`%APPDATA%\Claude\claude_desktop_config.json`（Windows）/
  `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
- Cursor：`~/.cursor/mcp.json`
- VS Code：`.vscode/mcp.json`（键名是 `servers`，其余字段相同）

Windows 上客户端找不到 `ownta-mcp` 时，把 `command` 写成 pip 的 Scripts 全路径，
例如 `C:\Users\<you>\AppData\Local\Programs\Python\Python312\Scripts\ownta-mcp.exe`。

`OWNTA_GW_BASE_URL` 可省略，默认就是 `https://ai.ownta.ai`。

## 2b. 或者不装包：连远程 HTTP 端点

服务端在 `https://ai.ownta.ai/mcp` 跑了一份 streamable-http（无状态）。客户端支持
URL 时，不用装包、不用本机 Python：

```json
{
  "mcpServers": {
    "ownta": {
      "url": "https://ai.ownta.ai/mcp",
      "headers": { "Authorization": "Bearer sk-ownta-..." }
    }
  }
}
```

- Key 放 `Authorization` 头；没带 Key 的请求在门口 401。
- 端点只做协议适配：scope、余额、日封顶仍由网关判定，错误码与 stdio 完全一致。
- 只支持 streamable-http（Claude Desktop 目前只起子进程，走第 2 步 stdio）；旧版 SSE transport（`/sse`）不提供。
- 远程与 stdio 是同一套 11 个工具、同一份计价，选哪种只取决于客户端能不能起子进程。

## 3. 先跑这一句

> 用 ownta 的 generate_image 画一只在雨林里的蓝顶亚马逊鹦鹉，1024x1024，然后轮询到出图，把图片 URL 给我。

Agent 应该先拿到 `job_id`，再调 `query_job` 取 `url`。第一次调用会扣点；
余额不足会收到 `insufficient_credits`。

### 想看视频：这一句按秒扣点

> 用 ownta 的 generate_video 生成一段 5 秒、16:9、720P 的视频：热带雨林里蓝顶亚马逊鹦鹉
> 缓慢推近，拿 job_id 轮询到成片，把 URL 给我。

`generate_video` 立即回 `job_id`，视频通常 1~5 分钟（H3 约 3 分钟）：隔 20~30 秒
`query_job` 一次，不要在一次调用里等。默认 720P/5s/16:9 是最便宜的一档（H3 18 点/秒，
约 90 点）；1080P 28 点/秒；4K 110 点/秒且最长 8 秒；16~30 秒会切到长视频档（更贵）。
首帧参考图只收 https 直链或 base64，`http://` 会被上游拒收。真实扣点以 `query_job` 的
`credits_charged` 为准，失败会退。余额可以先用 `get_wallet` 免费查。

### 想看「题材 × 风格」能拼成什么：这一句零扣点

> 先从 ownta 的百科里找「蓝顶亚马逊鹦鹉」，再找一条「3D 渲染」风格，用 compose_prompt
> 拼成提示词，把 prompt_zh 原样给我，先别出图。

预期三步：`browse_library(domain="nature")` 与 `browse_library(domain="style", sub="form")`
各取一条 `path` → `compose_prompt(subject=…, style=…)` → 回 `prompt_zh` / `prompt_en` /
`negative` / `blocks`。`blocks` 固定三段（`subject` / `form` / `constraints`），
**`constraints` 在最后** —— 工艺红线不能被风格覆盖。

拿到 `prompt_zh` 后再原样交给 `generate_image(prompt=…)`，这时才扣点。
`negative` 只作参考：`generate_image` 没有负向词入参，别拼进 prompt 正文（会稀释主体）。

**不要自己拼**：块序、工艺约束与负向词方向都由组合层决定，自己拼漏掉不报错，
只表现为「图不对但说不上为什么」，成本回到每次重生成的点数上。

## 工具

| 工具 | scope | 计费 | 说明 |
|---|---|---|---|
| `generate_image` | `img.gen` | 按计价表扣点 | 提交出图（异步，立即回 `job_id`）；支持参考图、透明底、DTF/DTG |
| `generate_video` | `vid.gen` | 按秒扣点（720P 18 点/秒、1080P 28、4K 110） | 提交出视频（异步，立即回 `job_id`）；默认 720P/5s/16:9，4K ≤8s，首帧可传 https/base64 |
| `generate_brazil_pattern` | `img.gen` | 按计价表扣点 | 巴西 T 恤印花一步提交（10 款技能，透明底 DTF） |
| `query_job` | — | 免费 | 轮询任务状态与成品 URL，可反复调（图片与视频共用） |
| `get_wallet` | — | 免费 | 查这把 Key 所属账户的余额（1 点 = 1 美分） |
| `list_skills` | — | 免费 | 平台模板 + 你自己的「我的技能」 |
| `get_skill` | — | 免费 | 取单个技能的提示词全文与图位清单 |
| `apply_op` | `img.ops` | 按档 0~16 点（明细见下） | 13 档图像处理；`compress` 兼做等比下采（**没有 `resize`**） |
| `browse_library` | — | 免费 | 百科知识库目录与检索（10 个域，含 nature 题材 / style 风格层） |
| `read_library_entry` | — | 免费 | 读百科正文或 references/ 附件，支持分段续读 |
| `compose_prompt` | — | 免费 | 把 1 条 nature 题材 + 1 条 style 造型（+ 可选配色）拼成成品提示词 |

`apply_op` 的 13 档按点数分四组（价目真值在网关 `Price` 表）：

- **0 点**：`compress` / `crop` / `watermark` / `print_text` / `whitebg`
- **2 点**：`matting` / `kit`　　**4 点**：`seamless`　　**5 点**：`upscale`　　**6 点**：`seamless_pro`
- **8 点**：`print_extract`　　**10 点**：`inpaint_swap`　　**16 点**：`outpaint`

`apply_op` 的 `src` 只收本站 CDN 对象（`image/` `uploads/` `processed/` 前缀），
不收外链与 base64；`generate_image` 的参考图反过来只收 data URL / 裸 base64，不收 http URL。

## 错误码

回包 `ok=false` 时按 `code` 分支（原样透传网关的 `detail.reason`）：

| code | 含义 | 怎么办 |
|---|---|---|
| `insufficient_credits` | 余额不足 | 充值，或换一把有余额账号的 Key |
| `scope_forbidden` | 这把 Key 没有该动作的 scope | `apply_op` 需要 `img.ops`，新建一把带它的 Key |
| `rate_limited` | 触发 RPM / 突发 / 日封顶 | 按回包 `retry_after` 退避 |
| `content_blocked` | 内容审核拒了 | 改写提示词 |
| `invalid_request` | 参数或来源不合规 | 按 `message` 改；`src` 必须是本站对象 |

## 已知边界

- 远程端点只支持 streamable-http（无状态），不提供旧 SSE transport 与会话恢复；
  stdio 仍要求客户端能起子进程。
- 一次任务不等待出图/出片；`generate_image` / `generate_video` 返回后必须用 `query_job` 轮询。
- 视频比图片慢得多（H3 常见 1~5 分钟）：轮询间隔建议 20~30 秒，别在一次工具调用里死等。
- stdout 是 JSON-RPC 通道，本包日志只写 stderr；不要用 `print` 调试。

## 从源码安装（开发）

```bash
cd gateway/mcp_server
pip install -e .
```

版本：**0.2.0**（PyPI）。相对 0.1.3 加两只工具：`generate_video`（`vid.gen`，按秒扣点，
默认 720P/5s/16:9，4K ≤8s）与 `get_wallet`（免费查余额），共 11 只。视频技能从这版起
`runnable=true`：`duration_sec` / `aspect_ratio` 留空时按技能标注提交；套图（batch）仍只能
在前端跑。之前 9 只工具的签名与回包未变；远程 `/mcp` 与本包同步。

0.1.3 只改文案：`compose_prompt` 的 `hint` 原本把 `negative` 说成「单独作负向词」，但
`generate_image` 没有负向词入参（网关 `GenerateRequest` 也没有这个字段），照做只会去调一个
不存在的参数。现在写成「仅作参考、别拼进正文」，并补了上面那句零扣点示例。

0.1.2 加 `compose_prompt`（当时共 9 只）：把 1 条 `nature` 题材 + 1 条 `style` 造型
（`sub=form`/`print`，可选 1 条 `palette-light` 配色）交给网关组合层，回 `prompt_zh` /
`prompt_en` / `negative` / `blocks`。之前这一步只能让 Agent 自己拼——块序、工艺约束
（红线，必须压最后）与负向词方向都会漏，而漏掉那次不报错，只表现为「图不对但说不上为什么」。
0.1.1 的 8 只工具签名与回包未变。
