auq-mcp-server 0.1.5 → 0.1.7

package/README.md

@@ -1,36 +1,64 @@
+![AUQ Demo](media/demo.png)
+
 # AUQ - ask-user-questions MCP
 
 [![npm version](https://img.shields.io/npm/v/auq-mcp-server.svg)](https://www.npmjs.com/package/auq-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/paulp-o/ask-user-questions-mcp/test.yml)](https://github.com/paulp-o/ask-user-questions-mcp/actions)
-
-**A lightweight MCP server & CLI tool that allows your LLMs to ask questions to you in a clean, separate space with great terminal UX.**
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en-US/install-mcp?name=ask-user-questions&config=eyJlbnYiOnt9LCJjb21tYW5kIjoibnB4IC15IGF1cS1tY3Atc2VydmVyIHNlcnZlciJ9)
 
-![AUQ Demo](docs/screenshot.png)
+**A lightweight MCP server & CLI tool that allows your LLMs to ask questions to you in a clean, separate space with great terminal UX. Made for multi-agent parallel coding workflows.**
 
 ---
 
 ## What does it do?
 
-Through this MCP server, your LLM can generate question sets consisting of multiple-choice, single-choice, and free-text questions (with an "Other" option for custom input) while coding or working, and wait for your answers.
+This MCP server lets your AI assistants generate clarifying questions consisting of multiple-choice/single-choice questions (with an "Other" option for custom input) while coding or working, and wait for your answers through a separate CLI tool without messing up your workflow.
 
-You can keep the `auq` CLI running in advance, or start it when questions are pending. With simple arrow key navigation, you can select answers and send them back to the AI—all within a clean terminal interface.
+You can keep the CLI running in advance, or start it when questions are pending. With simple arrow key navigation, you can select answers and send them back to the AI—all within a clean terminal interface.
 
-## Why?
+## Background
 
-In AI-assisted coding, **clarifying questions** have always been recognized as a powerful prompt engineering technique to overcome LLM hallucination and generate more contextually appropriate code ([research paper](https://arxiv.org/abs/2308.13507)).
+In AI-assisted coding, guiding LLMs to ask **clarifying questions** have been widely recognized as a powerful prompt engineering technique to overcome LLM hallucination and generate more contextually appropriate code [1].
 
-On October 18th, Claude Code 2.0.21 introduced an internal `ask-user-question` tool, and I loved this feature. Inspired by it, I created this project to overcome what I saw as a few limitations:
+On October 18th, Claude Code 2.0.21 introduced an internal `ask-user-question` tool. Inspired by it, I decided to build a similar tool that is:
 
 - **Tool-agnostic** - Works with any MCP client (Claude Desktop, Cursor, etc.)
 - **Non-invasive** - Doesn't heavily integrate with your coding CLI workflow or occupy UI space
 - **Multi-agent friendly** - Supports receiving questions from multiple agents simultaneously in parallel workflows
 
-This is AUQ—a human-AI question-answer loop tool designed for modern AI coding workflows.
+---
+
+## ✨ Features
+
+<https://github.com/user-attachments/assets/3a135a13-fcb1-4795-9a6b-f426fa079674>
+
+### 🖥️ CLI-Based
+
+- **Lightweight**: Adds only ~150 tokens to your context per question
+- **SSH-compatible**: Use over remote connections
+- **Fast**: Instant startup, minimal resource usage
+
+### 📦 100% Local
+
+All information operates based on your local file system. No data leaves your machine.
+
+### 🔄 Resumable & Stateless
+
+The CLI app doesn't need to be running in advance. Whether the model calls the MCP first and you start the CLI later, or you keep it running—you can immediately answer pending questions in FIFO order.
+
+### ❌ Question Set Rejection with Feedback Loop
+
+When the LLM asks about the wrong domain entirely, you can reject the question set, optionally providing the reason to the LLM. The rejection feedback is sent back to the LLM, allowing it to ask more helpful questions or align on what's important for the project.
+
+### 📋 Question Set Queuing
+
+Recent AI workflows often use parallel sub-agents for concurrent coding. AUQ handles multiple simultaneous LLM calls gracefully—when a new question set arrives while you're answering another, it's queued and processed sequentially. Perfect for multi-agent parallel coding workflows.
 
 ---
 
-## 🚀 Quick Start
+# Setup Instructions
+
+## 🚀 Step 1: Setup CLI
 
 ### Global Installation (Recommended)
 
@@ -53,13 +81,13 @@ npx auq
 ```
 
 **Session Storage:**
+
 - **Global install**: `~/Library/Application Support/auq/sessions` (macOS), `~/.local/share/auq/sessions` (Linux)
 - **Local install**: `.auq/sessions/` in your project root
-- **Override**: Set `AUQ_SESSION_DIR` environment variable
 
 ---
 
-## 🔌 MCP Server Configuration
+## 🔌 Step 2: Setup MCP Server
 
 ### Cursor
 
@@ -91,30 +119,6 @@ Add to `.mcp.json` in your project root (for team-wide sharing):
 
 Or add to `~/.claude.json` for global access across all projects.
 
-**With environment variables:**
-
-```json
-{
-  "mcpServers": {
-    "ask-user-questions": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "auq-mcp-server", "server"],
-      "env": {
-        "AUQ_SESSION_DIR": "${AUQ_SESSION_DIR}"
-      }
-    }
-  }
-}
-```
-
-**Manage servers:**
-```bash
-claude mcp list              # View all servers
-claude mcp get ask-user-questions   # Server details
-claude mcp remove ask-user-questions  # Remove server
-```
-
 **Verify setup:** Type `/mcp` in Claude Code to check server status.
 
 ### Codex CLI
@@ -165,33 +169,13 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ---
 
-## ✨ Features
-
-### 🖥️ CLI-Based
-- **Lightweight**: Adds only ~150 tokens to your context per question
-- **SSH-compatible**: Use over remote connections
-- **Fast**: Instant startup, minimal resource usage
-
-### 📦 100% Local
-All information operates based on your local file system. No data leaves your machine.
-
-### 🔄 Resumable & Stateless
-The CLI app doesn't need to be running in advance. Whether the model calls the MCP first and you start the CLI later, or you keep it running—you can immediately answer pending questions in FIFO order.
-
-### ❌ Question Set Rejection with Feedback Loop
-When the LLM asks about the wrong domain entirely, you can reject the question set, optionally providing the reason to the LLM. The rejection feedback is sent back to the LLM, allowing it to ask more helpful questions or align on what's important for the project.
-
-### 📋 Question Set Queuing
-Recent AI workflows often use parallel sub-agents for concurrent coding. AUQ handles multiple simultaneous LLM calls gracefully—when a new question set arrives while you're answering another, it's queued and processed sequentially. Perfect for multi-agent parallel coding workflows.
-
----
-
 ## 💻 Usage
 
 ### Starting the CLI tool
 
 ```bash
-auq
+auq  # if you installed globally
+npx auq  # if you installed locally
 ```
 
 Then just start working with your coding agent or AI assistant. You may prompt to ask questions with the tool the agent got; it will mostly just get what you mean.
@@ -227,17 +211,17 @@ rm -rf .auq/sessions/*
 - [ ] Light & dark mode themes
 - [ ] MCP prompt mode switch (Anthropic style / minimal)
 - [ ] Custom color themes
-- [ ] Question history/recall
 - [ ] Multi-language support
-- [ ] Audio notifications (optional)
-- [ ] Export answers to file
+- [ ] Audio notifications on new question
+- [ ] Simple option to prompt the LLM to/not ask more questions after answering.
+- [ ] Optional 'context' field privided by the LLM, that describes the context of the questions - will be useful for multi-agent coding
 
 ---
 
-
 ## 📄 License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
+[1] arXiv:2308.13507 <https://arxiv.org/abs/2308.13507>

package/dist/bin/auq.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// import { exec } from "child_process";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -167,14 +168,19 @@ const App = () => {
         }
     });
     // Show toast notification
-    const showToast = (message, type = "success") => {
-        setToast({ message, type });
+    const showToast = (message, type = "success", title) => {
+        setToast({ message, type, title });
     };
     // Handle session completion
-    const handleSessionComplete = (wasRejected = false) => {
+    const handleSessionComplete = (wasRejected = false, rejectionReason) => {
         // Show appropriate toast
         if (wasRejected) {
-            showToast("Question set rejected", "info");
+            if (rejectionReason) {
+                showToast(`Rejection reason: ${rejectionReason}`, "info", "Question set rejected");
+            }
+            else {
+                showToast("", "info", "Question set rejected");
+            }
         }
         else {
             showToast("✓ Answers submitted successfully!", "success");
@@ -207,7 +213,7 @@ const App = () => {
     return (React.createElement(Box, { flexDirection: "column", paddingX: 1 },
         React.createElement(Header, { pendingCount: sessionQueue.length }),
         toast && (React.createElement(Box, { marginBottom: 1, marginTop: 1 },
-            React.createElement(Toast, { message: toast.message, onDismiss: () => setToast(null), type: toast.type }))),
+            React.createElement(Toast, { message: toast.message, onDismiss: () => setToast(null), type: toast.type, title: toast.title }))),
         mainContent,
         showSessionLog && (React.createElement(Box, { marginTop: 1 },
             React.createElement(Text, { dimColor: true },

package/dist/src/server.js

@@ -21,7 +21,7 @@ const server = new FastMCP({
         "returning formatted responses for continued reasoning. " +
         "Each question supports 2-4 multiple-choice options with descriptions, and users can always provide custom text input. " +
         "Both single-select and multi-select modes are supported.",
-    version: "0.1.0",
+    version: "0.1.7",
 });
 // Define the question and option schemas
 const OptionSchema = z.object({

package/dist/src/tui/components/StepperView.js

@@ -117,9 +117,9 @@ export const StepperView = ({ onComplete, sessionId, sessionRequest, }) => {
         try {
             const sessionManager = new SessionManager({ baseDir: getSessionDirectory() });
             await sessionManager.rejectSession(sessionId, reason);
-            // Call onComplete with rejection flag
+            // Call onComplete with rejection flag and reason
             if (onComplete) {
-                onComplete(true);
+                onComplete(true, reason);
             }
         }
         catch (error) {

package/dist/src/tui/components/Toast.js

@@ -4,7 +4,7 @@ import React, { useEffect } from "react";
  * Toast component for brief non-blocking notifications
  * Auto-dismisses after specified duration (default 2000ms)
  */
-export const Toast = ({ message, type = "success", onDismiss, duration = 2000, }) => {
+export const Toast = ({ message, type = "success", onDismiss, duration = 2000, title, }) => {
     // Auto-dismiss after duration
     useEffect(() => {
         const timer = setTimeout(() => {
@@ -14,6 +14,7 @@ export const Toast = ({ message, type = "success", onDismiss, duration = 2000, }
     }, [duration, onDismiss]);
     // Color based on type
     const color = type === "success" ? "green" : type === "error" ? "red" : "cyan";
-    return (React.createElement(Box, { borderColor: color, borderStyle: "round", paddingX: 2, paddingY: 0.5 },
-        React.createElement(Text, { bold: true, color: color }, message)));
+    return (React.createElement(Box, { borderColor: color, borderStyle: "round", paddingX: 2, paddingY: 0, flexDirection: "column" },
+        title && (React.createElement(Text, { bold: true, color: color }, title)),
+        React.createElement(Text, { color: color }, message)));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auq-mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "main": "dist/index.js",
   "bin": {
     "auq": "dist/bin/auq.js"