# Seedance / Seedream MCP

Python MCP server for BytePlus Seedream 5.0 Pro, Seedance 2.0, TOS media
staging, and the private portrait asset library. It is designed for local
verification first and deployment as a Native Python 3.11 Web Application on
BytePlus veFaaS.

## Runtime shape

- Streamable HTTP MCP endpoint: `POST /mcp`
- Health endpoint: `GET /health`
- Upload widget: `GET /widget/`
- Upload API: `POST /api/uploads`
- Redis-backed short-lived sessions
- Per-tenant ModelArk credentials selected from the API Gateway API key

## Setup

Create a virtual environment, install dependencies, and copy the environment
template:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env
```

On PowerShell:

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env
```

Fill every required value in `.env`. Startup fails immediately when any
required value is missing. For generation, configure `MCP_TENANTS_JSON` and a
separate `ARK_API_KEY_*` secret for each ModelArk project; the legacy shared
`ARK_API_KEY` is never used for generation.

## Run locally

```bash
bash run.sh
```

or:

```bash
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```

Verify:

```bash
curl http://127.0.0.1:8000/health
MCP_AUTHORIZATION="<gateway-api-key>" python scripts/smoke_mcp.py http://127.0.0.1:8000/mcp
```

On Windows, verify the deployed remote MCP and call its runtime-config tool:

```powershell
.\scripts\test_remote_mcp.ps1
```

## Tools

Planning tools never call generation APIs:

- `creative_plan_launch_set`
- `creative_resolve_video_preset`

Deferred in multi-tenant v1:

- `media_start_upload_session`
- `media_finalize_upload_session`
- `media_get_upload_session`
- `media_import_generated_asset`

Generation:

- `seedream_generate_image`
- `seedance_generate_video`

Task control and diagnostics:

- `generation_get_task`
- `generation_list_tasks`
- `generation_cancel_task`
- `system_get_runtime_config`
- `system_validate_byteplus_connectivity`

`system_get_runtime_config` masks all legacy/shared secrets and returns only
the calling tenant's principal/project identifiers; it never returns ModelArk
keys or other tenants' mappings.

## Main workflows

### Seedream image

1. Call `seedream_generate_image`.
2. Reuse the returned `reference_session_id` directly with Seedance. Outputs
   generated by ModelArk are trusted and do not need private-asset conversion.

### Tenant isolation

The public `/mcp` endpoint requires the API Gateway key in `Authorization`.
The server hashes that key and maps it to exactly one ModelArk project. The
ModelArk key is loaded only from the matching server-side secret and is never
returned to the MCP client. Seedance tasks and Seedream reference sessions are
owned by that tenant and cannot be reused by another tenant.

### Deferred shared-media workflows

The TOS upload, upload widget, and portrait Asset Library workflows are disabled
in multi-tenant v1 because their current storage/assets are shared. They will be
reintroduced only with isolated project-compatible storage and asset credentials.

## Tests

```bash
python -m pytest -q
```

The default suite uses mocks and requires no production credentials. Tests
cover config validation, secret masking, schemas, planning helpers, upload
state, provider adapters, MCP tool discovery, and MCP initialize.

Live integration calls are intentionally not part of the default suite because
they consume provider quota and require configured BytePlus resources.

## Claude Desktop local verification

Claude Desktop can reach the Streamable HTTP server through a local bridge:

```json
{
  "mcpServers": {
    "seedance-seedream": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}
```

Restart Claude Desktop, confirm tool discovery, then try:

1. `Create a 2K JPEG product hero image with Seedream.`
2. `Open the upload flow for a normal image, then animate it with Seedance.`
3. `Open the portrait upload flow, prepare the private asset, wait until it is Active, then create a five-second 9:16 video.`

Expected results are structured tool outputs containing reference session IDs,
provider task IDs, asset URIs when active, and suggested next actions.

See [DEPLOY.md](DEPLOY.md) for veFaaS and API Gateway deployment.