@rawwee/interactive-mcp 1.0.0

package/dist/tool-definitions/request-user-input.js

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+// Define capability conforming to ToolCapabilityInfo
+const capabilityInfo = {
+    description: 'Ask the user a question in an OpenTUI terminal prompt and await their reply.',
+    parameters: {
+        type: 'object',
+        properties: {
+            projectName: {
+                type: 'string',
+                description: 'Identifies the context/project making the request (used in prompt formatting)',
+            },
+            message: {
+                type: 'string',
+                description: 'The specific question for the user (appears in the prompt)',
+            },
+            predefinedOptions: {
+                type: 'array',
+                items: { type: 'string' },
+                optional: true, // Mark as optional here too for consistency
+                description: 'Predefined options for the user to choose from (optional)',
+            },
+            baseDirectory: {
+                type: 'string',
+                description: 'Required absolute path to the current repository root (must be a git repo root; used as file autocomplete/search scope)',
+            },
+        },
+        required: ['projectName', 'message', 'baseDirectory'],
+    },
+};
+// Define description conforming to ToolRegistrationDescription
+const registrationDescription = (globalTimeoutSeconds) => `<description>
+Send a question to the user via the OpenTUI terminal prompt. **Crucial for clarifying requirements, confirming plans, or resolving ambiguity.**
+You should call this tool whenever it has **any** uncertainty or needs clarification or confirmation, even for trivial or silly questions.
+Feel free to ask anything! **Proactive questioning is preferred over making assumptions.**
+</description>
+
+<importantNotes>
+- (!important!) **Use this tool FREQUENTLY** for any question that requires user input or confirmation.
+- (!important!) Continue to generate existing messages after user answers.
+- (!important!) Provide predefined options for quick selection if applicable.
+- (!important!) **Essential for validating assumptions before proceeding with significant actions (e.g., code edits, running commands).**
+</importantNotes>
+
+<whenToUseThisTool>
+- When you need clarification on user requirements or preferences
+- When multiple implementation approaches are possible and user input is needed
+- **Before making potentially impactful changes (code edits, file operations, complex commands)**
+- When you need to confirm assumptions before proceeding
+- When you need additional information not available in the current context
+- When validating potential solutions before implementation
+- When facing ambiguous instructions that require clarification
+- When seeking feedback on generated code or solutions
+- When needing permission to modify critical files or functionality
+- **Whenever you feel even slightly unsure about the user's intent or the correct next step.**
+</whenToUseThisTool>
+
+<features>
+- OpenTUI prompt with markdown rendering (including code/diff blocks)
+- Supports option mode + free-text input mode when predefinedOptions are provided
+- Returns user response or timeout notification (timeout defaults to ${globalTimeoutSeconds} seconds)
+- Maintains context across user interactions
+- Handles empty responses gracefully
+- Properly formats prompt with project context
+- baseDirectory is required, must be the current repository root, and controls file autocomplete/search scope explicitly
+</features>
+
+<bestPractices>
+- Keep questions concise and specific
+- Provide clear options when applicable
+- Do not ask the question if you have another tool that can answer the question
+  - e.g. when you searching file in the current repository, do not ask the question "Do you want to search for a file in the current repository?"
+  - e.g. prefer to use other tools to find the answer (Cursor tools or other MCP Server tools)
+- Limit questions to only what's necessary **to resolve the uncertainty**
+- Format complex questions into simple choices
+- Reference specific code or files when relevant
+- Indicate why the information is needed
+- Use appropriate urgency based on importance
+</bestPractices>
+
+<parameters>
+- projectName: Identifies the context/project making the request (used in prompt formatting)
+- message: The specific question for the user (appears in the prompt)
+- predefinedOptions: Predefined options for the user to choose from (optional)
+- baseDirectory: Required absolute path to the current repository root (must be a git repo root)
+</parameters>
+
+<examples>
+- "Should I implement the authentication using JWT or OAuth?"
+- "Do you want to use TypeScript interfaces or type aliases for this component?"
+- "I found three potential bugs. Should I fix them all or focus on the critical one first?"
+- "Can I refactor the database connection code to use connection pooling?"
+- "Is it acceptable to add React Router as a dependency?"
+- "I plan to modify function X in file Y. Is that correct?"
+- { "projectName": "web-app", "message": "Which file should I edit?", "baseDirectory": "/workspace/web-app" }
+</examples>`;
+// Define the Zod schema (as a raw shape object)
+const rawSchema = {
+    projectName: z
+        .string()
+        .describe('Identifies the context/project making the request (used in prompt formatting)'),
+    message: z
+        .string()
+        .describe('The specific question for the user (appears in the prompt)'),
+    predefinedOptions: z
+        .array(z.string())
+        .optional()
+        .describe('Predefined options for the user to choose from (optional)'),
+    baseDirectory: z
+        .string()
+        .describe('Required absolute path to the current repository root (must be a git repo root; used as file autocomplete/search scope)'),
+};
+// Combine into a single ToolDefinition object
+export const requestUserInputTool = {
+    capability: capabilityInfo,
+    description: registrationDescription,
+    schema: rawSchema, // Use the raw shape here
+};

package/dist/tool-definitions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/base-directory.js

@@ -0,0 +1,44 @@
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * Validate that the provided base directory is an absolute path pointing to a
+ * git repository root (contains a `.git` entry).
+ */
+export async function validateRepositoryBaseDirectory(baseDirectory) {
+    if (baseDirectory.trim().length === 0) {
+        throw new Error('Invalid baseDirectory: value cannot be empty. Provide an absolute path to the current repository root.');
+    }
+    if (!path.isAbsolute(baseDirectory)) {
+        throw new Error('Invalid baseDirectory: path must be absolute and point to the current repository root.');
+    }
+    const normalizedPath = path.resolve(baseDirectory);
+    let baseDirectoryStats;
+    try {
+        baseDirectoryStats = await fs.stat(normalizedPath);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            throw new Error(`Invalid baseDirectory: "${normalizedPath}" does not exist. Provide an absolute path to the current repository root.`);
+        }
+        throw new Error(`Invalid baseDirectory: unable to access "${normalizedPath}". Provide an absolute path to the current repository root.`);
+    }
+    if (!baseDirectoryStats.isDirectory()) {
+        throw new Error(`Invalid baseDirectory: "${normalizedPath}" is not a directory. Provide an absolute path to the current repository root.`);
+    }
+    try {
+        await fs.access(path.join(normalizedPath, '.git'));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            throw new Error(`Invalid baseDirectory: "${normalizedPath}" is not a git repository root (missing ".git").`);
+        }
+        throw new Error(`Invalid baseDirectory: unable to verify ".git" in "${normalizedPath}".`);
+    }
+    return normalizedPath;
+}

package/dist/utils/clipboard.js

@@ -0,0 +1,67 @@
+import os from 'os';
+import { spawn } from 'child_process';
+function runCommand(command, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('error', (error) => {
+            reject(error);
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve({ stdout });
+                return;
+            }
+            reject(new Error(`Command "${command} ${args.join(' ')}" failed with code ${code}: ${stderr || 'no stderr output'}`));
+        });
+        if (typeof input === 'string') {
+            child.stdin.write(input);
+        }
+        child.stdin.end();
+    });
+}
+export async function copyTextToClipboard(text) {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        await runCommand('pbcopy', [], text);
+        return;
+    }
+    if (platform === 'linux') {
+        await runCommand('xclip', ['-selection', 'clipboard'], text);
+        return;
+    }
+    if (platform === 'win32') {
+        await runCommand('clip', [], text);
+        return;
+    }
+    throw new Error(`Clipboard copy is not supported on platform: ${platform}`);
+}
+export async function readTextFromClipboard() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        const result = await runCommand('pbpaste', []);
+        return result.stdout;
+    }
+    if (platform === 'linux') {
+        const result = await runCommand('xclip', ['-selection', 'clipboard', '-o']);
+        return result.stdout;
+    }
+    if (platform === 'win32') {
+        const result = await runCommand('powershell', [
+            '-NoProfile',
+            '-Command',
+            'Get-Clipboard -Raw',
+        ]);
+        return result.stdout;
+    }
+    throw new Error(`Clipboard paste is not supported on platform: ${platform}`);
+}

package/dist/utils/logger.js

@@ -0,0 +1,65 @@
+import { pino, } from 'pino';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+const logDir = path.resolve(os.tmpdir(), 'interactive-mcp-logs');
+const logFile = path.join(logDir, 'dev.log');
+// Ensure log directory exists
+if (process.env.NODE_ENV === 'development' && !fs.existsSync(logDir)) {
+    try {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    catch (error) {
+        console.error('Failed to create log directory:', error); // Use console here as logger isn't initialized yet
+        // Consider fallback behavior or exiting if logging is critical
+    }
+}
+const isDevelopment = process.env.NODE_ENV === 'development';
+const loggerOptions = {
+    level: isDevelopment ? 'trace' : 'silent', // Default level
+};
+if (isDevelopment) {
+    let devTransportConfig;
+    try {
+        // Attempt to open the file in append mode to check writability before setting up transport
+        const fd = fs.openSync(logFile, 'a');
+        fs.closeSync(fd);
+        devTransportConfig = {
+            targets: [
+                {
+                    target: 'pino-pretty', // Log to console with pretty printing
+                    options: {
+                        colorize: true,
+                        sync: false, // Use async logging
+                        translateTime: 'SYS:yyyy-mm-dd HH:MM:ss',
+                        ignore: 'pid,hostname',
+                    },
+                    level: 'trace', // Log all levels to the console in dev
+                },
+                {
+                    target: 'pino/file', // Log to file
+                    options: { destination: logFile, mkdir: true }, // Specify file path and ensure directory exists
+                    level: 'trace', // Log all levels to the file in dev
+                },
+            ],
+        };
+    }
+    catch (error) {
+        console.error(`Failed to setup file transport for ${logFile}. Falling back to console-only logging. Error:`, error);
+        // Fallback transport to console only using pino-pretty if file access fails
+        devTransportConfig = {
+            target: 'pino-pretty',
+            options: {
+                colorize: true,
+                sync: false,
+                translateTime: 'SYS:yyyy-mm-dd HH:MM:ss',
+                ignore: 'pid,hostname',
+            },
+            level: 'trace',
+        };
+    }
+    // Add transport to logger options only in development
+    loggerOptions.transport = devTransportConfig;
+}
+const logger = pino(loggerOptions);
+export default logger;

package/dist/utils/search-root.js

@@ -0,0 +1,85 @@
+import fs from 'fs/promises';
+import path from 'path';
+export const SEARCH_ROOT_ENV_KEY = 'INTERACTIVE_MCP_SEARCH_ROOT';
+const normalizeAbsolutePath = (value) => {
+    if (!value) {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (!trimmed || !path.isAbsolute(trimmed)) {
+        return null;
+    }
+    return path.resolve(trimmed);
+};
+const existsAsDirectory = async (targetPath) => {
+    try {
+        const stats = await fs.stat(targetPath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const isGitRepositoryRoot = async (targetPath) => {
+    if (!(await existsAsDirectory(targetPath))) {
+        return false;
+    }
+    try {
+        await fs.access(path.join(targetPath, '.git'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const findRepositoryRootFrom = async (startPath) => {
+    let current = path.resolve(startPath);
+    while (true) {
+        if (await isGitRepositoryRoot(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+};
+const toDirectoryPath = async (targetPath) => {
+    try {
+        const stats = await fs.stat(targetPath);
+        return stats.isDirectory() ? targetPath : path.dirname(targetPath);
+    }
+    catch {
+        return null;
+    }
+};
+const findRepositoryRootFromScriptEntry = async (argvEntry) => {
+    if (!argvEntry) {
+        return null;
+    }
+    const resolvedArgvEntry = path.isAbsolute(argvEntry)
+        ? path.resolve(argvEntry)
+        : path.resolve(process.cwd(), argvEntry);
+    const startDirectory = await toDirectoryPath(resolvedArgvEntry);
+    if (!startDirectory) {
+        return null;
+    }
+    return findRepositoryRootFrom(startDirectory);
+};
+export async function resolveSearchRoot(preferredSearchRoot, runtimeHints = {}) {
+    const preferredCandidate = normalizeAbsolutePath(preferredSearchRoot);
+    if (preferredCandidate && (await isGitRepositoryRoot(preferredCandidate))) {
+        return preferredCandidate;
+    }
+    const envCandidate = normalizeAbsolutePath(process.env[SEARCH_ROOT_ENV_KEY]);
+    if (envCandidate && (await isGitRepositoryRoot(envCandidate))) {
+        return envCandidate;
+    }
+    const argvEntryRoot = await findRepositoryRootFromScriptEntry(runtimeHints.argvEntry ?? process.argv[1]);
+    if (argvEntryRoot) {
+        return argvEntryRoot;
+    }
+    const cwdRoot = await findRepositoryRootFrom(runtimeHints.cwd ?? process.cwd());
+    return cwdRoot ?? undefined;
+}

package/dist/utils/spawn-detached-terminal.js

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import logger from './logger.js';
+function resolveRuntimeExecutable() {
+    if (process.versions.bun) {
+        return process.execPath;
+    }
+    return process.env.INTERACTIVE_MCP_BUN_PATH || 'bun';
+}
+function createEscapedRuntimeCommand(executable, scriptPath, args, env) {
+    const runtimeArgs = [scriptPath, ...args].map((arg) => `"${arg}"`).join(' ');
+    const envPrefix = createShellEnvPrefix(env);
+    return `${envPrefix}exec "${executable}" ${runtimeArgs}; exit 0`
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"');
+}
+function createLauncherScript(executable, scriptPath, args, env) {
+    const runtimeArgs = [scriptPath, ...args].map((arg) => `"${arg}"`).join(' ');
+    const envPrefix = createShellEnvPrefix(env);
+    return `#!/bin/bash\n${envPrefix}exec "${executable}" ${runtimeArgs}\n`;
+}
+function escapeForDoubleQuotedShellString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\$/g, '\\$')
+        .replace(/`/g, '\\`');
+}
+function createShellEnvPrefix(env) {
+    if (!env) {
+        return '';
+    }
+    return Object.entries(env)
+        .filter(([key, value]) => typeof value === 'string' &&
+        key.length > 0 &&
+        /^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        .map(([key, value]) => {
+        const escapedValue = escapeForDoubleQuotedShellString(value);
+        return `export ${key}="${escapedValue}"; `;
+    })
+        .join('');
+}
+export function spawnDetachedTerminal(options) {
+    const platform = os.platform();
+    const runtimeExecutable = resolveRuntimeExecutable();
+    const spawnEnv = {
+        ...process.env,
+        ...options.env,
+    };
+    if (platform === 'darwin') {
+        const darwinArgs = options.darwinArgs ?? options.args;
+        const escapedRuntimeCommand = createEscapedRuntimeCommand(runtimeExecutable, options.scriptPath, darwinArgs, options.env);
+        const command = `osascript -e 'tell application "Terminal" to activate' -e 'tell application "Terminal" to do script "${escapedRuntimeCommand}"'`;
+        const childProcess = spawn(command, [], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            shell: true,
+            detached: true,
+            env: spawnEnv,
+        });
+        const launchViaOpenCommand = async () => {
+            try {
+                await fs.writeFile(options.macLauncherPath, createLauncherScript(runtimeExecutable, options.scriptPath, darwinArgs, options.env), 'utf8');
+                await fs.chmod(options.macLauncherPath, 0o755);
+                const openProc = spawn('open', ['-a', 'Terminal', options.macLauncherPath], {
+                    stdio: ['ignore', 'ignore', 'ignore'],
+                    detached: true,
+                    env: spawnEnv,
+                });
+                openProc.unref();
+            }
+            catch (error) {
+                logger.error({ error }, options.macFallbackLogMessage);
+            }
+        };
+        childProcess.on('error', () => {
+            void launchViaOpenCommand();
+        });
+        childProcess.on('close', (code) => {
+            if (code !== null && code !== 0) {
+                void launchViaOpenCommand();
+            }
+        });
+        return childProcess;
+    }
+    if (platform === 'win32') {
+        return spawn(runtimeExecutable, [options.scriptPath, ...options.args], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            shell: true,
+            detached: true,
+            windowsHide: false,
+            env: spawnEnv,
+        });
+    }
+    return spawn(runtimeExecutable, [options.scriptPath, ...options.args], {
+        stdio: ['ignore', 'ignore', 'ignore'],
+        shell: true,
+        detached: true,
+        env: spawnEnv,
+    });
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@rawwee/interactive-mcp",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "interactive-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc --outDir dist && tsc-alias",
+    "start": "bun dist/index.js",
+    "lint": "eslint \"src/**/*.{js,ts,jsx,tsx}\"",
+    "format": "prettier --write \"src/**/*.{js,ts,jsx,tsx,json,md}\"",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "description": "",
+  "devDependencies": {
+    "@eslint/js": "^9.25.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.2",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^22.15.2",
+    "@types/node-notifier": "^8.0.5",
+    "@types/pino": "^7.0.5",
+    "@types/react": "^19.1.2",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "eslint": "^9.25.1",
+    "eslint-config-prettier": "^10.1.2",
+    "eslint-plugin-prettier": "^5.2.6",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jiti": "^2.4.2",
+    "lint-staged": "^15.5.1",
+    "pino-pretty": "^13.0.0",
+    "prettier": "^3.5.3",
+    "semantic-release": "^24.2.3",
+    "tsc-alias": "^1.8.15",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.31.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "@opentui/core": "^0.1.86",
+    "@opentui/react": "^0.1.86",
+    "@types/yargs": "^17.0.33",
+    "node-notifier": "^10.0.1",
+    "pino": "^9.6.0",
+    "react": "^19.2.0",
+    "yargs": "^17.7.2",
+    "zod": "^3.24.3"
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx}": [
+      "eslint --fix"
+    ],
+    "*.{js,ts,jsx,tsx,json,md}": [
+      "prettier --write"
+    ]
+  },
+  "packageManager": "bun@1.3.10"
+}