watch-cli

@sonpiaz/watch-cli-mcp

MCP（Model Context Protocol）stdio 服务，可将 watch-cli 作为可调用工具提供。

观看任意社交视频 → 自动获取架构图、可运行组件、可运行笔记本或分步速查表。

一个 MCP 服务即可连接所有支持 MCP 的 Agent 运行时——Claude Desktop、Claude Code、Cursor、OpenClaw、hermes-agent、Cline、Continue.dev、Windsurf、Zed、Codex、Kiro、VS Code Copilot——无需针对每个 IDE 单独开发插件。此软件包封装了 watch-cli，让它们都能通过一个通道调用该工具。

前置条件

• Node.js >= 18。

• 已安装 watch CLI，且位于 PATH 中。安装方式：

  curl -fsSL https://raw.githubusercontent.com/sonpiaz/watch-cli/main/install.sh | bash
  

MCP 服务会调用 watch，不会将 CLI 打包在内。

安装

npm install -g @sonpiaz/watch-cli-mcp

也可以通过 npx 按需运行：

npx -y @sonpiaz/watch-cli-mcp

二进制文件为 watch-cli-mcp。它从 stdin 读取 JSON-RPC，向 stdout 写入 JSON-RPC，并将日志写入 stderr。

工具

注册了一个工具：watch。

输入架构：

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "A social video URL. Supported: YouTube, X / Twitter, LinkedIn, TikTok, Vimeo, Reddit, Facebook."
    },
    "frames": {
      "type": "integer",
      "minimum": 1,
      "maximum": 64,
      "description": "Number of evenly-spaced frames to extract. Default 8."
    }
  },
  "required": ["url"],
  "additionalProperties": false
}

输出： 来自 docs/output-schema.md 的 v1 JSON 对象，原样传递。字段说明请参阅架构。

错误映射

CLI 退出码	MCP 响应
0	工具结果，v1 JSON 位于 content[0].text。
2	InternalError，消息包含 tag=missing-dep:<bin>。
3 download-auth / download-region	InvalidParams，消息包含该标签——调用方可通过 Cookie 或更换 URL 进行恢复。
3 download-network / download-other	InternalError，消息包含该标签。
4（部分成功）	工具结果，isError: false。帧已填充，转录为 null，JSON 负载中的 exit_code: 4。调用方根据 obj.exit_code === 4 进行分支处理。
64	InvalidParams，消息包含 tag=usage-error。
1 / 其他	InternalError，消息包含 CLI stderr 的末尾内容（≤ 1 KB）。

标签始终包含在 MCP 错误的 message 字段中，因此调用方可以搜索与 CLI stderr 中相同的 tag=... 标记。

客户端配置

Claude Desktop

配置文件路径：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

将以下内容合并到现有的 mcpServers 对象中：

{
  "mcpServers": {
    "watch-cli": {
      "command": "npx",
      "args": ["-y", "@sonpiaz/watch-cli-mcp"]
    }
  }
}

编辑后重启 Claude Desktop。

Cursor

配置文件路径：.cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（用户全局）。mcpServers 对象结构与 Claude Desktop 相同：

{
  "mcpServers": {
    "watch-cli": {
      "command": "npx",
      "args": ["-y", "@sonpiaz/watch-cli-mcp"]
    }
  }
}

hermes-agent

配置文件路径：hermes-agent 安装目录中的 optional-skills/mcp.json，或用户全局路径 ~/.hermes-agent/mcp.json。mcpServers 结构与上文相同。

其他 MCP 客户端

任何支持 MCP 且接受 npx 命令的 Agent 都可以使用上面的代码片段。替换为客户端的配置文件路径即可；command / args 配置可通用。

从源代码构建

git clone https://github.com/sonpiaz/watch-cli
cd watch-cli/mcp-server
npm install
npm run build
node dist/index.js

许可证

MIT。© 2026 Son Piaz。