sorb-mcp 0.1.0__tar.gz

sorb_mcp-0.1.0/.gitignore

@@ -0,0 +1,196 @@
+# ============================================
+# Python
+# ============================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual Environment
+venv/
+ENV/
+env/
+.venv
+.virtualenv
+
+# PyInstaller
+*.spec
+
+# ============================================
+# IDEs & Editors
+# ============================================
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.project
+.classpath
+.settings/
+.claude/
+.worktrees/
+
+# ============================================
+# OS
+# ============================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# ============================================
+# Logs
+# ============================================
+*.log
+logs/
+*.log.*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# ============================================
+# Database
+# ============================================
+*.db
+*.sqlite
+*.sqlite3
+data/
+*.db-journal
+
+# ============================================
+# Media & Uploads
+# ============================================
+static/uploads/
+backend/data/
+backend/media/
+backend/logs/
+
+# ============================================
+# Environment Variables
+# ============================================
+.env
+.env.local
+.env.*.local
+.env.development
+.env.production
+.env.test
+
+# ============================================
+# Docker
+# ============================================
+.dockerignore
+!backend/.dockerignore    # 允许 backend 的 .dockerignore
+docker-compose.override.yml
+docker/backup/
+# 本地备份目录
+docker/data/
+docker/logs/
+docker/media/
+
+# ============================================
+# Redis
+# ============================================
+dump.rdb
+*.rdb
+
+# ============================================
+# Celery
+# ============================================
+celerybeat-schedule
+celerybeat.pid
+celerybeat-schedule.db
+
+# ============================================
+# Test Coverage
+# ============================================
+htmlcov/
+.coverage
+.coverage.*
+.pytest_cache/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+
+# ============================================
+# Node.js / Frontend
+# ============================================
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# ============================================
+# Build Outputs
+# ============================================
+dist/
+dist-ssr/
+build/
+.nuxt/
+.next/
+.cache/
+out/
+*.tsbuildinfo
+
+# ============================================
+# Temporary Files
+# ============================================
+*.tmp
+*.temp
+.temp/
+temp/
+*.bak
+*.backup
+
+# ============================================
+# Documentation (optional)
+# ============================================
+# Uncomment if you don't want to commit these
+# PROJECT_STATUS*.md
+# IMPLEMENTATION_SUMMARY.md
+# FINAL_REPORT.md
+
+# ============================================
+# AI/Editor specific
+# ============================================
+.qoder/
+Default/
+.antigravitycli/
+.serena/

sorb_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: sorb-mcp
+Version: 0.1.0
+Summary: Sorb task tools for external MCP agents
+Project-URL: Homepage, https://sorb.huche.games
+Project-URL: Documentation, https://sorb.huche.games/settings/me/mcp?tab=help
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.13
+Requires-Dist: anyio==4.15.1
+Requires-Dist: httpx==0.28.1
+Requires-Dist: mcp==2.2.0
+Requires-Dist: pydantic==2.13.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio==0.23.3; extra == 'dev'
+Requires-Dist: pytest==7.4.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sorb MCP
+
+Sorb MCP is the local stdio MCP integration for [Sorb](https://sorb.huche.games), a multimodal content generation platform. It connects an external Agent to Sorb's existing projects, models, resources and task APIs using your personal access token (PAT).
+
+The package provides 38 tools for discovery, task creation and estimation, status and output queries, task operations, and bounded local file upload/download. Tasks retain Sorb's existing project permissions, billing, confirmation, idempotency and audit behavior. Canvas operations are outside this package's scope.
+
+Requires **Python 3.13**. A Sorb account and access to a running Sorb server are required. This package does not contain the Sorb backend or any model Provider credentials.
+
+## Install and connect
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/). The MCP client can then launch a pinned version directly from PyPI:
+
+```sh
+uvx --python 3.13 --from sorb-mcp==0.1.0 sorb-mcp
+```
+
+Or install the command in a Python 3.13 environment:
+
+```sh
+python -m pip install sorb-mcp==0.1.0
+```
+
+In Sorb, open **个人中心 → 用户信息 → MCP → 访问令牌** (Personal Center → User Information → MCP → Access Tokens). Create a token with the operations you need. Start with the default read scopes to verify the connection. The token is displayed only once.
+
+For clients using the `mcpServers` configuration format:
+
+```json
+{
+  "mcpServers": {
+    "sorb": {
+      "command": "uvx",
+      "args": ["--python", "3.13", "--from", "sorb-mcp==0.1.0", "sorb-mcp"],
+      "env": {
+        "SORB_BASE_URL": "https://sorb.huche.games",
+        "SORB_PAT": "<your personal access token>"
+      }
+    }
+  }
+}
+```
+
+Use your own Sorb server's root URL, without `/api` or `/api/mcp`. Remote servers must use HTTPS; HTTP is permitted only for loopback development addresses. If the client cannot find `uvx`, set `command` to its actual executable path. Store the PAT in your client's secure configuration, never in chat messages or shared files.
+
+After restarting or refreshing the client, ask the Agent to list your visible projects using `sorb_list_projects`. Successful tool output verifies the connection. Use `sorb_select_project`, `sorb_list_models`, `sorb_get_model_schema` and `sorb_get_task_capabilities` before requesting generation. Query operations do not create Sorb tasks; generation can incur the existing Sorb model fees.
+
+## Local files
+
+Local upload/download requires explicitly configured, existing absolute directories:
+
+```json
+{
+  "SORB_INPUT_DIRS": "/absolute/path/references",
+  "SORB_OUTPUT_DIRS": "/absolute/path/outputs"
+}
+```
+
+Add these keys to the client's `env` only when needed. Multiple directories use the operating system's path separator (`:` on macOS/Linux, `;` on Windows). Client roots may further narrow these directories. Downloads do not overwrite existing files; symlink traversal is rejected. Transfer limits default to 512 MiB and 120 seconds, and Sorb's server-side upload limits still apply.
+
+Optional settings: `SORB_CA_FILE` for a trusted private CA, `SORB_TIMEOUT_SECONDS` (default 60), `SORB_MAX_TRANSFER_BYTES`, and `SORB_TRANSFER_TIMEOUT_SECONDS`. TLS verification remains enabled.
+
+## Permissions and retries
+
+- Each operation rechecks the token scopes and current user/project permissions. Read-only projects cannot create tasks.
+- Keep the same `client_namespace` and `idempotency_key` for one logical write. After a timeout, query `sorb_get_submission` with the original identity instead of generating a new key and repeating the task.
+- Tasks requiring human preview or confirmation return a Sorb user-action link. The Agent prepares the proposal and queries its state; the user confirms in Sorb.
+- Revoke or replace a PAT in the MCP panel. Revocation prevents subsequent calls but does not cancel tasks already accepted by Sorb.
+
+## Remote OAuth alternative
+
+Compatible clients can connect directly to `https://<your Sorb host>/api/mcp` over Streamable HTTP and OAuth without installing this package. The remote endpoint uses MCP `2026-07-28` and supports CIMD or administrator pre-registered public clients, without a DCR endpoint. OAuth tokens are distinct from PATs; do not put a PAT into the remote OAuth connection.
+
+Remote client compatibility must be verified by an authenticated tool call. This PyPI package installs the local **stdio + PAT** integration; it does not configure or enable the remote Sorb server.
+
+For the Chinese installation guide, configuration examples and troubleshooting, open **个人中心 → 用户信息 → MCP → 接入帮助** on your Sorb server. The guide can also be downloaded as Markdown.

sorb_mcp-0.1.0/PYPI_README.md

@@ -0,0 +1,74 @@
+# Sorb MCP
+
+Sorb MCP is the local stdio MCP integration for [Sorb](https://sorb.huche.games), a multimodal content generation platform. It connects an external Agent to Sorb's existing projects, models, resources and task APIs using your personal access token (PAT).
+
+The package provides 38 tools for discovery, task creation and estimation, status and output queries, task operations, and bounded local file upload/download. Tasks retain Sorb's existing project permissions, billing, confirmation, idempotency and audit behavior. Canvas operations are outside this package's scope.
+
+Requires **Python 3.13**. A Sorb account and access to a running Sorb server are required. This package does not contain the Sorb backend or any model Provider credentials.
+
+## Install and connect
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/). The MCP client can then launch a pinned version directly from PyPI:
+
+```sh
+uvx --python 3.13 --from sorb-mcp==0.1.0 sorb-mcp
+```
+
+Or install the command in a Python 3.13 environment:
+
+```sh
+python -m pip install sorb-mcp==0.1.0
+```
+
+In Sorb, open **个人中心 → 用户信息 → MCP → 访问令牌** (Personal Center → User Information → MCP → Access Tokens). Create a token with the operations you need. Start with the default read scopes to verify the connection. The token is displayed only once.
+
+For clients using the `mcpServers` configuration format:
+
+```json
+{
+  "mcpServers": {
+    "sorb": {
+      "command": "uvx",
+      "args": ["--python", "3.13", "--from", "sorb-mcp==0.1.0", "sorb-mcp"],
+      "env": {
+        "SORB_BASE_URL": "https://sorb.huche.games",
+        "SORB_PAT": "<your personal access token>"
+      }
+    }
+  }
+}
+```
+
+Use your own Sorb server's root URL, without `/api` or `/api/mcp`. Remote servers must use HTTPS; HTTP is permitted only for loopback development addresses. If the client cannot find `uvx`, set `command` to its actual executable path. Store the PAT in your client's secure configuration, never in chat messages or shared files.
+
+After restarting or refreshing the client, ask the Agent to list your visible projects using `sorb_list_projects`. Successful tool output verifies the connection. Use `sorb_select_project`, `sorb_list_models`, `sorb_get_model_schema` and `sorb_get_task_capabilities` before requesting generation. Query operations do not create Sorb tasks; generation can incur the existing Sorb model fees.
+
+## Local files
+
+Local upload/download requires explicitly configured, existing absolute directories:
+
+```json
+{
+  "SORB_INPUT_DIRS": "/absolute/path/references",
+  "SORB_OUTPUT_DIRS": "/absolute/path/outputs"
+}
+```
+
+Add these keys to the client's `env` only when needed. Multiple directories use the operating system's path separator (`:` on macOS/Linux, `;` on Windows). Client roots may further narrow these directories. Downloads do not overwrite existing files; symlink traversal is rejected. Transfer limits default to 512 MiB and 120 seconds, and Sorb's server-side upload limits still apply.
+
+Optional settings: `SORB_CA_FILE` for a trusted private CA, `SORB_TIMEOUT_SECONDS` (default 60), `SORB_MAX_TRANSFER_BYTES`, and `SORB_TRANSFER_TIMEOUT_SECONDS`. TLS verification remains enabled.
+
+## Permissions and retries
+
+- Each operation rechecks the token scopes and current user/project permissions. Read-only projects cannot create tasks.
+- Keep the same `client_namespace` and `idempotency_key` for one logical write. After a timeout, query `sorb_get_submission` with the original identity instead of generating a new key and repeating the task.
+- Tasks requiring human preview or confirmation return a Sorb user-action link. The Agent prepares the proposal and queries its state; the user confirms in Sorb.
+- Revoke or replace a PAT in the MCP panel. Revocation prevents subsequent calls but does not cancel tasks already accepted by Sorb.
+
+## Remote OAuth alternative
+
+Compatible clients can connect directly to `https://<your Sorb host>/api/mcp` over Streamable HTTP and OAuth without installing this package. The remote endpoint uses MCP `2026-07-28` and supports CIMD or administrator pre-registered public clients, without a DCR endpoint. OAuth tokens are distinct from PATs; do not put a PAT into the remote OAuth connection.
+
+Remote client compatibility must be verified by an authenticated tool call. This PyPI package installs the local **stdio + PAT** integration; it does not configure or enable the remote Sorb server.
+
+For the Chinese installation guide, configuration examples and troubleshooting, open **个人中心 → 用户信息 → MCP → 接入帮助** on your Sorb server. The guide can also be downloaded as Markdown.

sorb_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "sorb-mcp"
+version = "0.1.0"
+description = "Sorb task tools for external MCP agents"
+readme = "PYPI_README.md"
+requires-python = ">=3.13,<3.14"
+dependencies = ["mcp==2.2.0", "httpx==0.28.1", "pydantic==2.13.4", "anyio==4.15.1"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://sorb.huche.games"
+Documentation = "https://sorb.huche.games/settings/me/mcp?tab=help"
+
+[project.scripts]
+sorb-mcp = "sorb_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest==7.4.4", "pytest-asyncio==0.23.3"]
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sorb_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/sorb_mcp", "pyproject.toml", "PYPI_README.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sorb_mcp-0.1.0/src/sorb_mcp/__init__.py

@@ -0,0 +1 @@
+"""Lightweight task MCP client; no backend or Provider imports."""

sorb_mcp-0.1.0/src/sorb_mcp/config.py

@@ -0,0 +1,59 @@
+from dataclasses import dataclass, field
+import ipaddress
+import os
+from pathlib import Path
+import ssl
+from urllib.parse import urlsplit
+
+
+@dataclass(frozen=True)
+class Settings:
+    base_url: str
+    pat: str = field(repr=False)
+    ca_file: str | None = None
+    timeout_seconds: float = 60
+    input_dirs: tuple[str, ...] = ()
+    output_dirs: tuple[str, ...] = ()
+    max_transfer_bytes: int = 512 * 1024 * 1024
+    transfer_timeout_seconds: float = 120
+
+    def __post_init__(self):
+        url = urlsplit(self.base_url)
+        # urlsplit defers validation of malformed or out-of-range ports.
+        _ = url.port
+        if (url.scheme not in {"http", "https"} or not url.hostname or url.username or url.password
+                or url.query or url.fragment or url.path not in {"", "/"}):
+            raise ValueError("SORB_BASE_URL 必须为 HTTP/HTTPS 服务根地址，不含凭据、路径或查询参数")
+        loopback = url.hostname == "localhost"
+        try:
+            loopback = loopback or ipaddress.ip_address(url.hostname).is_loopback
+        except ValueError:
+            pass
+        if url.scheme == "http" and not loopback:
+            raise ValueError("非本机 Sorb 连接必须使用 HTTPS")
+        if not self.pat.startswith("sorb_") or not 40 <= len(self.pat) <= 100 or any(c.isspace() for c in self.pat):
+            raise ValueError("SORB_PAT 缺失或格式无效，请在 Sorb 访问令牌页面创建")
+        if not 5 <= self.timeout_seconds <= 300:
+            raise ValueError("SORB_TIMEOUT_SECONDS 必须在 5–300 秒之间")
+        if self.ca_file and not Path(self.ca_file).is_file():
+            raise ValueError("SORB_CA_FILE 不存在")
+        for directory in (*self.input_dirs, *self.output_dirs):
+            if not Path(directory).is_absolute() or not Path(directory).is_dir():
+                raise ValueError("Sorb 文件输入/输出目录必须为已存在的绝对目录")
+        if not 1 <= self.max_transfer_bytes <= 2 * 1024 * 1024 * 1024:
+            raise ValueError("SORB_MAX_TRANSFER_BYTES 必须在 1–2147483648 之间")
+        if not 5 <= self.transfer_timeout_seconds <= 300:
+            raise ValueError("SORB_TRANSFER_TIMEOUT_SECONDS 必须在 5–300 秒之间")
+
+    def tls_context(self):
+        return ssl.create_default_context(cafile=self.ca_file)
+
+    @classmethod
+    def from_env(cls):
+        return cls(base_url=os.getenv("SORB_BASE_URL", "http://localhost:8042"),
+                   pat=os.getenv("SORB_PAT", ""), ca_file=os.getenv("SORB_CA_FILE") or None,
+                   timeout_seconds=float(os.getenv("SORB_TIMEOUT_SECONDS", "60")),
+                   input_dirs=tuple(filter(None, os.getenv("SORB_INPUT_DIRS", "").split(os.pathsep))),
+                   output_dirs=tuple(filter(None, os.getenv("SORB_OUTPUT_DIRS", "").split(os.pathsep))),
+                   max_transfer_bytes=int(os.getenv("SORB_MAX_TRANSFER_BYTES", str(512 * 1024 * 1024))),
+                   transfer_timeout_seconds=float(os.getenv("SORB_TRANSFER_TIMEOUT_SECONDS", "120")))