auq-mcp-server 0.1.0

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

@@ -0,0 +1,170 @@
+/**
+ * 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({
+    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);
+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 = {
+                options: [], // Empty array
+                prompt: "Test question?",
+                title: "Test",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject missing prompt", () => {
+            const invalidQuestion = {
+                options: [{ label: "Option 1" }],
+                title: "Test",
+                // prompt missing
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject missing options field", () => {
+            const invalidQuestion = {
+                // options missing
+                prompt: "Test question?",
+                title: "Test",
+            };
+            expect(() => QuestionSchema.parse(invalidQuestion)).toThrow();
+        });
+        it("should reject option with missing label", () => {
+            const invalidQuestion = {
+                options: [
+                    {
+                        description: "A description",
+                        // label missing
+                    },
+                ],
+                prompt: "Test question?",
+                title: "Test",
+            };
+            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 = {
+                options: [
+                    {
+                        description: "A helpful description",
+                        label: "Option 1",
+                    },
+                ],
+                prompt: "What is your choice?",
+                title: "Language",
+            };
+            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 = {
+                options: [
+                    {
+                        description: "A helpful description",
+                        label: "Option 1",
+                    },
+                ],
+                prompt: "What is your choice?",
+                title: "Framework",
+            };
+            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 = {
+                options: [
+                    {
+                        label: "Option 1",
+                        // description omitted (optional)
+                    },
+                ],
+                prompt: "What is your choice?",
+                title: "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 = [
+                {
+                    options: [{ label: "A" }],
+                    prompt: "Question 1?",
+                    title: "First",
+                },
+                {
+                    options: [{ label: "B" }, { label: "C" }],
+                    prompt: "Question 2?",
+                    title: "Second",
+                },
+            ];
+            expect(() => QuestionsArraySchema.parse(validQuestions)).not.toThrow();
+            const parsed = QuestionsArraySchema.parse(validQuestions);
+            expect(parsed).toHaveLength(2);
+        });
+        it("should accept question with multiSelect: true", () => {
+            const multiSelectQuestion = {
+                options: [{ label: "A" }, { label: "B" }, { label: "C" }],
+                prompt: "Select multiple options",
+                title: "Features",
+                multiSelect: true,
+            };
+            expect(() => QuestionSchema.parse(multiSelectQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(multiSelectQuestion);
+            expect(parsed.multiSelect).toBe(true);
+        });
+        it("should accept question with multiSelect: false", () => {
+            const singleSelectQuestion = {
+                options: [{ label: "A" }, { label: "B" }],
+                prompt: "Select one option",
+                title: "Choice",
+                multiSelect: false,
+            };
+            expect(() => QuestionSchema.parse(singleSelectQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(singleSelectQuestion);
+            expect(parsed.multiSelect).toBe(false);
+        });
+        it("should accept question with multiSelect omitted (defaults to undefined)", () => {
+            const defaultQuestion = {
+                options: [{ label: "A" }],
+                prompt: "Default single-select",
+                title: "Default",
+            };
+            expect(() => QuestionSchema.parse(defaultQuestion)).not.toThrow();
+            const parsed = QuestionSchema.parse(defaultQuestion);
+            expect(parsed.multiSelect).toBeUndefined();
+        });
+    });
+});

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

@@ -0,0 +1,274 @@
+/**
+ * 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?",
+                    title: "Language",
+                },
+            ];
+            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?",
+                    title: "Language",
+                },
+                {
+                    options: [
+                        { description: "Web application", label: "Web" },
+                        { description: "Command-line tool", label: "CLI" },
+                        { description: "Desktop application", label: "Desktop" },
+                    ],
+                    prompt: "What type of application?",
+                    title: "App Type",
+                },
+            ];
+            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",
+                    title: "Test",
+                },
+            ];
+            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",
+                    title: "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",
+                    title: "Structure",
+                },
+            ];
+            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",
+                    title: "Concurrent",
+                },
+            ];
+            // 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",
+                    title: "Lifecycle",
+                },
+            ];
+            // 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",
+                    title: "Validation",
+                },
+            ];
+            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",
+                    title: "Performance",
+                },
+            ];
+            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",
+                    title: "Efficiency",
+                },
+            ];
+            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/src/add.js

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

package/dist/src/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);
+});

package/dist/src/server.js

@@ -0,0 +1,163 @@
+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 });
+const server = new FastMCP({
+    name: "AskUserQuestions",
+    instructions: "This MCP server provides a tool to ask structured questions to the user. " +
+        "Use the ask_user_questions tool when you need to:\n" +
+        "- Gather user preferences or requirements during execution\n" +
+        "- Clarify ambiguous instructions or implementation choices\n" +
+        "- Get decisions on what direction to take\n" +
+        "- Offer choices to the user about multiple valid approaches\n\n" +
+        "The tool allows AI models to pause execution and gather direct user input through an interactive TUI, " +
+        "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",
+});
+// 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)"),
+});
+// Add the ask_user_questions tool
+server.addTool({
+    name: "ask_user_questions",
+    annotations: {
+        title: "Ask User Questions",
+        openWorldHint: true, // This tool interacts with the user's terminal
+        readOnlyHint: false, // This tool waits for user input
+        idempotentHint: true,
+    },
+    description: "Use this tool when you need to ask the user questions during execution. " +
+        "This allows you to:\n" +
+        "1. Gather user preferences or requirements\n" +
+        "2. Clarify ambiguous instructions\n" +
+        "3. Get decisions on implementation choices as you work\n" +
+        "4. Offer choices to the user about what direction to take\n\n" +
+        "FEATURES:\n" +
+        "- Ask 1-4 structured questions via an interactive terminal interface\n" +
+        "- Each question includes 2-4 multiple-choice options with explanatory descriptions\n" +
+        "- Users can always provide custom free-text input as an alternative to predefined options\n" +
+        "- Single-select mode (default): User picks ONE option or provides custom text\n" +
+        "- Multi-select mode (multiSelect: true): User can select MULTIPLE options\n\n" +
+        "USAGE NOTES:\n" +
+        "- Always provide a descriptive 'title' field (max 12 chars) for each question\n" +
+        "- 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" +
+        "- 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 }) => {
+        try {
+            // Initialize session manager if not already done
+            await sessionManager.initialize();
+            // Clean up old sessions on startup (non-blocking)
+            sessionManager
+                .cleanupExpiredSessions()
+                .then((count) => {
+                if (count > 0) {
+                    log.info(`Cleaned up ${count} expired session(s)`);
+                }
+            })
+                .catch((error) => {
+                log.warn("Cleanup failed:", { error: String(error) });
+            });
+            // Validate questions (using existing Zod schema validation)
+            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);
+            log.info("Session completed successfully", { sessionId, callId });
+            // Return formatted response to AI model
+            return {
+                content: [
+                    {
+                        text: formattedResponse,
+                        type: "text",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            log.error("Session failed", { error: String(error) });
+            return {
+                content: [
+                    {
+                        text: `Error in session: ${error}`,
+                        type: "text",
+                    },
+                ],
+            };
+        }
+    },
+    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)."),
+    }),
+});
+// Start the server with stdio transport
+server.start({
+    transportType: "stdio",
+});