ask-user-mcp-app: Instructions file for Codex

Agent Guide: ask-user-mcp-app

This document helps AI agents understand and navigate the codebase efficiently.

Quick Overview

This is an MCP App that provides an ask_user tool for AI agents to ask users multiple questions with tab-based navigation and keyboard support. The UI renders inline in the host client (Claude, ChatGPT, etc.).

Key features:

• Multi-question tabs: Ask multiple questions displayed as navigable tabs
• Keyboard navigation: Tab/Shift+Tab for tabs, Arrow keys for options, Enter to select/submit
• "Other" input handling: When user clicks "Other", textbox auto-focuses; Arrow keys work for editing; Tab/Escape blur the input
• Auto-navigation: Single-select questions auto-advance to next tab
• Response format: question -> answer format for clear output

Documentation Requirements

IMPORTANT: You MUST update the documentation when making changes to the codebase.

Update README.md when:

• Adding or modifying tool parameters/schema
• Changing installation or usage instructions
• Adding new features users need to know about
• Modifying CLI commands or flags
• Changing default behavior

Update AGENTS.md when:

• Adding or modifying files in the project structure
• Changing implementation patterns or architecture
• Adding new common tasks or workflows
• Updating build output or dependencies
• Discovering new debugging tips

This ensures both users and future agents have accurate, up-to-date information.

Project Structure

ask-user-mcp-app/
├── server.ts              # MCP server - tool + resource registration
├── main.ts                # Entry point - HTTP and stdio transports
├── landing.ts             # Self-contained HTML for GET / landing page
├── api/
│   └── index.ts           # Vercel serverless entry (wires /, /mcp, /health)
├── mcp-app.html           # UI entry point (Vite input)
├── src/
│   ├── mcp-app.tsx        # Main React component - multi-question state management
│   ├── components/        # UI components (all use TailwindCSS)
│   │   ├── TabBar.tsx           # Pill-style tab navigation with progress indicator
│   │   ├── QuestionPanel.tsx    # Renders single question with refined card styling
│   │   ├── SubmitTab.tsx        # Review page with staggered animations
│   │   ├── QuestionHeader.tsx   # Question text with optional subtitle
│   │   ├── OptionButton.tsx     # Elegant option cards with hover/selection states
│   │   ├── OptionList.tsx       # List of OptionButtons with focusedIndex
│   │   ├── OtherInput.tsx       # "Other" option with text input; imperatively focuses on toggle, blurs on Tab/Escape
│   │   ├── SubmitButton.tsx     # Primary action button with accent color
│   │   └── index.ts             # Barrel export
│   ├── hooks/             # Custom React hooks
│   │   ├── useTabNavigation.ts    # Tab/Shift+Tab & arrow key tab navigation; Tab works even when focused on input
│   │   ├── useOptionNavigation.ts # Arrow key option navigation, Enter/Space select
│   │   └── useWindowFocus.ts      # Tracks window focus state for conditional focus outlines
│   ├── types/index.ts     # TypeScript interfaces (QuestionConfig, MultiQuestionState)
│   └── styles/app.css     # Tailwind directives + CSS variables
├── tsconfig.json          # Browser TypeScript (for Vite/React)
├── tsconfig.server.json   # Server TypeScript (for Node.js)
├── vite.config.ts         # Vite config with viteSingleFile plugin
├── tailwind.config.js     # TailwindCSS config with theme colors
└── postcss.config.js      # PostCSS config for Tailwind