sorftime-mcp 0.1.0__tar.gz

sorftime_mcp-0.1.0/.env.example

@@ -0,0 +1,10 @@
+# Sorftime Account-SK. Do not commit a real key.
+SORFTIME_API_KEY=
+
+# Optional runtime settings.
+SORFTIME_API_BASE_URL=https://standardapi.sorftime.com/api
+SORFTIME_API_TIMEOUT_SECONDS=120
+SORFTIME_API_MAX_RETRIES=3
+SORFTIME_API_RETRY_BASE_DELAY_SECONDS=2
+SORFTIME_API_RETRY_MAX_DELAY_SECONDS=15
+SORFTIME_AUDIT_LOG_PATH=

sorftime_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.venv/
+__pycache__/
+.pytest_cache/
+*.pyc
+dist/
+build/
+*.egg-info/
+logs/
+

sorftime_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: sorftime-mcp
+Version: 0.1.0
+Summary: Stdio MCP server for read-only Sorftime Enterprise API access.
+Project-URL: Repository, https://github.com/ccchenhuohuo/sorftime-mcp
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.8
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic>=2.10.6
+Description-Content-Type: text/markdown
+
+# Sorftime MCP
+
+把 Sorftime Enterprise API 封装成 Codex、Claude Code 等 AI Agent 可直接调用的 MCP 服务。
+
+本项目默认使用 `stdio` 模式，本地安装后只需要配置 `SORFTIME_API_KEY`。Sorftime Account-SK 保存在使用者自己的 MCP 客户端配置或服务器环境变量中，不写入代码仓库。
+
+## 重点
+
+- 默认传输：`stdio`
+- 本地必需环境变量：`SORFTIME_API_KEY`
+- 公开 MCP 工具数：10 个
+- 支持安全取数方法：32 个
+- 默认站点：`domain=1`，即美国站
+- 返回统一结构：`endpoint`、`domain`、`estimatedRequestCost`、`requestConsumed`、`requestLeft`、`code`、`message`、`data`、`rawResponse`
+- 默认排除账户修改、订阅管理、监控任务管理类接口
+
+## 安装方式
+
+### npm 安装
+
+Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "npx"
+args = ["-y", "sorftime-mcp"]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+Claude Code 安装：
+
+```bash
+claude mcp add --scope user \
+  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
+  sorftime -- npx -y sorftime-mcp
+```
+
+### PyPI 安装
+
+Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "uvx"
+args = ["sorftime-mcp"]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+Claude Code 安装：
+
+```bash
+claude mcp add --scope user \
+  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
+  sorftime -- uvx sorftime-mcp
+```
+
+### GitHub 源码安装
+
+```bash
+uvx --from git+https://github.com/ccchenhuohuo/sorftime-mcp.git sorftime-mcp
+```
+
+对应 Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "uvx"
+args = [
+  "--from",
+  "git+https://github.com/ccchenhuohuo/sorftime-mcp.git",
+  "sorftime-mcp"
+]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+## 工具列表
+
+| 工具 | 用途 |
+| --- | --- |
+| `sorftime_methods` | 查看支持的方法、分类、消耗、是否异步、是否有快捷工具 |
+| `sorftime_method_schema` | 查看单个方法的参数、示例、站点映射和消耗说明 |
+| `sorftime_call` | 白名单路由工具，用于调用低频安全取数方法 |
+| `product_request` | 产品详情，对应 `ProductRequest` |
+| `category_request` | 类目 Top 100，对应 `CategoryRequest` |
+| `keyword_request` | 关键词详情，对应 `KeywordRequest` |
+| `product_query` | 产品搜索，对应 `ProductQuery` |
+| `category_trend` | 类目趋势，对应 `CategoryTrend` |
+| `request_stream_month` | Request 使用和余额，对应 `RequestStreamMonth` |
+| `coin_query` | 积分余额，对应 `CoinQuery` |
+
+高频场景优先使用快捷工具。低频场景使用 `sorftime_call`，先用 `sorftime_methods` 和 `sorftime_method_schema` 查询 method 和参数。
+
+## 调用示例
+
+查询产品详情：
+
+```json
+{
+  "input": {
+    "asin": "B0CVM8TXHP",
+    "domain": 1,
+    "trend": 1
+  }
+}
+```
+
+通过路由查询销量估算：
+
+```json
+{
+  "input": {
+    "method": "AsinSalesVolume",
+    "domain": 1,
+    "params": {
+      "ASIN": "B0CVM8TXHP",
+      "Page": 1
+    }
+  }
+}
+```
+
+查看某个方法的参数：
+
+```json
+{
+  "input": {
+    "method": "ProductRequest"
+  }
+}
+```
+
+## 站点映射
+
+| domain | 站点 |
+| --- | --- |
+| 1 | US 美国 |
+| 2 | GB 英国 |
+| 3 | DE 德国 |
+| 4 | FR 法国 |
+| 5 | IN 印度 |
+| 6 | CA 加拿大 |
+| 7 | JP 日本 |
+| 8 | ES 西班牙 |
+| 9 | IT 意大利 |
+| 10 | MX 墨西哥 |
+| 11 | AE 阿联酋 |
+| 12 | AU 澳大利亚 |
+| 13 | BR 巴西 |
+| 14 | SA 沙特阿拉伯 |
+
+IN、AE、AU、BR、SA 不支持历史数据回填。
+
+## 返回结构
+
+所有真实 Sorftime 请求都返回统一结构：
+
+```json
+{
+  "endpoint": "ProductRequest",
+  "domain": 1,
+  "estimatedRequestCost": 1,
+  "requestConsumed": 1,
+  "requestLeft": 1200,
+  "code": 0,
+  "message": null,
+  "data": {},
+  "rawResponse": {}
+}
+```
+
+Agent 应优先读取 `code`、`message`、`data`、`requestConsumed` 和 `requestLeft`。
+
+## 安全边界
+
+v1 只开放安全取数接口，默认不开放：
+
+- 收藏词新增、修改、删除等账户状态变更接口
+- 关键词监控、榜单监控、跟卖库存监控、ASIN 订阅等订阅管理接口
+- 消耗监控点数或订阅点数、但不属于通用取数的接口
+
+## 审计日志
+
+默认不向标准输出写日志，避免污染 MCP stdio 协议。需要审计记录时，通过环境变量写入本地 JSONL 文件：
+
+```bash
+SORFTIME_AUDIT_LOG_PATH=logs/sorftime-mcp-audit.jsonl
+```
+
+审计日志会记录 endpoint、domain、参数摘要、估算消耗、实际消耗、剩余 Request、耗时和 Sorftime 返回码。日志不会记录 Sorftime Account-SK。
+
+## 仓库
+
+```text
+https://github.com/ccchenhuohuo/sorftime-mcp
+```

sorftime_mcp-0.1.0/README.md

@@ -0,0 +1,201 @@
+# Sorftime MCP
+
+把 Sorftime Enterprise API 封装成 Codex、Claude Code 等 AI Agent 可直接调用的 MCP 服务。
+
+本项目默认使用 `stdio` 模式，本地安装后只需要配置 `SORFTIME_API_KEY`。Sorftime Account-SK 保存在使用者自己的 MCP 客户端配置或服务器环境变量中，不写入代码仓库。
+
+## 重点
+
+- 默认传输：`stdio`
+- 本地必需环境变量：`SORFTIME_API_KEY`
+- 公开 MCP 工具数：10 个
+- 支持安全取数方法：32 个
+- 默认站点：`domain=1`，即美国站
+- 返回统一结构：`endpoint`、`domain`、`estimatedRequestCost`、`requestConsumed`、`requestLeft`、`code`、`message`、`data`、`rawResponse`
+- 默认排除账户修改、订阅管理、监控任务管理类接口
+
+## 安装方式
+
+### npm 安装
+
+Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "npx"
+args = ["-y", "sorftime-mcp"]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+Claude Code 安装：
+
+```bash
+claude mcp add --scope user \
+  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
+  sorftime -- npx -y sorftime-mcp
+```
+
+### PyPI 安装
+
+Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "uvx"
+args = ["sorftime-mcp"]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+Claude Code 安装：
+
+```bash
+claude mcp add --scope user \
+  -e SORFTIME_API_KEY="你的 Sorftime Account-SK" \
+  sorftime -- uvx sorftime-mcp
+```
+
+### GitHub 源码安装
+
+```bash
+uvx --from git+https://github.com/ccchenhuohuo/sorftime-mcp.git sorftime-mcp
+```
+
+对应 Codex 配置：
+
+```toml
+[mcp_servers.sorftime]
+command = "uvx"
+args = [
+  "--from",
+  "git+https://github.com/ccchenhuohuo/sorftime-mcp.git",
+  "sorftime-mcp"
+]
+
+[mcp_servers.sorftime.env]
+SORFTIME_API_KEY = "你的 Sorftime Account-SK"
+```
+
+## 工具列表
+
+| 工具 | 用途 |
+| --- | --- |
+| `sorftime_methods` | 查看支持的方法、分类、消耗、是否异步、是否有快捷工具 |
+| `sorftime_method_schema` | 查看单个方法的参数、示例、站点映射和消耗说明 |
+| `sorftime_call` | 白名单路由工具，用于调用低频安全取数方法 |
+| `product_request` | 产品详情，对应 `ProductRequest` |
+| `category_request` | 类目 Top 100，对应 `CategoryRequest` |
+| `keyword_request` | 关键词详情，对应 `KeywordRequest` |
+| `product_query` | 产品搜索，对应 `ProductQuery` |
+| `category_trend` | 类目趋势，对应 `CategoryTrend` |
+| `request_stream_month` | Request 使用和余额，对应 `RequestStreamMonth` |
+| `coin_query` | 积分余额，对应 `CoinQuery` |
+
+高频场景优先使用快捷工具。低频场景使用 `sorftime_call`，先用 `sorftime_methods` 和 `sorftime_method_schema` 查询 method 和参数。
+
+## 调用示例
+
+查询产品详情：
+
+```json
+{
+  "input": {
+    "asin": "B0CVM8TXHP",
+    "domain": 1,
+    "trend": 1
+  }
+}
+```
+
+通过路由查询销量估算：
+
+```json
+{
+  "input": {
+    "method": "AsinSalesVolume",
+    "domain": 1,
+    "params": {
+      "ASIN": "B0CVM8TXHP",
+      "Page": 1
+    }
+  }
+}
+```
+
+查看某个方法的参数：
+
+```json
+{
+  "input": {
+    "method": "ProductRequest"
+  }
+}
+```
+
+## 站点映射
+
+| domain | 站点 |
+| --- | --- |
+| 1 | US 美国 |
+| 2 | GB 英国 |
+| 3 | DE 德国 |
+| 4 | FR 法国 |
+| 5 | IN 印度 |
+| 6 | CA 加拿大 |
+| 7 | JP 日本 |
+| 8 | ES 西班牙 |
+| 9 | IT 意大利 |
+| 10 | MX 墨西哥 |
+| 11 | AE 阿联酋 |
+| 12 | AU 澳大利亚 |
+| 13 | BR 巴西 |
+| 14 | SA 沙特阿拉伯 |
+
+IN、AE、AU、BR、SA 不支持历史数据回填。
+
+## 返回结构
+
+所有真实 Sorftime 请求都返回统一结构：
+
+```json
+{
+  "endpoint": "ProductRequest",
+  "domain": 1,
+  "estimatedRequestCost": 1,
+  "requestConsumed": 1,
+  "requestLeft": 1200,
+  "code": 0,
+  "message": null,
+  "data": {},
+  "rawResponse": {}
+}
+```
+
+Agent 应优先读取 `code`、`message`、`data`、`requestConsumed` 和 `requestLeft`。
+
+## 安全边界
+
+v1 只开放安全取数接口，默认不开放：
+
+- 收藏词新增、修改、删除等账户状态变更接口
+- 关键词监控、榜单监控、跟卖库存监控、ASIN 订阅等订阅管理接口
+- 消耗监控点数或订阅点数、但不属于通用取数的接口
+
+## 审计日志
+
+默认不向标准输出写日志，避免污染 MCP stdio 协议。需要审计记录时，通过环境变量写入本地 JSONL 文件：
+
+```bash
+SORFTIME_AUDIT_LOG_PATH=logs/sorftime-mcp-audit.jsonl
+```
+
+审计日志会记录 endpoint、domain、参数摘要、估算消耗、实际消耗、剩余 Request、耗时和 Sorftime 返回码。日志不会记录 Sorftime Account-SK。
+
+## 仓库
+
+```text
+https://github.com/ccchenhuohuo/sorftime-mcp
+```

sorftime_mcp-0.1.0/bin/sorftime-mcp.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+
+const userArgs = process.argv.slice(2);
+const pythonArgs = userArgs.length === 0 ? ["stdio"] : userArgs;
+const child = spawn(
+  "uvx",
+  ["--from", "sorftime-mcp", "sorftime-mcp", ...pythonArgs],
+  {
+    env: process.env,
+    stdio: "inherit"
+  }
+);
+
+child.on("error", (error) => {
+  if (error.code === "ENOENT") {
+    console.error("未找到 uvx。请先安装 uv：https://docs.astral.sh/uv/getting-started/installation/");
+    process.exit(127);
+  }
+  console.error(`启动 sorftime-mcp 失败：${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

sorftime_mcp-0.1.0/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "sorftime-mcp",
+  "version": "0.1.0",
+  "description": "Sorftime API MCP stdio launcher for Codex and Claude Code.",
+  "bin": {
+    "sorftime-mcp": "bin/sorftime-mcp.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ccchenhuohuo/sorftime-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "sorftime",
+    "codex",
+    "claude-code"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --check bin/sorftime-mcp.js"
+  }
+}

sorftime_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "sorftime-mcp"
+version = "0.1.0"
+description = "Stdio MCP server for read-only Sorftime Enterprise API access."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1.8",
+    "fastmcp==3.4.2",
+    "httpx>=0.27.2",
+    "pydantic>=2.10.6",
+    "pydantic-settings>=2.8.1",
+]
+
+[project.scripts]
+sorftime-mcp = "sorftime_mcp.cli:cli"
+
+[project.urls]
+Repository = "https://github.com/ccchenhuohuo/sorftime-mcp"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.25.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sorftime_mcp-0.1.0/src/sorftime_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Sorftime MCP server package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

sorftime_mcp-0.1.0/src/sorftime_mcp/__main__.py

@@ -0,0 +1,6 @@
+from sorftime_mcp.cli import cli
+
+
+if __name__ == "__main__":
+    cli()
+

sorftime_mcp-0.1.0/src/sorftime_mcp/audit.py

@@ -0,0 +1,56 @@
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SENSITIVE_KEY_PARTS = ("authorization", "token", "secret", "password", "api_key", "sk")
+LONG_VALUE_KEYS = ("image",)
+
+
+class AuditLogger:
+    def __init__(self, path: Path | None = None, *, emit_stdout: bool = True) -> None:
+        self._path = path
+        self._emit_stdout = emit_stdout
+        if self._path is not None:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(self, record: dict[str, Any]) -> None:
+        line = json.dumps(record, ensure_ascii=False, separators=(",", ":"))
+        if self._emit_stdout:
+            sys.stdout.write(f"{line}\n")
+            sys.stdout.flush()
+        if self._path is not None:
+            with self._path.open("a", encoding="utf-8") as file:
+                file.write(f"{line}\n")
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def sanitize_for_audit(value: Any) -> Any:
+    if isinstance(value, dict):
+        sanitized: dict[str, Any] = {}
+        for key, item in value.items():
+            lower_key = str(key).lower()
+            if any(part in lower_key for part in SENSITIVE_KEY_PARTS):
+                sanitized[key] = "[REDACTED]"
+            elif any(part in lower_key for part in LONG_VALUE_KEYS):
+                sanitized[key] = summarize_long_value(item)
+            else:
+                sanitized[key] = sanitize_for_audit(item)
+        return sanitized
+    if isinstance(value, list):
+        return [sanitize_for_audit(item) for item in value]
+    if isinstance(value, str):
+        return summarize_long_value(value)
+    return value
+
+
+def summarize_long_value(value: Any) -> Any:
+    if not isinstance(value, str):
+        return sanitize_for_audit(value)
+    if len(value) <= 180:
+        return value
+    return f"{value[:80]}...[truncated:{len(value)}]"