# Video Studio MCP Server

Video Studio MCP lets AI agents call the cloud AI creation service and local content download tools.

## Features

- AI video generation with models such as Sora, Grok, and Veo.
- AI image generation and editing.
- Video content analysis.
- Copywriting/chat helper.
- Douyin/Xiaohongshu download helpers.
- Balance and generation status checks.
- **Billing receipts after billed calls**: generation tools read the cloud balance endpoint and report the current balance and settlement/refund state.

## Quick Start

Install dependencies:

```bash
pip install -r requirements.txt
```

Add the server to your MCP config:

```json
{
  "mcpServers": {
    "video-studio": {
      "command": "python",
      "args": ["/path/to/mcp-server/server.py"]
    }
  }
}
```

Then ask your agent to log in:

```text
Login to video-studio with username xxx and password xxx.
```

## Tools

| Tool | Purpose | Costs credits | Billing receipt |
| --- | --- | --- | --- |
| `login` | Log in to the cloud service | No | No |
| `whoami` | Show login and balance status | No | No |
| `list_models` | List available models and supported params | No | No |
| `check_balance` | Check remaining credits | No | No |
| `check_mcp_update` | Check the current MCP version and update policy | No | No |
| `video_create` | Create an AI video | Yes (pre-charge) | Yes; pending settlement |
| `video_status` | Poll video generation progress | No | On terminal settlement/refund |
| `video_download` | Get video download URL | No | No |
| `image_generate` | Unified image generation/editing; omit or include up to 9 reference images | Yes | Yes |
| `video_analyze` | Analyze video content | Yes (dispatch ticket) | Yes |
| `chat` | Chat/copywriting helper | Yes | Yes |
| `download_video` | Download Douyin/Xiaohongshu content locally | No | No |

Every billed tool uses the cloud billing system; MCP never deducts credits locally. For proxy calls, the cloud creates a recoverable reservation, settles it on clear success, and refunds clear terminal failures. For videos, creation is initially a pre-charge and `video_status` reports the final outcome.

## Billing interfaces

The cloud endpoints used by MCP are:

- `GET /api/credits/balance`: current balance, `{ "credits_balance": 80 }`.
- `GET /api/credits/costs`: default and model-level pricing rules.
- `GET /api/credits/history`: auditable credit ledger.
- `POST /api/dispatch/request` and `POST /api/dispatch/report`: reservation and settlement for direct-dispatch services such as video analysis.

Generation tools append a `计费回执` section to their normal result. It includes the cloud pricing rule when available, whether the request was settled, pending, or refunded, and a post-call balance snapshot. The balance is a concurrent snapshot; use `/api/credits/history` for exact attribution when multiple calls run at once.

Example:

```text
生成完成！共 1 张图片:
  1. https://cdn.example/image.png
计费回执；规则费用=20积分；本次调用已由云端结算；当前余额=80积分。
```

For the complete lifecycle and troubleshooting guidance, see [`docs/billing.md`](docs/billing.md) in this repository and [`docs/mcp-and-billing.md`](../docs/mcp-and-billing.md) in the main repository.

## Version and updates

The MCP server has its own semantic version (`MCP_VERSION`) and sends it to the
cloud as `X-MCP-Version` on every request. The cloud exposes the read-only
`GET /api/mcp/version` policy endpoint. Cloud responses also carry update
headers, so billed MCP results can include a version reminder. Run `check_mcp_update()` to compare the
installed version with the latest/minimum versions and get release notes.

The recommended update is:

```bash
git pull origin master
pip install -r requirements.txt --upgrade
```

Restart the MCP process (or open a new agent session) after updating. The MCP
server intentionally does not overwrite its own running process or credentials.

## Generation Contract

MCP follows the same client contract as frontend, local backend, and future CLI clients:

- Image requests use OpenAI-style fields such as `model`, `prompt`, `size`, `n`, and optional `images` for reference-image generation (up to 9 references). The single public endpoint `/api/v1/images/generations` selects text-to-image when no images are supplied and the image-input workflow when images are supplied.
- Before image generation, MCP validates the generic size contract: `auto` or any `宽x高` pixel size with both dimensions divisible by 16 and no larger than 4096x4096. Common ratio aliases are convenience inputs; they are converted to pixel values. The model preset list is informational, not an allowlist.
- Local reference images are prepared in memory and never overwrite the source file. Opaque images are compressed as JPEG; images with alpha remain PNG. The MCP caps the prepared image at 7 MiB and 4096 px on the longest edge, keeping it below the cloud's 8 MiB public-reference limit.
- Video requests use OpenAI-style fields such as `model`, `prompt`, `size`, `seconds`, and `input_reference`.
- Cloud normalizes those fields into canonical routing params and then applies provider `field_mapping`.

MCP convenience arguments are converted to the cloud public contract; provider-only fields such as `aspect_ratio`, `image_size`, and `reference_images` are not sent.

## Project Structure

```text
mcp-server/
  server.py
  SKILL.md
  requirements.txt
  .env.example
  output/
  downloads/
```

## Testing

Run the offline contract test; it does not call the cloud and does not consume credits:

```bash
python test_contract.py
```

Live integration tests consume credits. Use a dedicated test account and set credentials via environment variables; do not commit passwords:

```bash
MCP_TEST_USERNAME='test-user' MCP_TEST_PASSWORD='***' python test_all.py
```

## License

MIT