qencode

qencode-mcp

面向 Qencode Transcoding API 的模型上下文协议（MCP）服务。

将任意兼容 MCP 的 AI 客户端——Claude、Cursor、ChatGPT、Grok、Gemini——连接到你的 Qencode 账户，让它代表你提交、监控转码作业并分析作业情况。

快速示例

连接客户端后（请参阅连接客户端），用日常语言向 Agent 提出请求：

将 https://example.com/input.mp4 转码为包含 1080/720/540/360 的 HLS 梯度。将其放到我的 R2 存储桶 videos/demo/ 中。

Agent 会选择 hls_abr 配方，填写每个输出分辨率对应的编码参数，通过 start_encode2_raw 提交作业，并持续轮询直至作业完成。

前置条件

• Qencode 门户账户，且至少有一个项目——请登录与你的环境对应的门户：https://portal.qencode.com（生产环境）或 https://portal-qa.qencode.com（QA 环境）。你将在 OAuth 授权步骤中选择项目。
• 兼容 MCP 的客户端（Claude、Cursor、ChatGPT、Grok、Gemini 或任何自定义客户端）。

无需将 API 密钥复制到客户端配置中——身份验证通过浏览器中的 OAuth 完成。

工作原理

此连接器使用标准 OAuth 2.1——客户端配置中无需 API 密钥。首次使用时，客户端会打开浏览器，你登录 Qencode 门户账户、选择项目并批准请求的权限范围。客户端会保存令牌；后续调用无需任何操作，直到令牌过期。

客户端在授权时应请求的权限范围（通过受保护资源元数据发布）：

权限范围	用途
openid	OIDC 身份
profile	显示名称
email	账户电子邮件
offline_access	刷新令牌
transcoding:read	get_job_status、list_jobs、文档工具
transcoding:write	transcode_video、start_encode2_raw

RS 会在传输层对访问令牌强制执行 transcoding:read 和 transcoding:write 权限。

你的 Qencode API 密钥不会离开门户。MCP 服务会通过内部门户端点，为每个请求派生一个短期会话令牌。

环境

同一个连接器部署在两个环境中。每个环境都有各自的域名、账户、项目和凭据——请登录与你连接的端点对应的门户。

角色	生产环境	QA（测试）
MCP 端点（在此连接）	https://mcp.qencode.com/mcp	https://mcp-qa.qencode.com/mcp
门户（登录 / 项目）	https://portal.qencode.com	https://portal-qa.qencode.com
授权服务器	https://auth.qencode.com	https://auth-qa.qencode.com
Qencode API	https://api.qencode.com	https://api-qa.qencode.com

以下说明使用生产环境端点。若要针对 QA 环境测试，请替换为 QA URL，并登录 QA 门户。

连接客户端

端点：https://mcp.qencode.com/mcp — 以下所有客户端均使用此端点。浏览器打开后，登录你的 Qencode 账号并批准访问。

**QA（内部测试）：**使用 https://mcp-qa.qencode.com/mcp，并改为在 QA 门户登录。

客户端	添加位置	MCP URL / 配置
Claude（聊天）	消息框 → + → Connectors → Add connector	https://mcp.qencode.com/mcp
Claude Code	终端	claude mcp add --transport http qencode https://mcp.qencode.com/mcp
ChatGPT	Apps → 搜索 Qencode → Connect；或 Developer Mode → Build app	连接器 URL：https://mcp.qencode.com/mcp
Gemini	~/.gemini/settings.json → mcpServers	"httpUrl": "https://mcp.qencode.com/mcp" — 然后在命令行中运行 /mcp auth qencode
Cursor	Settings → Tools & MCP → New MCP Server（或 ~/.cursor/mcp.json）	"url": "https://mcp.qencode.com/mcp" — 保存后重启 Cursor

Cursor（mcp.json）：

{
  "mcpServers": {
    "qencode": { "url": "https://mcp.qencode.com/mcp" }
  }
}

Gemini（settings.json）：

{
  "mcpServers": {
    "qencode": {
      "httpUrl": "https://mcp.qencode.com/mcp",
      "timeout": 30000,
      "trust": false
    }
  }
}

提示：连接前，先在浏览器中登录 portal.qencode.com — OAuth 流程会更顺畅。

连接器提供的功能

工具

转码与作业

工具	描述
transcode_video	将作业提交到一个或多个输出，源为 URL。便捷封装 — 如果未提供 encoder_version，会自动注入 encoder_version: 2（VMAF 使用 1）。
start_encode2_raw	备用入口 — 按照 Qencode API 的要求，使用完整的 query JSON 提交作业。
get_job_status	根据 task_token 获取一次状态快照。
get_job_status_detailed	完整、权威的作业状态，包括各个转码版本的进度和输出详情。
list_jobs	为当前对话的 task_tokens 显示内嵌作业卡片 — 包括状态徽标、筛选器、可展开行和输出 URL。只要有作业仍在运行，卡片就会自动刷新。
fetch_job_result	读取分析作业生成的结果文件内容（转录文本、VMAF 报告、元数据、分类结果）。
wait_for_job	已弃用。会立即返回并指向 list_jobs；保留此工具是为了避免较早的对话遇到“找不到工具”的错误。
search_qencode_docs	搜索内置的配方与参考文档知识库。
fetch_qencode_doc	通过 qencode:// URI 获取知识库资源的完整内容（作为 resources/read 的工具版对应项）。

播放

工具	描述
open_player	在页面内渲染可播放的结果 — 渐进式 MP4/WebM 或 HLS/DASH 清单。服务会应用调用方主机的沙箱策略，因此允许哪些源站取决于客户端。
refresh_jobs	作业卡片自身的静默轮询。不供 Agent 直接调用；用于支持卡片的自动刷新和 Refresh 按钮。

媒体存储

Qencode Media Storage 的存储桶管理与媒体导入。这些功能使用与转码工具相同的 OAuth 授权 — 无需额外权限范围，也无需重新授权。

工具	描述
list_buckets	列出账号可用的 Media Storage 存储桶。
create_bucket	创建新存储桶。仅在收到明确请求时调用 — 不要为了填补缺失的 destination 而调用。
list_objects	浏览存储桶内容。
get_download_url	返回现有对象的限时下载 URL。
download_url_to_bucket	在服务器端将公共 URL 复制到存储桶（媒体导入，不进行转码）。

资源

该服务附带一个包含配方和参考文档的知识库，并将其作为 MCP 资源公开，供 Agent 按需获取。重要 URI：

• qencode://docs/best-practices — Agent 自动应用的合成默认设置
• qencode://docs/storage — 目标存储兼容性矩阵（Qencode S3、R2、AWS S3、Azure、B2、FTP/SFTP）
• qencode://docs/error-codes — 错误代码 → 原因 → 修复方法
• qencode://docs/gotchas — 不明显的 API 特性
• qencode://schema/digest — start_encode2 的完整属性参考
• qencode://recipe/<slug> — 每种功能流程对应一个配方：ai_detection、ai_upscaling、audio_outputs、callbacks、clip_trim、codec_av1、codec_lcevc、drm_aes128、drm_buydrm、drm_doverunner、drm_expressplay、drm_fairplay_ezdrm、drm_forensic_watermark、drm_playready_ezdrm、drm_widevine_ezdrm、hdr_to_sdr、hls_abr、incremental_abr、mp4_ladder、per_title_encoding、refresh_abr_playlist、reliability、repack、rotate_deinterlace、smart_crop、smart_thumbnail、speech_to_text、stitching、subtitles、thumbnails、video_intelligence、video_metadata、vmaf_quality、vr_360、vr_mode、watermark_logo、waveform

使用 search_qencode_docs 查找适合目标的配方 URI。

提示词（斜杠命令）

在支持 MCP 提示词的客户端中，有 40 个单次使用模板可用。每个模板都会指示 Agent 读取匹配的 qencode://recipe/... 资源，并通过 start_encode2_raw 提交。

ABR / 打包： encode_hls_abr、encode_dash_abr、encode_mp4_ladder、encode_incremental_rung、encode_refreshing_playlist、remux_repack

编解码器 / 质量： encode_av1、encode_lcevc、tune_per_title、check_vmaf、ai_upscale_video、convert_hdr_to_sdr

音频 / 图像 / 文本： extract_audio、generate_thumbnails、generate_smart_thumbnails、generate_waveform、transcribe、add_subtitles

编辑 / 画面构图： trim_clip、rotate_video、deinterlace_video、enable_smart_crop、add_watermark、add_html_overlay

沉浸式： enable_vr_mode、inject_360_metadata

分析： get_video_metadata、analyze_video、detect_ai_generated

探测 / 拼接： stitch_videos

生产环境钩子： enable_callbacks、enable_reliability

DRM： encode_aes128_hls、encode_widevine_ezdrm、encode_playready_ezdrm、encode_fairplay_ezdrm、encode_drm_buydrm、encode_drm_expressplay、encode_drm_doverunner、encode_forensic_watermark

源 URL 规则

transcode_video 和 start_encode2_raw 接受使用 https://、http://、s3:// 或 tus: 协议的 source 值。FTP/SFTP 和私有/元数据 URL 会在工具边界处被拒绝（SSRF 防护）。限制详见 docs/security/THREAT_MODEL.md。

安全

仅支持 OAuth 2.1 身份验证——没有静态 API 密钥模式。你的 Qencode API 密钥不会离开门户；服务会通过内部门户端点，为每个请求派生一个全新的短期会话令牌。源 URL 会在工具边界处进行验证（SSRF 防护——参见源 URL 规则）。

完整威胁模型和对抗性测试覆盖范围：docs/security/THREAT_MODEL.md。

开发

uv venv && uv pip install -e ".[dev]"
NO_NETWORK=1 pytest -q              # offline L1 + L2 + L5 (~900 tests)
pytest -m protocol                # MCP wire conformance only
pytest -m unit                    # per-tool logic (FakeQencode)
pytest -m security                # OWASP MCP Top 10 adversarial suite

协议测试完全离线运行（模拟授权服务器、门户和 Qencode API）。CI 使用 Jenkins 作业 mcp_automated_tests（Jenkinsfile.manual）：可通过手动复选框选择任意层级，每晚运行 L3 cron，每周运行 L4 cron。

支持的 MCP 协议版本

客户端在 initialize 阶段协商版本。此服务以 MCP 2025-11-25 为主要目标版本。CI 也会针对 2025-06-18 运行一致性测试，因为 JSON-RPC 批处理行为在较早的修订版之间有所不同。除底层 SDK 协商支持的范围外，我们不声称支持 2025-03-26 或更早版本的线协议语义。

版本	支持情况	备注
2025-11-25	主要版本	流式 HTTP；在适用时支持可恢复的 SSE
2025-06-18	CI 矩阵	为 2025 年年中客户端提供回归保护
2025-03-26	非目标版本	批处理语义与 2025-06-18 不同

目录列表（Glama）

用户安装的连接器是上方托管的端点。仅用于 Glama Servers / awesome-mcp-servers 评分时，此仓库还会提供 qencode-mcp-inspect（stdio、虚拟环境变量、 拒绝 tools/call）。这不是受支持的客户端传输方式。请参阅 docs/glama-release.md。

更多文档

• 本地服务 / 环境变量：docs/local-development.md
• 测试层级（L1–L5）：docs/testing.md 和 tests/README.md
• 针对实时 QA / PROD 的 L3 测试：tests/integration/README.md
• L4 Agent 评估：evals/README.md
• 发布前检查：docs/release-checklist.md

版本策略

连接器遵循 SemVer，并将其应用于 MCP 接口——工具、提示词、资源、OAuth 作用域和支持的协议版本。Qencode HTTP API 的变更不在此范围内（这属于 API 本身的职责，而非连接器的职责）。

• MAJOR — 破坏性接口变更：移除或重命名工具 / 提示词 / 资源、将之前可选的参数改为必填、添加或收紧 OAuth 作用域而导致必须重新授权，或弃用某个受支持的 MCP 协议版本。
• MINOR — 向后兼容的新增内容：新增工具 / 提示词 / 资源、新增可选参数，或新增受支持的协议版本。
• PATCH — 接口结构不变：调整工具 / 提示词描述的措辞、更新知识库 / 文档，以及修复错误。

接口变更由 tests/protocol/ 下的快照测试进行保护。更改接口时，请重新生成快照（python scripts/regen_tools_snapshot.py），并在同一个 PR 中更新版本：pyproject.toml、src/qencode_mcp/__init__.py、server.json 和新的 CHANGELOG.md 条目必须保持一致。

链接

• 更新日志：CHANGELOG.md
• OAuth 2.1 授权服务器规范：docs/oauth-spec.md
• Qencode 门户：https://portal.qencode.com（生产环境）· https://portal-qa.qencode.com（QA）
• Qencode API 参考：https://docs.qencode.com/api-reference/transcoding