watch-cli

@sonpiaz/watch-cli-mcp

watch-cliを呼び出し可能なツールとして公開する、MCP（Model Context Protocol）stdio サーバーです。

あらゆるソーシャル動画を視聴し、アーキテクチャ図、動作するコンポーネント、実行可能なノートブック、または手順ごとのチートシートを自動で取得できます。

1 つの MCP サーバーで、Claude Desktop、Claude Code、Cursor、OpenClaw、hermes-agent、Cline、Continue.dev、Windsurf、Zed、Codex、Kiro、VS Code Copilot など、MCP 対応のあらゆるエージェントランタイムにアクセスできます。IDE ごとのプラグイン作業は不要です。このパッケージはwatch-cliをラップし、いずれの環境からも 1 つのチャネルを通じて呼び出せるようにします。

前提条件

• 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 にログを出力します。

ツール

登録されるツールは 1 つです：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	content[0].textに v1 JSON を含むツール結果。
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）が含まれます。

呼び出し元が CLI の stderr で確認できるものと同じtag=...トークンを検索できるよう、タグは常に MCP エラーのmessageフィールドに含まれます。

クライアント設定

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 クライアント

npxコマンドを受け付ける MCP 対応エージェントであれば、上記のスニペットを使用できます。クライアントの設定ファイルのパスを指定してください。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。