ask-user-question-plus 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JoJoJotarou
+
+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,264 @@
+# AskUserQuestionPlus
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/ask-user-question-plus.svg)](https://www.npmjs.com/package/ask-user-question-plus)
+
+一个功能强大的 MCP (Model Context Protocol) 服务器，通过精美的 TUI 风格 Web 界面让 LLM（如 Claude）向用户提问。
+
+![TUI Interface](./assets/screenshot.png)
+
+## ✨ 特性
+
+- **🎨 TUI 风格界面**：浏览器中呈现像素级完美的类终端外观（暗/浅色主题）
+- **⌨️ 全键盘操作**：支持方向键、Tab、Space、Enter 快捷键
+- **📊 丰富交互**：单选、多选、推荐选项、自定义输入（Other）
+- **🔄 实时通信**：基于 WebSocket 的实时消息传递
+- **⏱️ 超时保护**：可配置超时（默认 10 分钟）
+- **📈 可扩展**：支持 1-20 个问题，每个问题选项数量不限
+
+### Claude Code AskUserQuestion Tool vs AskUserQuestionPlus
+
+| 对比项       | AskUserQuestion (内置) | ask-user-question-plus (MCP) |
+| ------------ | ---------------------- | ---------------------------- |
+| 问题数量限制 | 1-4 个                 | 1-20 个                      |
+| 选项数量限制 | 2-4 个                 | 无限制                       |
+
+## 📦 安装
+
+### 方式 1：直接安装（推荐）
+
+```bash
+npm install -g ask-user-question-plus
+```
+
+### 方式 2：从源码构建
+
+```bash
+git clone https://github.com/JoJoJotarou/AskUserQuestionPlus.git
+cd AskUserQuestionPlus
+npm install
+npm run build
+```
+
+## 🚀 配置
+
+将此服务器添加到你的 MCP 客户端配置文件（Claude Desktop 的 `claude_desktop_config.json` 或 Claude Code 配置）。
+
+### Claude Desktop 配置
+
+**基础配置：**
+
+```json
+{
+  "mcpServers": {
+    "ask-user-question-plus": {
+      "command": "npx",
+      "args": ["ask-user-question-plus"]
+    }
+  }
+}
+```
+
+**自定义超时（毫秒）：**
+
+```json
+{
+  "mcpServers": {
+    "ask-user-question-plus": {
+      "command": "npx",
+      "args": ["ask-user-question-plus", "--timeout=300000"]
+    }
+  }
+}
+```
+
+### 启动参数
+
+| 参数               | 说明           | 默认值           | 示例               |
+| ------------------ | -------------- | ---------------- | ------------------ |
+| `--timeout=<毫秒>` | 会话超时时间   | 600000 (10 分钟) | `--timeout=300000` |
+| `--port=<端口>`    | WebSocket 端口 | 3456             | `--port=8080`      |
+
+## 📖 使用方法
+
+### 基本流程
+
+1. 启动与 Claude 的对话
+2. 让 Claude 使用工具：`使用 ask_user_question_plus 工具问我 3 个问题`
+3. 浏览器自动打开问卷界面
+4. 使用键盘（方向键、Space、Enter）回答问题
+5. 提交后浏览器标签页自动关闭
+
+### 键盘快捷键
+
+| 快捷键             | 功能                          |
+| ------------------ | ----------------------------- |
+| `↑` `↓`            | 在选项之间移动 / 滚动问题内容 |
+| `←` `→` / `Tab`    | 在问题标签页之间切换          |
+| `Space`            | 选中/取消选中当前选项         |
+| `Cmd/Ctrl + Enter` | 进入审查模式 / 提交答案       |
+
+## 🔧 工具 API
+
+### MCP 工具：`ask_user_question_plus`
+
+**输入 Schema：**
+
+```typescript
+{
+  questions: [
+    {
+      id: string;              // 问题唯一标识
+      header: string;          // 标签标题（≤12 字符推荐）
+      text: string;            // 问题文本
+      type: "single" | "multiple";  // 单选或多选
+      options: [
+        {
+          value: string;        // 选项值
+          label: string;        // 选项标签
+          description?: string; // 选项描述（可选）
+          recommended?: boolean;// 是否推荐（可选）
+        }
+      ]
+    }
+  ]  // 最少 1 个，最多 20 个问题
+}
+```
+
+**输出 Schema：**
+
+```typescript
+{
+  [questionId: string]: string | string[]  // 单选为字符串，多选为数组
+}
+```
+
+> **💡 提示**：前端会自动为每个问题添加 "Other (自定义输入)" 选项，无需手动指定。
+
+### 使用示例
+
+**单选问题：**
+
+```json
+{
+  "questions": [
+    {
+      "id": "framework",
+      "header": "Framework",
+      "text": "选择你的前端框架：",
+      "type": "single",
+      "options": [
+        {
+          "value": "react",
+          "label": "React",
+          "description": "用于构建用户界面的 JavaScript 库",
+          "recommended": true
+        },
+        {
+          "value": "vue",
+          "label": "Vue",
+          "description": "渐进式 JavaScript 框架"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**多选问题：**
+
+```json
+{
+  "questions": [
+    {
+      "id": "features",
+      "header": "Features",
+      "text": "你需要哪些功能？（可多选）",
+      "type": "multiple",
+      "options": [
+        {
+          "value": "auth",
+          "label": "用户认证",
+          "description": "登录、注册、密码重置"
+        },
+        {
+          "value": "api",
+          "label": "REST API",
+          "description": "RESTful API 端点"
+        },
+        {
+          "value": "db",
+          "label": "数据库",
+          "description": "PostgreSQL/MySQL 支持"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 🛠️ 开发
+
+### 运行开发模式
+
+```bash
+npm run dev
+```
+
+### 构建项目
+
+```bash
+npm run build
+```
+
+### 目录结构
+
+```
+ask-user-question-plus/
+├── src/
+│   ├── index.ts           # 主入口文件
+│   ├── ws-service.ts      # WebSocket 服务
+│   └── mcp-server.ts      # MCP 服务器逻辑
+├── public/
+│   └── index.html         # TUI 前端界面
+├── dist/                  # 编译输出目录
+└── package.json           # 项目配置
+```
+
+### 技术栈
+
+- **后端**：Node.js 20+, TypeScript, Express, ws, @modelcontextprotocol/sdk, Zod
+- **前端**：原生 HTML/CSS/JavaScript（单文件 1184 行）
+
+## 🐳 Docker 部署
+
+```bash
+# 使用 Docker Compose
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 停止服务
+docker-compose down
+```
+
+## 🤝 贡献
+
+欢迎贡献！请提交 [Issues](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues) 或 Pull Requests。
+
+## 📄 许可证
+
+[MIT License](LICENSE)
+
+## 🔗 相关链接
+
+- [GitHub 仓库](https://github.com/JoJoJotarou/AskUserQuestionPlus)
+- [npm 包](https://www.npmjs.com/package/ask-user-question-plus)
+- [问题反馈](https://github.com/JoJoJotarou/AskUserQuestionPlus/issues)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://github.com/anthropics/claude-code)
+
+---
+
+**注意**：此工具需要浏览器支持，确保系统可以自动打开默认浏览器。

package/dist/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import "dotenv/config"; // Load .env file
+import express from "express";
+import { WebSocketServer } from "ws";
+import { createServer } from "http";
+import path from "path";
+import { fileURLToPath } from "url";
+import { WebSocketService } from "./ws-service.js";
+import { MCPServerService } from "./mcp-server.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG = {
+    PORT: 3456,
+    TIMEOUT: 600000, // 10 minutes
+};
+/**
+ * Parse configuration from environment variables and command line arguments
+ * Priority: CLI args > Environment variables > Defaults
+ */
+function parseConfig() {
+    const config = {
+        // 1. Defaults
+        ...DEFAULT_CONFIG,
+    };
+    // 2. Environment variables
+    if (process.env.PORT) {
+        const port = parseInt(process.env.PORT, 10);
+        if (!isNaN(port) && port > 0 && port <= 65535) {
+            config.PORT = port;
+        }
+        else {
+            console.error(`[Config] Invalid PORT environment variable: ${process.env.PORT}`);
+        }
+    }
+    if (process.env.TIMEOUT) {
+        const timeout = parseInt(process.env.TIMEOUT, 10);
+        if (!isNaN(timeout) && timeout > 0) {
+            config.TIMEOUT = timeout;
+        }
+        else {
+            console.error(`[Config] Invalid TIMEOUT environment variable: ${process.env.TIMEOUT}`);
+        }
+    }
+    // 3. Command line arguments (override environment variables)
+    const args = process.argv.slice(2);
+    for (const arg of args) {
+        if (arg.startsWith("--port=")) {
+            const port = parseInt(arg.split("=")[1], 10);
+            if (!isNaN(port) && port > 0 && port <= 65535) {
+                config.PORT = port;
+            }
+            else {
+                console.error(`[Config] Invalid --port argument: ${arg}`);
+            }
+        }
+        else if (arg.startsWith("--timeout=")) {
+            const timeout = parseInt(arg.split("=")[1], 10);
+            if (!isNaN(timeout) && timeout > 0) {
+                config.TIMEOUT = timeout;
+            }
+            else {
+                console.error(`[Config] Invalid --timeout argument: ${arg}`);
+            }
+        }
+    }
+    return config;
+}
+// --- Main ---
+async function main() {
+    console.error("=== Server Starting ===");
+    try {
+        const config = parseConfig();
+        console.error(`[Main] Configuration:`);
+        console.error(`[Main] - Port: ${config.PORT}`);
+        console.error(`[Main] - Timeout: ${config.TIMEOUT}ms (${config.TIMEOUT / 1000}s)`);
+        // Create Express app
+        const app = express();
+        // Middleware
+        app.use(express.json());
+        app.use(express.static(path.join(__dirname, "../public")));
+        // Health check endpoint
+        app.get("/health", (_req, res) => {
+            res.json({
+                status: "ok",
+                timestamp: new Date().toISOString(),
+                activeSessions: wsService.getSessionCount(),
+            });
+        });
+        // Create HTTP server
+        const server = createServer(app);
+        // Create WebSocket server with /ws path
+        const wss = new WebSocketServer({
+            server,
+            path: "/ws",
+        });
+        // Initialize services
+        const wsService = new WebSocketService(wss, config.TIMEOUT, config.PORT);
+        const mcpService = new MCPServerService(wsService);
+        // MCP routes
+        app.post("/mcp", async (req, res) => {
+            await mcpService.handleRequest(req, res);
+        });
+        app.get("/mcp", (_req, res) => {
+            res.status(405).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Method not allowed. Use POST.",
+                },
+                id: null,
+            });
+        });
+        app.delete("/mcp", (_req, res) => {
+            res.status(405).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Method not allowed. Use POST.",
+                },
+                id: null,
+            });
+        });
+        // Start server
+        server.listen(config.PORT, () => {
+            console.error(`[Main] Server listening on port ${config.PORT}`);
+            console.error(`[Main] - HTTP: http://localhost:${config.PORT}`);
+            console.error(`[Main] - WebSocket: ws://localhost:${config.PORT}/ws`);
+            console.error(`[Main] - MCP: http://localhost:${config.PORT}/mcp`);
+            console.error(`[Main] - Health: http://localhost:${config.PORT}/health`);
+        });
+        // Graceful shutdown
+        const shutdown = async () => {
+            console.error("[Main] Shutting down...");
+            await wsService.cleanup();
+            server.close(() => {
+                console.error("[Main] Server closed");
+                process.exit(0);
+            });
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (error) {
+        console.error("[Main] Startup failed:", error);
+        process.exit(1);
+    }
+}
+main();

package/dist/mcp-server.js

@@ -0,0 +1,137 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { v4 as uuidv4 } from "uuid";
+import { z } from "zod";
+export class MCPServerService {
+    wsService;
+    constructor(wsService) {
+        this.wsService = wsService;
+    }
+    // Create a new server instance for each request (stateless)
+    createServer() {
+        const server = new McpServer({
+            name: "ask-user-question-plus",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.registerTools(server);
+        return server;
+    }
+    registerTools(server) {
+        server.registerTool("ask_user_question_plus", {
+            description: "一个基于 MCP 的用户交互工具，用于向用户提出结构化问题并收集反馈。该工具支持单选、多选类型的问题，允许标记推荐选项，并支持任意数量的问题与答案选项。前端会自动为每个问题添加 'Other'（自定义输入）选项，适用于复杂配置与决策流程。",
+            inputSchema: {
+                questions: z
+                    .array(z.object({
+                    id: z.string().describe("问题唯一标识"),
+                    header: z
+                        .string()
+                        .max(12)
+                        .describe("问题标题（最多 12 个字符）"),
+                    text: z.string().describe("问题文本"),
+                    type: z
+                        .enum(["single", "multiple"])
+                        .describe("问题类型：single（单选）或 multiple（多选）"),
+                    options: z
+                        .array(z.object({
+                        value: z.string().describe("选项值"),
+                        label: z.string().describe("选项标签"),
+                        description: z
+                            .string()
+                            .optional()
+                            .describe("选项描述（可选）"),
+                        recommended: z
+                            .boolean()
+                            .optional()
+                            .describe("是否为推荐选项（可选）"),
+                    }))
+                        .describe("选项列表（不限数量）。注意：前端会自动添加 'Other'（自定义输入）选项，用户可自定义输入。"),
+                }))
+                    .min(1)
+                    .max(20)
+                    .describe("问题列表（最多可支持 20 个问题）"),
+            },
+        }, async ({ questions }) => {
+            console.error("[MCP] Tool invoked: ask_user_question_plus");
+            if (!questions || !Array.isArray(questions) || questions.length === 0) {
+                const error = "Questions list cannot be empty";
+                console.error("[MCP] Validation error:", error);
+                return {
+                    content: [{ type: "text", text: `Error: ${error}` }],
+                    isError: true,
+                };
+            }
+            if (questions.length > 20) {
+                const error = "Questions list cannot exceed 20 items";
+                console.error("[MCP] Validation error:", error);
+                return {
+                    content: [{ type: "text", text: `Error: ${error}` }],
+                    isError: true,
+                };
+            }
+            const sessionId = uuidv4();
+            console.error("[MCP] Session created:", sessionId);
+            try {
+                const answer = await new Promise((resolve, reject) => {
+                    this.wsService
+                        .createSession(sessionId, questions, resolve, reject)
+                        .catch(reject);
+                });
+                console.error("[MCP] User answer received:", sessionId);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(answer, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                console.error("[MCP] Session failed:", sessionId, error.message);
+                const errorMessage = error.message || "Unknown error occurred";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: errorMessage,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // Handle StreamableHTTP request
+    async handleRequest(req, res) {
+        const server = this.createServer();
+        try {
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+            res.on("close", () => {
+                console.error("[MCP] Request closed");
+                transport.close();
+                server.close();
+            });
+        }
+        catch (error) {
+            console.error("[MCP] Request handling error:", error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error",
+                    },
+                    id: null,
+                });
+            }
+        }
+    }
+}