# Implementation Plan: Add YouTube Comments Tool
## Executive Summary
- **Problem Statement**
- The VidCap API added `GET /api/v1/youtube/comments` to fetch video comments with pagination and optional replies. The MCP server currently exposes several YouTube tools but lacks comments retrieval.
- **Proposed Solution (KISS)**
- Mirror existing patterns for YouTube endpoints: add Zod schemas, add a service method using the existing axios client, register a new MCP tool (`youtube_getComments`), and optionally add a CLI command/controller for parity.
- **Resource Requirements**
- 1 engineer familiar with this codebase, ~3–5 hours (including review and docs).
- **Timeline (realistic)**
- Day 1 (0.5 day): Schemas + service + tool
- Day 1 (0.5 day): CLI/controller + README + manual tests
- Day 2 (optional): Light refactors/tests if needed
## Architecture Overview
- **System Components (minimal viable set)**
- Zod schemas (`types/youtube.schemas.ts`): request + response data for comments
- Service (`services/youtube.service.ts`): `getYoutubeComments(params)`
- Tool (`tools/youtube.tool.ts`): `youtube_getComments`
- CLI/controller (`controllers/youtube.controller.ts`, `cli/youtube.cli.ts`): getComments parity with other commands
- **Data Flow (simplified)**
- MCP client calls `youtube_getComments` → tool validates args → service calls VidCap API with API key → transforms/validates response via Zod → MCP returns JSON text to client.
- **Integration Points (essential only)**
- Existing axios `apiClient` with baseURL `https://vidcap.xyz/api/v1` and `X-API-Key` header (`env.VIDCAP_API_KEY`)
- No new env vars; reuse existing `VIDCAP_API_KEY`.
## Implementation Phases
### Phase 1: Core Functionality (YAGNI applied)
1. Define types and schemas (`src/types/youtube.schemas.ts`)
- Add `YoutubeCommentsQuerySchema`
- Fields:
- `url?: string` (url)
- `videoId?: string`
- `order?: enum('time', 'relevance')` default `'time'`
- `format?: enum('plainText', 'html')` default `'plainText'`
- `pageToken?: string`
- `includeReplies?: boolean` default `false`
- `hl?: string` default `'en'`
- Add refine to enforce “either url or videoId required”.
- Add `YoutubeCommentSchema`:
- Minimal safe shape aligned to docs:
- `id: string`
- `videoId: string`
- `textOriginal: string`
- `authorDisplayName: string`
- `likeCount: number`
- `publishedAt: string`
- `totalReplyCount: number`
- `replies: any[]` optional (YAGNI: don’t over-spec replies without stable doc)
- Add `YoutubeCommentsDataSchema`:
- `{ nextPageToken?: string; data: YoutubeCommentSchema[] }`
- Add `YoutubeCommentsResponseSchema` via `successDataSchema(YoutubeCommentsDataSchema)`
2. Implement service method (`src/services/youtube.service.ts`)
- `export const getYoutubeComments = async (
params: z.infer<typeof YoutubeCommentsQuerySchema>
): Promise<z.infer<typeof YoutubeCommentsResponseSchema>>`
- Behavior:
- `GET /youtube/comments` with params
- Log raw response (debug)
- Transform to `{ success: raw.status === 1, data: { nextPageToken, data: [] } | null, error?: string }`
- Accept both `raw.data` and `raw.data.data` nesting patterns for robustness (project already does this)
- Zod-parse into `YoutubeCommentsResponseSchema`
- On errors, mirror other service methods:
- ZodError → validation message + return `{ success: false, data: null, error }`
- Axios errors → include message and log `response.data` if present
- Unknown errors → generic message, null data
3. Register MCP tool (`src/tools/youtube.tool.ts`)
- Import `YoutubeCommentsQuerySchema` and `YoutubeService.getYoutubeComments`
- `server.tool(
'youtube_getComments',
'Get YouTube video comments with optional pagination and replies. Provide either a video URL or a videoId.',
YoutubeCommentsQuerySchema.shape,
async (args) => handleServiceToolExecution(YoutubeService.getYoutubeComments, args, 'youtube_getComments')
)`
- Keep output formatting consistent: JSON.stringify of result.data as text
### Phase 2: Essential Integrations
4. CLI parity (optional but recommended for developer workflow)
- Controller (`src/controllers/youtube.controller.ts`)
- Add `getYoutubeCommentsCli(params: z.infer<typeof YoutubeCommentsQuerySchema>)`
- Follow same pattern as other CLI controllers: call service, return `{ success, data }` or `{ success: false, error }`
- CLI (`src/cli/youtube.cli.ts`)
- Add `youtube getComments` command with options:
- `--url <url>`
- `--videoId <id>`
- `--order <time|relevance>`
- `--format <plainText|html>`
- `--pageToken <token>`
- `--includeReplies` (boolean)
- `--hl <lang>`
- Parse via `YoutubeCommentsQuerySchema`
- Invoke `youtubeController.getYoutubeCommentsCli`
- Print JSON or error
5. Documentation update (`README.md`)
- Add new tool: `youtube_getComments` (args and description)
- Add CLI example:
- `npm run dev:cli -- youtube getComments --url "https://www.youtube.com/watch?v=..." --includeReplies true --order relevance`
- Note pagination via `pageToken` and presence of `nextPageToken` in response
### Phase 3: Performance Optimization (if actually needed)
- Not needed now. Comments payloads are moderate and paginated.
- Optional later: auto-pagination helper at CLI level. YAGNI for now.
## Risk Assessment & Mitigation
- **High-Risk Items**
- API response nesting inconsistency (`data` vs `data.data`)
- Mitigation: parse both shapes (pattern used in existing services)
- Replies structure may vary or be large
- Mitigation: treat replies as `z.array(z.any())` and do not auto-expand replies unless requested (`includeReplies` default false)
- Zod validation failures due to undocumented fields or missing fields
- Mitigation: Keep schema lenient; only validate fields we truly need; allow optional where uncertain
- **Probable Failure Points**
- Missing `VIDCAP_API_KEY` at runtime
- Mitigation: `env.ts` already enforces it; logs clearly on failures
- Bad pagination token
- Mitigation: Service returns `success:false` with meaningful error message from API
- **Mitigation Strategies**
- Log raw responses at debug for troubleshooting
- Maintain consistent error shape (`success:false, data:null, error:string`)
- Validate with zod and fall back gracefully
## Success Criteria
- **Measurable Outcomes**
- New MCP tool `youtube_getComments` appears in the MCP Inspector and executes successfully with required/optional args
- CLI command returns comments JSON with `nextPageToken` when available
- **Performance Benchmarks**
- Single request typical p95 < 2s given remote API; pagination confirmed works
- **Quality Gates**
- `npm run typecheck` passes
- `npm run lint` passes
- Manual tests for:
- url only
- videoId only
- includeReplies true
- order relevance
- format html
- hl non-default (e.g., es)
- pageToken flow
## Concrete Change List (by file)
- `src/types/youtube.schemas.ts`
- Add:
- `YoutubeCommentsQuerySchema` (with refine: require url or videoId)
- `YoutubeCommentSchema`
- `YoutubeCommentsDataSchema`
- `YoutubeCommentsResponseSchema = successDataSchema(YoutubeCommentsDataSchema)`
- `src/services/youtube.service.ts`
- Add `getYoutubeComments(params)`
- `GET /youtube/comments`
- Transform + Zod-parse + robust error handling
- `src/tools/youtube.tool.ts`
- Register `youtube_getComments` tool using shared `handleServiceToolExecution`
- `src/controllers/youtube.controller.ts` (optional but recommended)
- Add `getYoutubeCommentsCli(params)` mirroring style of other CLI controllers
- `src/cli/youtube.cli.ts` (optional but recommended)
- Add `youtube getComments` command with options; validate via schema; call controller; print JSON
- `README.md`
- Add tool + CLI documentation, examples, pagination note
## Manual Test Plan
- MCP Inspector (dev server)
- Call `youtube_getComments` with:
- `{ url: "<video_url>" }`
- `{ videoId: "dQw4w9WgXcQ" }`
- `{ url, includeReplies: true }`
- `{ url, order: "relevance" }`
- `{ url, format: "html" }`
- `{ url, hl: "es" }`
- If `nextPageToken` present, re-call with `pageToken`
- CLI
- `npm run dev:cli -- youtube getComments --url "<url>" --includeReplies true --order relevance`
- Verify JSON includes `nextPageToken`, top-level `data` list
## Brutal Honesty Checklist
- Unrealistic expectations identified?
- No myths of auto-pagination or nested reply modeling; kept simple and manual
- Over-engineering called out?
- Avoided deep reply schema and auto-pagination; replies typed as `any[]`
- Questioned “requirements”?
- Not auto-fetching all pages; optional CLI/controller parity flagged as “recommended,” not mandatory
- Probable failure points identified?
- API nesting variance, pagination token errors, missing key
- Realistic timelines?
- 3–5 hours including docs and review
## YAGNI Application
- Can features be removed?
- Yes, CLI/controller parity can be deferred; reply structure modeling deferred
- Is this solving a real problem?
- Deliver the tool endpoint; skip batch pagination until needed
- Build later when needed?
- Auto-pagination, detailed reply models
- Building for scale we don’t have?
- No; simple single call + pageToken
## KISS Validation
- Simplest solution that works?
- Yes: schema + service + tool
- Can a junior developer understand this?
- Yes; mirrors existing endpoint patterns
- Added complexity for complexity’s sake?
- No; avoided
- Explain in one sentence?
- Add a new MCP tool that calls VidCap’s comments endpoint and returns comments (with optional replies) and nextPageToken.
## DRY Verification
- Duplicating existing functionality?
- No; reusing `successDataSchema` and existing axios client
- Can existing solutions be reused?
- Yes; same error/log patterns as other YouTube methods
- Reinventing the wheel?
- No; consistent with current code style
## Dependencies and Constraints
- Env: `VIDCAP_API_KEY` must be set (already enforced)
- External API contract: https://vidcap.xyz/api-docs/#/YouTube/get_api_v1_youtube_comments
- Transport: No changes needed to MCP/HTTP transports
## Security Considerations
- API key stays in header `X-API-Key` (already in `apiClient`)
- No additional PII handling beyond VidCap’s returned `authorDisplayName`; return data as-is and rely on client usage policies
## Rollback Plan
- Changes are additive; tool can be unregistered by removing code and rebuild
- No schema or API surface breaking changes to existing tools
## Approval Gate
- Proceed once the above plan is accepted
- After implementation, produce a small smoke-test report with sample outputs and confirm MCP Inspector tool visibility
