mcp-git

--- description: 'APPLY when working with mcp-question package TO understand package structure, architecture, available tools, and development guidelines' globs: alwaysApply: true --- # @ver0/mcp-question Overview ## Context - This rule is injected whenever files under `packages/mcp-question` are referenced. - It gives the AI a quick mental model of the package so it can navigate and edit confidently. - Use it for orientation; it is not exhaustive documentation. ## Core Idea `@ver0/mcp-question` is an **MCP (Model Context Protocol)** server that enables **AI agents to ask users questions** through an interactive terminal interface. It spawns new terminal windows with user-friendly questionnaires and returns structured responses. Supports both **open-ended text questions** and **multiple choice questions** with automatic "Other" option for custom responses. ## Key Directories ```text src/ index.ts // Server bootstrap + tool registration types.ts // Shared type definitions tools/ ask-question.ts // Main tool implementation with Zod schemas terminal/ terminal.ts // Terminal spawning and process management runner.mts // Questionnaire runner executed in spawned terminal ``` ## Question Types **Open Questions:** - Free-text input with validation (min/max length) - Optional placeholder text - Supports multiline responses **Multiple Choice Questions:** - Single or multiple selection modes - Automatic "Other" option (unless disabled with `allowOwnVariant: false`) - Custom text input when "Other" is selected - Validation for min/max selections ## Tool Interface The package exposes a single MCP tool: `ask-question` **Input Schema:** - `questions`: Array of 1-10 questions (mixed types allowed) - Each question has: `id`, `prompt`, optional `description` - Validation rules and defaults configurable per question **Response Format:** - `responses`: Array of user answers - `cancelled`: Boolean if user cancelled - `timedOut`: Boolean if process timed out - `customText`: String when user selected "Other" option ## Development Guidelines - Keep changes minimal & focused on user interaction patterns. - Validate **all** user inputs with clear error messages. - Terminal spawning is **platform-specific** (macOS/Windows/Linux). - All questionnaire data flows through temporary JSON files. - Process management handles timeouts and graceful cleanup. - Respect project-wide code quality & comment standards. ## Gotchas - Terminal spawning requires platform-specific commands. - Temporary files are auto-cleaned but process crashes may leave artifacts. - User can cancel questionnaire at any time with Ctrl+C. - 5-minute timeout prevents infinite waiting. - Multiple choice questions **always** include "Other" option unless explicitly disabled.