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.
