ask-user-questions

An MCP (Model Context Protocol) tool that allows AI models to ask users questions via a local web interface, enabling human-in-the-loop interactions.

中文文档

Features

• Daemon architecture: Independent background process for HTTP/WS, supports multiple MCP clients simultaneously
• Batch questions: Up to 4 sub-questions per call, with single/multi-select and free text
• Rich options: Options support label, description, and recommended flags
• Free text: Every sub-question always includes an "Other" free text input
• Routed navigation: Home page with pending questions + history; detail page for each question
• Internationalization: 5 languages (English, 中文, 한국어, 日本語, Русский)
• Dark mode: System / Light / Dark themes
• Responsive: Desktop and mobile friendly
• Configurable: Timeout, notification toggle, auto-open browser toggle

Quick Start

1. Configure MCP Client

ask-user-questions provides an MCP STDIO server as a tool interface, which can connect to any MCP client you prefer, such as Claude Desktop or VS Code.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ask-user-questions": {
      "command": "npx",
      "args": ["ask-user-questions"]
    }
  }
}

2. Get Started

1. When the model invokes the ask_user tool during a conversation, the browser interface will automatically open to display the question.
2. Use the browser interface to view pending questions, history, and details for each question, then submit your answers.
3. The model receives your responses in real time, enabling seamless human-in-the-loop interaction.

MCP Tool

ask_user

Ask the user questions and wait for their response. Supports batch questions (1–4 sub-questions), each with configurable options and multi-select mode. An "Other" free text input is always available—no need to add it manually.

Parameters:

Parameter	Type	Required	Description
questions	SubQuestion[]	✅	Array of 1–4 sub-questions

SubQuestion:

Field	Type	Required	Description
question	string	✅	Question text
multiSelect	boolean	❌	Allow multiple selections (default false)
options	Option[]	❌	Preset options (omit for free text only)

Option:

Field	Type	Required	Description
label	string	✅	Option label
description	string	❌	Option description
recommended	boolean	❌	Mark as recommended

Example:

{
  "name": "ask_user",
  "arguments": {
    "questions": [
      {
        "question": "Which API style do you prefer?",
        "options": [
          { "label": "Composition API", "recommended": true },
          { "label": "Options API" }
        ]
      },
      {
        "question": "Which features do you need?",
        "multiSelect": true,
        "options": [
          { "label": "TypeScript", "description": "Add type support" },
          { "label": "i18n", "description": "Internationalization" },
          { "label": "Dark Mode" }
        ]
      }
    ]
  }
}

Configuration

Config file: ~/.ask-user-questions/config.json (also editable via the Web UI settings panel).

{
  "timeout": 0,
  "notification": true,
  "autoOpenBrowser": true
}

Option	Type	Default	Description
timeout	number	0	Timeout for waiting (ms), 0 = no timeout
notification	boolean	true	Show desktop notifications
autoOpenBrowser	boolean	true	Auto-open browser

How It Works

┌──────────┐  stdio  ┌──────────┐  HTTP   ┌────────────────┐  WebSocket  ┌──────────┐
│ AI Model │◄───────►│ MCP STDIO│────────►│ Daemon Server  │◄───────────►│ Web App  │
│ (Claude, │         │ (bin.mjs)│ proxy   │ (daemon.mjs)   │             │ (Browser)│
│  GPT...) │         └──────────┘         │ localhost:13390│             └──────────┘
└──────────┘                              └────────────────┘
                                          ▲ HTTP proxy  ▲
┌──────────┐  stdio  ┌──────────┐         │             │
│ AI Model │◄───────►│ MCP STDIO│─────────┘             │
│ (another) │         │ (bin.mjs)│                       │
└──────────┘         └──────────┘               ┌───────┴──────┐
                                                │    Store     │
                                                │  (in-memory) │
                                                └──────────────┘

1. First MCP launch: bin.mjs auto-spawns a background daemon daemon.mjs (HTTP + WebSocket server on port 13390)
2. Subsequent MCP launches: Detects the daemon is already running and reuses it
3. All MCP instances proxy to the daemon's Store via HTTP API (create questions + long-poll for answers)
4. The daemon pushes real-time events to the browser via WebSocket
5. The daemon detects browser presence via WebSocket connection count—only opens the browser when no clients are connected

Development

Prerequisites

• Node.js >= 20
• pnpm >= 9

Local Development

# Install dependencies
pnpm install

# Start App dev server (with HMR)
pnpm dev

# Start Server dev server (HTTP only)
pnpm dev:server

# Build all packages
pnpm build

# Type checking
pnpm typecheck

Project Structure

ask-user-questions/
├── packages/
│   ├── server/       # Daemon + MCP Shell + HTTP Server
│   │   └── src/
│   │       ├── bin.ts       # MCP entry: ensure daemon + start MCP STDIO
│   │       ├── daemon.ts    # Daemon entry: background HTTP+WS server
│   │       ├── server.ts    # Hono + @hono/node-ws HTTP/WS server
│   │       ├── mcp.ts       # MCP stdio + tool definitions (HTTP API proxy)
│   │       ├── store.ts     # In-memory state + event pub/sub
│   │       ├── config.ts    # Config file management
│   │       ├── notify.ts    # Desktop notifications + browser management
│   │       ├── types.ts     # Type definitions
│   │       └── index.ts     # Public API exports
│   └── app/          # Vue 3 Web UI
│       └── src/
│           ├── App.vue              # Shell layout (header + router-view)
│           ├── router.ts            # Vue Router config
│           ├── pages/               # Page components
│           │   ├── home.vue         # Home: pending list + history
│           │   └── question-detail.vue # Question detail page
│           ├── components/          # UI components
│           │   ├── question-card.vue  # Question card (batch sub-questions)
│           │   └── settings-panel.vue # Settings panel
│           ├── composables/         # Vue composables
│           │   ├── use-questions.ts  # Question state + WebSocket
│           │   └── use-dark-mode.ts  # Dark mode
│           └── lib/
│               ├── api.ts           # API client + WebSocket
│               └── i18n.ts          # i18n (5 languages)
├── docs/             # Architecture docs
├── .github/workflows # CI/CD
└── pnpm-workspace.yaml

See Architecture (English) | 架构文档 (中文) for details.

Publishing

This project uses GitHub Actions + npm provenance (OIDC):

# 1. Bump version
cd packages/server
npm version patch  # or minor / major

# 2. Push tag
git push --follow-tags

# 3. GitHub Actions auto-builds and publishes to npm

License

MIT