ownta-mcp

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

安装

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 这一层）：

{
  "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：

{
  "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 是同一套 9 个工具、同一份计价，选哪种只取决于客户端能不能起子进程。

3. 先跑这一句

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

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

工具

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）：

已知边界

• 远程端点只支持 streamable-http（无状态），不提供旧 SSE transport 与会话恢复； stdio 仍要求客户端能起子进程。
• 一次任务不等待出图；generate_image 返回后必须用 query_job 轮询。
• stdout 是 JSON-RPC 通道，本包日志只写 stderr；不要用 print 调试。

从源码安装（开发）

cd gateway/mcp_server
pip install -e .

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