使用说明

🎬 YouTube观看后期清理器-FastMCP服务器

将您混乱的YouTube“稍后观看”列表转化为一个有组织、可操作的观看系统。内置于 FastMCP 2.0 与Claude Desktop和其他MCP客户端无缝集成。

✨ 特性

🔍 智能分析：使用分类细分分析您的“稍后观看”播放列表
🧹 清理工具：自动删除已删除/私人视频
🏷️ 自动分类：使用标题/频道分析进行智能视频分类
📋 概念整合：将组织好的视频导出到漂亮的Notion数据库
📅 日程表安排：在Google日历中创建查看会话
🎵 创建播放列表：生成基于类别的YouTube播放列表
📊 进度跟踪：监控查看进度和统计数据

🚀 快速开始

1.安装

# Clone and navigate to project
cd Youtube-Sched-MCP/

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.API设置

复制环境文件:
```
cp env.example .env
```
获取YouTube API密钥:
- 首选谷歌开发者控制台
- 创建项目→ 启用YouTube数据API v3→ 创建API密钥
- 增添 .env: YOUTUBE_API_KEY=your_key_here
获取通知API密钥 （可选）：
- 首选概念整合
- 创建新的内部集成→ 复制机密
- 增添 .env: NOTION_API_KEY=your_key_here

3.测试服务器

# Test basic functionality
python src/server.py

# Open FastMCP Inspector (recommended)
fastmcp dev src/server.py

期望输出:

🎬 YouTube Watch Later Cleaner - FastMCP Server
==================================================
Server: YouTube Watch Later Cleaner
Tools: 8 available
Resources: 2 available
==================================================
✅ API keys configured
==================================================
🚀 Starting FastMCP server...
   Use 'fastmcp dev src/server.py' for MCP Inspector
   Use 'fastmcp install src/server.py' for Claude Desktop
==================================================

4.测试工具

服务器运行后，测试以下工具：

// Test basic functionality
{
  "tool": "hello_world",
  "arguments": {"name": "YouTube Cleaner"}
}

// Test async functionality
{
  "tool": "test_async",
  "arguments": {"message": "Testing FastMCP setup"}
}

// Test main tool (stub implementation)
{
  "tool": "analyze_watch_later",
  "arguments": {"max_results": 10, "include_stats": true}
}

🔧 开发设置

# Install development dependencies
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pre-commit install

# Run tests
pytest

# Format code
black src/

# Type checking
mypy src/

📱 Claude桌面集成

安装服务器:
```
fastmcp install src/server.py
```

或者手动添加到Claude配置中:

{
  "mcpServers": {
    "youtube-cleaner": {
      "command": "python",
      "args": ["/path/to/Youtube-Sched-MCP/src/server.py"],
      "env": {
        "YOUTUBE_API_KEY": "your_key_here",
        "NOTION_API_KEY": "your_key_here"
      }
    }
  }
}

🛠️ 可用工具

工具	状态	描述
`hello_world`	✅ 准备就绪	测试FastMCP设置
`test_async`	✅ 就绪	测试异步功能
`analyze_watch_later`	🚧 Stub	分析稍后观看播放列表
`cleanup_unavailable`	🚧 Stub	删除已删除/私人视频
`categorize_videos`	🚧 Stub	自动分类视频
`create_notion_database`	🚧 Stub	导出到Notion
`schedule_viewing`	🚧 Stub	创建日历事件
`create_filtered_playlists`	🚧 Stub	生成类别播放列表

备注：Stub工具返回模拟数据进行测试。后续任务中的实际实现。

📋 资源和提示

config://categories：可用视频类别
stats://server：服务器状态和统计信息
categorization_help：手动分类辅助
scheduling_help：最佳观看时间表建议

🐛 故障排除

常见问题：

“未找到FastMCP”:
```
pip install fastmcp>=2.9.0
```
“API密钥不工作”:
- 检查 .env 文件存在且密钥正确
- 验证YouTube API是否已在Google控制台中启用
- 确保API密钥中没有额外的空格

“导入错误”:

pip install -r requirements.txt --upgrade

“权限被拒绝”:
```
chmod +x src/server.py
```

调试模式：

# Enable debug logging
DEBUG=true python src/server.py

# Enable API mocking (no quotas used)
MOCK_YOUTUBE_API=true python src/server.py

📖 后续步骤

任务1.1完成后，继续执行：

任务1.2：加强项目结构和基本测试
任务3.1：YouTube API集成（analyze_watch_later，cleanup_unavailable）
任务3.2：分类系统（category_video）
任务3.3：外部集成（通知、日历、播放列表）

📄 许可证

MIT许可证-请参阅许可证了解详情。