ownta-mcp 0.1.0__tar.gz

ownta_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+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

ownta_mcp-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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

ownta_mcp-0.1.0/__init__.py

@@ -0,0 +1,8 @@
+"""MCP 首刀的服务端包（独立进程，stdio transport）。
+
+边界（new-plans 定案）：
+- **不 import 网关 app**，只经 HTTP 调 `/v1/generate` 与 `/v1/jobs/{id}` —— 鉴权、计费、
+  幂等、内容审核的唯一真源都留在网关，MCP 只是一层协议适配，崩了不拖生成主链。
+- `client.py` / `tools.py` 不依赖 `mcp` SDK（纯 httpx + 纯函数），可在无 SDK 的环境跑单测；
+  只有 `server.py` 需要 `mcp`（`requirements-mcp.txt`），生产镜像不必装。
+"""

ownta_mcp-0.1.0/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m mcp_server` 的入口：等价于 console script `ownta-mcp`。"""
+from mcp_server.server import main
+
+if __name__ == "__main__":
+    main()

ownta_mcp-0.1.0/client.py

@@ -0,0 +1,202 @@
+"""MCP → 网关的 HTTP 客户端（唯一耦合面）。
+
+为什么不是「import main 再调函数」：MCP 是**另一个进程**（new-plans 定案），复用网关的
+`require_auth`（JWT 与 sk-ownta- 平台 Key 同一套）、计费与 Idempotency-Key 语义，最省事
+且不产生第二份真源的方式就是走 HTTP。
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://ai.ownta.ai"
+
+# 网关自己的 detail.reason 优先；没带 reason 的旧路径按状态码兜底成同一套机器码，
+# 让 Agent 侧只认一组 code（insufficient_credits / rate_limited / …）就够分支。
+_REASON_BY_STATUS = {
+    402: "insufficient_credits",
+    403: "scope_forbidden",
+    422: "invalid_request",
+    429: "rate_limited",
+    451: "content_blocked",
+}
+
+
+class GatewayError(RuntimeError):
+    """一次失败的网关调用。`code` 给 Agent 分支，`message` 给人看。"""
+
+    def __init__(self, status: int, code: str, message: str,
+                 retry_after: int | None = None):
+        super().__init__(f"[{status} {code}] {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.retry_after = retry_after
+
+    def as_dict(self) -> dict:
+        out = {"ok": False, "status": self.status, "code": self.code, "message": self.message}
+        if self.retry_after is not None:
+            out["retry_after"] = self.retry_after
+        return out
+
+
+def _error_from(res: httpx.Response) -> GatewayError:
+    detail: dict = {}
+    plain = ""                              # FastAPI 的 detail 常是字符串，别再丢进 JSON 文本
+    try:
+        body = res.json()
+    except ValueError:                      # 非 JSON（网关/边缘 5xx 的 HTML 页）
+        body = None
+    if isinstance(body, dict):
+        d = body.get("detail")
+        if isinstance(d, dict):
+            detail = d
+        else:
+            detail = body
+            plain = d if isinstance(d, str) else ""
+    elif isinstance(body, str):
+        plain = body
+    code = str(detail.get("reason") or detail.get("code")
+               or _REASON_BY_STATUS.get(res.status_code, "upstream_error"))
+    msg = str(detail.get("message") or detail.get("error") or plain
+              or (res.text or "").strip()[:300] or res.reason_phrase)
+    ra = res.headers.get("Retry-After") or ""
+    return GatewayError(res.status_code, code, msg, int(ra) if ra.isdigit() else None)
+
+
+class GatewayClient:
+    """一个 Key 一个实例。构造即校验 Key 存在（缺了直接退出，别让工具调用到一半才炸）。"""
+
+    def __init__(self, base_url: str | None = None, api_key: str | None = None,
+                 timeout: float = 60.0, transport: httpx.BaseTransport | None = None):
+        self.base_url = (base_url or os.getenv("OWNTA_GW_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = (api_key if api_key is not None else os.getenv("OWNTA_GW_API_KEY", "")).strip()
+        if not self.api_key:
+            raise SystemExit(
+                "缺少 OWNTA_GW_API_KEY（sk-ownta-…）。请写进 MCP 客户端配置的 env，"
+                "不要写进仓库。"
+            )
+        self._timeout = timeout
+        self._transport = transport            # 单测注入 httpx.MockTransport；生产为 None
+
+    def _send(self, method: str, path: str, *, payload: Any = None,
+              idem: str = "") -> dict:
+        headers = {"Accept": "application/json",
+                   "Authorization": f"Bearer {self.api_key}",
+                   # 来源标记（2026-11-02 百科读数）：读百科的主体有两个 —— 站内的
+                   # 浏览器和跑在 IDE 里的 MCP 客户端，两者都带 Bearer、在鉴权层同形状，
+                   # 只能自带身份才能分开。没有这一行，「858 条有没有人用」永远分不清
+                   # 是自己人在读还是用户在读（评审要的正是可证伪的那一句）。
+                   # 只用于读数归类，不参与任何权限判定 —— 网关不拿它当凭据。
+                   "X-Ownta-Via": "mcp"}
+        if idem:
+            headers["Idempotency-Key"] = idem
+        try:
+            with httpx.Client(timeout=self._timeout, transport=self._transport) as c:
+                res = c.request(method, f"{self.base_url}{path}", json=payload, headers=headers)
+        except httpx.HTTPError as e:
+            # 连不上/超时是「不知道网关收没收到」，不能当业务失败重试 —— 语义交给调用方，
+            # 这里只标记 network_error（status=0），不猜。
+            raise GatewayError(0, "network_error", f"{method} {path} 失败：{e}") from e
+        if res.status_code >= 400:
+            raise _error_from(res)
+        return res.json()
+
+    # ---- 首刀两个端点 ----
+    def generate(self, payload: dict, idem: str = "") -> dict:
+        """POST /v1/generate（202 → {job_id,status,poll,sse}）。"""
+        return self._send("POST", "/v1/generate", payload=payload, idem=idem)
+
+    def job(self, job_id: str) -> dict:
+        """GET /v1/jobs/{id}（JobStatus：status/output_urls/credits_charged/error/…）。"""
+        return self._send("GET", f"/v1/jobs/{job_id}")
+
+    # ---- skills 发现（只读，不需要幂等键） ----
+    def skills(self) -> dict:
+        """GET /v1/skills → {skills:[{id,name,icon,kind,ratio,prompt,batch?,requires?,…}]}。
+
+        该端点在网关是公开的（未登录可查），但这里仍带 Bearer —— 没理由为一次
+        只读调用新开一条无鉴权通道，鉴权层的唯一真源留在网关。
+        """
+        return self._send("GET", "/v1/skills")
+
+    def skills_mine(self) -> dict:
+        """GET /v1/skills/mine → {skills:[…], limit}（只看本人的私有技能）。
+
+        与 `skills()` 的差别在**鉴权面**：那个是平台公开模板，这个由网关按 Key
+        解析 uid 过滤，看不到别人的行。guest Key 会 403 `guest_not_allowed` ——
+        那是「访客不存在私有技能」，不是故障。
+        """
+        return self._send("GET", "/v1/skills/mine")
+
+    # ---- 百科层（2026-10-31 新增）：与 /v1/skills 是两回事 ----
+    def skill_library(self, *, domain: str = "", sub: str = "", q: str = "",
+                      offset: int = 0, limit: int = 30) -> dict:
+        """GET /v1/skill-library → {tree, page, errors[, matched_tree]}。
+
+        别和 `skills()` 混：那边是**出图模板**（kind 只有 image/video，能直接喂
+        generate_image）；这边是**百科知识层**（方法论正文，跑不了图）。两个端点
+        都只读，鉴权口径相同。
+
+        `q` 非空时网关做全字段检索（**含正文**）并多回 `matched_tree`；那个键也是
+        「网关是不是新版」的探针 —— 旧网关会把 q 当未知参数忽略、照回全集第一页，
+        调用方看到缺 `matched_tree` 就该走本地回退。中文必须 quote，否则非法 URL。
+
+        网关侧 `paging.bounds` 会把非法 limit/offset 夹回默认值而不抛 500，所以这里
+        不重复校验上界；`page.has_more` 由网关算，客户端不要自己推。
+        """
+        params = []
+        if domain:
+            params.append(f"domain={quote(domain, safe='')}")
+        if sub:
+            params.append(f"sub={quote(sub, safe='')}")
+        if q:
+            params.append(f"q={quote(str(q), safe='')}")
+        params.append(f"offset={int(offset)}")
+        params.append(f"limit={int(limit)}")
+        return self._send("GET", "/v1/skill-library?" + "&".join(params))
+
+    def skill_library_body(self, *, path: str, file: str = "", offset: int = 0,
+                           limit: int = 20000) -> dict:
+        """GET /v1/skill-library/body → {path, body, offset, total, has_more[, file][, files]}。
+
+        `path` 是 `domain/sub/slug`。越界或格式不符网关回 404（`read_body` 的白名单
+        正则挡 `..` 与绝对路径），不会读到库外文件。拼 URL 前仍要 quote：Agent 传进
+        中文或空格时，不编码得到的是非法 URL，报错信息会指向网关而不是参数。
+
+        `offset` 与 `limit` 都是**字符**数，与回包的 `total` 同口径；`has_more` 是
+        「后面还有」，不是「本次可能被截断」。
+
+        `file` 非空时改读该条目的附件（`references/**` 下的纯文本），同样支持
+        `offset` 续读。**不带 file 时网关会多回 `files` 清单**（有附件才有这个键），
+        那是「正文说的 references/x.md 到底在不在」的唯一可靠依据。
+        """
+        url = (f"/v1/skill-library/body?path={quote(str(path), safe='')}"
+               f"&offset={int(offset)}&limit={int(limit)}")
+        if file:
+            url += f"&file={quote(str(file), safe='')}"
+        return self._send("GET", url)
+
+    def brand_kits(self) -> dict:
+        """GET /v1/brand-kits → {kits:[…], enabled, block_max}（只看本人，永远不公开）。
+
+        只给一处用：技能声明 `requires=["brand_kit"]` 时判断「有没有可注入的默认合同」。
+        注入只认 `is_default`（brand.default_kit），所以这里必须拿整张列表而不是总数。
+        """
+        return self._send("GET", "/v1/brand-kits")
+
+    # ---- 处理档（P1 交付链）：唯一耦合面上的极薄转发 ----
+    def op_apply(self, op: str, src: str, params: dict | None = None) -> dict:
+        """POST /v1/image/ops/apply（201 → {job_id,op,url,key,content_type,ext,size,credits,…}）。
+
+        这里**不做任何校验**：op 白名单、params 规格、源图归属（只认自家 CDN 前缀）
+        全在网关 `imageops.validate` / `own_key`，钱也走网关那条 reserve→settle。
+        转发层多写一行，就多一套会漂移的真值。
+        注意回包的 `size` 是**字节数**，不是像素。
+        """
+        return self._send("POST", "/v1/image/ops/apply",
+                          payload={"op": str(op or ""), "src": str(src or ""),
+                                   "params": params if isinstance(params, dict) else {}})