AppsGolem YouTube Cutter

appsgolem-mcp（Node / TypeScript）

一个用于 AppsGolem YouTube 剪辑 API 的 MCP 服务。它可以让 AI Agent（Claude Desktop、Claude Code、Cursor，……）从 YouTube 视频中剪辑片段——支持网页剪辑工具支持的任何格式——并返回直接下载 URL。REST 逻辑位于轻量级客户端（依赖项很少）src/client.ts 中；src/server.ts 则是基于该客户端的精简 MCP 工具层。

获取 API 密钥 → appsgolem.com/agents — 注册、添加预付费额度，然后生成密钥（ag_live_…）。该页面还提供 Claude Code、Codex、Cursor 和任何 MCP 客户端的复制粘贴式配置，以及提示词指南。

要求

• Node.js >= 18（使用全局 fetch）。
• AppsGolem API 密钥（ag_live_…）——可前往 appsgolem.com/agents 获取（注册 → 添加额度 → 在控制面板中生成密钥）。额度为预付费；可购买额度包或订阅，无需自动续订。

安装 / 连接（无需手动安装）

npx 会按需获取并运行服务——无需全局安装。

Claude Desktop / Cursor — 添加到客户端的 MCP 配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "appsgolem": {
      "command": "npx",
      "args": ["-y", "appsgolem-mcp"],
      "env": { "APPSGOLEM_API_KEY": "ag_live_…" }
    }
  }
}

Claude Code — 执行一条命令：

claude mcp add appsgolem -e APPSGOLEM_API_KEY=ag_live_… -- npx -y appsgolem-mcp

服务通过 stdio（这些客户端使用的传输方式）运行 MCP。启动时缺少 APPSGOLEM_API_KEY 不会导致失败——服务仍会启动并公布其工具；之后每次调用都会返回清晰的 config_error，提示你设置密钥。

配置

环境变量	必需	默认值	说明
APPSGOLEM_API_KEY	是	—	你的 ag_live_… 密钥。
APPSGOLEM_API_BASE	否	https://appsgolem.com	用于自托管 / 开发的覆盖值。

定价

每个生成的剪辑 = 1 个额度。2160p（4K）= 每个剪辑 4 个额度——但 audio_only 除外，它仍为 1 个。源视频时长超过 2 小时时，每个任务额外增加 +1 个额度，但仅在已知时长时收取（如果探测无法确定时长，则不收取附加费）。批量处理 / 拼接 N 个剪辑时，每个剪辑按原价计费，共需 N 个额度。失败的剪辑绝不会收费。

---

工具

该服务提供三个工具。通过 MCP 输入模式验证的调用会返回结构化结果——成功时返回 API 自身的 JSON，处理程序 / API 失败时返回 { "error": … }——且绝不会引发协议级错误，因此 Agent 始终能获得可用对象。（无效的工具参数会在处理程序运行前由 MCP SDK 拒绝，并以纯文本 isError 结果返回。）

1. cut_youtube_video

从 YouTube 视频中剪辑片段（或批量剪辑多个片段）。默认情况下，工具会等待片段生成完毕并返回其状态（下载令牌就绪后会包含 download_url）；设置 wait: false 可立即提交并返回当前任务（派发后通常处于 queued 状态）。

参数

名称	类型	默认值	说明
url	string	—	必填。 YouTube 观看／分享链接或 youtu.be URL。不接受播放列表。
start	string	—	片段起始时间："SS"、"MM:SS" 或 "HH:MM:SS"（≤ 300 h）。使用 clips 时省略。
end	string	—	片段结束时间，格式相同（≤ 300 h）。使用 clips 时省略。
resolution	string	1080p	144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p（4K；总剪辑时长 ≤ 60 min）。
mode	string	video	video · audio_only · both · nosound · short · gif · frames（见下方的模式）。
audio_format	string	—	audio_only 输出格式：mp3 · m4a · wav · flac（服务端默认使用 mp3）。both 始终生成 MP3。
bitrate	string	—	有损音频比特率 320 · 256 · 192 · 128（默认 320）：适用于 audio_only 中的 MP3/M4A，以及 both 中的 MP3；WAV/FLAC 不受影响。
fast	boolean	false	流复制（约快 10 倍，与关键帧对齐）；仅适用于 video / nosound / both。不能与非 1× 的 speed 同时使用；若两者都已设置，则以 fast 为准，并将 speed 强制设为 1.0。
speed	number	1.0	播放速度 0.5 · 1 · 1.25 · 1.5 · 2。适用于 video / nosound / both / audio_only。
interval_ms	integer	2000	frames 采样间隔：100 · 500 · 1000 · 2000 · 5000 · 10000（非图集提取的 JPG 总数上限为 1,800 张，适用于所有片段）。
burn_ts	boolean	false	frames：将源时间戳叠加到每张 JPG 上。
sheet	boolean	false	frames：返回单张联系表 JPG（2–80 帧，仅限单个片段）。设置此项会禁用 burn_ts。
clips	array	—	包含 1–10 个 { start, end } 时间范围的数组，替代 start/end（空数组会被拒绝）。
stitch	boolean	false	当 clips 有 2 个或更多条目时，将它们合并为一个文件（否则返回包含各片段的 zip）；单个片段时不受影响。适用于 video / audio_only / both / short / nosound。
idempotency_key	string	—	稳定密钥（≤ 200 chars），使重试请求复用同一任务（通过 Idempotency-Key 标头发送）。
wait	boolean	true	轮询直至就绪，最多等待至 timeout_seconds 设定的轮询截止时间。
timeout_seconds	integer	300	轮询截止时间，单位为秒（默认 300）。此值仅限制轮询时间；初始提交以及一个正在进行中的状态请求（每个请求超时上限为 30 s）可能会延长总耗时。

返回值（wait: true，默认） — 已生成的任务状态。下载令牌可用后会包含 download_url；如果尚未就绪，请再次轮询：

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "produced",
  "credits_reserved": 1,
  "created_at": "2026-08-22T12:00:00+00:00",
  "download_url": "https://appsgolem.com/v1/download/…/clip.mp4"
}

返回值（wait: false） — 立即返回任务及其当前状态（派发后通常为 queued），此时尚无 download_url；使用 id 轮询 get_cut_status（或获取 poll_url）：

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "queued",
  "credits_reserved": 1,
  "poll_url": "/v1/cuts/e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
}

如果等待超时，而片段尚未就绪，结果会包含 "still_processing": true 和任务 id — 使用该 id 轮询 get_cut_status。如果任务最终失败，结果为 { "error": "cut_failed", "state": "failed" | "refunded", "id": … }（且不会扣除积分）。

2. get_cut_status

按 ID 检查剪辑任务。可用于轮询通过 cut_youtube_video(wait=false) 启动的任务或超时的任务。

名称	类型	备注
job_id	string	必填。 cut_youtube_video 返回的任务 ID（UUID）。

返回值 — 任务状态；任务生成／交付后，如果有可用的下载令牌，也会附带 download_url（否则请再次轮询）：

{ "id": "e48db1a2-…", "state": "queued", "credits_reserved": 1, "created_at": "…" }

状态按 accepted → queued → produced → delivered 推进；出错时则为 failed → refunded。

3. get_account_balance

返回 API 账户可用的信用额度余额和当前每小时上限。无需参数。

返回值

{ "balance": 412, "hourly_cap": 60 }

---

模式

mode	输出	显著选项
video	无水印视频文件，通常为 MP4；fast 会保留源容器格式（例如高分辨率下的 WebM）	resolution、fast、speed
audio_only	mp3 / m4a / wav / flac	audio_format、bitrate、speed
both	视频和 MP3 打包为一个 zip（fast 可能会保留视频的源容器格式）	bitrate、fast、speed
nosound	无音轨视频，通常为 MP4；fast 会保留源容器格式	resolution、fast、speed
short	9:16 竖屏视频——适用时使用 AI 智能裁剪，否则使用信箱式模糊填充；具体纵横比取决于源视频（Shorts / Reels / TikTok）	resolution
gif	动态 GIF（≤ 5 分钟；不支持多个片段）	resolution
frames	JPG 静帧	interval_ms、burn_ts、sheet

---

提示词示例

由于 Agent 会根据你的请求选择参数，你可以用自然语言指示它：

• “从 https://youtu.be/dQw4w9WgXcQ 剪出 0:30 到 1:15，分辨率为 1080p。” → cut_youtube_video(url, start="0:30", end="1:15")
• “提取那个视频 2:00 到 5:00 的音频，格式为 mp3。” → mode="audio_only", audio_format="mp3"
• “将 10:00–10:45 的精彩片段制作成竖屏短视频。” → mode="short", start="10:00", end="10:45"
• “把 0:05–0:12 转成 GIF。” → mode="gif"
• “从 1:00 到 2:00 每隔 5 秒提取一帧，制作成联系表。” → mode="frames", interval_ms=5000, sheet=true
• “将 0:10–0:20 和 1:00–1:10 拼接成一个片段。” → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true
• “快速剪辑 0:00–0:30，使用流复制。” → fast=true
• “我还剩多少 API 信用额度？” → get_account_balance()

---

结果与错误格式

处理程序返回的每个结果都是普通对象（MCP 参数验证失败除外——请参阅上文的 Tools 说明）。失败时，对象会包含一个 error 代码（工具调用仍然成功）：

error	情况
config_error	缺少 APPSGOLEM_API_KEY。
invalid_api_key	密钥被拒绝（401）。
invalid_job_id	job_id 不是 UUID。
not_found	此账户没有此任务（404）。
cut_failed	任务进入 failed/refunded 状态（不会收费）。
network_error	连接／传输失败或请求超时。
bad_request	无法将配置的 API 基础地址／路径构建为 URL。
http_error	响应状态码 ≥400，且 JSON 正文不是 { error: … } 对象（包含 status）。
bad_response	成功响应的正文不是 JSON 对象（数组／标量／null），或在 wait: true 时，剪辑提交返回的结果中没有可用的任务 id。

API 级错误——验证错误 400、402 insufficient_credits、404 not_found、409 idempotency_conflict / duplicate_in_flight、429 rate_limited，以及 503 rate_limiter_unavailable / database_busy——会以 API 自身的错误正文形式返回，并附带 status 字段。429 还会包含 retry_after（秒数，取自 Retry-After）以及 reason（submission_cap · request_rate · poll_rate），以便 Agent 确定触发了哪项限制并正确退避。503 通常是暂时性的（短暂延迟后重试），但持续出现的 503 表示服务端问题，应当报告，而不是无限重试。

正常使用时，状态轮询不受速率限制——检查任务进度不会计入每小时提交次数上限。你无需自行限制 get_cut_status：cut_youtube_video(wait=true) 会为你轮询并控制频率（遵守服务器的 poll_after 间隔以及任何 Retry-After），因此单次工具调用即可处理较长的任务。

生成的下载链接会在有限时间后过期（appsgolem.com 默认约为 72 小时；可按部署配置）——请在此期限内获取文件。

相对 download_url（API 返回的是路径）只有在结果仍位于同一源站时，才会根据配置的 API 基础地址解析为完整 URL。任何解析后不在 API 源站上的 download_url——指向其他主机的绝对 URL，或逃逸源站的相对路径——都会出于安全考虑被丢弃：该字段会被移除，且结果会附带 download_url_dropped: true，以便你将其与尚未生成的任务区分开来。当 cut_youtube_video 等待结果时（wait=true，默认值），如果链接不在同一源站，则会返回 download_url_unsafe 错误，而不会提供有问题的 URL。

---

开发

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs node --test (no network)
npm start          # run the stdio server locally (key needed for calls, not startup)

发布

在此目录中运行 npm publish，即可让所有人使用 npx appsgolem-mcp。 prepare 脚本会在安装／发布时自动构建 dist/。