interactive-mcp

Instructions

Implementation Reference

• src/commands/intensive-chat/index.ts:49-142 (handler)

  Core handler function `startIntensiveChatSession` that implements the logic for starting an intensive chat session: creates temp dir, spawns platform-specific child process running ui.js with session payload.

  export async function startIntensiveChatSession(
    title: string,
    timeoutSeconds?: number,
  ): Promise<string> {
    // Create a session directory
    const sessionDir = await createSessionDir();
  
    // Generate a unique session ID
    const sessionId = path.basename(sessionDir).replace('intensive-chat-', '');
  
    // Path to the UI script - Updated to use the compiled 'ui.js' filename
    const uiScriptPath = path.join(__dirname, 'ui.js');
  
    // Create options payload for the UI
    const options = {
      sessionId,
      title,
      outputDir: sessionDir,
      timeoutSeconds,
    };
  
    // Encode options as base64 payload
    const payload = Buffer.from(JSON.stringify(options)).toString('base64');
  
    // Platform-specific spawning
    const platform = os.platform();
    let childProcess: ChildProcess;
  
    if (platform === 'darwin') {
      // macOS
      // Escape potential special characters in paths/payload for the shell command
      // For the shell command executed by 'do script', we primarily need to handle spaces
      // or other characters that might break the command if paths aren't quoted.
      // The `${...}` interpolation within backticks handles basic variable insertion.
      // Quoting the paths within nodeCommand handles spaces.
      const escapedScriptPath = uiScriptPath; // Keep original path, rely on quotes below
      const escapedPayload = payload; // Keep original payload, rely on quotes below
  
      // Construct the command string directly for the shell. Quotes handle paths with spaces.
      const nodeCommand = `exec node "${escapedScriptPath}" "${escapedPayload}"; exit 0`;
  
      // Escape the node command for osascript's AppleScript string:
      // 1. Escape existing backslashes (\ -> \\)
      // 2. Escape double quotes (" -> \")
      const escapedNodeCommand = nodeCommand
        // Escape backslashes first
        .replace(/\\/g, '\\\\') // Using /\\/g instead of /\/g
        // Then escape double quotes
        .replace(/"/g, '\\"');
  
      // Activate Terminal first, then do script with exec
      const command = `osascript -e 'tell application "Terminal" to activate' -e 'tell application "Terminal" to do script "${escapedNodeCommand}"'`;
      const commandArgs: string[] = []; // No args needed when command is a single string for shell
  
      childProcess = spawn(command, commandArgs, {
        stdio: ['ignore', 'ignore', 'ignore'],
        shell: true,
        detached: true,
      });
    } else if (platform === 'win32') {
      // Windows
      childProcess = spawn('node', [uiScriptPath, payload], {
        stdio: ['ignore', 'ignore', 'ignore'],
        shell: true,
        detached: true,
        windowsHide: false,
      });
    } else {
      // Linux or other - use original method (might not pop up window)
      childProcess = spawn('node', [uiScriptPath, payload], {
        stdio: ['ignore', 'ignore', 'ignore'],
        shell: true,
        detached: true,
      });
    }
  
    // Unref the process so it can run independently
    childProcess.unref();
  
    // Store session info
    activeSessions[sessionId] = {
      id: sessionId,
      process: childProcess, // Use the conditionally spawned process
      outputDir: sessionDir,
      lastHeartbeatTime: Date.now(),
      isActive: true,
      title,
    };
  
    // Wait a bit to ensure the UI has started
    await new Promise((resolve) => setTimeout(resolve, 500));
  
    return sessionId;
  }

• src/index.ts:175-221 (registration)

  Registers the 'start_intensive_chat' MCP tool on the server, providing description, schema from tool-definitions, and inline async handler that calls startIntensiveChatSession and handles response/error formatting.

    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 } = args;
        try {
          // Start a new intensive chat session, passing global timeout
          const sessionId = await startIntensiveChatSession(
            sessionTitle,
            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: unknown) {
          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,
              },
            ],
          };
        }
      },
    );
  }

• src/tool-definitions/intensive-chat.ts:11-86 (schema)

  Defines the input schema (JSON Schema in capability.parameters and Zod schema) and tool definition object for 'start_intensive_chat' used in registration.

  const startCapability: ToolCapabilityInfo = {
    description:
      'Start an intensive chat session for gathering multiple answers quickly.',
    parameters: {
      type: 'object',
      properties: {
        sessionTitle: {
          type: 'string',
          description: 'Title for the intensive chat session',
        },
      },
      required: ['sessionTitle'],
    },
  };
  
  const startDescription: ToolRegistrationDescription = (
    globalTimeoutSeconds: number,
  ) => `<description>
  Start an intensive chat session 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 console window for continuous interaction
  - Supports starting with an initial question
  - 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
  </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)
  </parameters>
  
  <examples>
  - Start session for project setup: { "sessionTitle": "Project Configuration" }
  </examples>`;
  
  const startSchema: ZodRawShape = {
    sessionTitle: z.string().describe('Title for the intensive chat session'),
  };
  
  const startToolDefinition: ToolDefinition = {
    capability: startCapability,
    description: startDescription,
    schema: startSchema,
  };