feat: MCP server mode for AI agents

[jdwit]

Summary

• New ytstudio mcp sub-app exposes the CLI surface as FastMCP tools so AI agents (Claude Desktop, Cursor, custom clients) can manage a channel through the Model Context Protocol.
• Read tools (13) are always on; write tools (11) are only registered when the server is started with --allow-write or with YTSTUDIO_MCP_ALLOW_WRITE=1 set in the environment. --read-only forces a read-only server regardless.
• Optional install path: uv tool install "ytstudio-cli[mcp]". fastmcp is a lazy import; the cold CLI startup cost is unchanged for non-MCP commands and the rest of the CLI still works when the extra is not installed.

Highlights

• New commands:
  • ytstudio mcp serve [--transport stdio|http] [--host] [--port] [--allow-write] [--read-only] [--profile] [--log-level]
  • ytstudio mcp tools [--output table|json] [--allow-write]
  • ytstudio mcp print-config [--client claude-desktop|cursor|generic] [--name] [--allow-write] (no fastmcp import, no API calls)
• Read-only tools: whoami, list_videos, get_video, list_categories, analytics_overview, analytics_query, list_comments, list_broadcasts, get_broadcast, list_playlists, get_playlist, list_playlist_items, list_captions.
• Write-gated tools: update_video, publish_comments, reject_comments, schedule_broadcast, transition_broadcast, update_broadcast, create_playlist, update_playlist, delete_playlist, add_to_playlist, remove_from_playlist.
• Stream keys are always redacted via the existing _redact_key helper, even when the server is started with --allow-write.
• Quota/permission errors are translated to ToolError instead of SystemExit, so a single failing call no longer kills the server.
• stdio transport redirects the rich console to stderr so the JSON-RPC channel on stdout stays clean.
• HTTP transport binds to 127.0.0.1 by default; --host 0.0.0.0 prints a stderr warning about the lack of transport-level auth.
• New env var: YTSTUDIO_MCP_ALLOW_WRITE=1. Precedence: --read-only > --allow-write > env var > default off.
• README and docs/mcp.md document the install snippet, Claude Desktop config, full tool inventory, and the security model. mkdocs.yml nav updated.

Example Claude Desktop snippet emitted by ytstudio mcp print-config:

{
  "mcpServers": {
    "ytstudio": {
      "command": "/usr/local/bin/ytstudio",
      "args": ["mcp", "serve"]
    }
  }
}

Test plan

• uv sync --group dev --extra mcp
• uv run ruff check .
• uv run ruff format --check .
• uv run pytest -q (full suite: 232 passed, including 27 new MCP tests)
• New tests cover: CLI surface (tests/test_mcp_cli.py), in-memory FastMCP client interaction with read + write tools (tests/test_mcp_server.py), and write-gate precedence (tests/test_mcp_env_gating.py).
• Suggested manual checks:
  • Run ytstudio mcp serve from Claude Desktop using the generated config snippet and confirm tool discovery.
  • Confirm that quota errors mid-session surface as ToolErrors instead of killing the server.
  • Confirm that get_broadcast redacts the stream key in --allow-write mode.

Out of scope

• No CLI sub-app for playlists or captions; those land in separate PRs. The MCP layer ships its own playlist read helpers in src/ytstudio/mcp/playlists.py so the new tools are not blocked on the CLI work.
• Caption writes (captions().insert/update/delete) are deliberately deferred; only list_captions is exposed in this PR.
• No HTTP-level authentication for the MCP transport. The server binds to 127.0.0.1 by default and warns on non-loopback bindings.
• No interactive comment moderation TUI.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	fastmcp@​3.4.2
	pytest-asyncio@​1.4.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Potentially malicious package (AI signal): pypi pywin32 is 60.0% likely malicious Notes: The code implements a straightforward proxy/redirect mechanism via a hardcoded target and path, enabling open-proxy-like behavior. While it may be a minimal sample, deployment in publicly accessible environments is risky due to lack of access controls, input validation, and robust error handling. Strongly consider removing or securing this logic, applying authentication, validating URLs, and restricting usage to trusted clients. Confidence: 0.60 Severity: 0.90 From: uv.lock → pypi/pywin32@312 ℹ Read more on: This package | This alert | What is AI-detected potential malware? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Given the AI system's identification of this package as malware, extreme caution is advised. It is recommended to avoid downloading or installing this package until the threat is confirmed or flagged as a false positive. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore pypi/pywin32@312. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[jdwit]

Closing per current direction; only the playlists PR (#25) is being shipped from this trio. Branch left in place in case we revisit.