auq-mcp-server 0.1.10 → 1.2.5

package/README.md

@@ -144,6 +144,7 @@ args = ["-y", "auq-mcp-server", "server"]
 # Optional: Whitelist additional env vars
 # env_vars = ["AUQ_SESSION_DIR"]
 
+
 # Optional: Working directory
 # cwd = "/Users/<user>/projects"
 ```
@@ -169,6 +170,29 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ---
 
+## 🔌 OpenCode Plugin (Optional)
+
+If you want the OpenCode tool to call `auq ask` directly (without MCP), install
+the plugin package and add it to your OpenCode config.
+
+```bash
+npm install -g auq-mcp-server
+npm install -g @paulp-o/opencode-auq
+```
+
+Add to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@paulp-o/opencode-auq"]
+}
+```
+
+The plugin assumes `auq` is available on `PATH` (global install or equivalent).
+
+---
+
 ## 💻 Usage
 
 ### Starting the CLI tool

package/dist/bin/auq.js

@@ -15,10 +15,9 @@ import { createTUIWatcher } from "../src/tui/session-watcher.js";
 // Handle command-line arguments
 const args = process.argv.slice(2);
 const command = args[0];
-// Display help
 if (command === "--help" || command === "-h") {
     console.log(`
-AUQ MCP Server - Ask User Questions
+AUQ - Ask User Questions
 
 Usage:
   auq [command] [options]
@@ -26,15 +25,42 @@ Usage:
 Commands:
   (default)     Start the TUI (Terminal User Interface)
   server        Start the MCP server (for use with MCP clients)
+  ask <json>    Ask questions via CLI (alternative to MCP)
 
 Options:
   --help, -h    Show this help message
   --version, -v Show version information
 
+ASK COMMAND:
+  Use 'auq ask' when you need to ask the user questions during execution.
+  This allows you to:
+  1. Gather user preferences or requirements
+  2. Clarify ambiguous instructions
+  3. Get decisions on implementation choices as you work
+  4. Offer choices to the user about what direction to take
+
+  FEATURES:
+  - Ask 1-4 structured questions via an interactive terminal interface
+  - Each question includes 2-4 multiple-choice options with explanatory descriptions
+  - Users can always provide custom free-text input as an alternative to predefined options
+  - Single-select mode (default): User picks ONE option or provides custom text
+  - Multi-select mode (multiSelect: true): User can select MULTIPLE options
+
+  USAGE NOTES:
+  - Always provide a descriptive 'title' field (max 12 chars) for each question
+  - Use multiSelect: true when choices are not mutually exclusive
+  - Option labels should be concise (1-5 words)
+  - Questions should end with a question mark
+  - Don't include an 'Other' option - it's provided automatically
+  - Mark one option as recommended.
+
+  Returns a formatted summary of all questions and answers.
+
 Examples:
   auq                    # Start TUI (wait for questions from AI)
   auq server             # Start MCP server (for Claude Desktop, etc.)
-  auq --help             # Show this help message
+  auq ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript (recommended)"}, {"label": "Python"}], "multiSelect": false}]}'
+  echo '{"questions": [...]}' | auq ask   # Pipe JSON to ask command
 
 For more information, visit:
   https://github.com/paulp-o/ask-user-questions-mcp
@@ -43,12 +69,30 @@ For more information, visit:
 }
 // Display version
 if (command === "--version" || command === "-v") {
-    // Read version from package.json
+    // Read version from package.json (handle both local dev and global install)
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = dirname(__filename);
-    const packageJsonPath = join(__dirname, "..", "package.json");
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-    console.log(`auq-mcp-server v${packageJson.version}`);
+    // Try different possible paths for package.json
+    const possiblePaths = [
+        join(__dirname, "..", "package.json"), // dist/../package.json (local dev)
+        join(__dirname, "..", "..", "package.json"), // dist/bin/../../package.json (global install)
+    ];
+    let packageJson = null;
+    for (const path of possiblePaths) {
+        try {
+            packageJson = JSON.parse(readFileSync(path, "utf-8"));
+            break;
+        }
+        catch {
+            // Try next path
+        }
+    }
+    if (packageJson) {
+        console.log(`auq-mcp-server v${packageJson.version}`);
+    }
+    else {
+        console.log("auq-mcp-server v0.1.17"); // Fallback version
+    }
     process.exit(0);
 }
 // Handle 'server' command
@@ -60,6 +104,82 @@ if (command === "server") {
     // Keep process alive
     await new Promise(() => { });
 }
+// Handle 'ask' command
+if (command === "ask") {
+    const { SessionManager } = await import("../src/session/index.js");
+    const { randomUUID } = await import("crypto");
+    const sessionDir = getSessionDirectory();
+    const sessionManager = new SessionManager({ baseDir: sessionDir });
+    await sessionManager.initialize();
+    let questionsJson = args[1];
+    if (!questionsJson) {
+        const chunks = [];
+        const stdin = process.stdin;
+        stdin.setEncoding("utf8");
+        // Only read from stdin if it's piped (not interactive TTY)
+        if (!stdin.isTTY) {
+            for await (const chunk of stdin) {
+                chunks.push(Buffer.from(chunk));
+            }
+            questionsJson = Buffer.concat(chunks).toString("utf8").trim();
+        }
+    }
+    if (!questionsJson) {
+        console.error("Error: Questions JSON required. Provide as argument or pipe to stdin.");
+        console.error("");
+        console.error("Usage:");
+        console.error('  auq ask \'{"questions": [{"prompt": "...", "title": "...", "options": [...], "multiSelect": false}]}\'');
+        console.error("");
+        console.error("Or pipe JSON:");
+        console.error("  echo '{...}' | auq ask");
+        process.exit(1);
+    }
+    try {
+        const input = JSON.parse(questionsJson);
+        const questions = input.questions;
+        if (!questions || !Array.isArray(questions) || questions.length === 0) {
+            console.error("Error: 'questions' array is required and must not be empty.");
+            process.exit(1);
+        }
+        for (let i = 0; i < questions.length; i++) {
+            const q = questions[i];
+            if (!q.prompt || typeof q.prompt !== "string") {
+                console.error(`Error: Question ${i + 1} missing 'prompt' field.`);
+                process.exit(1);
+            }
+            if (!q.title || typeof q.title !== "string") {
+                console.error(`Error: Question ${i + 1} missing 'title' field.`);
+                process.exit(1);
+            }
+            if (!q.options || !Array.isArray(q.options) || q.options.length < 2) {
+                console.error(`Error: Question ${i + 1} requires 'options' array with at least 2 options.`);
+                process.exit(1);
+            }
+            if (q.multiSelect === undefined) {
+                q.multiSelect = false;
+            }
+        }
+        const callId = randomUUID();
+        // Log status to stderr so stdout contains only the formatted response
+        console.error(`[AUQ] Session directory: ${sessionDir}`);
+        console.error(`[AUQ] Waiting for user to answer ${questions.length} question(s)...`);
+        console.error(`[AUQ] User should run 'auq' in another terminal to answer.`);
+        const { formattedResponse, sessionId } = await sessionManager.startSession(questions, callId);
+        console.error(`[AUQ] Session ${sessionId} completed.`);
+        console.log(formattedResponse);
+        process.exit(0);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            console.error("Error: Invalid JSON input.");
+            console.error(error.message);
+        }
+        else {
+            console.error("Error:", error instanceof Error ? error.message : String(error));
+        }
+        process.exit(1);
+    }
+}
 const App = () => {
     const [state, setState] = useState({ mode: "WAITING" });
     const [sessionQueue, setSessionQueue] = useState([]);
@@ -201,12 +321,23 @@ const App = () => {
 // Clear terminal before showing app
 console.clear();
 const { waitUntilExit } = render(React.createElement(App, null));
+// Periodically clear performance measures to prevent memory leak warnings
+// React development mode creates performance marks that can accumulate over time
+const clearPerformanceBuffer = () => {
+    if (typeof performance !== 'undefined' && performance.clearMeasures) {
+        performance.clearMeasures();
+    }
+};
+// Clear performance buffer every 5 minutes to prevent accumulation
+const performanceCleanupInterval = setInterval(clearPerformanceBuffer, 5 * 60 * 1000);
 // Handle Ctrl+C gracefully
 process.on("SIGINT", () => {
+    clearInterval(performanceCleanupInterval);
     process.exit(0);
 });
 // Show goodbye after Ink unmounts
 waitUntilExit().then(() => {
+    clearInterval(performanceCleanupInterval);
     process.stdout.write("\n");
     console.log("👋 Goodbye! See you next time.");
 });

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "0.1.0",
+    "version": "1.2.5",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"
@@ -11,14 +11,19 @@
         "README.md",
         "LICENSE"
     ],
+    "workspaces": [
+        "packages/opencode-plugin"
+    ],
     "scripts": {
-        "build": "tsc",
+        "build": "npm run sync-schemas && tsc",
         "prepare": "npm run build",
         "postinstall": "node scripts/postinstall.cjs",
+        "deploy": "node scripts/deploy.mjs",
         "server": "node dist/src/server.js",
         "start": "tsx src/server.ts",
         "dev": "fastmcp dev src/server.ts",
         "lint": "prettier --check . && eslint . && tsc --noEmit",
+        "sync-schemas": "node scripts/sync-schemas.mjs",
         "test": "vitest run",
         "format": "prettier --write . && eslint --fix ."
     },
@@ -30,21 +35,26 @@
         "terminal"
     ],
     "repository": {
-        "url": "https://github.com/paulp-o/ask-user-question-mcp"
+        "url": "git+https://github.com/paulp-o/ask-user-questions-mcp.git"
     },
     "author": "Paul Park",
-    "homepage": "https://github.com/paulp-o/ask-user-question-mcp",
+    "homepage": "https://github.com/paulp-o/ask-user-questions-mcp",
     "type": "module",
     "license": "MIT",
     "description": "An MCP server that provides a tool to ask a user questions via the terminal",
     "dependencies": {
+        "@inkjs/ui": "^2.0.0",
+        "@modelcontextprotocol/sdk": "1.17.2",
         "@types/uuid": "^10.0.0",
-        "fastmcp": "^1.27.3",
+        "chalk": "^5.6.2",
+        "fastmcp": "^3.23.0",
+        "gradient-string": "^3.0.0",
         "ink": "^6.4.0",
+        "ink-gradient": "^3.0.0",
         "ink-text-input": "^6.0.0",
         "react": "^19.2.0",
         "uuid": "^13.0.0",
-        "zod": "^3.24.4"
+        "zod": "^4.1.13"
     },
     "release": {
         "branches": [
@@ -60,6 +70,7 @@
     "devDependencies": {
         "@eslint/js": "^9.26.0",
         "@tsconfig/node22": "^22.0.1",
+        "@types/node": "^22.13.0",
         "@types/react": "^19.2.2",
         "eslint-config-prettier": "^10.1.3",
         "eslint-plugin-perfectionist": "^4.12.3",

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

@@ -3,26 +3,15 @@
  * 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({
-    options: z.array(OptionSchema).min(1),
-    prompt: z.string(),
-    title: z.string().min(1),
-    multiSelect: z.boolean().optional(),
-});
-const QuestionsArraySchema = z.array(QuestionSchema).min(1);
+import { QuestionSchema, QuestionsSchema, } from "../core/ask-user-questions.js";
 describe("Schema Validation - Edge Cases", () => {
     describe("Invalid Input (should reject)", () => {
         it("should reject missing title field", () => {
             const invalidQuestion = {
                 // title missing
-                options: [{ label: "Option 1" }],
+                options: [{ label: "Option 1" }, { label: "Option 2" }],
                 prompt: "Test question?",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
         });
@@ -31,14 +20,16 @@ describe("Schema Validation - Edge Cases", () => {
                 options: [], // Empty array
                 prompt: "Test question?",
                 title: "Test",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
         });
         it("should reject missing prompt", () => {
             const invalidQuestion = {
-                options: [{ label: "Option 1" }],
+                options: [{ label: "Option 1" }, { label: "Option 2" }],
                 title: "Test",
                 // prompt missing
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
         });
@@ -47,6 +38,7 @@ describe("Schema Validation - Edge Cases", () => {
                 // options missing
                 prompt: "Test question?",
                 title: "Test",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
         });
@@ -57,15 +49,17 @@ describe("Schema Validation - Edge Cases", () => {
                         description: "A description",
                         // label missing
                     },
+                    { label: "Option 2" },
                 ],
                 prompt: "Test question?",
                 title: "Test",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
         });
         it("should reject empty questions array", () => {
             const invalidQuestions = [];
-            expect(() => QuestionsArraySchema.parse(invalidQuestions)).toThrow();
+            expect(() => QuestionsSchema.parse(invalidQuestions)).toThrow();
         });
     });
     describe("Valid Input (should accept)", () => {
@@ -76,15 +70,20 @@ describe("Schema Validation - Edge Cases", () => {
                         description: "A helpful description",
                         label: "Option 1",
                     },
+                    {
+                        description: "Another helpful description",
+                        label: "Option 2",
+                    },
                 ],
                 prompt: "What is your choice?",
                 title: "Language",
+                multiSelect: false,
             };
             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);
+            expect(parsed.options).toHaveLength(2);
         });
         it("should accept valid question with all fields", () => {
             const validQuestion = {
@@ -93,14 +92,19 @@ describe("Schema Validation - Edge Cases", () => {
                         description: "A helpful description",
                         label: "Option 1",
                     },
+                    {
+                        description: "Another helpful description",
+                        label: "Option 2",
+                    },
                 ],
                 prompt: "What is your choice?",
                 title: "Framework",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(validQuestion)).not.toThrow();
             const parsed = QuestionSchema.parse(validQuestion);
             expect(parsed.prompt).toBe("What is your choice?");
-            expect(parsed.options).toHaveLength(1);
+            expect(parsed.options).toHaveLength(2);
         });
         it("should accept valid question with description omitted", () => {
             const validQuestion = {
@@ -109,9 +113,13 @@ describe("Schema Validation - Edge Cases", () => {
                         label: "Option 1",
                         // description omitted (optional)
                     },
+                    {
+                        label: "Option 2",
+                    },
                 ],
                 prompt: "What is your choice?",
                 title: "Choice",
+                multiSelect: false,
             };
             expect(() => QuestionSchema.parse(validQuestion)).not.toThrow();
             const parsed = QuestionSchema.parse(validQuestion);
@@ -120,18 +128,20 @@ describe("Schema Validation - Edge Cases", () => {
         it("should accept multiple valid questions", () => {
             const validQuestions = [
                 {
-                    options: [{ label: "A" }],
+                    options: [{ label: "A" }, { label: "B" }],
                     prompt: "Question 1?",
                     title: "First",
+                    multiSelect: false,
                 },
                 {
                     options: [{ label: "B" }, { label: "C" }],
                     prompt: "Question 2?",
                     title: "Second",
+                    multiSelect: false,
                 },
             ];
-            expect(() => QuestionsArraySchema.parse(validQuestions)).not.toThrow();
-            const parsed = QuestionsArraySchema.parse(validQuestions);
+            expect(() => QuestionsSchema.parse(validQuestions)).not.toThrow();
+            const parsed = QuestionsSchema.parse(validQuestions);
             expect(parsed).toHaveLength(2);
         });
         it("should accept question with multiSelect: true", () => {
@@ -156,15 +166,13 @@ describe("Schema Validation - Edge Cases", () => {
             const parsed = QuestionSchema.parse(singleSelectQuestion);
             expect(parsed.multiSelect).toBe(false);
         });
-        it("should accept question with multiSelect omitted (defaults to undefined)", () => {
+        it("should reject question with multiSelect omitted", () => {
             const defaultQuestion = {
-                options: [{ label: "A" }],
+                options: [{ label: "A" }, { label: "B" }],
                 prompt: "Default single-select",
                 title: "Default",
             };
-            expect(() => QuestionSchema.parse(defaultQuestion)).not.toThrow();
-            const parsed = QuestionSchema.parse(defaultQuestion);
-            expect(parsed.multiSelect).toBeUndefined();
+            expect(() => QuestionSchema.parse(defaultQuestion)).toThrow();
         });
     });
 });

package/dist/src/core/ask-user-questions.js

@@ -0,0 +1,35 @@
+import { SessionManager } from "../session/index.js";
+import { getSessionDirectory } from "../session/utils.js";
+import { AskUserQuestionsParametersSchema, QuestionSchema, QuestionsSchema, } from "../shared/schemas.js";
+// Re-export schemas for backward compatibility
+export { QuestionSchema, QuestionsSchema, AskUserQuestionsParametersSchema };
+export const createAskUserQuestionsCore = (options = {}) => {
+    const baseDir = options.baseDir ?? getSessionDirectory();
+    const sessionManager = options.sessionManager ?? new SessionManager({ baseDir });
+    let initialized = false;
+    const ensureInitialized = async () => {
+        if (initialized)
+            return;
+        await sessionManager.initialize();
+        initialized = true;
+    };
+    const normalizeQuestions = (questions) => questions.map((question) => ({
+        options: question.options.map((option) => ({
+            description: option.description,
+            label: option.label,
+        })),
+        prompt: question.prompt,
+        title: question.title,
+        multiSelect: question.multiSelect,
+    }));
+    const ask = async (questions, callId) => {
+        await ensureInitialized();
+        const parsedQuestions = QuestionsSchema.parse(questions);
+        return sessionManager.startSession(normalizeQuestions(parsedQuestions), callId);
+    };
+    return {
+        ask,
+        cleanupExpiredSessions: () => sessionManager.cleanupExpiredSessions(),
+        ensureInitialized,
+    };
+};

package/dist/src/server.js

@@ -1,14 +1,7 @@
 import { FastMCP } from "fastmcp";
 import { randomUUID } from "crypto";
-import { z } from "zod";
-import { SessionManager } from "./session/index.js";
-import { getSessionDirectory } from "./session/utils.js";
-// Get session directory (auto-detects global vs local install)
-const sessionDir = getSessionDirectory();
-// Log session directory for debugging
-console.error(`[AUQ] Session directory: ${sessionDir}`);
-// Initialize session manager with detected session directory
-const sessionManager = new SessionManager({ baseDir: sessionDir });
+import { AskUserQuestionsParametersSchema, createAskUserQuestionsCore, } from "./core/ask-user-questions.js";
+const askUserQuestionsCore = createAskUserQuestionsCore();
 const server = new FastMCP({
     name: "AskUserQuestions",
     instructions: "This MCP server provides a tool to ask structured questions to the user. " +
@@ -21,43 +14,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.8",
-});
-// Define the question and option schemas
-const OptionSchema = z.object({
-    label: z
-        .string()
-        .describe("The display text for this option that the user will see and select. " +
-        "Should be concise (1-5 words) and clearly describe the choice."),
-    description: z
-        .string()
-        .optional()
-        .describe("Explanation of what this option means or what will happen if chosen. " +
-        "Useful for providing context about trade-offs or implications."),
-});
-const QuestionSchema = z.object({
-    prompt: z
-        .string()
-        .describe("The complete question to ask the user. Should be clear, specific, and end with a question mark. " +
-        "Example: 'Which programming language do you want to use?' " +
-        "If multiSelect is true, phrase it accordingly, e.g. 'Which features do you want to enable?'"),
-    title: z
-        .string()
-        .min(1, "Question title is required. Provide a short summary like 'Language' or 'Framework'.")
-        .describe("Very short label displayed as a chip/tag (max 12 chars). " +
-        "Examples: 'Auth method', 'Library', 'Approach'. " +
-        "This title appears in the interface to help users quickly identify questions."),
-    options: z
-        .array(OptionSchema)
-        .min(2)
-        .max(4)
-        .describe("The available choices for this question. Must have 2-4 options. " +
-        "Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). " +
-        "There should be no 'Other' option, that will be provided automatically."),
-    multiSelect: z
-        .boolean()
-        .describe("Set to true to allow the user to select multiple options instead of just one. " +
-        "Use when choices are not mutually exclusive. Default: false (single-select)"),
+    version: "0.1.17",
 });
 // Add the ask_user_questions tool
 server.addTool({
@@ -85,15 +42,17 @@ server.addTool({
         "- Use multiSelect: true when choices are not mutually exclusive\n" +
         "- Option labels should be concise (1-5 words)\n" +
         "- Questions should end with a question mark\n" +
-        "- Don't include an 'Other' option - it's provided automatically\n\n" +
+        "- Don't include an 'Other' option - it's provided automatically\n" +
+        "- Mark one option as recommended.\n\n" +
         "- If user seems not aware how to answer the question, inform them that they need to install the 'auq' cli tool.\n\n" +
         "Returns a formatted summary of all questions and answers.",
-    execute: async (args, { log }) => {
+    execute: async (args, ctx) => {
+        const { log } = ctx;
         try {
             // Initialize session manager if not already done
-            await sessionManager.initialize();
+            await askUserQuestionsCore.ensureInitialized();
             // Clean up old sessions on startup (non-blocking)
-            sessionManager
+            askUserQuestionsCore
                 .cleanupExpiredSessions()
                 .then((count) => {
                 if (count > 0) {
@@ -107,23 +66,9 @@ server.addTool({
             if (!args.questions || args.questions.length === 0) {
                 throw new Error("At least one question is required");
             }
-            // Convert Zod-validated questions to our internal Question type
-            const questions = args.questions.map((q) => ({
-                options: q.options.map((opt) => ({
-                    description: opt.description,
-                    label: opt.label,
-                })),
-                prompt: q.prompt,
-                title: q.title,
-                multiSelect: q.multiSelect,
-            }));
-            log.info("Starting session and waiting for user answers...", {
-                questionCount: questions.length,
-            });
-            // Start complete session lifecycle - this will wait for user answers
             // Generate a per-tool-call ID and persist it with the session
             const callId = randomUUID();
-            const { formattedResponse, sessionId } = await sessionManager.startSession(questions, callId);
+            const { formattedResponse, sessionId } = await askUserQuestionsCore.ask(args.questions, callId);
             log.info("Session completed successfully", { sessionId, callId });
             // Return formatted response to AI model
             return {
@@ -147,15 +92,7 @@ server.addTool({
             };
         }
     },
-    parameters: z.object({
-        questions: z
-            .array(QuestionSchema)
-            .min(1)
-            .max(4)
-            .describe("Questions to ask the user (1-4 questions). " +
-            "Each question must include: prompt (full question text), title (short label, max 12 chars), " +
-            "options (2-4 choices with labels and descriptions), and multiSelect (boolean)."),
-    }),
+    parameters: AskUserQuestionsParametersSchema,
 });
 // Start the server with stdio transport
 server.start({