AskUserQuestionPlus

A MCP server (Streamable HTTP) for asking user questions via a web interface, inspired by the Claude Code AskUserQuestion Tool.

Fork — Continuação de AskUserQuestionPlus com mudanças de produto e documentação: sem timeout forçado na sessão do questionário; limite configurável do corpo JSON em POST /mcp via AUQP_JSON_BODY_LIMIT (padrão 50mb, útil para prompts grandes ou muitas opções); validação e sanitização do payload da ferramenta; e README em português (Brasil) e inglês. Issues e pull requests: neste repositório.

This fork: no forced session timeout, configurable JSON body limit on MCP POST /mcp, safer tool payloads, pt-BR + EN docs—use this repo for issues and PRs.

🌟 Supports Claude Code, Codex, and Gemini CLI!

English | Português (Brasil)

✨ Recursos

🎨 Interface refinada: estilo Claude Code AskUserQuestions, com temas claro e escuro.
⌨️ Uso só com teclado: setas, Tab, Space e Enter para navegação fluida.
📊 Interação rica: escolha única, múltipla escolha, opção recomendada e entrada personalizada (Other).
📝 Markdown nas opções: o texto da pergunta e a description de cada opção aceitam Markdown (code blocks com fonte mono e scroll horizontal, listas, negrito, itálico, links, blockquotes, tabelas GFM). Auto-detecta marcadores; texto simples continua renderizando como antes. HTML é sanitizado com DOMPurify, sem necessidade de mudar o schema MCP.
🔄 Tempo real: mensagens via WebSocket com resposta imediata.
⏱️ Sessão: sem timeout forçado; o usuário envia quando quiser.
📈 Escalável: de 1 a 20 perguntas, com quantidade ilimitada de opções por pergunta.

🚀 Implantação

Parâmetros de inicialização

Parâmetro	Descrição	Padrão	Exemplo
`--port=<porta>`	Porta	3456	`--port=8080`

Variável de ambiente (opcional): AUQP_JSON_BODY_LIMIT — tamanho máximo do corpo JSON no POST /mcp (padrão 50mb). Aumente para SQL longo ou muitas opções.

Execução em primeiro plano

npx ask-user-question-plus

# Porta personalizada
npx ask-user-question-plus -- --port=3456

Execução em segundo plano (recomendado)

Com pm2

Instale o pm2 antes: npm install -g pm2

pm2 start "npx ask-user-question-plus" --name ask-user-question-plus-service

# Com parâmetros
pm2 start "npx ask-user-question-plus -- --port=3456" --name ask-user-question-plus-service

# Parar o serviço
pm2 stop ask-user-question-plus-service

# Windows
pm2 start cmd --name ask-user-question-plus-service -- /c npx ask-user-question-plus

Com Docker

docker compose up -d

⚙️ Configuração

Claude Code

claude mcp add -s user -t http AskUserQuestionPlus http://localhost:3456/mcp

Codex

Adicione em ~/.codex/config.toml:

[mcp_servers.AskUserQuestionPlus]
url = "http://localhost:3456/mcp/"

Ou pela linha de comando:

codex mcp add AskUserQuestionsPlus --url http://localhost:3456/mcp/

~~[MCP] Add support for streamable HTTP MCP servers~~

~~Replace experimental_use_rmcp_client with [features].rmcp_client~~

Gemini CLI

gemini mcp add AskUserQuestionPlus http://localhost:3456/mcp -s user --transport http

⚠️ Atenção: se aparecer [Error: Unrecognized key(s) in object: 'type'] (veja issue #15449):

~~Remova o campo type em ~/.gemini/settings.json.~~

~~Ou aguarde o gemini cli v0.23.0.~~

🕹️ Uso

Fluxo básico

Inicie uma conversa com Claude Code, Codex ou Gemini.
Peça ao modelo para usar a ferramenta, por exemplo: use ask_user_question_plus to ask me 3 questions.
O navegador abre automaticamente o questionário.
Responda com o teclado (setas, Space, Enter) ou com o mouse.
Ao enviar, a aba fecha e as respostas voltam ao modelo.

Atalhos de teclado

Atalho	Função
`↑` `↓`	Mover entre opções / rolar
`←` `→` / `Tab`	Trocar de aba de pergunta
`Space` / `Enter`	Selecionar / desmarcar opção
`Cmd/Ctrl + Enter`	Aba Enviar / enviar respostas

🔧 Definição da ferramenta (Tools)

`ask_user_question_plus`

Schema de entrada (Input):

{
  questions: [
    {
      id: string;              // identificador único da pergunta
      header: string;          // título da aba (recomendado ≤12 caracteres)
      text: string;            // texto da pergunta
      type: "single" | "multiple";  // tipo: única ou múltipla escolha
      options: [
        {
          value: string;        // valor da opção
          label: string;        // texto exibido
          description?: string; // descrição (opcional)
          recommended?: boolean;// marca como recomendada (opcional)
        }
      ]
    }
  ]  // limite: 1–20 perguntas
}

Schema de saída (Output):

{
  "answers": {
    "questionId1": {"value" : "", "other":""},
    "questionId2": {"value" : "", "other":""},
  }
}

💡 Dica: o front-end acrescenta automaticamente a opção "Other" (entrada personalizada) em cada pergunta.

📝 Markdown em `text` e `option.description`

O front-end detecta marcadores comuns de Markdown (cercas triplas de crase para code blocks, backticks para inline code, **negrito**, __sublinhado__, # título, - lista, > citação, [link](url), quebras de linha) e renderiza com marked + DOMPurify. Quando nenhum marcador aparece, o texto é apenas escapado, como antes (compatibilidade total).

Exemplo de payload com SQL em bloco de código:

{
  "questions": [
    {
      "id": "join_style",
      "header": "JOIN",
      "text": "Qual estilo de **JOIN / ON** adotar?",
      "type": "single",
      "options": [
        {
          "value": "multiline_and_aligned",
          "label": "A) Multilinha + AND alinhado",
          "description": "```sql\nINNER JOIN dbo.nfIngressos ing\n    ON  ing.opeCodigo  = ot.opeCodigo\n    AND ing.empCodigo  = ot.empCodigo\n    AND ing.sacCodigo  = ot.sacCodigo\n    AND ing.ingDocumento = ot.opetitDocumento\n```",
          "recommended": true
        }
      ]
    }
  ]
}

Segurança: <script>, <iframe>, style, onerror/onload/onclick e URLs javascript: são sempre removidos pelo DOMPurify, mesmo dentro de blocos de código (que ficam em <pre><code>).

🛠️ Desenvolvimento

Clonar o repositório

git clone https://github.com/anderson-prfilho/BetterAskUserQuestionPlus.git && cd BetterAskUserQuestionPlus

Instalar dependências

npm install

Modo desenvolvimento

npm run dev

Build

npm run build
# npm start

Estrutura de pastas

ask-user-question-plus/
├── src/
│   ├── index.ts           # ponto de entrada
│   ├── ws-service.ts      # WebSocket
│   └── mcp-server.ts      # servidor MCP
├── public/
│   └── index.html         # interface web
├── dist/                  # saída da compilação
└── package.json

🤝 Contribuição

Abra Issues neste fork ou envie pull requests. Bugs e melhorias do upstream podem ser reportados em JoJoJotarou/AskUserQuestionPlus.

📄 Licença

MIT License

🔗 Links relacionados

✨ Features

🎨 Beautiful Interface: Replicates the Claude Code AskUserQuestions style with support for Dark/Light themes.
⌨️ Full Keyboard Control: Seamless navigation using Arrow keys, Tab, Space, and Enter.
📊 Rich Interactions: Supports single choice, multiple choice, recommended options, and custom input ("Other").
📝 Markdown in options: Question text and each option's description accept Markdown (fenced code blocks with mono font and horizontal scroll, lists, bold, italic, links, blockquotes, GFM tables). Auto-detected on common markers; plain strings keep rendering as before. Output HTML is sanitized with DOMPurify — no schema change required on the MCP side.
🔄 Real-time Communication: WebSocket-based messaging for instant feedback.
⏱️ Session duration: No forced timeout; users can complete the form at their own pace.
📈 Scalable: Supports 1 to 20 questions with unlimited options per question.

🚀 Deployment

Startup Parameters

Argument	Description	Default	Example
`--port=<port>`	Server port	3456	`--port=8080`

Optional env: AUQP_JSON_BODY_LIMIT — max JSON body size for POST /mcp (MCP tools/call payloads). Default 50mb. Increase for long SQL text or many/large option strings.

Foreground

npx ask-user-question-plus

# Custom port
npx ask-user-question-plus -- --port=3456

Background (Recommended)

Using pm2

Install pm2 first: npm install -g pm2

pm2 start "npx ask-user-question-plus" --name ask-user-question-plus-service

# With arguments
pm2 start "npx ask-user-question-plus -- --port=3456" --name ask-user-question-plus-service

# Stop service
pm2 stop ask-user-question-plus-service

# Windows
pm2 start cmd --name ask-user-question-plus-service -- /c npx ask-user-question-plus

Using Docker

docker compose up -d

⚙️ Configuration

Claude Code

claude mcp add -s user -t http AskUserQuestionPlus http://localhost:3456/mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.AskUserQuestionPlus]
url = "http://localhost:3456/mcp/"

Or via CLI:

codex mcp add AskUserQuestionsPlus --url http://localhost:3456/mcp/

~~[MCP] Add support for streamable HTTP MCP servers~~

~~Replace experimental_use_rmcp_client with [features].rmcp_client~~

Gemini CLI

gemini mcp add AskUserQuestionPlus http://localhost:3456/mcp -s user --transport http

⚠️ Note: If you encounter [Error: Unrecognized key(s) in object: 'type'] (Issue #15449):

~~Remove the type field in ~/.gemini/settings.json.~~

~~Or wait for gemini cli v0.23.0.~~

🕹️ Usage

Basic Workflow

Start a conversation with Claude, Codex, or Gemini.
Ask the model to use the tool: e.g., "Use ask_user_question_plus to ask me 3 questions."
A browser tab will automatically open with the questionnaire.
Answer using your keyboard (Arrows, Space, Enter) or mouse.
Upon submission, the tab closes, and answers are sent back to the model.

Keyboard Shortcuts

Shortcut	Function
`↑` `↓`	Move between options / Scroll
`←` `→` / `Tab`	Switch between question tabs
`Space` / `Enter`	Select/Deselect option
`Cmd/Ctrl + Enter`	Submit Tab / Submit answers

🔧 Tools Definition

`ask_user_question_plus`

Input Schema:

{
  questions: [
    {
      id: string;              // Unique identifier
      header: string;          // Tab header (Rec. ≤12 chars)
      text: string;            // Question text
      type: "single" | "multiple";  // Question type
      options: [
        {
          value: string;        // Option value
          label: string;        // Option label
          description?: string; // Option description (optional)
          recommended?: boolean;// Recommended flag (optional)
        }
      ]
    }
  ]  // Limit: 1-20 questions
}

Output Schema:

{
  "answers": {
    "questionId1": { "value": "", "other": "" },
    "questionId2": { "value": "", "other": "" }
  }
}

💡 Tip: The "Other" (custom input) option is automatically added by the frontend.

📝 Markdown in `text` and `option.description`

The frontend auto-detects common Markdown markers (triple-backtick fences for code blocks, backticks for inline code, **bold**, __italic__, # heading, - list, > quote, [link](url), line breaks) and renders the text with marked + DOMPurify. When no markers are present, the string is just HTML-escaped, same as before (fully backward compatible).

Example payload with a SQL code block:

{
  "questions": [
    {
      "id": "join_style",
      "header": "JOIN",
      "text": "Which **JOIN / ON** style should we adopt?",
      "type": "single",
      "options": [
        {
          "value": "multiline_and_aligned",
          "label": "A) Multi-line + aligned AND",
          "description": "```sql\nINNER JOIN dbo.nfIngressos ing\n    ON  ing.opeCodigo  = ot.opeCodigo\n    AND ing.empCodigo  = ot.empCodigo\n    AND ing.sacCodigo  = ot.sacCodigo\n    AND ing.ingDocumento = ot.opetitDocumento\n```",
          "recommended": true
        }
      ]
    }
  ]
}

Security: <script>, <iframe>, style, onerror/onload/onclick handlers and javascript: URLs are always stripped by DOMPurify — even inside code blocks (which render as <pre><code>).

🛠️ Development

Clone

git clone https://github.com/anderson-prfilho/BetterAskUserQuestionPlus.git && cd BetterAskUserQuestionPlus

Install Dependencies

npm install

Run Dev Mode

npm run dev

Build

npm run build
# npm start

🤝 Contribution

Contributions are welcome! Open issues on this fork or pull requests. For upstream-only changes, use JoJoJotarou/AskUserQuestionPlus.

📄 License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
assets		assets
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.docker		.env.docker
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

AskUserQuestionPlus

✨ Recursos

🚀 Implantação

Parâmetros de inicialização

Execução em primeiro plano

Execução em segundo plano (recomendado)

Com pm2

Com Docker

⚙️ Configuração

Claude Code

Codex

Gemini CLI

🕹️ Uso

Fluxo básico

Atalhos de teclado

🔧 Definição da ferramenta (Tools)

ask_user_question_plus

📝 Markdown em text e option.description

🛠️ Desenvolvimento

Clonar o repositório

Instalar dependências

Modo desenvolvimento

Build

Estrutura de pastas

🤝 Contribuição

📄 Licença

🔗 Links relacionados

✨ Features

🚀 Deployment

Startup Parameters

Foreground

Background (Recommended)

Using pm2

Using Docker

⚙️ Configuration

Claude Code

Codex

Gemini CLI

🕹️ Usage

Basic Workflow

Keyboard Shortcuts

🔧 Tools Definition

ask_user_question_plus

📝 Markdown in text and option.description

🛠️ Development

Clone

Install Dependencies

Run Dev Mode

Build

🤝 Contribution

📄 License

🔗 Related Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`ask_user_question_plus`

📝 Markdown em `text` e `option.description`

`ask_user_question_plus`

📝 Markdown in `text` and `option.description`

Packages