Purpose
interactive-mcp is an MCP (Model Context Protocol) server implemented in Node.js/TypeScript, designed to facilitate interactive communication between an LLM and the user. This server is designed to run locally alongside an MCP client (e.g., Claude Desktop, VS Code), because it requires direct access to the user's operating system to display notifications and command-line prompts. The project is currently in an early stage.
Main Capabilities
This server exposes the following tools through the Model Context Protocol (MCP):
- request_user_input: Ask the user a question and return their answer, with the option to display preset choices.
- message_complete_notification: Send a simple operating system notification.
- start_intensive_chat: Start a persistent command-line chat session.
- ask_intensive_chat: Ask a question in an active intensive chat session.
- stop_intensive_chat: Close an active intensive chat session.
Usage
Client Configuration
By default, user prompts time out after 30 seconds. Server options such as timeout or disabling tools can be customized by adding command-line flags directly to the args array when configuring the client. Please ensure that the npx command is available.
Using with Claude Desktop / Cursor: Add the minimal configuration to claude_desktop_config.json (Claude Desktop) or mcp.json (Cursor). Specifying a version is supported, as is a custom timeout (e.g., 30 seconds).
Using with VS Code: Add the minimal configuration to the user settings (JSON) file or .vscode/mcp.json. When using the default Terminal.app on macOS, consider the following profile setting for a smoother experience: in the "Shell" tab, under "When the shell exits" (Terminal > Settings > Profiles > [your profile] > Shell), select "If the shell exits cleanly, close" or "Close the window." This helps manage windows when the MCP server starts and stops.
Development Setup
This section is mainly intended for developers who want to modify or contribute to the server. If you just want to use the server with an MCP client, please refer to the "Client Configuration" section above.
- Node.js: See package.json for version compatibility.
- pnpm: Used for package management. After installing Node.js, install it via npm install -g pnpm.
Installation (developers):
Clone the repository:
git clone https://github.com/ttommyth/interactive-mcp.git cd interactive-mcp
Install dependencies:
pnpm install
Run the application (developer):
The interactive-mcp server accepts the following command-line options. These options should typically be configured in the MCP client's JSON settings, added directly to the args array (see the "Client Configuration" example).
Example: Set multiple options in the client configuration's args array.
Development commands:
- Build: pnpm build
- Lint: pnpm lint
- Format: pnpm format
When to Use
This server is suitable for scenarios where the LLM needs to interact directly with the user on the user's local machine, such as:
- Interactive setup or configuration processes.
- Collecting feedback during code generation or modification.
- Clarifying instructions or confirming actions during pair programming.
- Any workflow that requires obtaining user input or confirmation while the LLM is running.
Interaction Guidelines
When interacting with this MCP server (for example, as an LLM client), follow these principles to ensure clarity and reduce unintended changes:
- Prioritize interaction: Frequently use the provided MCP tools (request_user_input, start_intensive_chat, etc.) to interact 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 (such as modifying files, running complex commands, or making architectural decisions), confirm the plan with the user.
- Provide options: Where possible, provide preset options to the user through MCP tools to enable quick decision-making.
These instructions can be provided to the LLM client like this.
Limitations
The project is in an early stage. The default user prompt timeout is 30 seconds. Other limitations are not yet provided.
Contributing and License
Contributions are welcome! Please follow standard development practices. (More details may be added later.)
MIT (see the LICENSE file for details—if applicable, or specify the license directly).
