@rawwee/interactive-mcp 1.0.0

package/dist/index.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env bun
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import notifier from 'node-notifier';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { getCmdWindowInput } from './commands/input/index.js';
+import { startIntensiveChatSession, askQuestionInSession, stopIntensiveChatSession, } from './commands/intensive-chat/index.js';
+import { USER_INPUT_TIMEOUT_SECONDS, USER_INPUT_TIMEOUT_SENTINEL, } from './constants.js';
+import logger from './utils/logger.js';
+import { validateRepositoryBaseDirectory } from './utils/base-directory.js';
+// Import tool definitions using the new structure
+import { requestUserInputTool } from './tool-definitions/request-user-input.js';
+import { messageCompleteNotificationTool } from './tool-definitions/message-complete-notification.js';
+import { intensiveChatTools } from './tool-definitions/intensive-chat.js';
+const allToolCapabilities = {
+    request_user_input: requestUserInputTool.capability,
+    message_complete_notification: messageCompleteNotificationTool.capability,
+    start_intensive_chat: intensiveChatTools.start.capability,
+    ask_intensive_chat: intensiveChatTools.ask.capability,
+    stop_intensive_chat: intensiveChatTools.stop.capability,
+};
+const argv = yargs(hideBin(process.argv))
+    .option('timeout', {
+    alias: 't',
+    type: 'number',
+    description: 'Default timeout for user input prompts in seconds',
+    default: USER_INPUT_TIMEOUT_SECONDS,
+})
+    .option('disable-tools', {
+    alias: 'd',
+    type: 'string',
+    description: 'Comma-separated list of tool names to disable. Available options: request_user_input, message_complete_notification, intensive_chat (disables all intensive chat tools).',
+    default: '',
+})
+    .help()
+    .alias('help', 'h')
+    .parseSync();
+const globalTimeoutSeconds = argv.timeout;
+const disabledTools = argv['disable-tools']
+    .split(',')
+    .map((tool) => tool.trim())
+    .filter(Boolean);
+logger.info({
+    globalTimeoutSeconds,
+    disabledTools,
+}, 'Interactive MCP server configuration loaded.');
+// Store active intensive chat sessions
+const activeChatSessions = new Map();
+// --- Filter Capabilities Based on Args ---
+// Helper function to check if a tool is effectively disabled (directly or via group)
+const isToolDisabled = (toolName) => {
+    if (disabledTools.includes(toolName)) {
+        return true;
+    }
+    if ([
+        // Check if tool belongs to the intensive_chat group and the group is disabled
+        'start_intensive_chat',
+        'ask_intensive_chat',
+        'stop_intensive_chat',
+    ].includes(toolName) &&
+        disabledTools.includes('intensive_chat')) {
+        return true;
+    }
+    return false;
+};
+// Create a new object with only the enabled tool capabilities
+const enabledToolCapabilities = Object.fromEntries(Object.entries(allToolCapabilities).filter(([toolName]) => {
+    return !isToolDisabled(toolName);
+})); // Assert type after filtering
+// --- End Filter Capabilities Based on Args ---
+// Helper function to check if a tool should be registered (used later)
+const isToolEnabled = (toolName) => {
+    // A tool is enabled if it's present in the filtered capabilities
+    return toolName in enabledToolCapabilities;
+};
+// Initialize MCP server with FILTERED capabilities
+const server = new McpServer({
+    name: 'Interactive MCP',
+    version: '1.0.0',
+    capabilities: {
+        tools: enabledToolCapabilities, // Use the filtered capabilities
+    },
+});
+// Conditionally register tools based on command-line arguments
+if (isToolEnabled('request_user_input')) {
+    // Use properties from the imported tool object
+    server.tool('request_user_input', 
+    // Need to handle description potentially being a function
+    typeof requestUserInputTool.description === 'function'
+        ? requestUserInputTool.description(globalTimeoutSeconds)
+        : requestUserInputTool.description, requestUserInputTool.schema, // Use schema property
+    async (args) => {
+        // Use inferred args type
+        const { projectName, message, predefinedOptions, baseDirectory } = args;
+        try {
+            const validatedBaseDirectory = await validateRepositoryBaseDirectory(baseDirectory);
+            const promptMessage = `${projectName}: ${message}`;
+            const answer = await getCmdWindowInput(projectName, promptMessage, globalTimeoutSeconds, true, validatedBaseDirectory, predefinedOptions);
+            // Check for the specific timeout indicator
+            if (answer === USER_INPUT_TIMEOUT_SENTINEL) {
+                return {
+                    content: [
+                        { type: 'text', text: 'User did not reply: Timeout occurred.' },
+                    ],
+                };
+            }
+            // Empty string means user submitted empty input, non-empty is actual reply
+            else if (answer === '') {
+                return {
+                    content: [{ type: 'text', text: 'User replied with empty input.' }],
+                };
+            }
+            else {
+                const reply = `User replied: ${answer}`;
+                return { content: [{ type: 'text', text: reply }] };
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error
+                ? `Failed to request user input: ${error.message}`
+                : 'Failed to request user input: unknown error.';
+            return { content: [{ type: 'text', text: errorMessage }] };
+        }
+    });
+}
+if (isToolEnabled('message_complete_notification')) {
+    // Use properties from the imported tool object
+    server.tool('message_complete_notification', 
+    // Description is a string here, but handle consistently
+    typeof messageCompleteNotificationTool.description === 'function'
+        ? messageCompleteNotificationTool.description(globalTimeoutSeconds) // Should not happen based on definition, but safe
+        : messageCompleteNotificationTool.description, messageCompleteNotificationTool.schema, // Use schema property
+    (args) => {
+        // Use inferred args type
+        const { projectName, message } = args;
+        notifier.notify({ title: projectName, message });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Notification sent. You can now wait for user input.',
+                },
+            ],
+        };
+    });
+}
+// --- Intensive Chat Tool Registrations ---
+// Each tool must be checked individually based on filtered capabilities
+if (isToolEnabled('start_intensive_chat')) {
+    // Use properties from the imported intensiveChatTools object
+    server.tool('start_intensive_chat', 
+    // Description is a function here
+    typeof intensiveChatTools.start.description === 'function'
+        ? intensiveChatTools.start.description(globalTimeoutSeconds)
+        : intensiveChatTools.start.description, intensiveChatTools.start.schema, // Use schema property
+    async (args) => {
+        // Use inferred args type
+        const { sessionTitle, baseDirectory } = args;
+        try {
+            const validatedBaseDirectory = await validateRepositoryBaseDirectory(baseDirectory);
+            // Start a new intensive chat session, passing global timeout
+            const sessionId = await startIntensiveChatSession(sessionTitle, validatedBaseDirectory, globalTimeoutSeconds);
+            // Track this session for the client
+            activeChatSessions.set(sessionId, sessionTitle);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Intensive chat session started successfully. Session ID: ${sessionId}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            let errorMessage = 'Failed to start intensive chat session.';
+            if (error instanceof Error) {
+                errorMessage = `Failed to start intensive chat session: ${error.message}`;
+            }
+            else if (typeof error === 'string') {
+                errorMessage = `Failed to start intensive chat session: ${error}`;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorMessage,
+                    },
+                ],
+            };
+        }
+    });
+}
+if (isToolEnabled('ask_intensive_chat')) {
+    // Use properties from the imported intensiveChatTools object
+    server.tool('ask_intensive_chat', 
+    // Description is a string here
+    typeof intensiveChatTools.ask.description === 'function'
+        ? intensiveChatTools.ask.description(globalTimeoutSeconds) // Should not happen, but safe
+        : intensiveChatTools.ask.description, intensiveChatTools.ask.schema, // Use schema property
+    async (args) => {
+        // Use inferred args type
+        const { sessionId, question, predefinedOptions, baseDirectory } = args;
+        // Check if session exists
+        if (!activeChatSessions.has(sessionId)) {
+            return {
+                content: [
+                    { type: 'text', text: 'Error: Invalid or expired session ID.' },
+                ],
+            };
+        }
+        try {
+            const validatedBaseDirectory = await validateRepositoryBaseDirectory(baseDirectory);
+            // Ask the question in the session
+            const answer = await askQuestionInSession(sessionId, question, validatedBaseDirectory, predefinedOptions);
+            // Check for the specific timeout indicator
+            if (answer === USER_INPUT_TIMEOUT_SENTINEL) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'User did not reply to question in intensive chat: Timeout occurred.',
+                        },
+                    ],
+                };
+            }
+            else if (answer === null) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'User closed intensive chat session before replying.',
+                        },
+                    ],
+                };
+            }
+            // Empty string means user submitted empty input, non-empty is actual reply
+            else if (answer === '') {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'User replied with empty input in intensive chat.',
+                        },
+                    ],
+                };
+            }
+            else {
+                return {
+                    content: [{ type: 'text', text: `User replied: ${answer}` }],
+                };
+            }
+        }
+        catch (error) {
+            let errorMessage = 'Failed to ask question in session.';
+            if (error instanceof Error) {
+                errorMessage = `Failed to ask question in session: ${error.message}`;
+            }
+            else if (typeof error === 'string') {
+                errorMessage = `Failed to ask question in session: ${error}`;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: errorMessage,
+                    },
+                ],
+            };
+        }
+    });
+}
+if (isToolEnabled('stop_intensive_chat')) {
+    // Use properties from the imported intensiveChatTools object
+    server.tool('stop_intensive_chat', 
+    // Description is a string here
+    typeof intensiveChatTools.stop.description === 'function'
+        ? intensiveChatTools.stop.description(globalTimeoutSeconds) // Should not happen, but safe
+        : intensiveChatTools.stop.description, intensiveChatTools.stop.schema, // Use schema property
+    async (args) => {
+        // Use inferred args type
+        const { sessionId } = args;
+        // Check if session exists
+        if (!activeChatSessions.has(sessionId)) {
+            return {
+                content: [
+                    { type: 'text', text: 'Error: Invalid or expired session ID.' },
+                ],
+            };
+        }
+        try {
+            // Stop the session
+            const success = await stopIntensiveChatSession(sessionId);
+            // Remove session from map if successful
+            if (success) {
+                activeChatSessions.delete(sessionId);
+            }
+            const message = success
+                ? 'Session stopped successfully.'
+                : 'Session not found or already stopped.';
+            return { content: [{ type: 'text', text: message }] };
+        }
+        catch (error) {
+            let errorMessage = 'Failed to stop intensive chat session.';
+            if (error instanceof Error) {
+                errorMessage = `Failed to stop intensive chat session: ${error.message}`;
+            }
+            else if (typeof error === 'string') {
+                errorMessage = `Failed to stop intensive chat session: ${error}`;
+            }
+            return { content: [{ type: 'text', text: errorMessage }] };
+        }
+    });
+}
+// --- End Intensive Chat Tool Registrations ---
+// Run the server over stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tool-definitions/intensive-chat.js

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+// === Start Intensive Chat Definition ===
+const startCapability = {
+    description: 'Start a persistent OpenTUI intensive chat session for gathering multiple answers quickly.',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionTitle: {
+                type: 'string',
+                description: 'Title for the intensive chat session',
+            },
+            baseDirectory: {
+                type: 'string',
+                description: 'Required absolute path to the current repository root (must be a git repo root; default autocomplete/search scope for this session)',
+            },
+        },
+        required: ['sessionTitle', 'baseDirectory'],
+    },
+};
+const startDescription = (globalTimeoutSeconds) => `<description>
+Start an intensive chat session (OpenTUI terminal UI) for gathering multiple answers quickly from the user.
+**Highly recommended** for scenarios requiring a sequence of related inputs or confirmations.
+Very useful for gathering multiple answers from the user in a short period of time.
+Especially useful for brainstorming ideas or discussing complex topics with the user.
+</description>
+
+<importantNotes>
+- (!important!) Opens a persistent console window that stays open for multiple questions.
+- (!important!) Returns a session ID that **must** be used for subsequent questions via 'ask_intensive_chat'.
+- (!important!) **Must** be closed with 'stop_intensive_chat' when finished gathering all inputs.
+- (!important!) After starting a session, **immediately** continue asking all necessary questions using 'ask_intensive_chat' within the **same response message**. Do not end the response until the chat is closed with 'stop_intensive_chat'. This creates a seamless conversational flow for the user.
+</importantNotes>
+
+<whenToUseThisTool>
+- When you need to collect a series of quick answers from the user (more than 2-3 questions)
+- When setting up a project with multiple configuration options
+- When guiding a user through a multi-step process requiring input at each stage
+- When gathering sequential user preferences
+- When you want to maintain context between multiple related questions efficiently
+- When brainstorming ideas with the user interactively
+</whenToUseThisTool>
+
+<features>
+- Opens a persistent OpenTUI window for continuous interaction
+- Renders markdown prompts, including code/diff snippets, for richer question context
+- Supports option mode + free-text mode while asking follow-up questions
+- Configurable timeout for each question (set via -t/--timeout, defaults to ${globalTimeoutSeconds} seconds)
+- Returns a session ID for subsequent interactions
+- Keeps full chat history visible to the user
+- Maintains state between questions
+- Requires baseDirectory and pins autocomplete/search scope to the repository root
+</features>
+
+<bestPractices>
+- Use a descriptive session title related to the task
+- Start with a clear initial question when possible
+- 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)
+- Always store the returned session ID for later use
+- Always close the session when you're done with stop_intensive_chat
+</bestPractices>
+
+<parameters>
+- sessionTitle: Title for the intensive chat session (appears at the top of the console)
+- baseDirectory: Required absolute path to the current repository root (must be a git repo root)
+</parameters>
+
+<examples>
+- Start session for project setup: { "sessionTitle": "Project Configuration", "baseDirectory": "/workspace/project" }
+- Start session with repository root scope: { "sessionTitle": "Project Configuration", "baseDirectory": "/workspace/project" }
+</examples>`;
+const startSchema = {
+    sessionTitle: z.string().describe('Title for the intensive chat session'),
+    baseDirectory: z
+        .string()
+        .describe('Required absolute path to the current repository root (must be a git repo root; default autocomplete/search scope for this session)'),
+};
+const startToolDefinition = {
+    capability: startCapability,
+    description: startDescription,
+    schema: startSchema,
+};
+// === Ask Intensive Chat Definition ===
+const askCapability = {
+    description: 'Ask a question in an active OpenTUI intensive chat session.',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionId: {
+                type: 'string',
+                description: 'ID of the intensive chat session',
+            },
+            question: {
+                type: 'string',
+                description: 'Question to ask the user',
+            },
+            predefinedOptions: {
+                type: 'array',
+                items: { type: 'string' },
+                optional: true,
+                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; autocomplete/search scope for this question)',
+            },
+        },
+        required: ['sessionId', 'question', 'baseDirectory'],
+    },
+};
+const askDescription = `<description>
+Ask a new question in an active intensive chat session previously started with 'start_intensive_chat'.
+</description>
+
+<importantNotes>
+- (!important!) Requires a valid session ID from 'start_intensive_chat'.
+- (!important!) Supports predefined options for quick selection.
+- (!important!) Returns the user's answer or indicates if they didn't respond.
+- (!important!) **Use this repeatedly within the same response message** after 'start_intensive_chat' until all questions are asked.
+</importantNotes>
+
+<whenToUseThisTool>
+- When continuing a series of questions in an intensive chat session.
+- When you need the next piece of information in a multi-step process initiated via 'start_intensive_chat'.
+- When offering multiple choice options to the user within the session.
+- When gathering sequential information from the user within the session.
+</whenToUseThisTool>
+
+<features>
+- Adds a new question to an existing chat session
+- Supports predefined options for quick selection
+- Returns the user's response
+- Maintains the chat history in the console
+- Requires baseDirectory for each question and scopes autocomplete/search to the repository root
+</features>
+
+<bestPractices>
+- Ask one clear question at a time
+- Provide predefined options when applicable
+- Don't ask overly complex questions
+- Keep questions focused on a single piece of information
+</bestPractices>
+
+<parameters>
+- sessionId: ID of the intensive chat session (from start_intensive_chat)
+- question: The question text to display to the user
+- predefinedOptions: Array of 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>
+- Simple question: { "sessionId": "abcd1234", "question": "What is your project named?", "baseDirectory": "/workspace/project" }
+- With predefined options: { "sessionId": "abcd1234", "question": "Would you like to use TypeScript?", "predefinedOptions": ["Yes", "No"], "baseDirectory": "/workspace/project" }
+- Ask another repo-scoped question: { "sessionId": "abcd1234", "question": "Pick a file", "baseDirectory": "/workspace/project" }
+</examples>`;
+const askSchema = {
+    sessionId: z.string().describe('ID of the intensive chat session'),
+    question: z.string().describe('Question to ask the user'),
+    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; autocomplete/search scope for this question)'),
+};
+const askToolDefinition = {
+    capability: askCapability,
+    description: askDescription,
+    schema: askSchema,
+};
+// === Stop Intensive Chat Definition ===
+const stopCapability = {
+    description: 'Stop and close an active intensive chat session.',
+    parameters: {
+        type: 'object',
+        properties: {
+            sessionId: {
+                type: 'string',
+                description: 'ID of the intensive chat session to stop',
+            },
+        },
+        required: ['sessionId'],
+    },
+};
+const stopDescription = `<description>
+  Stop and close an active intensive chat session. **Must be called** after all questions have been asked using 'ask_intensive_chat'.
+</description>
+
+<importantNotes>
+- (!important!) Closes the console window for the intensive chat.
+- (!important!) Frees up system resources.
+- (!important!) **Should always be called** as the final step when finished with an intensive chat session, typically at the end of the response message where 'start_intensive_chat' was called.
+</importantNotes>
+
+<whenToUseThisTool>
+- When you've completed gathering all needed information via 'ask_intensive_chat'.
+- When the multi-step process requiring intensive chat is complete.
+- When you're ready to move on to processing the collected information.
+- When the user indicates they want to end the session (if applicable).
+- As the final action related to the intensive chat flow within a single response message.
+</whenToUseThisTool>
+
+<features>
+- Gracefully closes the console window
+- Cleans up system resources
+- Marks the session as complete
+</features>
+
+<bestPractices>
+- Always stop sessions when you're done to free resources
+- Provide a summary of the information collected before stopping
+</bestPractices>
+
+<parameters>
+- sessionId: ID of the intensive chat session to stop
+</parameters>
+
+<examples>
+- { "sessionId": "abcd1234" }
+</examples>`;
+const stopSchema = {
+    sessionId: z.string().describe('ID of the intensive chat session to stop'),
+};
+const stopToolDefinition = {
+    capability: stopCapability,
+    description: stopDescription,
+    schema: stopSchema,
+};
+// === Export Combined Intensive Chat Definitions ===
+export const intensiveChatTools = {
+    start: startToolDefinition,
+    ask: askToolDefinition,
+    stop: stopToolDefinition,
+};

package/dist/tool-definitions/message-complete-notification.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+// Define capability conforming to ToolCapabilityInfo
+const capabilityInfo = {
+    description: 'Notify when a response has completed via OS notification.',
+    parameters: {
+        type: 'object',
+        properties: {
+            projectName: {
+                type: 'string',
+                description: 'Identifies the context/project making the notification (appears in notification title)',
+            },
+            message: {
+                type: 'string',
+                description: 'The specific notification text (appears in the body)',
+            },
+        },
+        required: ['projectName', 'message'],
+    },
+};
+// Define description conforming to ToolRegistrationDescription
+const registrationDescription = `<description>
+Notify when a response has completed. Use this tool **once** at the end of **each and every** message to signal completion to the user.
+</description>
+
+<importantNotes>
+- (!important!) **MANDATORY:** ONLY use this tool exactly once per message to signal completion. **Do not forget this step.**
+</importantNotes>
+
+<whenToUseThisTool>
+- When you've completed answering a user's query
+- When you've finished executing a task or a sequence of tool calls
+- When a multi-step process is complete
+- When you want to provide a summary of completed actions just before ending the response
+</whenToUseThisTool>
+
+<features>
+- Cross-platform OS notifications (Windows, macOS, Linux)
+- Reusable tool to signal end of message
+- Should be called exactly once per LLM response
+</features>
+
+<bestPractices>
+- Keep messages concise
+- Use projectName consistently to group notifications by context
+</bestPractices>
+
+<parameters>
+- projectName: Identifies the context/project making the notification (appears in notification title)
+- message: The specific notification text (appears in the body)
+</parameters>
+
+<examples>
+- { "projectName": "MyApp", "message": "Feature implementation complete. All tests passing." }
+- { "projectName": "MyLib", "message": "Analysis complete: 3 issues found and fixed." }
+</examples>`;
+// Define the Zod schema (as a raw shape object)
+const rawSchema = {
+    projectName: z.string().describe('Notification title'),
+    message: z.string().describe('Notification body'),
+};
+// Combine into a single ToolDefinition object
+export const messageCompleteNotificationTool = {
+    capability: capabilityInfo,
+    description: registrationDescription,
+    schema: rawSchema, // Use the raw shape here
+};