Metadata-Version: 2.4
Name: sorb-mcp
Version: 26.41.372
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: httpx2==2.13.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

PyPI releases use the same CalVer version as their source Git tag. Server deployments may retain an earlier package release when the package has not changed.

版本 26.41.372 改善 OAuth 权限选择：首次缺省申请完整候选，授权页按账号权限过滤并默认只读，补充授权保留有效旧权限并要求主动勾选新增权限。需要配套 Sorb 服务端版本；已有授权不会自动扩权。包同时提供 `sorb_update_resource_tags`：批量增量追加或移除四类库的标签，需 `resources:write`，不覆盖其他标签。资源发现也支持普通提示词模板。本版本同时包含余额查询、管理员充值和 OAuth 代理 instructions 透传。升级后重新连接 MCP 刷新工具目录。

Sorb MCP connects external Agents to [Sorb](https://sorb.huche.games) projects, models, resources and tasks. You can use browser OAuth with the remote MCP service, or a personal access token (PAT) with the original local tools.

The package provides tools for discovery, task creation and estimation, status and output queries, task operations, billing and account/Provider/model administration, and bounded local file upload/download. Tool discovery follows the current account permissions. 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.

## Project tag matching

`sorb_list_resources` accepts `project_tags` as an array and `project_tags_match` as `any` (default, OR) or `all` (AND). Use `all` when the user asks for resources carrying both tags, and `any` when either tag is acceptable. An empty array does not restrict tags; an unknown tag in `all` produces no matches. Filtering happens before pagination and counting. Other audio tag categories keep their existing OR behavior within each category.

```json
{"params":{"resource_kind":"media","asset_type":"image","project_tags":["末日公路","UI"],"project_tags_match":"all","page":1,"page_size":20}}
```

This requires a server and client package containing the project tag matching update; the example does not imply that an older installed release supports this field.

## Browser login

Version 0.3.1 publishes union branches inline for clients such as ZCode 3.14.4 whose initial prevalidator does not resolve `$ref`. Backend contracts, strict runtime validation and tuple constraints remain unchanged. Reconnect MCP after upgrading to refresh cached tool schemas. Native HTTP clients receive the fix from the updated server; local PAT and OAuth bridge clients need this package version.

Requires a Sorb server with remote MCP enabled and the official public client `sorb-mcp-cli` registered (included in the corresponding Sorb release). Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run on your desktop:

```sh
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp login
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp check
```

The first command opens your browser for Sorb login and consent. The second verifies tool discovery and queries visible projects without creating tasks. Add this to your Agent's MCP configuration:

```json
{
  "mcpServers": {
    "sorb": {
      "command": "uvx",
      "args": ["--python", "3.13", "--from", "sorb-mcp==26.41.372", "sorb-mcp", "remote"]
    }
  }
}
```

Refresh or restart the client to load the configuration. No token belongs in the config. The bridge discovers the remote server's tools according to the current account permissions, uses the current upstream MCP protocol, and adapts local stdio clients through the official SDK. Remote project selection requires explicit project IDs in subsequent calls; remote tools do not perform local file upload or download.

Credentials are stored per Sorb address in `~/.config/sorb/mcp/`, with private directory/file permissions on macOS/Linux. A durable SQLite refresh claim coordinates client processes; each refresh token is sent at most once. New credentials persist before the claim is cleared. A lost response or crashed refresh requires login. On Windows, protect the account directory with its user ACL. Revoke OAuth grants in the Sorb MCP panel. If a refresh response is lost, log in again rather than replaying a refresh token.

Login without `--scopes` requests the complete candidate list advertised by Sorb. The consent page only shows scopes allowed for your account and selects the five basic read scopes on first authorization. Select generation, upload, download or administration permissions explicitly. To restrict the requested list for a task creation workflow, use:

```sh
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp login --scopes 'projects:read models:read resources:read voices:read tasks:read tasks:create'
```

When reauthorizing the same account and client, Sorb preselects still-valid permissions from the latest matching authorization and marks new scopes for explicit selection. Revoked or expired authorizations are not restored. Refresh tokens never expand permission scope. The user still confirms the permissions on Sorb's page. An insufficient-scope response returns an error for the current tool, lists the required scopes, and keeps the connection and other authorized tools available. Log in again for the same account/profile with the union of previously granted and required scopes, confirm consent, then explicitly retry the operation; the bridge does not automatically expand consent or replay the call. To use a different Sorb server, pass `--base-url https://your-sorb-host` to **each** command or set `SORB_BASE_URL` consistently. OAuth is only sent to the upstream HTTP MCP endpoint; the downstream stdio client receives no credentials. No DCR or public metadata hosting is needed for the official pre-registered client.

## Access token connection

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==26.41.372 sorb-mcp
```

Or install the command in a Python 3.13 environment:

```sh
python -m pip install sorb-mcp==26.41.372
```

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==26.41.372", "sorb-mcp"],
      "env": {
        "SORB_PAT": "<your personal access token>"
      }
    }
  }
}
```

The tool defaults to `https://sorb.huche.games`; only `SORB_PAT` is required for this Sorb service. To connect to a self-hosted or local instance, optionally set `SORB_BASE_URL` to its 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 DCR, CIMD or administrator pre-registered public clients. 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 package also provides the optional OAuth login and stdio bridge described above; 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.


## Account permissions, billing and administration

Billing tools require both the server and client package to include the billing update. `sorb_get_billing(page=1,page_size=20)` reads your own balance, consumption totals and recharge history with `tasks:read`. `sorb_admin_list_users(page=1,page_size=20,search?)` and `sorb_admin_get_user_billing(user_id,page=1,page_size=20)` require `users:read`; user discovery returns only IDs, usernames, full names and active flags plus pagination. Pages start at 1, page sizes are 1–100, and search is an optional string of at most 100 characters.

`sorb_admin_recharge_user(user_id,request)` requires `users:write`. Verify the connected identity and target user before calling. Send `amount` as a nonzero decimal string with at most 8 integer digits and 4 decimal places, for example `"12.3456"`; JSON numbers, scientific notation and implicit rounding are rejected. Negative values correct a balance under Sorb's native validation. An optional `note` is limited to 500 characters. The required `client_namespace` and `idempotency_key` each contain 1–100 characters. Response monetary values remain decimal strings.

Keep the original namespace/key and parameters for one recharge intent. After a timeout or lost response, query `sorb_get_submission` with `params={client_namespace,idempotency_key,operation:"recharge_user"}` using `users:write`. Same-key retries return the original result; changed parameters conflict. Do not automatically create a new key or replay an uncertain recharge. These tools affect Sorb's durable accounting and do not read or write client/server filesystem paths.

Existing credentials do not gain scopes when upgraded. Reauthorize OAuth with the same account/profile and the union of existing and required scopes, or issue a replacement PAT with the required scopes; then reconnect to refresh tool discovery. Previously published client packages do not gain local tools from a server deployment alone.

Version 0.4.0 adds Common Config details/create/update and pricing scheme/tier queries/create/update. Writes require both current role permissions and explicit `common_configs:write` / `pricing:write` OAuth or PAT scopes. Existing grants are not expanded by upgrading. Common Config detail responses can contain sensitive configuration values; metadata listings omit TOML. Create calls are non-idempotent: query before retrying an uncertain response. Pricing changes preserve tier IDs and historical task price snapshots.

Version 0.3.0 adds account-filtered discovery, `sorb_get_identity`, model and
Provider administration tools. Current account permissions and approved credential
scopes are both enforced by Sorb. Provider secrets are never returned by these tools.

For multiple accounts on one service, run commands with separate profiles:

```sh
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp login --profile admin --scopes 'model_configs:read model_configs:write providers:read providers:write common_configs:read common_configs:write pricing:read pricing:write'
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp check --profile admin
uvx --python 3.13 --from sorb-mcp==26.41.372 sorb-mcp remote --profile admin
```

Use another profile for a different account, and a distinct named connection in
your Agent. Native HTTP clients must isolate OAuth grants themselves. Previously
published packages do not gain new local tools from a server deployment alone.
