interactive-model-communication-framework

This is an MCP Server implementation leveraging Node.js and TypeScript, engineered to mediate bidirectional communication between sophisticated Language Models and human operators. Crucially: This service necessitates local execution, co-located with the MCP client (e.g., Claude Desktop or IDE extensions), because it requires direct system-level access for functionalities like OS alerts and command-line query handling.

(Note: This project is currently in an initial development phase.)

Seeking a rapid synopsis? Review the introductory essay: Stop Your AI Assistant From Guessing — Introducing interactive-mcp

Demo Video

Exposed Functionalities

This server furnishes the following utilities through the Model Context Protocol (MCP):

• request_user_input: Queries the end-user and captures their response. Can optionally present selectable choices.
• message_complete_notification: Triggers a standard operating system notification.
• start_intensive_chat: Initiates a dedicated, ongoing session within the terminal interface.
• ask_intensive_chat: Submits a query into an already established intensive chat session.
• stop_intensive_chat: Terminates an active intensive session.

Demonstrations

Visualizations of the interactive capabilities:

Normal Question	Completion Notification

Intensive Chat Start	Intensive Chat End

Suitable Deployment Contexts

This server excels in operational contexts where the LLM needs to directly interface with the user's local environment, including:

• Orchestrating guided setup or configuration routines.
• Soliciting critical feedback during software development or code synthesis.
• Resolving ambiguities or securing approvals in collaborative coding sessions.
• Any workflow demanding explicit user intervention or validation during automated LLM execution.

Client Integration Guide

This section details the necessary steps for configuring MCP clients to utilize the interactive-mcp service.

By default, prompts requesting user affirmation will expire after 30 seconds. Server parameters, such as timeout duration or specific tool deactivation, can be modified by appending command-line arguments to the args list in your client's configuration file.

Ensure the npx utility is accessible in your environment.

Usage with Claude Desktop / Cursor

Integrate the subsequent minimal configuration into your claude_desktop_config.json (for Claude Desktop) or mcp.json (for Cursor):

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

Specifying a particular version

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

Example Adjusting Timeout (Set to 30s):

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

Usage with VS Code

Incorporate the following basic configuration into your User Settings (JSON) file or a project-specific .vscode/mcp.json:

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

macOS Terminal Recommendations

For superior window management on macOS when utilizing the standard Terminal.app, adjust the profile settings as follows:

• (Shell Tab): Navigate to "When the shell exits" (Terminal > Settings > Profiles > [Your Profile Name] > Shell), and choose either "Close if the shell exited cleanly" or "Close the window". This optimizes how terminal windows are handled upon server termination.

Developer Setup

This area is targeted towards developers intending to modify or extend the server logic. Users primarily interested in consuming the server should reference the "Client Integration Guide."

Prerequisites

• Node.js: Consult package.json for required version compatibility.
• pnpm: Package management tool. Obtain via npm install -g pnpm after Node.js installation.

Local Installation (For Contributors)

1. Obtain the source code repository:

bash git clone https://github.com/ttommyth/interactive-mcp.git cd interactive-mcp

1. Install required dependencies:

bash pnpm install

Executing the Application (For Developers)

pnpm start

Command-Line Arguments

The interactive-mcp server recognizes the following parameters. These are typically injected into the args array within the client's JSON configuration (refer to the "Client Integration Guide" examples).

Argument	Shorthand	Detailed Explanation
--timeout	-t	Specifies the maximum delay (in seconds) permitted for capturing user input responses. Defaults to 30 seconds.
--disable-tools	-d	Suppresses advertisement/registration of specific capabilities (comma-separated list). Valid options: request_user_input, message_complete_notification, intensive_chat.

Example: Applying Multiple Parameters in Client Configuration args:

// Illustrative configuration snippet for client 'args':
"args": [
  "-y", "interactive-mcp",
  "-t", "30", // Setting the input wait time to 30 seconds
  "--disable-tools", "message_complete_notification,intensive_chat" // Deactivating notifications and chat tools
]

Development Workflow Commands

• Compilation: pnpm build
• Code Quality Check: pnpm lint
• Formatting Enforcement: pnpm format

Interaction Governance Principles

When interfacing with this MCP server (especially from an LLM client perspective), adhere strictly to these directives to ensure operational clarity and mitigate unintended behavior:

• Favor Intervention: Maximize the use of the exposed MCP utilities (request_user_input, start_intensive_chat, etc.) to actively engage the human operator.
• Mandatory Clarification: If any directive, context, or requirement is ambiguous, always pause and solicit specific clarification before proceeding. Assumptions are strictly prohibited.
• Pre-Action Confirmation: Prior to executing substantial operations (e.g., system file modifications, intricate command execution, or major structural design choices), secure explicit user affirmation regarding the intended course of action.
• Option Provision: Where feasible, utilize the MCP tools to present the user with a curated set of choices to expedite decision-making.

You can convey these operational guidelines to an LLM client like this:

# Operational Directives

- Utilize the interactive MCP utilities proactively.
- When possible, furnish discrete options via interactive MCP mechanisms.

# Preventing Unwanted Alterations

- Absolutely avoid making inferences or assumptions.
- Increase the frequency of interrogatives until requirement certainty is achieved.

Collaboration

We welcome external contributions! Standard development contribution protocols should be followed. (Further documentation pending).

Licensing

Distributed under the MIT License (Refer to the LICENSE file for comprehensive terms).