Metadata-Version: 2.4
Name: ownta-mcp
Version: 0.1.0
Summary: OWNTA MCP server (stdio): image generation, image ops, and read-only skill/library tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.9
Requires-Dist: httpx>=0.27

# ownta-mcp

OWNTA 的 MCP 服务端（stdio）：把出图、图像处理、技能与百科只读封装成 Agent 可直接调用的 8 个工具。
不需要克隆本仓库，装好包 + 一把 Key 就能用。

## 安装

```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`。

## 3. 先跑这一句

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

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

## 工具

| 工具 | scope | 计费 | 说明 |
|---|---|---|---|
| `generate_image` | `img.gen` | 按计价表扣点 | 提交出图（异步，立即回 `job_id`）；支持参考图、透明底、DTF/DTG |
| `generate_brazil_pattern` | `img.gen` | 按计价表扣点 | 巴西 T 恤印花一步提交（10 款技能，透明底 DTF） |
| `query_job` | — | 免费 | 轮询任务状态与成品 URL，可反复调 |
| `list_skills` | — | 免费 | 平台模板 + 你自己的「我的技能」 |
| `get_skill` | — | 免费 | 取单个技能的提示词全文与图位清单 |
| `apply_op` | `img.ops` | 按档 0~16 点（明细见下） | 13 档图像处理；`compress` 兼做等比下采（**没有 `resize`**） |
| `browse_library` | — | 免费 | 百科知识库目录与检索（10 个域，含 nature 题材 / style 风格层） |
| `read_library_entry` | — | 免费 | 读百科正文或 references/ 附件，支持分段续读 |

`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` 必须是本站对象 |

## 已知边界

- 只有 stdio，没有远程 HTTP 端点：Agent 必须跑在能起子进程的客户端里。
- 一次任务不等待出图；`generate_image` 返回后必须用 `query_job` 轮询。
- stdout 是 JSON-RPC 通道，本包日志只写 stderr；不要用 `print` 调试。

## 从源码安装（开发）

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

版本：0.1.0
