星战科技xingzhan.cloud
返回市场
语音转写下载MCP服务器

语音转写下载MCP服务器

作者：jedarden3 星标更新：2025-07-17
安装使用来源：spider==github.com

项目介绍

🎬 YouTube 字幕下载 MCP 服务器

一个全面的 MCP（模型上下文协议）服务器，用于提取 YouTube 视频字幕，支持多种传输方式（标准 I/O、服务发送事件（SSE）、HTTP），Docker 部署和 npm 包分发。

✨ 特性

  • 🎯 多传输支持：标准 I/O、服务发送事件（SSE）和 HTTP
  • 📹 全面的字幕提取：单个视频、批量处理和播放列表
  • 🌍 多语言支持：提取不同语言的字幕
  • 📝 多种输出格式：文本、JSON 和 SRT 字幕格式
  • 🚀 高性能：内置缓存和速率限制
  • 🐳 Docker 就绪：完整的容器化支持
  • 📦 npm 包：易于安装和分发
  • 🧪 测试驱动开发：覆盖超过 90% 的综合测试套件
  • 🔧 TypeScript：完全类型安全和现代 JavaScript 功能

📦 安装

🔧 作为 npm 包

npm install -g yt-transcript-dl-mcp

🛠️ 从源码

git clone <repository-url>
cd yt-transcript-dl-repo
npm install
npm run build

🐳 Docker

# 从 GitHub 容器注册表（推荐）
docker pull ghcr.io/jedarden/yt-transcript-dl-mcp:latest
docker run -p 3001:3001 -p 3002:3002 ghcr.io/jedarden/yt-transcript-dl-mcp:latest --multi-transport

# 从源码构建
docker build -t yt-transcript-dl-mcp .
docker run -p 3001:3001 -p 3002:3002 yt-transcript-dl-mcp --multi-transport

🚀 使用

🖥️ MCP 服务器

以不同模式启动 MCP 服务器：

# 标准 I/O 模式（默认）
yt-transcript-dl-mcp start

# SSE 模式
yt-transcript-dl-mcp start --transport sse --port 3000

# HTTP 模式
yt-transcript-dl-mcp start --transport http --port 3000

# 启用详细日志
yt-transcript-dl-mcp start --verbose

💻 命令行工具

使用示例视频测试服务器：

# 使用 YouTube 视频测试
yt-transcript-dl-mcp test dQw4w9WgXcQ

# 使用不同语言测试
yt-transcript-dl-mcp test dQw4w9WgXcQ --language es

# 使用不同格式测试
yt-transcript-dl-mcp test dQw4w9WgXcQ --format srt

🔧 程序化使用

import { YouTubeTranscriptService } from 'yt-transcript-dl-mcp';

const service = new YouTubeTranscriptService();

// 提取单个视频字幕
const result = await service.getTranscript('dQw4w9WgXcQ', 'en', 'json');
console.log(result);

// 批量处理
const bulkResult = await service.getBulkTranscripts({
  videoIds: ['dQw4w9WgXcQ', 'jNQXAC9IVRw'],
  outputFormat: 'json',
  language: 'en'
});
console.log(bulkResult);

🛠️ MCP 工具

服务器提供以下 MCP 工具：

get_transcript

从单个 YouTube 视频中提取字幕。

参数：

  • videoId（必需）：YouTube 视频 ID 或 URL
  • language（可选）：语言代码（默认：'en'）
  • format（可选）：输出格式 - 'text', 'json', 或 'srt'（默认：'json'）

get_bulk_transcripts

从多个 YouTube 视频中提取字幕。

参数：

  • videoIds（必需）：YouTube 视频 ID 或 URL 数组
  • language（可选）：语言代码（默认：'en'）
  • outputFormat（可选）：输出格式 - 'text', 'json', 或 'srt'（默认：'json'）
  • includeMetadata（可选）：在响应中包含元数据（默认：true）

get_playlist_transcripts

从 YouTube 播放列表中的所有视频中提取字幕。

参数：

  • playlistId（必需）：YouTube 播放列表 ID 或 URL
  • language（可选）：语言代码（默认：'en'）
  • outputFormat（可选）：输出格式 - 'text', 'json', 或 'srt'（默认：'json'）
  • includeMetadata（可选）：在响应中包含元数据（默认：true）

format_transcript

将现有字幕数据格式化为不同的格式。

参数：

  • transcript（必需）：字幕数据数组
  • format（必需）：输出格式 - 'text', 'json', 或 'srt'

get_cache_stats

获取缓存统计信息和性能指标。

clear_cache

清除字幕缓存。

⚙️ 配置

🌍 环境变量

# 服务器配置
PORT=3000
HOST=0.0.0.0
MCP_TRANSPORT=stdio

# CORS 设置
CORS_ENABLED=true
CORS_ORIGINS=*

# 速率限制
RATE_LIMIT_WINDOW=900000  # 15 分钟，单位为毫秒
RATE_LIMIT_MAX=100

# 缓存
CACHE_ENABLED=true
CACHE_TTL=3600  # 1 小时，单位为秒
CACHE_MAX_SIZE=1000

# 日志
LOG_LEVEL=info
LOG_FORMAT=simple

📝 配置文件

创建一个 config.json 文件：

{
  "port": 3000,
  "host": "0.0.0.0",
  "cors": {
    "enabled": true,
    "origins": ["*"]
  },
  "rateLimit": {
    "windowMs": 900000,
    "max": 100
  },
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": 1000
  },
  "logging": {
    "level": "info",
    "format": "simple"
  }
}

🐳 Docker 部署

🐙 Docker Compose

version: '3.8'

services:
  yt-transcript-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "dist/health-check.js"]
      interval: 30s
      timeout: 10s
      retries: 3

健康检查

Docker 容器包括内置健康检查：

# 检查容器健康
docker ps
docker exec <container-id> node dist/health-check.js

开发

设置

git clone <repository-url>
cd yt-transcript-dl-repo
npm install

运行测试

# 运行所有测试
npm test

# 运行带有覆盖率的测试
npm run test:coverage

# 运行特定测试套件
npm run test:unit
npm run test:integration
npm run test:e2e

# 监视模式
npm run test:watch

构建

# 构建 TypeScript
npm run build

# 开发模式带监视
npm run dev

# 代码检查
npm run lint
npm run lint:fix

测试 MCP 服务器

# 测试标准 I/O 传输
./scripts/test-stdio.sh

# 使用示例视频测试
npm run test:sample

API 文档

响应格式

所有字幕响应遵循此结构：

interface TranscriptResponse {
  videoId: string;
  title?: string;
  language: string;
  transcript: TranscriptItem[];
  metadata?: {
    extractedAt: string;
    source: string;
    duration?: number;
    error?: string;
  };
}

interface TranscriptItem {
  text: string;
  start: number;
  duration: number;
}

错误处理

服务器处理各种错误场景：

  • 视频未找到：返回空字幕并在元数据中包含错误
  • 私有视频：优雅地处理错误并提供描述性消息
  • 速率限制：内置延迟和重试逻辑
  • 网络错误：自动重试并采用指数退避策略

性能

基准测试

  • 单个视频提取：< 5 秒
  • 批量处理：< 2 秒/视频
  • 并发请求：10 并发请求成功率 > 90%
  • 内存使用：正常负载下 < 512MB
  • 缓存命中率：重复请求命中率 > 70%

优化

  • LRU 缓存：可配置的 TTL 和大小限制
  • 速率限制：防止 API 被滥用
  • 并发处理：针对批量操作进行优化
  • 内存管理：高效的垃圾回收

故障排除

常见问题

  1. 视频未找到：检查视频是否公开且具有字幕
  2. 速率限制：减少并发请求或增加延迟
  3. 内存问题：减少缓存大小或定期清理缓存
  4. 网络错误：检查互联网连接和防火墙设置

调试模式

启用调试日志：

export LOG_LEVEL=debug
yt-transcript-dl-mcp start --verbose

日志

检查 logs/ 目录下的日志：

tail -f logs/combined.log
tail -f logs/error.log

贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 为新功能编写测试
  4. 确保所有测试通过
  5. 提交拉取请求

代码风格

  • 使用 TypeScript 编写所有代码
  • 遵循 ESLint 配置
  • 编写全面的测试
  • 为公共 API 添加 JSDoc 注释
  • 使用约定的提交消息

许可证

MIT 许可证 - 查看 LICENSE 文件了解详情。

支持

更新日志

v1.0.0

  • 初始发布
  • 支持标准 I/O、SSE 和 HTTP 传输的 MCP 服务器
  • 单个视频和批量字幕提取
  • Docker 容器化
  • 综合测试套件
  • TypeScript 支持
  • 缓存和速率限制
  • 多种输出格式（文本、JSON、SRT）