interactive-mcp

interactive-mcp

A MCP Server implemented in Node.js/TypeScript, facilitating interactive communication between LLMs and users. Note: This server is designed to run locally alongside the MCP client (e.g., Claude Desktop, VS Code), as it needs direct access to the user's operating system to display notifications and command-line prompts.

(Note: This project is in its early stages.)

Features

• Interactive Prompts: Ask users questions via OS notifications or a dedicated command prompt.
• Simple Notifications: Send informational messages to the user's OS.
• Intensive Chat: Initiate persistent command-line chat sessions for multi-turn interactions.
• Cross-Platform: Designed to work on Windows, macOS, and Linux (leveraging node-notifier).
• Customizable Timeout: Set a custom timeout for user prompts (default: 30 seconds) using the -t or --timeout flag.

Tools

This server exposes the following tools via the Model Context Protocol (MCP):

• request_user_input: Asks the user a question and returns their answer. Can display predefined options.
• message_complete_notification: Sends a simple OS notification.
• start_intensive_chat: Initiates a persistent command-line chat session.
• ask_intensive_chat: Asks a question within an active intensive chat session.
• stop_intensive_chat: Closes an active intensive chat session.

Usage Scenarios

This server is ideal for scenarios where an LLM needs to interact directly with the user on their local machine, such as:

• Interactive setup or configuration processes.
• Gathering feedback during code generation or modification.
• Clarifying instructions or confirming actions in pair programming.
• Any workflow requiring user input or confirmation during LLM operation.

Client Configuration

This section explains how to configure MCP clients to use the interactive-mcp server.

By default, user prompts will time out after 30 seconds. You can change this by adding the timeout flag (-t <seconds> or --timeout <seconds>) to the args array after "--" when configuring your client.

Please make sure you have the npx command available.

Usage with Claude Desktop / Cursor

Add the following minimal configuration to your claude_desktop_config.json (Claude Desktop) or mcp.json (Cursor):

{
  "mcpServers": {
    "interactive": {
      "command": "npx",
      "args": ["-y", "interactive-mcp"]
    }
  }
}

Example with Custom Timeout (60 seconds):

{
  "mcpServers": {
    "interactive": {
      "command": "npx",
      "args": ["-y", "interactive-mcp", "--", "-t", "60"]
    }
  }
}

Usage with VS Code

Add the following minimal configuration to your User Settings (JSON) file or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "interactive-mcp": {
        "command": "npx",
        "args": ["-y", "interactive-mcp"]
      }
    }
  }
}

macOS Recommendations

For a smoother experience on macOS using the default Terminal.app, consider these profile settings:

• (Shell Tab): Under "When the shell exits" (Terminal > Settings > Profiles > [Your Profile] > Shell), select "Close if the shell exited cleanly" or "Close the window". This helps manage windows when the MCP server starts and stops.
• (Advanced Tab): Under Input (Terminal > Settings > Profiles > [Your Profile] > Advanced), uncheck the option "Delete sends Control-H". By default, macOS Terminal sends Control-H (ASCII Backspace) when you press Delete. Unchecking this might help in applications that expect a different sequence, though achieving a specific sequence like \033[3~ (often needed for forward delete) might still require other configurations or terminal alternatives.

Demo

Here's a demonstration of the interactive features (chat and prompts):

Here's a demonstration of the completion notification:

Development Setup

This section is primarily for developers looking to modify or contribute to the server. If you just want to use the server with an MCP client, see the "Client Configuration" section above.

Prerequisites

• Node.js: Check package.json for version compatibility.
• pnpm: Used for package management. Install via npm install -g pnpm after installing Node.js.

Installation (Developers)

1. Clone the repository:

   git clone <your-repo-url>
   cd interactive-mcp
   

2. Install dependencies:

   pnpm install
   

Running the Application (Developers)

pnpm start

To run with a custom timeout (e.g., 60 seconds), pass the arguments after --:

pnpm start -- -t 60
# or
pnpm start -- --timeout 60

Development Commands

• Build: pnpm build
• Lint: pnpm lint
• Format: pnpm format

Guiding Principles for Interaction

When interacting with this MCP server (e.g., as an LLM client), please adhere to the following principles to ensure clarity and reduce unexpected changes:

• Prioritize Interaction: Utilize the provided MCP tools (request_user_input, start_intensive_chat, etc.) frequently to engage with the user.
• Seek Clarification: If requirements, instructions, or context are unclear, always ask clarifying questions before proceeding. Do not make assumptions.
• Confirm Actions: Before performing significant actions (like modifying files, running complex commands, or making architectural decisions), confirm the plan with the user.
• Provide Options: Whenever possible, present the user with predefined options through the MCP tools to facilitate quick decisions.

You can provide these instructions to an LLM client like this:

# Interaction

- Please use the interactive MCP tools
- Please provide options to interactive MCP if possible

# Reduce Unexpected Changes

- Do not make assumption.
- Ask more questions before executing, until you think the requirement is clear enough.

Contributing

Contributions are welcome! Please follow standard development practices. (Further details can be added later).

License

MIT (See LICENSE file for details - if applicable, or specify license directly).