ask-question-mcp

Desktop multiple-choice over MCP — a local stdio server that opens a real dialog (ask_multiple_choice) on any compatible host. Works text-only (click / type); TTS/STT are optional extras.

Linux	Windows	Agents
Gtk4/Adw · text-first, optional voice	Phase 1 tkinter · text-only	Full contract → docs/AGENTS.md

Demo · SETUP · Dependencies · Security (3-year fix window) · Maintainers

Use at your own risk. Heavily AI-facilitated; runs on your display. Voice is optional. No warranty — LICENSE. Report problems via GitHub Issues.

---

Quick start (Linux)

sudo apt install -y python3 python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 zenity
curl -LsSf https://astral.sh/uv/install.sh | sh   # if needed
git clone https://github.com/DynamicDevices/ask-question-mcp.git
cd ask-question-mcp && uv sync
uv run ask-question-install --host cursor --skill

Then Developer: Reload Window. Ask the agent for check_setup, then a smoke ask_multiple_choice. Leave TTS/STT unset unless you want voice.

Windows (text-only): docs/WINDOWS.md — same install command works with uv.exe.

---

Configuration

Prefer the installer above. Manual stdio launch — use an absolute uv (command -v uv); GUI hosts often miss ~/.local/bin.

"ask-question": {
  "command": "/home/YOU/.local/bin/uv",
  "args": [
    "run",
    "--directory",
    "/absolute/path/to/ask-question-mcp",
    "ask-question-mcp"
  ]
}

Default is text-only. Optional voice (env — omit entirely if you only want click/type):

"env": {
  "ASK_QUESTION_TTS_URL": "http://127.0.0.1:8200",
  "ASK_QUESTION_STT_URL": "http://127.0.0.1:8201/transcribe"
}

Host	Where
Any stdio MCP host	Same JSON shape under that host’s mcpServers / MCP config
Cursor	~/.cursor/mcp.json · Win: %USERPROFILE%\.cursor\mcp.json
Claude Code	claude mcp add --transport stdio … or project .mcp.json — @jackghx
Claude Desktop	mcpServers in the app config JSON; quit + relaunch

Full env / prefs: SETUP.md. Never commit tokens.

---

Features

• Radiolist / checklist; recommended option first; options capped at 8
• Keyboard: 1–8 select · Enter OK · Esc cancel (footer hint; see docs/AGENTS.md — Dialog UX)
• Remembers last dialog size (prefs.window; position on Windows; size-only on typical Wayland)
• Windows: scrollable option list
• Danger chrome; OK/Enter briefly armed (~1s / ~4s)
• Something else is always available (type, or Speak→STT when configured)
• Works text-only without TTS/STT; lean JSON results by default
• Optional TTS / mic answers / acks (auto-listen and acks off until opted in)
• Optional PipeWire media duck while speaking/listening
• Agent skill (ask-multiple-choice) so models use the dialog, not markdown A/B/C
• One-shot wiring: uv run ask-question-install --host cursor --skill

Packages & audio matrix: DEPENDENCIES.md.

---

Tested platforms

Setup	Host	UI	Voice	Status
Ubuntu 24.04 + GNOME + PipeWire	Cursor	Yes	Yes	Verified (2026-07)
Same stack	Claude Code	Yes	Text-only	Verified (2026-07) — @jackghx
Windows 10/11 + tkinter	Cursor	Text	No	Phase 1 — not yet reported
macOS / headless CI	—	No	No	Unsupported / N/A

More rows & how to report: CONTRIBUTING.md.

---

Smoke test

cd /absolute/path/to/ask-question-mcp
uv run python -c "
from ask_question_mcp.zenity_ask import ask_zenity
print(ask_zenity(
    'Smoke?',
    [{'id':'a','label':'OK (recommended)'},{'id':'b','label':'Other'}],
    recommended_id='a', agent='smoke',
))
"

Keyboard check in the dialog: press 2, wait for OK to arm, Enter. Esc cancels.

Troubleshooting: docs/AGENTS.md · SETUP.md.

---

Contributing

CONTRIBUTING.md · SECURITY.md · docs/CRA-COMPLIANCE.md

Copyright © 2026 Dynamic Devices Ltd.