auq-mcp-server 0.1.0

package/dist/format/__tests__/ResponseFormatter.test.js

@@ -0,0 +1,380 @@
+/**
+ * Unit tests for Response Formatter
+ */
+import { describe, expect, it } from "vitest";
+import { ResponseFormatter } from "../ResponseFormatter.js";
+describe("ResponseFormatter", () => {
+    const mockSessionRequest = {
+        sessionId: "test-session-123",
+        status: "pending",
+        timestamp: "2025-01-01T12:00:00.000Z",
+        questions: [
+            {
+                prompt: "What is your favorite programming language?",
+                options: [
+                    { label: "JavaScript", description: "Dynamic web language" },
+                    { label: "TypeScript", description: "Typed JavaScript" },
+                    { label: "Python", description: "Versatile and readable" },
+                ],
+            },
+            {
+                prompt: "What type of application are you building?",
+                options: [
+                    { label: "Web", description: "Frontend or backend web application" },
+                    { label: "CLI", description: "Command-line tool" },
+                    { label: "Mobile", description: "Mobile application" },
+                ],
+            },
+            {
+                prompt: "Any additional requirements?",
+                options: [
+                    { label: "No additional requirements", description: "Standard setup only" },
+                    { label: "Security focus", description: "High security requirements" },
+                ],
+            },
+        ],
+    };
+    const mockSessionAnswer = {
+        sessionId: "test-session-123",
+        timestamp: "2025-01-01T12:05:00.000Z",
+        answers: [
+            {
+                questionIndex: 0,
+                selectedOption: "TypeScript",
+                timestamp: "2025-01-01T12:01:00.000Z",
+            },
+            {
+                questionIndex: 1,
+                customText: "Desktop app with Electron",
+                timestamp: "2025-01-01T12:02:00.000Z",
+            },
+            {
+                questionIndex: 2,
+                selectedOption: "Security focus",
+                timestamp: "2025-01-01T12:03:00.000Z",
+            },
+        ],
+    };
+    describe("formatResponse", () => {
+        it("should format a complete response with all question types", () => {
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, mockSessionAnswer);
+            expect(result.formatted_response).toContain("Here are the user's answers:");
+            expect(result.formatted_response).toContain("1. What is your favorite programming language?");
+            expect(result.formatted_response).toContain("→ TypeScript — Typed JavaScript");
+            expect(result.formatted_response).toContain("2. What type of application are you building?");
+            expect(result.formatted_response).toContain("→ Other: 'Desktop app with Electron'");
+            expect(result.formatted_response).toContain("3. Any additional requirements?");
+            expect(result.formatted_response).toContain("→ Security focus — High security requirements");
+            expect(result.metadata).toEqual({
+                totalQuestions: 3,
+                answeredQuestions: 3,
+                sessionDuration: 5 * 60 * 1000, // 5 minutes
+                hasCustomAnswers: true,
+            });
+        });
+        it("should handle responses with only selected options", () => {
+            const answerOnlyOptions = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "Python",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                ],
+            };
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, answerOnlyOptions);
+            expect(result.formatted_response).toContain("→ Python — Versatile and readable");
+            expect(result.formatted_response).not.toContain("Other:");
+            expect(result.metadata.hasCustomAnswers).toBe(false);
+        });
+        it("should handle responses with only custom text", () => {
+            const answerOnlyCustom = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        customText: "Rust for performance and safety",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                ],
+            };
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, answerOnlyCustom);
+            expect(result.formatted_response).toContain("→ Other: 'Rust for performance and safety'");
+            expect(result.metadata.hasCustomAnswers).toBe(true);
+        });
+        it("should handle options without descriptions", () => {
+            const questionWithoutDescription = {
+                ...mockSessionRequest,
+                questions: [
+                    {
+                        prompt: "Simple question?",
+                        options: [{ label: "Option 1" }, { label: "Option 2" }],
+                    },
+                ],
+            };
+            const simpleAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "Option 1",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                ],
+            };
+            const result = ResponseFormatter.formatResponse(questionWithoutDescription, simpleAnswer);
+            expect(result.formatted_response).toContain("→ Option 1");
+            expect(result.formatted_response).not.toContain("—");
+        });
+        it("should handle unanswered questions", () => {
+            const incompleteAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "JavaScript",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    // Missing answers for questions 1 and 2
+                ],
+            };
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, incompleteAnswer);
+            expect(result.formatted_response).toContain("→ JavaScript — Dynamic web language");
+            expect(result.formatted_response).toContain("2. What type of application are you building?");
+            expect(result.formatted_response).toContain("→ [No answer provided]");
+            expect(result.formatted_response).toContain("3. Any additional requirements?");
+            expect(result.formatted_response).toContain("→ [No answer provided]");
+            expect(result.metadata.answeredQuestions).toBe(1);
+            expect(result.metadata.totalQuestions).toBe(3);
+        });
+        it("should handle custom formatting options", () => {
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, mockSessionAnswer, {
+                includePreamble: false,
+                includeTimestamps: true,
+                maxLineLength: 50,
+            });
+            expect(result.formatted_response).not.toContain("Here are the user's answers:");
+            expect(result.formatted_response).toContain("(Answered:");
+            // Note: Text wrapping might work differently than expected
+        });
+    });
+    describe("validateAnswers", () => {
+        it("should validate complete and correct answers", () => {
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, mockSessionAnswer);
+            expect(validation.isValid).toBe(true);
+            expect(validation.issues).toHaveLength(0);
+            expect(validation.warnings).toHaveLength(0);
+        });
+        it("should detect missing answers", () => {
+            const incompleteAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "JavaScript",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    // Missing answers for questions 1 and 2
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, incompleteAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues).toHaveLength(1);
+            expect(validation.issues[0]).toContain("2 question(s) were not answered");
+        });
+        it("should detect duplicate answers", () => {
+            const duplicateAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "JavaScript",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    {
+                        questionIndex: 0,
+                        selectedOption: "Python",
+                        timestamp: "2025-01-01T12:02:00.000Z",
+                    },
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, duplicateAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues).toContain("Duplicate answers detected for some questions");
+        });
+        it("should detect invalid question indices", () => {
+            const invalidIndexAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 5, // Invalid index (only 0-2 exist)
+                        selectedOption: "JavaScript",
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, invalidIndexAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues.length).toBeGreaterThan(0);
+        });
+        it("should detect invalid selected options", () => {
+            // Provide answers for all questions to avoid missing answer detection
+            const invalidOptionAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "NonExistentOption", // Not in question options
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Web",
+                        timestamp: "2025-01-01T12:02:00.000Z",
+                    },
+                    {
+                        questionIndex: 2,
+                        selectedOption: "No additional requirements",
+                        timestamp: "2025-01-01T12:03:00.000Z",
+                    },
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, invalidOptionAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues).toContain("Answer 1 references non-existent option: NonExistentOption");
+        });
+        it("should detect empty answers", () => {
+            // Provide answers for all questions but one is empty
+            const emptyAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        // No selected option or custom text
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Web",
+                        timestamp: "2025-01-01T12:02:00.000Z",
+                    },
+                    {
+                        questionIndex: 2,
+                        selectedOption: "No additional requirements",
+                        timestamp: "2025-01-01T12:03:00.000Z",
+                    },
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, emptyAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues).toContain("Answer 1 has no selected option or custom text");
+        });
+        it("should warn about very long custom answers", () => {
+            // Provide answers for all questions to avoid missing answer detection
+            const longAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        customText: "x".repeat(1500), // Very long answer
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Web",
+                        timestamp: "2025-01-01T12:02:00.000Z",
+                    },
+                    {
+                        questionIndex: 2,
+                        selectedOption: "No additional requirements",
+                        timestamp: "2025-01-01T12:03:00.000Z",
+                    },
+                ],
+            };
+            const validation = ResponseFormatter.validateAnswers(mockSessionRequest, longAnswer);
+            expect(validation.isValid).toBe(true);
+            expect(validation.warnings.length).toBeGreaterThanOrEqual(1);
+            const longTextWarning = validation.warnings.find(w => w.includes("very long custom text"));
+            expect(longTextWarning).toBeTruthy();
+            expect(longTextWarning).toContain("1500 characters");
+        });
+    });
+    describe("createSessionSummary", () => {
+        it("should create a comprehensive session summary", () => {
+            const summary = ResponseFormatter.createSessionSummary(mockSessionRequest, mockSessionAnswer);
+            expect(summary).toContain("Session Summary:");
+            expect(summary).toContain("Session ID: test-session-123");
+            expect(summary).toContain("Total Questions: 3");
+            expect(summary).toContain("Answered Questions: 3");
+            expect(summary).toContain("Duration: 300s"); // 5 minutes
+            expect(summary).toContain("Custom Answers: 1");
+            expect(summary).toContain("Status: pending");
+        });
+        it("should handle empty questions and answers", () => {
+            const emptySession = {
+                sessionId: "empty-session",
+                status: "completed",
+                timestamp: "2025-01-01T12:00:00.000Z",
+                questions: [],
+            };
+            const emptyAnswer = {
+                sessionId: "empty-session",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [],
+            };
+            const summary = ResponseFormatter.createSessionSummary(emptySession, emptyAnswer);
+            expect(summary).toContain("Total Questions: 0");
+            expect(summary).toContain("Answered Questions: 0");
+            expect(summary).toContain("Custom Answers: 0");
+        });
+    });
+    describe("Edge Cases", () => {
+        it("should handle empty custom text", () => {
+            const emptyCustomAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [
+                    {
+                        questionIndex: 0,
+                        customText: "   ", // Only whitespace
+                        timestamp: "2025-01-01T12:01:00.000Z",
+                    },
+                ],
+            };
+            const result = ResponseFormatter.formatResponse(mockSessionRequest, emptyCustomAnswer);
+            expect(result.formatted_response).toContain("→ [No answer provided]");
+        });
+        it("should handle malformed session data gracefully", () => {
+            const malformedRequest = {
+                sessionId: "test-session-123",
+                status: "pending",
+                timestamp: "2025-01-01T12:00:00.000Z",
+                questions: [
+                    {
+                        prompt: "Test question",
+                        options: [],
+                    },
+                ],
+            };
+            const malformedAnswer = {
+                sessionId: "test-session-123",
+                timestamp: "2025-01-01T12:05:00.000Z",
+                answers: [],
+            };
+            const validation = ResponseFormatter.validateAnswers(malformedRequest, malformedAnswer);
+            expect(validation.isValid).toBe(false);
+            expect(validation.issues.length).toBeGreaterThan(0);
+        });
+    });
+});

package/dist/package.json

@@ -0,0 +1,74 @@
+{
+    "name": "auq-mcp-server",
+    "version": "0.1.0",
+    "main": "dist/index.js",
+    "bin": {
+        "auq": "dist/bin/auq.js"
+    },
+    "files": [
+        "dist",
+        "scripts/postinstall.cjs",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepare": "npm run build",
+        "postinstall": "node scripts/postinstall.cjs",
+        "server": "node dist/src/server.js",
+        "start": "tsx src/server.ts",
+        "dev": "fastmcp dev src/server.ts",
+        "lint": "prettier --check . && eslint . && tsc --noEmit",
+        "test": "vitest run",
+        "format": "prettier --write . && eslint --fix ."
+    },
+    "keywords": [
+        "fastmcp",
+        "mcp",
+        "ask-user-questions",
+        "tui",
+        "terminal"
+    ],
+    "repository": {
+        "url": "https://github.com/paulp-o/ask-user-question-mcp"
+    },
+    "author": "Paul Park",
+    "homepage": "https://github.com/paulp-o/ask-user-question-mcp",
+    "type": "module",
+    "license": "MIT",
+    "description": "An MCP server that provides a tool to ask a user questions via the terminal",
+    "dependencies": {
+        "@types/uuid": "^10.0.0",
+        "fastmcp": "^1.27.3",
+        "ink": "^6.4.0",
+        "ink-text-input": "^6.0.0",
+        "react": "^19.2.0",
+        "uuid": "^13.0.0",
+        "zod": "^3.24.4"
+    },
+    "release": {
+        "branches": [
+            "main"
+        ],
+        "plugins": [
+            "@semantic-release/commit-analyzer",
+            "@semantic-release/release-notes-generator",
+            "@semantic-release/npm",
+            "@semantic-release/github"
+        ]
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.26.0",
+        "@tsconfig/node22": "^22.0.1",
+        "@types/react": "^19.2.2",
+        "eslint-config-prettier": "^10.1.3",
+        "eslint-plugin-perfectionist": "^4.12.3",
+        "jiti": "^2.4.2",
+        "prettier": "^3.5.3",
+        "semantic-release": "^24.2.3",
+        "tsx": "^4.19.4",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.32.0",
+        "vitest": "^3.1.3"
+    }
+}

package/dist/server.js

@@ -0,0 +1,107 @@
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+import { SessionManager } from "./session/index.js";
+// import { resolveSessionDirectory } from "./session/utils.js";
+// Initialize session manager
+const sessionManager = new SessionManager();
+const server = new FastMCP({
+    instructions: "This MCP server provides a tool to ask users structured questions via the terminal. " +
+        "The ask_user_questions tool allows AI models to pause and gather direct user input through " +
+        "an interactive TUI, returning formatted responses for continued reasoning.",
+    name: "AskUserQuery",
+    version: "0.1.0",
+});
+// Define the question and option schemas
+const OptionSchema = z.object({
+    description: z
+        .string()
+        .optional()
+        .describe("Optional explanatory note for this option"),
+    label: z.string().describe("The visible text of the choice"),
+});
+const QuestionSchema = z.object({
+    title: z.string().describe("Short 1-2 word summary for UI display"),
+    options: z
+        .array(OptionSchema)
+        .min(1)
+        .describe("Non-empty list of predefined answer choices"),
+    prompt: z.string().describe("The full question text"),
+});
+// Add the ask_user_questions tool
+server.addTool({
+    annotations: {
+        openWorldHint: true, // This tool interacts with the user's terminal
+        readOnlyHint: false, // This tool waits for user input
+        title: "Ask User Questions",
+    },
+    description: "Ask the user one or more structured questions via an interactive terminal interface. " +
+        "Each question includes multiple-choice options and allows custom free-text responses. " +
+        "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) => ({
+                title: q.title,
+                options: q.options.map((opt) => ({
+                    description: opt.description,
+                    label: opt.label,
+                })),
+                prompt: q.prompt,
+            }));
+            log.info("Starting session and waiting for user answers...", {
+                questionCount: questions.length,
+            });
+            // Start complete session lifecycle - this will wait for user answers
+            const { formattedResponse, sessionId } = await sessionManager.startSession(questions);
+            log.info("Session completed successfully", { sessionId });
+            // 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",
+                    },
+                ],
+            };
+        }
+    },
+    name: "ask_user_questions",
+    parameters: z.object({
+        questions: z
+            .array(QuestionSchema)
+            .min(1)
+            .describe("Array of questions to ask the user"),
+    }),
+});
+// Start the server with stdio transport
+server.start({
+    transportType: "stdio",
+});