Metadata-Version: 2.4
Name: littleorange-video-mcp
Version: 0.0.4.post1
Summary: MCP server for LittleOrange video model APIs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: PyYAML>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"

#

<p align="center">
  <img src="https://camo.githubusercontent.com/c4ee5534eada64e3523941b2e0f0ec1a050cd48ebf69b133e8f84e3aba72c391/68747470733a2f2f696e7465726e616c2d6170692d64726976652d73747265616d2e6c61726b6f66666963652e636f6d2f73706163652f6170692f626f782f73747265616d2f646f776e6c6f61642f61757468636f64652f3f636f64653d4e6a4e6b5a6d466c4d7a63795a6d49314f54566d4d6a55334e7a4d344d5745314e4755784d7a4d325a545a665957517a5a5745334e5445794d324933596a55304f574e6d4e4451795a474d354e6a4d324d7a6b314e7a6866535551364e7a59304e7a41784d5441784e7a49354d5449314e5441794e4638784e7a67774e4455344e544d334f6a45334f4441314e4451354d7a6466566a4d" alt="Image" width="200"  />
  <h1 align="center"> LittleOrange Video MCP 官方文档</h1>
</p>

**LittleOrange Video MCP** 是一款基于 **Model Context Protocol (MCP)** 开源标准的服务端工具，专为 AI 应用打造，提供统一、标准化的视频生成 API 调用能力。服务基于官方视频生成 API 文档封装，支持主流 AI 视频模型，内置智能轮询、分层工具能力，完美适配各类 AI 客户端与 Agent 场景。

**协议标准**：[Model Context Protocol (MCP)](https://modelcontextprotocol.io)

**接口来源**：[视频生成大模型 API 官方文档](https://video-ai.apifox.cn)

***

## ✨ 功能特性

- **多模型全覆盖**：集成 Sora2、Veo3.1、Vidu Q3、Dreamina Seedance 2.0 等主流视频生成大模型
- **智能异步轮询**：自动轮询异步任务，无需手动查询，直接返回最终视频链接与完整任务状态
- **三层工具架构**：底层API映射、自动轮询工具、高层Agent工具，适配开发、自动化、AI代理全场景
- **完整素材管理**：支持AIGC素材/素材组、真人认证素材的增删改查，适配商用素材流程
- **通用透传能力**：内置原始请求透传工具，支持任意接口调试与新接口快速适配
- **结构化错误返回**：标准化JSON错误信息，包含错误类型、描述、详情，便于排查问题
- **隔离式调试日志**：日志写入本地文件，不污染MCP标准stdio通信协议

***

## 📌 覆盖范围

内置全套工具能力，覆盖视频生成、任务查询、素材管理全流程：

- ✅ 36 个基础文档接口工具
- ✅ 11 个「创建并自动等待」轮询工具
- ✅ 6 个高层 Agent 智能工具
- ✅ 1 个通用 API 透传调试工具

### 支持模型与功能明细

| 模型/类别                 | 核心支持功能                               |
| --------------------- | ------------------------------------ |
| 基础示例接口                | 创建视频任务、查询任务状态                        |
| Sora2                 | 文生视频、图生视频、任务状态查询                     |
| Veo3.1                | 文生视频、图生视频、视频时长扩展、任务查询                |
| Vidu Q3               | 文生视频、图生视频、首尾帧生成视频、主体/非主体参考生视频、生成物查询  |
| Dreamina Seedance 2.0 | AI视频生成、任务状态查询                        |
| Dreamina 素材库          | 素材/素材组CRUD、真人认证素材管理、认证H5、认证结果查询、资产删除 |

***

## 🚀 快速开始

### 1. 获取 API Key

使用前需前往 [LittleOrange 平台](https://portal.aig-ai.com) 注册账号，获取专属 `API Key`（密钥需妥善保管，禁止前端暴露）。

### 2. 安装 uv 包管理器

项目基于 uv 快速部署，未安装则执行以下命令安装：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

更多安装方式参考：[uv 官方仓库](https://github.com/astral-sh/uv)

### 3. 配置 MCP 客户端

#### 方式一：uvx 直接启动（推荐，无需源码）

PyPI 发布版本，一键拉起服务，适配所有 MCP 客户端：

```json
{
  "mcpServers": {
    "littleorange-video": {
      "command": "uvx",
      "args": ["littleorange-video-mcp"],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5",
        "LITTLEORANGE_DEBUG": "0"
      }
    }
  }
}
```

#### 方式二：GitHub 源码部署

指定版本源码安装，适合需要最新迭代功能的场景：

```json
{
  "mcpServers": {
    "littleorange-video": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/littleorange-ai/littleorange-video-mcp.git@v0.0.3",
        "littleorange-video-mcp"
      ],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5",
        "LITTLEORANGE_DEBUG": "0"
      }
    }
  }
}
```

#### 客户端专属配置说明

- **TRAE（Windows）**：直接复制上述推荐配置粘贴即可生效
- **Cursor**：`Preferences → Cursor Settings → MCP → Add new global MCP Server`，粘贴配置保存
- **Claude Desktop**：替换官方 MCP 配置文件对应内容

***

## ⚙️ 配置说明

### 环境变量配置（核心）

| 环境变量名                                   | 参数描述                         | 默认值                         | 必填  |
| --------------------------------------- | ---------------------------- | --------------------------- | --- |
| `LITTLEORANGE_API_KEY`                  | 平台接口密钥，身份认证核心参数              | 无                           | ✅ 是 |
| `LITTLEORANGE_BASE_URL`                 | API 接口基础请求地址                 | `https://vg-api.aig-ai.com` | ❌ 否 |
| `LITTLEORANGE_TIMEOUT`                  | HTTP 请求超时时间（单位：秒）            | 120                         | ❌ 否 |
| `LITTLEORANGE_POLL_INTERVAL_SECONDS`    | 任务轮询间隔（单位：秒）                 | 5                           | ❌ 否 |
| `LITTLEORANGE_MAX_POLL_ATTEMPTS`        | 最大轮询重试次数                     | 60                          | ❌ 否 |
| `LITTLEORANGE_FIRST_POLL_DELAY_SECONDS` | 首次轮询延迟时间（单位：秒）               | 5                           | ❌ 否 |
| `LITTLEORANGE_DEBUG`                    | 调试日志开关（1开启 / 0关闭）            | 0                           | ❌ 否 |
| `LITTLEORANGE_LOG_FILE`                 | 调试日志本地存储路径                   | 无                           | ❌ 否 |
| `LITTLEORANGE_CATALOG_AUTO_UPDATE`      | 接口目录自动更新开关（0关闭/1开启）          | 1                           | ❌ 否 |
| `LITTLEORANGE_CATALOG_REFRESH_SECONDS`  | 接口目录缓存刷新间隔（秒）；设为0表示每次都检查官方文档 | 3600                        | ❌ 否 |
| `LITTLEORANGE_CATALOG_FORCE_REFRESH`    | 强制刷新接口目录（1=每次都从Apifox拉取）     | 0                           | ❌ 否 |
| `LITTLEORANGE_CATALOG_LOG_FILE`         | 目录刷新日志本地存储路径                 | 无                           | ❌ 否 |
| `LITTLEORANGE_CATALOG_CACHE_FILE`       | 接口目录缓存文件路径                   | 系统缓存目录                      | ❌ 否 |

> **⚠️ 重要说明**：轮询参数支持双层优先级，单次调用传入参数可覆盖全局环境变量配置，灵活适配不同任务场景。

### 轮询参数场景推荐

| 使用场景    | 轮询间隔(秒) | 最大轮询次数 | 首次延迟(秒) |
| ------- | ------- | ------ | ------- |
| 快速调试    | 3       | 20     | 1       |
| 常规视频生成  | 5       | 60     | 2       |
| 长时长视频任务 | 10      | 120    | 3       |

### 本地开发安装

适合二次开发、本地调试场景：

```bash
# 进入项目目录
cd /path/to/littleorange-video-mcp

# 本地可编辑模式安装
python -m pip install -e .
```

无 pip 环境先安装依赖：

```bash
apt update && apt install -y python3-pip
```

本地开发 MCP 客户端配置：

```json
{
  "mcpServers": {
    "littleorange-video": {
      "command": "python",
      "args": ["-m", "littleorange_video_mcp.server"],
      "env": {
        "LITTLEORANGE_API_KEY": "sk-你的key",
        "LITTLEORANGE_TIMEOUT": "120",
        "LITTLEORANGE_BASE_URL": "https://vg-api.aig-ai.com",
        "LITTLEORANGE_POLL_INTERVAL_SECONDS": "10",
        "LITTLEORANGE_MAX_POLL_ATTEMPTS": "60",
        "LITTLEORANGE_FIRST_POLL_DELAY_SECONDS": "5"
      }
    }
  }
}
```

***

## 🛠️ 工具分类

所有工具分为四大类，从底层原生调用到高层智能封装，适配不同开发与自动化需求。

### 1. 底层 API 映射工具

完全对齐官方原生接口，适合精细化自定义开发，支持参数灵活覆写。

**通用入参**：`base_url`、`api_key`、`headers`、`query_params`、`request_body`

### 2. 自动轮询工具（`_wait`）

**推荐优先使用**，自动完成「创建任务 + 轮询等待 + 结果返回」全流程，直接输出视频链接与任务信息。

**统一返回字段**：`video_urls`、`elapsed_seconds`、`last_state`、`last_status`、`last_error`、完整查询结果

| 模型       | 可用轮询工具                                                                                     |
| -------- | ------------------------------------------------------------------------------------------ |
| Sora2    | `sora2_t2v_wait`、`sora2_i2v_wait`                                                          |
| Veo3.1   | `veo31_t2v_wait`、`veo31_i2v_wait`、`veo31_extend_wait`                                      |
| Vidu Q3  | `vidu_t2v_wait`、`vidu_i2v_wait`、`vidu_start_end_wait`、`vidu_ref_subj_wait`、`vidu_ref_wait` |
| Dreamina | `dreamina_create_video_wait`                                                               |

### 3. 高层 Agent 友好工具

极简封装、语义化命名，适配 IDE Agent、MCP 智能代理自动调用，无需手动区分模型。

| 工具名称                  | 功能描述             |
| --------------------- | ---------------- |
| `video_generate_wait` | 通用文生视频（智能适配最优模型） |
| `image_to_video_wait` | 通用图生视频           |
| `video_extend_wait`   | 视频时长扩展           |
| `video_query`         | 批量查询视频任务状态       |
| `asset_upload`        | 上传自定义素材          |
| `asset_list`          | 获取个人素材列表         |

### 4. 透传工具

通用调试工具 `littleorange_raw_request`，适配所有未封装接口、临时调试场景。

**适用场景**：新接口快速适配、请求头/参数调试、自定义原生请求、官方接口更新兼容

**支持入参**：`base_url`、`query_params`、`headers`、任意格式 `request_body`

***

## 🐛 错误处理与调试

### 标准化错误返回格式

所有异常统一返回结构化 JSON 数据，便于精准排查问题：

```json
{
  "status": "error",
  "error_type": "http_error",
  "message": "HTTP 400",
  "details": {
    "method": "POST",
    "url": "https://vg-api.aig-ai.com/v1/viduq3-turbo",
    "params": {},
    "status_code": 400,
    "response_excerpt": "..."
  }
}
```

### 常见错误类型

- `validation_error`：参数校验失败
- `request_error`：请求参数异常
- `http_error`：接口HTTP状态码异常
- `network_error`：网络连接失败
- `polling_timeout`：轮询超时，任务未完成
- `unknown_error`：未知异常

### 调试日志配置

日志独立写入文件，不干扰 MCP 标准通信，开启方式：

```bash
LITTLEORANGE_DEBUG=1
LITTLEORANGE_LOG_FILE=/path/to/littleorange-debug.log
```

**日志包含内容**：请求方式、脱敏URL、查询参数、轮询次数、任务状态、耗时信息

***

## ❓ 常见问题 FAQ

#### Q1：任务完成后没有返回 video\_urls？

可能原因：任务未真正完成、接口返回结构无视频地址、仅返回中间状态数据

解决方案：增大最大轮询次数、调整轮询间隔、查看 `last_status` 与任务最终返回数据

#### Q2：频繁出现轮询超时 timeout？

原因：视频生成任务耗时超出预设轮询上限

解决方案：调大 `LITTLEORANGE_MAX_POLL_ATTEMPTS`、适当增加轮询间隔，长任务建议设置为120次

#### Q3：提示缺少 API Key？

解决方案：配置全局环境变量 `LITTLEORANGE_API_KEY`，或单次调用单独传入密钥参数

#### Q4：TRAE 客户端看不到部分工具？

解决方案：重启 MCP 服务、更新至最新版本、检查配置文件是否生效、确认工具名长度合规

#### Q5：如何切换自定义 API 接口地址？

支持两种方式：全局修改 `LITTLEORANGE_BASE_URL`环境变量、单次调用传入 `base_url` 覆写

#### Q6：什么场景使用 raw\_request 透传工具？

适用于：官方新增未封装接口、接口参数调试、自定义请求头、排查底层接口异常

#### Q7：如何立即获取最新的 Apifox 接口文档？

快速方法：

1. 临时设置环境变量：`LITTLEORANGE_CATALOG_FORCE_REFRESH=1`
2. 重启 MCP 服务
3. 获取更新后记得改回 `0` 避免频繁请求

#### Q8：目录刷新机制的工作原理是什么？

1. 默认每 1 小时检查一次 Apifox 文档更新
2. 如果缓存过期，从 Apifox 下载最新文档
3. 如果网络不可用，使用最近一次缓存
4. 没有缓存时使用包内置的兜底目录

#### Q9：如何查看目录刷新日志？

设置环境变量：

- `LITTLEORANGE_DEBUG=1`
- `LITTLEORANGE_CATALOG_LOG_FILE=/path/to/catalog.log`

日志会记录：刷新时间、来源、接口数量、SHA256 校验等信息。

***

## 💻 开发与测试

### 安装开发依赖

```bash
python -m pip install -e '.[dev]'
```

### 运行单元测试

```bash
# pytest 测试
pytest

# 原生 unittest 测试
python3 -m unittest discover -s tests -v
```

### 文档与接口更新

MCP 服务启动时会自动读取 Apifox 官方 OpenAPI 文档并生成运行时接口目录，缓存文件默认位于系统缓存目录。官方接口更新后，用户重启 MCP 服务即可自动刷新接口目录和工具映射，不需要等待新的 MCP/PyPI 版本发布。

内置兜底目录文件路径：`littleorange_video_mcp/api_catalog.json`。当网络不可用或官方文档临时不可访问时，会自动使用最近一次缓存；如果没有缓存，则使用包内置目录。

可配置项：

- `LITTLEORANGE_CATALOG_AUTO_UPDATE=1`：默认开启自动更新；设为 `0` 可关闭。
- `LITTLEORANGE_CATALOG_REFRESH_SECONDS=3600`：缓存刷新间隔，默认 1 小时；设为 `0` 表示每次启动都检查官方文档。
- `LITTLEORANGE_CATALOG_FORCE_REFRESH=0`：强制刷新接口目录，设为 `1` 表示每次都从 Apifox 拉取最新文档。
- `LITTLEORANGE_CATALOG_LOG_FILE=/path/to/catalog.log`：目录刷新日志文件路径（可选）。
- `LITTLEORANGE_CATALOG_CACHE_FILE=/path/to/api_catalog.json`：自定义缓存文件路径（可选）。

**快速获取最新接口方法**：

1. 设置环境变量：`LITTLEORANGE_CATALOG_FORCE_REFRESH=1`
2. 重启 MCP 服务
3. 获取更新后记得改回 `0` 避免频繁请求

过渡期或新接口尚未形成稳定封装命名时，可使用 `littleorange_raw_request` 临时适配新接口。

***

## 📝 版本历史

| 版本号    | 发布日期       | 核心更新内容                                             |
| ------ | ---------- | -------------------------------------------------- |
| v0.0.4 | 2026-06-04 | 优化接口目录自动刷新机制：缩短默认刷新间隔为1小时，新增强制刷新与日志功能              |
| v0.0.3 | 2026-06-04 | 新增启动时自动刷新 Apifox 官方文档接口目录与工具映射；清理发布包冗余文档           |
| v0.0.2 | 2026-06-03 | 新增可自定义轮询参数、高层Agent工具、结构化错误返回、文件调试日志；优化TRAE/uvx部署配置 |
| v0.0.1 | 2026-06-02 | 项目首次正式发布，完成基础视频模型接口封装与MCP服务搭建                      |

详细版本迭代记录：[GitHub Releases](https://github.com/littleorange-ai/littleorange-video-mcp/releases)
