Transcriptor MCP

所有接受视频作为输入的工具都接受 url。该链接可以来自受支持的平台，也可以是纯 YouTube ID。每个工具都会返回 content（聊天文本）和 structuredContent（供代码使用的类型化 JSON）。

get_transcript

清理后的纯文本，不含时间戳、HTML 或说话者姓名。不提供 lang 时，工具会返回视频原始语言的音轨。除 YouTube 外，大多数平台不会说明视频使用的语言；如果工具无法判断是哪条音轨，会返回音轨列表，你可以再次调用该工具并提供 type 和 lang。输入参数与 get_raw_subtitles 相同。

响应：videoId、url（服务解析后的视频页面）、type、lang、text、is_truncated、total_length、start_offset、end_offset。如果还有更多文本，响应中也会包含 next_cursor。

get_raw_subtitles

分段返回原始 SRT 或 VTT 内容。

输入：

• type — official 或 auto。不提供 lang 时，工具会选择此类型的音轨
• lang — 语言代码或音轨名称，具体以 get_available_subtitles 列出的内容为准。不提供时，会像 get_transcript 一样使用视频的原始语言
• response_limit — 默认值为 50000，最小值为 1000，最大值为 200000
• next_cursor — 上一条响应中的游标

响应：包含 get_transcript 的所有字段，另加 format（srt 或 vtt）和 content。

get_available_subtitles

响应包含 official 和 auto。每个字段都是经过排序的语言代码列表。请先使用此工具，再向上文中的工具提供 type 和 lang。

get_video_info

来自 yt-dlp 的扩展元数据：

• 标识信息 — videoId、title、description、webpageUrl
• 作者 — uploader、uploaderId、channel、channelId、channelUrl
• 数值 — duration、uploadDate、viewCount、likeCount、commentCount
• 分类信息 — tags、categories、liveStatus、isLive、wasLive、availability
• 图片 — thumbnail 和 thumbnails

get_video_chapters

响应：chapters。每一项都有 startTime、endTime 和 title。如果视频没有章节，列表为空。

get_video_frame

输入：

• timecode — "MM:SS" 或 "HH:MM:SS.mmm"
• seconds — timecode 的替代参数。两者任选其一，不要同时提供
• format — jpeg（默认）或 png
• width — 默认值为 1280，最大值为 1920，且不能超过源图像的宽度
• quality — 2 到 31，仅适用于 jpeg

响应：一个图像块，以及 url、timestampSeconds、timestamp、mimeType、sizeBytes 和 width。此工具需要 ffmpeg。Docker 镜像中已包含该工具。

get_playlist_transcripts

输入：

• url — 播放列表 URL，或带有 list= 的观看 URL
• type、lang、format — 与 get_raw_subtitles 相同，但 lang 为必填项：一次只会为一个视频选择原始语言
• playlistItems — yt-dlp 的 -I 值，例如 1:5、1,3,7 或 -1
• maxItems — 视频数量上限

响应：results。每一项都有 videoId 和 text。

传输。 服务仅接受 POST /mcp。GET 和 DELETE 会返回 405。服务是无状态的，不会发送 Mcp-Session-Id。

Node 进程不会检查 bearer 令牌。请在其前面配置反向代理或网关，以实现身份验证和 TLS。托管端点也采用这种方式。

REST API。 另一个镜像通过普通 HTTP 提供相同的提取功能：

docker run --rm -p 3000:3000 artsamsonov/transcriptor-mcp-api:latest

Swagger 界面位于 http://localhost:3000/docs。如需包含 API 和 MCP 服务的完整堆栈，请阅读 docker-compose.example.yml。

开发。

npm ci
npm run build
npm run start:mcp        # stdio
npm run start:mcp:http   # Streamable HTTP on port 4200
npm test

你需要 Node.js 22 或更高版本（20 仍可使用，但已于 2026 年 4 月结束生命周期），并且需要将 yt-dlp 放在 PATH 中。捕获帧需要 ffmpeg，而 WHISPER_MAX_DURATION_SECONDS 需要 ffprobe（二者随同一个软件包提供，也包含在 Docker 镜像中）。其他脚本：lint、type-check、format、test:coverage、test:e2e:api 和 test:e2e:mcp。

发布。 发布由维护者负责。步骤详见 .claude/skills/release/SKILL.md。运行时版本来自 package.json，通过 src/version.ts 获取。推送 v* 标签会使 CI 构建两个镜像，并根据 server.json 发布 MCP Registry 条目。

目录结构。 src/mcp.ts（stdio 入口）、src/mcp-http.ts（Streamable HTTP）、src/mcp-core.ts（工具、提示词、小组件）、src/youtube.ts（yt-dlp）、src/whisper.ts、src/cache.ts、src/index.ts（REST API）、load/（k6）和 src/e2e/（Docker 冒烟测试）。