openboost-cli 0.1.0__py3-none-any.whl

proboost_cli/coerce_args.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def coerce_argument_value(raw: str, prop_schema: dict[str, Any] | None = None) -> Any:
+    s = raw.strip()
+    schema_type = prop_schema.get("type") if prop_schema else None
+
+    if schema_type == "integer":
+        return int(s, 10)
+    if schema_type == "number":
+        return float(s)
+    if schema_type == "boolean":
+        lowered = s.lower()
+        if lowered in {"true", "1", "yes", "y"}:
+            return True
+        if lowered in {"false", "0", "no", "n"}:
+            return False
+        raise ValueError(f"Invalid boolean value: {raw!r}")
+    if schema_type == "array":
+        if not s:
+            return []
+        if s.startswith("["):
+            decoded = json.loads(s)
+            if not isinstance(decoded, list):
+                raise ValueError(f"Expected JSON array: {raw!r}")
+            return decoded
+        return [part.strip() for part in s.split(",") if part.strip()]
+    if schema_type == "string":
+        return raw
+
+    if s.lower() == "null":
+        return None
+    if s.lower() in {"true", "false"}:
+        return s.lower() == "true"
+    try:
+        return int(s, 10)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        return raw
+
+
+def merge_tool_arguments_json(
+    base: dict[str, Any],
+    sets: tuple[str, ...] | list[str],
+    *,
+    props: dict[str, Any],
+) -> dict[str, Any]:
+    out = dict(base)
+    for item in sets:
+        if "=" not in item:
+            raise ValueError(f"Invalid argument (expected key=value): {item!r}")
+        key, value = item.split("=", 1)
+        key = key.strip()
+        schema = props.get(key) if isinstance(props.get(key), dict) else {}
+        out[key] = coerce_argument_value(value, schema if isinstance(schema, dict) else None)
+    return out

proboost_cli/config.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from proboost_cli import DEFAULT_BASE_URLS, MCP_NAMES
+
+
+def config_path() -> Path:
+    env = os.environ.get("PROBOOST_CONFIG", "").strip()
+    if env:
+        return Path(env).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    if xdg:
+        return Path(xdg) / "proboost" / "config.json"
+    return Path.home() / ".config" / "proboost" / "config.json"
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.is_file():
+        return {}
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        return {}
+    return json.loads(text)
+
+
+def save_config(data: dict[str, Any]) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def normalize_mcp_name(name: str) -> str:
+    mcp = name.strip().lower()
+    if mcp not in MCP_NAMES:
+        raise ValueError(f"Unknown MCP: {name}")
+    return mcp
+
+
+def _env_prefix(mcp: str) -> str:
+    return f"PROBOOST_{mcp.upper()}"
+
+
+def effective_secret_and_base(
+    mcp: str,
+    *,
+    secret_key: str | None = None,
+    base_url: str | None = None,
+) -> tuple[str, str]:
+    mcp = normalize_mcp_name(mcp)
+    cfg = load_config()
+    mcp_cfg = cfg.get("mcps", {}).get(mcp, {}) if isinstance(cfg.get("mcps"), dict) else {}
+    if not isinstance(mcp_cfg, dict):
+        mcp_cfg = {}
+
+    prefix = _env_prefix(mcp)
+    secret = (
+        secret_key
+        or os.environ.get(f"{prefix}_SECRET_KEY", "").strip()
+        or os.environ.get("PROBOOST_SECRET_KEY", "").strip()
+        or str(mcp_cfg.get("secret_key", "")).strip()
+        or str(cfg.get("secret_key", "")).strip()
+    )
+    base = (
+        base_url
+        or os.environ.get(f"{prefix}_BASE_URL", "").strip()
+        or str(mcp_cfg.get("base_url", "")).strip()
+        or DEFAULT_BASE_URLS[mcp]
+    ).rstrip("/")
+    return secret, base
+
+
+def update_config(
+    *,
+    mcp: str | None = None,
+    secret_key: str | None = None,
+    base_url: str | None = None,
+) -> dict[str, Any]:
+    data = load_config()
+    if mcp:
+        mcp = normalize_mcp_name(mcp)
+        data.setdefault("mcps", {})
+        if not isinstance(data["mcps"], dict):
+            data["mcps"] = {}
+        data["mcps"].setdefault(mcp, {})
+        if secret_key is not None:
+            data["mcps"][mcp]["secret_key"] = secret_key.strip()
+        if base_url is not None:
+            data["mcps"][mcp]["base_url"] = base_url.strip().rstrip("/")
+    else:
+        if secret_key is not None:
+            data["secret_key"] = secret_key.strip()
+        if base_url is not None:
+            data["base_url"] = base_url.strip().rstrip("/")
+    save_config(data)
+    return data
+
+
+def mask_secret(secret: str) -> str:
+    secret = secret.strip()
+    if not secret:
+        return "(empty)"
+    if len(secret) <= 8:
+        return "*" * len(secret)
+    return "*" * (len(secret) - 4) + secret[-4:]

proboost_cli/mcp_client.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import timedelta
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp import types as mtypes
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import create_mcp_http_client
+
+from proboost_cli.config import effective_secret_and_base, normalize_mcp_name
+from proboost_cli.parse_result import decode_embedded_payload
+from proboost_cli.schemas_loader import load_tool_definitions
+
+
+def extract_result_text(result: mtypes.CallToolResult) -> str:
+    chunks: list[str] = []
+    for block in result.content:
+        if isinstance(block, mtypes.TextContent):
+            chunks.append(block.text)
+    return "\n".join(chunks)
+
+
+async def invoke_tool_async(
+    base_url: str,
+    secret_key: str,
+    tool_name: str,
+    arguments: dict[str, Any],
+    *,
+    connect_timeout_sec: float = 30,
+    read_timeout_sec: float = 300,
+) -> mtypes.CallToolResult:
+    headers = {"secret-key": secret_key}
+    timeout = httpx.Timeout(connect_timeout_sec, read=read_timeout_sec, write=30, pool=30)
+
+    async with create_mcp_http_client(headers=headers, timeout=timeout) as client:
+        async with streamable_http_client(base_url, http_client=client) as (read, write, _get_id):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                return await session.call_tool(
+                    tool_name,
+                    arguments,
+                    read_timeout_seconds=timedelta(seconds=read_timeout_sec),
+                )
+
+
+class McpClient:
+    """Dynamic Python client for one Proboost MCP server."""
+
+    def __init__(
+        self,
+        mcp: str,
+        *,
+        secret_key: str | None = None,
+        base_url: str | None = None,
+        connect_timeout_sec: float = 30,
+        read_timeout_sec: float = 300,
+    ) -> None:
+        self.mcp = normalize_mcp_name(mcp)
+        resolved_secret, resolved_base = effective_secret_and_base(
+            self.mcp,
+            secret_key=secret_key,
+            base_url=base_url,
+        )
+        if not resolved_secret:
+            raise ValueError(
+                f"缺少 {self.mcp} secret-key。请设置 PROBOOST_SECRET_KEY 或 PROBOOST_{self.mcp.upper()}_SECRET_KEY。"
+            )
+        self.secret_key = resolved_secret
+        self.base_url = resolved_base
+        self.connect_timeout_sec = connect_timeout_sec
+        self.read_timeout_sec = read_timeout_sec
+        self._tools = load_tool_definitions(self.mcp)
+
+    async def call_tool_async(self, tool_name: str, arguments: dict[str, Any] | None = None) -> Any:
+        if tool_name not in self._tools:
+            raise ValueError(f"未知工具: {self.mcp}.{tool_name}")
+        result = await invoke_tool_async(
+            self.base_url,
+            self.secret_key,
+            tool_name,
+            dict(arguments or {}),
+            connect_timeout_sec=self.connect_timeout_sec,
+            read_timeout_sec=self.read_timeout_sec,
+        )
+        if result.isError:
+            text = extract_result_text(result)
+            raise RuntimeError(text or f"{self.mcp}.{tool_name} returned an MCP error")
+
+        structured = getattr(result, "structuredContent", None)
+        if isinstance(structured, (dict, list)):
+            return structured
+
+        text = extract_result_text(result)
+        try:
+            return decode_embedded_payload(text)
+        except ValueError:
+            return text
+
+    def call_tool(self, tool_name: str, arguments: dict[str, Any] | None = None) -> Any:
+        return asyncio.run(self.call_tool_async(tool_name, arguments))
+
+    def __getattr__(self, name: str):
+        if name in self._tools:
+            def method(**kwargs: Any) -> Any:
+                return self.call_tool(name, kwargs)
+
+            method.__name__ = name
+            method.__doc__ = str(self._tools[name].get("description", ""))
+            return method
+        raise AttributeError(name)

proboost_cli/parse_result.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*([\s\S]*?)```", re.IGNORECASE)
+_MARKER = "响应数据（JSON）"
+
+
+def _last_longest_json_value(text: str) -> tuple[Any | None, int]:
+    decoder = json.JSONDecoder()
+    best: Any | None = None
+    best_len = -1
+    for idx, ch in enumerate(text):
+        if ch not in "{[":
+            continue
+        try:
+            obj, end_idx = decoder.raw_decode(text[idx:])
+        except json.JSONDecodeError:
+            continue
+        if end_idx >= best_len:
+            best = obj
+            best_len = end_idx
+    return best, best_len
+
+
+def decode_embedded_payload(text: str) -> Any:
+    stripped = text.strip()
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError:
+        pass
+
+    marker_idx = text.find(_MARKER)
+    if marker_idx >= 0:
+        tail = text[marker_idx + len(_MARKER) :].lstrip("\n:")
+        try:
+            return decode_embedded_payload(tail)
+        except ValueError:
+            pass
+
+    for match in _JSON_FENCE_RE.finditer(text):
+        block = match.group(1).strip()
+        try:
+            return json.loads(block)
+        except json.JSONDecodeError:
+            continue
+
+    best, length = _last_longest_json_value(text)
+    if best is None or length < 2:
+        raise ValueError("No JSON object found in tool output")
+    return best

proboost_cli/registry.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from proboost_cli import MCP_LABELS, MCP_NAMES
+from proboost_cli.schemas_loader import load_tool_definitions, tool_schema_required
+
+
+@dataclass(frozen=True)
+class ToolMeta:
+    name: str
+    mcp: str
+    domain: str
+    label: str
+    required: list[str]
+    paginated: bool = False
+
+
+DOMAIN_LABELS: dict[str, dict[str, str]] = {
+    "tiktok": {
+        "statistics": "大盘统计",
+        "commodity": "商品选品",
+        "expert": "达人分析",
+        "video": "视频分析",
+        "shop": "店铺分析",
+        "other": "其它",
+    },
+    "patent": {
+        "search": "专利检索",
+        "detail": "专利详情",
+        "image": "图像检索",
+        "other": "其它",
+    },
+    "amazon": {
+        "product": "商品与市场",
+        "hot": "榜单",
+        "other": "其它",
+    },
+}
+
+
+def domain_for(mcp: str, tool_name: str) -> str:
+    if mcp == "tiktok":
+        if tool_name.startswith("tt_commodity_statistics_"):
+            return "statistics"
+        if tool_name.startswith(("tt_commodity_", "tt_sale_channel_")):
+            return "commodity"
+        if tool_name.startswith(("tt_expert_", "tk_expert_")):
+            return "expert"
+        if tool_name.startswith("tt_video_"):
+            return "video"
+        if tool_name.startswith("tt_shop_"):
+            return "shop"
+        return "other"
+    if mcp == "patent":
+        if "search" in tool_name or tool_name == "patent_query_count":
+            return "search"
+        if "image_search" in tool_name:
+            return "image"
+        return "detail"
+    if mcp == "amazon":
+        if tool_name.startswith("amz_hot_"):
+            return "hot"
+        return "product"
+    return "other"
+
+
+def _label_from_description(description: str, fallback: str) -> str:
+    desc = " ".join(description.split())
+    if not desc:
+        return fallback
+    for sep in ("：", "；", ";", "。", "."):
+        if sep in desc:
+            desc = desc.split(sep, 1)[0]
+            break
+    return desc[:50]
+
+
+def _is_paginated(tool: dict) -> bool:
+    props = tool.get("arguments", {}).get("properties", {})
+    if not isinstance(props, dict):
+        return False
+    return any(key in props for key in ("current", "size", "limit", "offset", "pages", "pagesSize", "currentPage", "pageSize"))
+
+
+def build_tools() -> dict[str, dict[str, ToolMeta]]:
+    out: dict[str, dict[str, ToolMeta]] = {}
+    for mcp in MCP_NAMES:
+        out[mcp] = {}
+        for name, tool in load_tool_definitions(mcp).items():
+            out[mcp][name] = ToolMeta(
+                name=name,
+                mcp=mcp,
+                domain=domain_for(mcp, name),
+                label=_label_from_description(str(tool.get("description", "")), name),
+                required=tool_schema_required(tool),
+                paginated=_is_paginated(tool),
+            )
+    return out
+
+
+TOOLS: dict[str, dict[str, ToolMeta]] = build_tools()
+
+DOMAIN_TOOLS: dict[str, dict[str, list[str]]] = {}
+for _mcp in MCP_NAMES:
+    DOMAIN_TOOLS[_mcp] = {}
+    for _name, _meta in sorted(TOOLS[_mcp].items()):
+        DOMAIN_TOOLS[_mcp].setdefault(_meta.domain, []).append(_name)
+
+
+def mcp_title(mcp: str) -> str:
+    return MCP_LABELS.get(mcp, mcp)

proboost_cli/schemas/__init__.py

@@ -0,0 +1 @@
+"""Bundled MCP tool schemas for Proboost servers."""

proboost_cli/schemas/amazon/__init__.py

@@ -0,0 +1 @@
+"""Amazon MCP tool manifests."""

proboost_cli/schemas/amazon/amz_category_query.json

@@ -0,0 +1,20 @@
+{
+  "name": "amz_category_query",
+  "description": "按分区日期与类目 ID 查询 AMZ 类目信息（层级、父子、路径等，Hologres big_prd / api_holo）；可选 webSiteId 限定站点",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "catId": {
+        "description": "类目 ID",
+        "type": "string"
+      },
+      "webSiteId": {
+        "description": "站点 ID，可选；为空则查所有站点",
+        "type": "string"
+      }
+    },
+    "required": [
+      "catId"
+    ]
+  }
+}

proboost_cli/schemas/amazon/amz_hot_amz_hot_cat_tree.json

@@ -0,0 +1,25 @@
+{
+  "name": "amz_hot_amz_hot_cat_tree",
+  "description": "AMZ 榜单可用商品类目树（多棵顶层树），与 `amzHotList` 等联用做类目筛选。",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "keyword": {
+        "description": "英文类目名，精确匹配；有值时返回包含该节点及父级的子树",
+        "type": "string"
+      },
+      "rankType": {
+        "description": "榜单类型（如 Best Seller、New Releases、Movers Shakers）",
+        "type": "string"
+      },
+      "webSiteId": {
+        "description": "站点 ID",
+        "type": "string"
+      }
+    },
+    "required": [
+      "rankType",
+      "webSiteId"
+    ]
+  }
+}

proboost_cli/schemas/amazon/amz_hot_amz_hot_list.json

@@ -0,0 +1,33 @@
+{
+  "name": "amz_hot_amz_hot_list",
+  "description": "AMZ 榜单 SKU 分页：类目路径、排名、主图与链接、品牌、近 30 天销量/销售额、售价与币种、销量/价格趋势、是否收藏等。",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "catId": {
+        "description": "类目 ID；可空，空时默认 fashion",
+        "type": "string"
+      },
+      "currentPage": {
+        "description": "当前页，默认 1",
+        "type": "integer"
+      },
+      "pageSize": {
+        "description": "每页条数，默认 10",
+        "type": "integer"
+      },
+      "rankType": {
+        "description": "榜单类型（如 Best Seller、New Releases、Movers Shakers）",
+        "type": "string"
+      },
+      "webSiteId": {
+        "description": "站点 ID",
+        "type": "string"
+      }
+    },
+    "required": [
+      "webSiteId",
+      "rankType"
+    ]
+  }
+}

proboost_cli/schemas/amazon/amz_market_price.json

@@ -0,0 +1,28 @@
+{
+  "name": "amz_market_price",
+  "description": "查询站点内销量 TopN SKU 的价格带分布（区间销量、销售额、SKU 列表及销量占比）；nodeId（cat_id）必填；可选月份 ds 或近30天",
+  "arguments": {
+    "type": "object",
+    "properties": {
+      "ds": {
+        "description": "统计月份，6 位 YYYYMM（如 202603）表示按月历史口径；不传则近 30 天口径",
+        "type": "string"
+      },
+      "nodeId": {
+        "description": "类目节点 ID（必填），对应 cat_id；仅该类目下取 TopN（mi 表既有列，df 表需已新增 cat_id）",
+        "type": "string"
+      },
+      "topN": {
+        "description": "按销量取前 N 个 SKU 再按价格带聚合，默认 10，最大 500",
+        "type": "integer"
+      },
+      "webSiteId": {
+        "description": "站点 ID；不传或空则默认 1（美国）。常用：1=us,2=gb,3=de,4=fr,5=jp,6=ca,8=it,9=es,10=in,11=mx,12=au,13=br,17=pl,21=ae,22=sa,23=eg",
+        "type": "string"
+      }
+    },
+    "required": [
+      "nodeId"
+    ]
+  }
+}