mcp-interactive-choice 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+# Interactive Choice MCP Server (Native UI)
+
+A Model Context Protocol (MCP) server that allows AI agents to ask questions through a **native window** (built with Tauri), preventing context-breaking interruptions and providing a premium user experience.
+
+## ✨ Features
+
+- **Native Window**: A native window appears when the agent needs your input.
+- **Markdown Support**: Detailed descriptions from the AI are rendered in markdown.
+- **Cross-Platform**: Supports Windows and macOS.
+
+## 🚀 Setup & Installation
+
+### Option A: Run with npx (Recommended)
+You can use the server directly via `npx` in your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "interactive-choice": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-interactive-choice"
+      ]
+    }
+  }
+}
+```
+
+### Option B: Local Build
+#### 1. Build Everything
+From the project root:
+```bash
+npm install
+npm run build
+```
+This will:
+1. Build the frontend (Vite)
+2. Build the Tauri binary (Rust)
+3. Compile the MCP server (TypeScript)
+4. Copy the binary to the `bin/` folder
+
+#### 2. Register with your MCP Client
+Update your configuration (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "interactive-choice": {
+      "command": "node",
+      "args": [
+        "/path/to/mcp-interactive-choice/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+## 🛠️ Tool: `ask_user`
+
+The agent calls this tool when it needs a human decision.
+
+**Arguments:**
+- `title` (optional): Short headline for the question.
+- `body` (optional): Detailed context in Markdown.
+- `choices` (required): List of strings.
+- `recommended` (optional): One of the strings from `choices` that the agent suggests.
+- `allowCustom` (optional): Boolean to show a text box for custom input.
+- `timeoutSec` (optional): How long to wait (in seconds) before the tool auto-fails.
+
+**Response:**
+- Returns the string value of the selected choice.
+- Returns the custom text if provided.
+- Returns `"user cancelled the selection"` if the window is closed manually.
+
+## 🛠️ Development & Debugging
+
+### UI Development (Hot Reloading)
+To iterate on the UI with hot reloading:
+1. Go to `packages/native-ui`.
+2. Run `npm run tauri dev`.
+
+**Running with CLI parameters (Windows/PowerShell):**
+To test specific data during development, use the flag `--input`:
+```powershell
+npm run tauri dev -- -- -- --input '{"title":"Dev Test","choices":["A","B"]}'
+```
+
+### 🔍 Testing with MCP Inspector
+1. **Build Everything**: `npm run build` at the root.
+2. **Run Inspector** from the project root:
+```bash
+npx -y @modelcontextprotocol/inspector node dist/index.js
+```
+
+## 📝 License
+MIT

package/dist/index.js

@@ -0,0 +1,184 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+import { Command } from "commander";
+import fs from "fs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// CLI Arguments for the MCP server itself
+const program = new Command();
+program
+    .option("--timeout <number>", "Default timeout in seconds", "60")
+    .option("--binary-path <string>", "Path to the native-ui binary")
+    .parse(process.argv);
+const options = program.opts();
+const DEFAULT_TIMEOUT = parseInt(options.timeout);
+/**
+ * Strategy to find the native-ui binary.
+ * 1. Explicit --binary-path flag.
+ * 2. Monorepo dev path.
+ * 3. npm installation path (bin/native-ui-<platform>-<arch>).
+ */
+function getBinaryPath() {
+    if (options.binaryPath)
+        return options.binaryPath;
+    const platform = process.platform;
+    const arch = process.arch;
+    const exeSuffix = platform === "win32" ? ".exe" : "";
+    // 1. Dev Path (Monorepo)
+    // When running from root/dist/index.js, native-ui is in root/packages/native-ui/...
+    const devPath = path.resolve(__dirname, `../packages/native-ui/src-tauri/target/release/native-ui${exeSuffix}`);
+    // 2. NPM Path (standardized binary name)
+    const npmPath = path.resolve(__dirname, `../bin/native-ui-${platform}-${arch}${exeSuffix}`);
+    if (fs.existsSync(npmPath))
+        return npmPath;
+    if (fs.existsSync(devPath))
+        return devPath;
+    // Fallback to debug path if release doesn't exist
+    const debugPath = path.resolve(__dirname, `../packages/native-ui/src-tauri/target/debug/native-ui${exeSuffix}`);
+    if (fs.existsSync(debugPath))
+        return debugPath;
+    return npmPath;
+}
+/**
+ * Resolves the recommended choice string to its index in the choices array.
+ * Returns -1 if no recommendation is provided.
+ * @throws McpError if the recommendation doesn't match any choice.
+ */
+export function resolveRecommendedIndex(choices, recommended) {
+    if (recommended === undefined || recommended === null)
+        return -1;
+    const target = recommended.trim();
+    const index = choices.findIndex(c => c.trim() === target);
+    if (index === -1) {
+        throw new McpError(ErrorCode.InvalidParams, `recommended choice "${recommended}" does not match any available choices. Available: ${choices.join(", ")}`);
+    }
+    return index;
+}
+const server = new Server({
+    name: "mcp-interactive-choice",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "ask_user",
+                description: "Ask the user a question with several choices via a native GUI window. Supports Markdown in the body and a recommended choice.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        title: {
+                            type: "string",
+                            description: "(Optional) A concise, high-level summary of the decision required.",
+                        },
+                        body: {
+                            type: "string",
+                            description: "(Optional) Detailed context or explanation. Supports Markdown (code blocks, lists, etc.) to help the user make an informed choice.",
+                        },
+                        choices: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "(Required) A list of predefined options for the user to select from.",
+                        },
+                        recommended: {
+                            type: "string",
+                            description: "(Optional) One of the exact strings from the 'choices' array that the agent recommends. The UI will highlight this option.",
+                        },
+                        allowCustom: {
+                            type: "boolean",
+                            description: "(Optional) Whether to provide a text area for the user to type a custom response not in the choices list. Defaults to false.",
+                            default: false
+                        },
+                        timeoutSec: {
+                            type: "number",
+                            description: `(Optional) How long to wait for a user response in seconds. Defaults to ${DEFAULT_TIMEOUT}. If exceeded, the tool returns a timeout error.`,
+                        }
+                    },
+                    required: ["choices"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "ask_user") {
+        const args = request.params.arguments;
+        const choices = args.choices;
+        const timeout = (args.timeoutSec || DEFAULT_TIMEOUT) * 1000;
+        const recommendedIndex = resolveRecommendedIndex(choices, args.recommended);
+        const inputData = {
+            title: args.title || "Action Required",
+            body: args.body || "",
+            choices,
+            recommendedIndex,
+            allowCustom: !!args.allowCustom,
+        };
+        const binaryPath = getBinaryPath();
+        return new Promise((resolve, reject) => {
+            const child = spawn(binaryPath, ["--input", JSON.stringify(inputData)], {
+                stdio: ["ignore", "pipe", "inherit"],
+            });
+            let stdoutData = "";
+            child.stdout.on("data", (data) => {
+                stdoutData += data.toString();
+            });
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                resolve({
+                    content: [{ type: "text", text: "Error: User feedback timed out." }],
+                    isError: true,
+                });
+            }, timeout);
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (code === 0) {
+                    try {
+                        const cleanedStdout = stdoutData.split('\n')
+                            .filter(line => !line.trim().startsWith('DEBUG'))
+                            .join('\n')
+                            .trim();
+                        const result = JSON.parse(cleanedStdout);
+                        const textResult = result.custom_input || result.choice || "No selection made";
+                        resolve({
+                            content: [{ type: "text", text: textResult }],
+                        });
+                    }
+                    catch (e) {
+                        resolve({
+                            content: [{ type: "text", text: `Error parsing result: ${stdoutData}` }],
+                            isError: true,
+                        });
+                    }
+                }
+                else {
+                    resolve({
+                        content: [{ type: "text", text: `Tool window closed unexpectedly (code ${code})` }],
+                        isError: true,
+                    });
+                }
+            });
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                reject(new McpError(ErrorCode.InternalError, `Failed to launch interactive window: ${err.message}`));
+            });
+        });
+    }
+    throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${request.params.name}`);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Interactive Choice MCP Server (Tauri) running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/dist/index.test.js

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import { resolveRecommendedIndex } from "./index.js";
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+describe("resolveRecommendedIndex", () => {
+    const choices = ["Apple", "Banana", "Cherry"];
+    it("should return -1 if recommended is null or undefined", () => {
+        expect(resolveRecommendedIndex(choices, null)).toBe(-1);
+        expect(resolveRecommendedIndex(choices, undefined)).toBe(-1);
+    });
+    it("should return the correct index for a valid recommendation", () => {
+        expect(resolveRecommendedIndex(choices, "Banana")).toBe(1);
+    });
+    it("should handle whitespace correctly", () => {
+        expect(resolveRecommendedIndex(choices, "  Cherry  ")).toBe(2);
+    });
+    it("should throw McpError for invalid recommendation", () => {
+        expect(() => resolveRecommendedIndex(choices, "Dragonfruit")).toThrow(McpError);
+        try {
+            resolveRecommendedIndex(choices, "Dragonfruit");
+        }
+        catch (e) {
+            expect(e.code).toBe(ErrorCode.InvalidParams);
+        }
+    });
+});

package/dist/spawn.test.js

@@ -0,0 +1,39 @@
+import { describe, it } from 'vitest';
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+describe('spawn native-ui', () => {
+    it('should be able to find and execute the native-ui binary with --help', async () => {
+        const platform = process.platform;
+        const exeSuffix = platform === 'win32' ? '.exe' : '';
+        // Check release first, then debug
+        const releasePath = path.resolve(__dirname, `../packages/native-ui/src-tauri/target/release/native-ui${exeSuffix}`);
+        const debugPath = path.resolve(__dirname, `../packages/native-ui/src-tauri/target/debug/native-ui${exeSuffix}`);
+        const binaryPath = fs.existsSync(releasePath) ? releasePath : debugPath;
+        if (!fs.existsSync(binaryPath)) {
+            console.warn(`Binary not found at ${binaryPath}, skipping execution test. Run 'npm run build' first.`);
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const child = spawn(binaryPath, ['--help'], {
+                stdio: ['ignore', 'pipe', 'pipe']
+            });
+            let stdout = '';
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.on('close', (code) => {
+                // Tauri apps return 0 for help usually, but some return non-zero if no event loop
+                // We just care that it lived long enough to print something or exit cleanly
+                console.log('Tauri help output:', stdout);
+                resolve(true);
+            });
+            child.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }, 10000); // 10s timeout
+});

package/dist/ui

@@ -0,0 +1,262 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Needs Your Choice</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;600&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --primary: #4f46e5;
+            --primary-hover: #4338ca;
+            --bg-gradient: linear-gradient(135deg, #0f172a 0%, #1e1b4b 100%);
+            --glass: rgba(255, 255, 255, 0.05);
+            --glass-border: rgba(255, 255, 255, 0.1);
+            --text-main: #f8fafc;
+            --text-dim: #94a3b8;
+        }
+
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+            font-family: 'Outfit', sans-serif;
+        }
+
+        body {
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background: var(--bg-gradient);
+            background-attachment: fixed;
+            color: var(--text-main);
+            overflow: hidden;
+        }
+
+        /* Abstract blobs for aesthetics */
+        .blob {
+            position: absolute;
+            width: 500px;
+            height: 500px;
+            background: linear-gradient(180deg, rgba(79, 70, 229, 0.2) 0%, rgba(147, 51, 234, 0.1) 100%);
+            filter: blur(80px);
+            border-radius: 50%;
+            z-index: -1;
+            animation: move 20s infinite alternate;
+        }
+
+        .blob-1 { top: -100px; left: -100px; }
+        .blob-2 { bottom: -100px; right: -100px; animation-delay: -5s; }
+
+        @keyframes move {
+            from { transform: translate(0, 0) scale(1); }
+            to { transform: translate(50px, 50px) scale(1.1); }
+        }
+
+        .container {
+            width: 100%;
+            max-width: 500px;
+            padding: 2rem;
+            background: var(--glass);
+            backdrop-filter: blur(12px);
+            border: 1px solid var(--glass-border);
+            border-radius: 24px;
+            box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
+            animation: fadeIn 0.6s cubic-bezier(0.16, 1, 0.3, 1);
+        }
+
+        @keyframes fadeIn {
+            from { opacity: 0; transform: translateY(20px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+
+        .header {
+            margin-bottom: 2rem;
+            text-align: center;
+        }
+
+        .ai-indicator {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.5rem;
+            background: rgba(79, 70, 229, 0.1);
+            padding: 0.5rem 1rem;
+            border-radius: 100px;
+            color: #818cf8;
+            font-size: 0.875rem;
+            font-weight: 600;
+            margin-bottom: 1rem;
+            border: 1px solid rgba(79, 70, 229, 0.2);
+        }
+
+        .pulse {
+            width: 8px;
+            height: 8px;
+            background: #818cf8;
+            border-radius: 50%;
+            animation: pulse 2s infinite;
+        }
+
+        @keyframes pulse {
+            0% { transform: scale(1); opacity: 1; box-shadow: 0 0 0 0 rgba(129, 140, 248, 0.7); }
+            70% { transform: scale(1); opacity: 1; box-shadow: 0 0 0 10px rgba(129, 140, 248, 0); }
+            100% { transform: scale(1); opacity: 0; }
+        }
+
+        h1 {
+            font-size: 1.5rem;
+            font-weight: 600;
+            line-height: 1.4;
+            color: var(--text-main);
+        }
+
+        .choices {
+            display: flex;
+            flex-direction: column;
+            gap: 0.75rem;
+        }
+
+        button {
+            width: 100%;
+            padding: 1.25rem;
+            background: rgba(255, 255, 255, 0.03);
+            border: 1px solid var(--glass-border);
+            border-radius: 16px;
+            color: var(--text-main);
+            font-size: 1rem;
+            font-weight: 400;
+            text-align: left;
+            cursor: pointer;
+            transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        button:hover {
+            background: rgba(255, 255, 255, 0.08);
+            border-color: rgba(255, 255, 255, 0.2);
+            transform: translateX(4px);
+        }
+
+        button:active {
+            transform: scale(0.98);
+        }
+
+        button .arrow {
+            opacity: 0;
+            transition: 0.2s;
+            transform: translateX(-10px);
+        }
+
+        button:hover .arrow {
+            opacity: 1;
+            transform: translateX(0);
+        }
+
+        .footer {
+            margin-top: 2rem;
+            text-align: center;
+            font-size: 0.75rem;
+            color: var(--text-dim);
+        }
+        
+        .loading-overlay {
+            position: fixed;
+            inset: 0;
+            background: var(--bg-gradient);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            z-index: 100;
+            transition: opacity 0.5s ease;
+        }
+        
+        .loading-overlay.hidden {
+            opacity: 0;
+            pointer-events: none;
+        }
+    </style>
+</head>
+<body>
+    <div class="blob blob-1"></div>
+    <div class="blob blob-2"></div>
+
+    <div id="loading" class="loading-overlay">
+        <div class="ai-indicator">
+            <div class="pulse"></div>
+            Connecting...
+        </div>
+    </div>
+
+    <div class="container">
+        <div class="header">
+            <div class="ai-indicator">
+                <div class="pulse"></div>
+                Agent Interaction
+            </div>
+            <h1 id="question">Please wait while the question loads...</h1>
+        </div>
+        
+        <div id="choices" class="choices">
+            <!-- Buttons will be injected here -->
+        </div>
+
+        <div class="footer">
+            Choice will be returned to the AI assistant immediately.
+        </div>
+    </div>
+
+    <script>
+        async function init() {
+            try {
+                const response = await fetch('/api/details');
+                const data = await response.json();
+                
+                document.getElementById('question').textContent = data.question;
+                const choicesContainer = document.getElementById('choices');
+                
+                data.choices.forEach(choice => {
+                    const btn = document.createElement('button');
+                    btn.innerHTML = `${choice} <span class="arrow">→</span>`;
+                    btn.onclick = () => submit(choice);
+                    choicesContainer.appendChild(btn);
+                });
+                
+                document.getElementById('loading').classList.add('hidden');
+            } catch (err) {
+                console.error('Failed to load details', err);
+                document.getElementById('question').textContent = "Error: Could not connect to MCP server.";
+            }
+        }
+
+        async function submit(choice) {
+            try {
+                await fetch('/api/respond', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ choice })
+                });
+                // Close window if possible
+                window.close();
+                // If window.close() is blocked (standard browser behavior), show success
+                document.querySelector('.container').innerHTML = `
+                    <div style="text-align: center; padding: 2rem;">
+                        <div class="ai-indicator" style="background: rgba(16, 185, 129, 0.1); color: #10b981; border-color: rgba(16, 185, 129, 0.2);">✓ Response Sent</div>
+                        <h1 style="margin-top: 1rem;">Done!</h1>
+                        <p style="color: var(--text-dim); margin-top: 0.5rem;">You can close this tab now.</p>
+                    </div>
+                `;
+            } catch (err) {
+                console.error('Failed to submit response', err);
+            }
+        }
+
+        init();
+    </script>
+</body>
+</html>
+

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "mcp-interactive-choice",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "MCP server for interactive user questions with native Tauri UI",
+    "main": "dist/index.js",
+    "bin": {
+        "mcp-interactive-choice": "dist/index.js"
+    },
+    "files": [
+        "dist",
+        "bin",
+        "README.md"
+    ],
+    "workspaces": [
+        "packages/*"
+    ],
+    "scripts": {
+        "build:server": "tsc",
+        "build:ui": "npm run build --workspace=native-ui",
+        "build": "npm run build:ui && npm run build:server && node scripts/copy-binaries.js",
+        "start": "node dist/index.js",
+        "test": "vitest run"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.3",
+        "commander": "^11.1.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.11.0",
+        "typescript": "^5.3.3",
+        "vitest": "^4.0.18"
+    }
+}