auq-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2025 Frank Fiegel (frank@glama.ai)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# 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-question-mcp/test.yml)](https://github.com/paulp-o/ask-user-question-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.**
+
+![AUQ Demo](docs/screenshot.png)
+
+---
+
+## What does it do?
+
+Through the 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.
+
+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.
+
+## Why?
+
+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)).
+
+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:
+
+- **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.
+
+---
+
+## 🚀 Quick Start
+
+### Global Installation (Recommended)
+
+```bash
+# Install globally
+npm install -g auq-mcp-server
+
+# Start the TUI
+auq
+```
+
+### Local Installation (Project-specific)
+
+```bash
+# Install in your project
+npm install auq-mcp-server
+
+# Start the TUI from project directory
+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
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "auq": {
+      "command": "npx",
+      "args": ["-y", "auq-mcp-server", "server"]
+    }
+  }
+}
+```
+
+**Restart Claude Desktop** after saving.
+
+### Cursor / Other MCP Clients
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "auq": {
+      "command": "npx",
+      "args": ["-y", "auq-mcp-server", "server"],
+      "env": {}
+    }
+  }
+}
+```
+
+Restart your client after configuration.
+
+---
+
+## ✨ 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
+```
+
+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.
+
+### Commands
+
+```bash
+# you won't likely need these at all
+auq server       # Start MCP server
+auq --version    # Show version
+auq --help       # Show help
+```
+
+---
+
+### Manual session cleanup
+
+Sessions auto-clean after completion or timeout. However, you can manually clean them up if you want to.
+
+```bash
+# Global install
+rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
+rm -rf ~/.local/share/auq/sessions/*                  # Linux
+
+# Local install
+rm -rf .auq/sessions/*
+```
+
+---
+
+## 🚀 Roadmap
+
+- [ ] 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
+
+---
+
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+

package/dist/__tests__/schema-validation.test.js

@@ -0,0 +1,137 @@
+/**
+ * Minimal schema validation tests for Question/Option types
+ * Tests the most common edge cases to catch obvious bugs
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+// Import schemas from server (in real implementation, might extract to validation module)
+const OptionSchema = z.object({
+    description: z.string().optional(),
+    label: z.string(),
+});
+const QuestionSchema = z.object({
+    title: z.string(),
+    options: z.array(OptionSchema).min(1),
+    prompt: z.string(),
+});
+const QuestionsArraySchema = z.array(QuestionSchema).min(1);
+describe("Schema Validation - Edge Cases", () => {
+    describe("Invalid Input (should reject)", () => {
+        it("should reject missing title field", () => {
+            const invalidQuestion = {
+                // title missing
+                options: [{ label: "Option 1" }],
+                prompt: "Test question?",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject empty options array", () => {
+            const invalidQuestion = {
+                title: "Test",
+                options: [], // Empty array
+                prompt: "Test question?",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject missing prompt", () => {
+            const invalidQuestion = {
+                title: "Test",
+                options: [{ label: "Option 1" }],
+                // prompt missing
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject missing options field", () => {
+            const invalidQuestion = {
+                title: "Test",
+                // options missing
+                prompt: "Test question?",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject option with missing label", () => {
+            const invalidQuestion = {
+                title: "Test",
+                options: [
+                    {
+                        description: "A description",
+                        // label missing
+                    },
+                ],
+                prompt: "Test question?",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject empty questions array", () => {
+            const invalidQuestions = [];
+            expect(() => QuestionsArraySchema.parse(invalidQuestions)).toThrow();
+        });
+    });
+    describe("Valid Input (should accept)", () => {
+        it("should accept valid question with title", () => {
+            const validQuestion = {
+                title: "Language",
+                options: [
+                    {
+                        description: "A helpful description",
+                        label: "Option 1",
+                    },
+                ],
+                prompt: "What is your choice?",
+            };
+            expect(() => QuestionSchema.parse(validQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(validQuestion);
+            expect(parsed.title).toBe("Language");
+            expect(parsed.prompt).toBe("What is your choice?");
+            expect(parsed.options).toHaveLength(1);
+        });
+        it("should accept valid question with all fields", () => {
+            const validQuestion = {
+                title: "Framework",
+                options: [
+                    {
+                        description: "A helpful description",
+                        label: "Option 1",
+                    },
+                ],
+                prompt: "What is your choice?",
+            };
+            expect(() => QuestionSchema.parse(validQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(validQuestion);
+            expect(parsed.prompt).toBe("What is your choice?");
+            expect(parsed.options).toHaveLength(1);
+        });
+        it("should accept valid question with description omitted", () => {
+            const validQuestion = {
+                title: "Choice",
+                options: [
+                    {
+                        label: "Option 1",
+                        // description omitted (optional)
+                    },
+                ],
+                prompt: "What is your choice?",
+            };
+            expect(() => QuestionSchema.parse(validQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(validQuestion);
+            expect(parsed.options[0].description).toBeUndefined();
+        });
+        it("should accept multiple valid questions", () => {
+            const validQuestions = [
+                {
+                    title: "First",
+                    options: [{ label: "A" }],
+                    prompt: "Question 1?",
+                },
+                {
+                    title: "Second",
+                    options: [{ label: "B" }, { label: "C" }],
+                    prompt: "Question 2?",
+                },
+            ];
+            expect(() => QuestionsArraySchema.parse(validQuestions)).not.toThrow();
+            const parsed = QuestionsArraySchema.parse(validQuestions);
+            expect(parsed).toHaveLength(2);
+        });
+    });
+});

package/dist/__tests__/server.integration.test.js

@@ -0,0 +1,263 @@
+/**
+ * Integration tests for FastMCP server and SessionManager interaction
+ */
+import { promises as fs } from "fs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { SessionManager } from "../session/index.js";
+describe("Server Integration", () => {
+    let sessionManager;
+    const testBaseDir = "/tmp/auq-test-integration";
+    beforeEach(async () => {
+        // Clean up test directory before each test
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+        sessionManager = new SessionManager({
+            baseDir: testBaseDir,
+            maxSessions: 10,
+            sessionTimeout: 5000, // 5 seconds for integration tests
+        });
+        await sessionManager.initialize();
+    });
+    afterEach(async () => {
+        // Clean up test directory after each test
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+    });
+    describe("Session Creation Integration", () => {
+        it("should create session when ask_user_questions tool is called", async () => {
+            const questions = [
+                {
+                    options: [
+                        { description: "Dynamic language", label: "JavaScript" },
+                        { description: "Static typing", label: "TypeScript" },
+                    ],
+                    prompt: "Which programming language do you prefer?",
+                },
+            ];
+            const sessionId = await sessionManager.createSession(questions);
+            expect(sessionId).toBeDefined();
+            expect(typeof sessionId).toBe("string");
+            // Verify session data integrity
+            const request = await sessionManager.getSessionRequest(sessionId);
+            const status = await sessionManager.getSessionStatus(sessionId);
+            expect(request?.sessionId).toBe(sessionId);
+            expect(request?.questions).toEqual(questions);
+            expect(request?.status).toBe("pending");
+            expect(status?.sessionId).toBe(sessionId);
+            expect(status?.status).toBe("pending");
+            expect(status?.totalQuestions).toBe(questions.length);
+        });
+        it("should handle multiple questions correctly", async () => {
+            const questions = [
+                {
+                    options: [
+                        { description: "Dynamic language", label: "JavaScript" },
+                        { description: "Static typing", label: "TypeScript" },
+                    ],
+                    prompt: "Which programming language?",
+                },
+                {
+                    options: [
+                        { description: "Web application", label: "Web" },
+                        { description: "Command-line tool", label: "CLI" },
+                        { description: "Desktop application", label: "Desktop" },
+                    ],
+                    prompt: "What type of application?",
+                },
+            ];
+            const sessionId = await sessionManager.createSession(questions);
+            const request = await sessionManager.getSessionRequest(sessionId);
+            const status = await sessionManager.getSessionStatus(sessionId);
+            expect(request?.questions).toHaveLength(2);
+            expect(request?.questions[0].prompt).toBe("Which programming language?");
+            expect(request?.questions[1].prompt).toBe("What type of application?");
+            expect(status?.totalQuestions).toBe(2);
+        });
+        it("should create unique sessions for multiple calls", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Test option" }],
+                    prompt: "Test question",
+                },
+            ];
+            const sessionId1 = await sessionManager.createSession(questions);
+            const sessionId2 = await sessionManager.createSession(questions);
+            expect(sessionId1).not.toBe(sessionId2);
+            // Verify both sessions exist and are independent
+            expect(await sessionManager.sessionExists(sessionId1)).toBe(true);
+            expect(await sessionManager.sessionExists(sessionId2)).toBe(true);
+            const request1 = await sessionManager.getSessionRequest(sessionId1);
+            const request2 = await sessionManager.getSessionRequest(sessionId2);
+            expect(request1?.sessionId).toBe(sessionId1);
+            expect(request2?.sessionId).toBe(sessionId2);
+        });
+    });
+    describe("Session Data Persistence", () => {
+        it("should persist session data across manager instances", async () => {
+            const questions = [
+                {
+                    options: [{ description: "Test description", label: "Test option" }],
+                    prompt: "Test question for persistence",
+                },
+            ];
+            // Create session with first manager instance
+            const sessionId = await sessionManager.createSession(questions);
+            // Create new manager instance with same directory
+            const newManager = new SessionManager({ baseDir: testBaseDir });
+            await newManager.initialize();
+            // Verify session data is accessible through new manager
+            const request = await newManager.getSessionRequest(sessionId);
+            const status = await newManager.getSessionStatus(sessionId);
+            expect(request?.sessionId).toBe(sessionId);
+            expect(request?.questions).toEqual(questions);
+            expect(status?.sessionId).toBe(sessionId);
+            expect(status?.totalQuestions).toBe(1);
+        });
+        it("should store session files with correct structure", async () => {
+            const questions = [
+                {
+                    options: [{ description: "Description", label: "Option" }],
+                    prompt: "File structure test",
+                },
+            ];
+            const sessionId = await sessionManager.createSession(questions);
+            const sessionDir = `${testBaseDir}/${sessionId}`;
+            // Verify request.json structure
+            const requestContent = await fs.readFile(`${sessionDir}/request.json`, "utf-8");
+            const requestData = JSON.parse(requestContent);
+            expect(requestData).toHaveProperty("sessionId", sessionId);
+            expect(requestData).toHaveProperty("questions");
+            expect(requestData).toHaveProperty("timestamp");
+            expect(requestData).toHaveProperty("status", "pending");
+            expect(requestData.questions).toEqual(questions);
+            // Verify status.json structure
+            const statusContent = await fs.readFile(`${sessionDir}/status.json`, "utf-8");
+            const statusData = JSON.parse(statusContent);
+            expect(statusData).toHaveProperty("sessionId", sessionId);
+            expect(statusData).toHaveProperty("status", "pending");
+            expect(statusData).toHaveProperty("createdAt");
+            expect(statusData).toHaveProperty("lastModified");
+            expect(statusData).toHaveProperty("totalQuestions", 1);
+        });
+    });
+    describe("Error Handling Integration", () => {
+        it("should handle invalid session directory gracefully", async () => {
+            const invalidManager = new SessionManager({
+                baseDir: "/root/invalid/path",
+            });
+            await expect(invalidManager.initialize()).rejects.toThrow();
+        });
+        it("should handle concurrent session creation", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Option" }],
+                    prompt: "Concurrent test",
+                },
+            ];
+            // Create multiple sessions concurrently
+            const sessionPromises = Array.from({ length: 5 }, () => sessionManager.createSession(questions));
+            const sessionIds = await Promise.all(sessionPromises);
+            // Verify all sessions were created with unique IDs
+            const uniqueIds = new Set(sessionIds);
+            expect(uniqueIds.size).toBe(5);
+            // Verify all sessions exist and are valid
+            for (const sessionId of sessionIds) {
+                expect(await sessionManager.sessionExists(sessionId)).toBe(true);
+                const validation = await sessionManager.validateSession(sessionId);
+                expect(validation.isValid).toBe(true);
+            }
+        });
+    });
+    describe("Session Lifecycle Integration", () => {
+        it("should support complete session lifecycle", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Option" }],
+                    prompt: "Lifecycle test",
+                },
+            ];
+            // Create session
+            const sessionId = await sessionManager.createSession(questions);
+            expect(await sessionManager.sessionExists(sessionId)).toBe(true);
+            // Update status to in-progress
+            await sessionManager.updateSessionStatus(sessionId, "in-progress", {
+                currentQuestionIndex: 0,
+            });
+            let status = await sessionManager.getSessionStatus(sessionId);
+            expect(status?.status).toBe("in-progress");
+            expect(status?.currentQuestionIndex).toBe(0);
+            // Save answers
+            const answers = {
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "Option",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+                sessionId,
+                timestamp: new Date().toISOString(),
+            };
+            await sessionManager.saveSessionAnswers(sessionId, answers);
+            // Verify final state
+            status = await sessionManager.getSessionStatus(sessionId);
+            expect(status?.status).toBe("completed");
+            const savedAnswers = await sessionManager.getSessionAnswers(sessionId);
+            expect(savedAnswers?.answers).toHaveLength(1);
+            expect(savedAnswers?.answers[0].selectedOption).toBe("Option");
+            // Cleanup
+            await sessionManager.deleteSession(sessionId);
+            expect(await sessionManager.sessionExists(sessionId)).toBe(false);
+        });
+        it("should handle session validation correctly", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Option" }],
+                    prompt: "Validation test",
+                },
+            ];
+            const sessionId = await sessionManager.createSession(questions);
+            const validation = await sessionManager.validateSession(sessionId);
+            expect(validation.isValid).toBe(true);
+            expect(validation.issues).toEqual([]);
+            // Corrupt the session by removing a required file
+            const sessionDir = `${testBaseDir}/${sessionId}`;
+            await fs.rm(`${sessionDir}/status.json`);
+            const validation2 = await sessionManager.validateSession(sessionId);
+            expect(validation2.isValid).toBe(false);
+            expect(validation2.issues).toContain("Required file missing: status.json");
+        });
+    });
+    describe("Performance Integration", () => {
+        it("should handle session creation under time limits", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Option" }],
+                    prompt: "Performance test",
+                },
+            ];
+            const startTime = Date.now();
+            const sessionId = await sessionManager.createSession(questions);
+            const endTime = Date.now();
+            // Session creation should be fast (under 100ms)
+            expect(endTime - startTime).toBeLessThan(100);
+            expect(sessionId).toBeDefined();
+        });
+        it("should handle multiple sessions efficiently", async () => {
+            const questions = [
+                {
+                    options: [{ label: "Option" }],
+                    prompt: "Efficiency test",
+                },
+            ];
+            const startTime = Date.now();
+            const sessionIds = await Promise.all(Array.from({ length: 10 }, () => sessionManager.createSession(questions)));
+            const endTime = Date.now();
+            // Creating 10 sessions should be fast (under 500ms)
+            expect(endTime - startTime).toBeLessThan(500);
+            expect(sessionIds).toHaveLength(10);
+            // Verify all sessions were created correctly
+            for (const sessionId of sessionIds) {
+                expect(await sessionManager.sessionExists(sessionId)).toBe(true);
+            }
+        });
+    });
+});

package/dist/add.js

@@ -0,0 +1 @@
+export const add = (a, b) => a + b;

package/dist/add.test.js

@@ -0,0 +1,5 @@
+import { expect, it } from "vitest";
+import { add } from "./add.js";
+it("should add two numbers", () => {
+    expect(add(1, 2)).toBe(3);
+});