zoom-agent-cli: Instructions file for Claude Code

zoom-agent-cli — Developer Guide

Architecture

Dual CLI + MCP server from a single codebase using the CommandDefinition pattern.

Single source of truth: Each command is defined once as a CommandDefinition object in src/commands/{group}/{subcommand}.ts. The same definition powers both the CLI (Commander.js) and MCP tool registration.

Directory Structure

src/
├── index.ts                    # CLI entry point (Commander.js)
├── mcp.ts                      # Direct MCP entry point
├── core/
│   ├── types.ts               # CommandDefinition, ZoomClient interfaces
│   ├── client.ts              # HTTP client (S2S OAuth, auto token refresh, retry)
│   ├── handler.ts             # executeCommand() — path/query/body + UUID encoding
│   ├── path.ts                # encodeMeetingPathId (double-encode / and //)
│   ├── auth.ts                # Credential resolution (flag > env > config)
│   ├── config.ts              # ~/.zoom-agent-cli/config.json manager
│   ├── output.ts              # JSON formatting, --fields, --quiet
│   └── errors.ts              # Typed error classes
├── commands/
│   ├── index.ts               # allCommands array + registerAllCommands()
│   ├── auth/                  # login, logout, status (special)
│   ├── mcp/                   # MCP server command
│   ├── meetings/              # 9 commands
│   ├── recordings/            # 9 commands
│   ├── users/                 # 6 commands
│   ├── past-meetings/         # 2 commands
│   ├── webinars/              # 10 commands
│   ├── reports/               # 6 commands
│   ├── dashboard/             # 4 commands
│   ├── chat/                  # 8 commands
│   └── groups/                # 7 commands
└── mcp/
    └── server.ts              # MCP server registration

Key Patterns

• executeCommand(): Standard REST endpoints use executeCommand(cmdDef, input, client) which routes fields to path/query/body based on fieldMappings. Path IDs that start with / or contain // are double-encoded.
• Custom handlers: Non-standard endpoints (e.g., user creation wraps body in {action, user_info}) use custom handler functions. recordings transcript lists recording files and downloads the VTT — Zoom has no standalone transcript endpoint.
• Auth: Zoom Server-to-Server OAuth with automatic token refresh. Client caches tokens and auto-refreshes on expiry or 401.