Marqasa/interact-mcp

Interact MCP

An interactive MCP (Model Context Protocol) server that enables real-time communication between AI assistants and users through a web-based chat interface.

Overview

This project provides an MCP server with an interact tool that allows AI assistants to:

• Ask questions and receive responses from users
• Request confirmation for actions
• Seek guidance or clarification
• Share information in real-time

The server features a Gradio-based web interface that provides a chat UI for seamless user interaction.

Features

• Real-time Interaction: Bidirectional communication between AI and users
• Web-based Chat Interface: Clean, modern UI powered by Gradio
• Multiple Transport Options: Supports both stdio and SSE (Server-Sent Events) transport
• Timeout Handling: Automatic timeout protection for user responses
• Chat History: Maintains conversation history during sessions

Installation

1. Clone this repository:

git clone <repository-url>
cd interact-mcp

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install fastmcp gradio

Usage

Running the Server

Option 1: SSE Transport (Default)

python server.py

This will start the server on 127.0.0.1:3033 and automatically open the chat interface in your browser.

Option 2: Custom Port

python server.py sse 8080

Specify a custom port for the SSE transport.

Option 3: Stdio Transport

python server.py --stdio

Use stdio transport for direct MCP communication.

Using the Chat Interface

1. The web interface will open automatically in your browser
2. Wait for AI assistant messages to appear
3. Respond to questions or prompts in the text input field
4. Your responses will be sent back to the AI assistant through the MCP protocol

Adding to Cursor IDE

To use this MCP server with Cursor IDE, you'll need to configure it in the MCP configuration file.

1. Open Cursor IDE and go to Cursor Settings > Tools & Integrations and click "New MCP Server"
2. This will open the ~/.cursor/mcp.json file for editing
3. Add the following configuration:

{
    "mcpServers": {
        "interact": {
            "command": "path/to/interact-mcp/venv/bin/python3",
            "args": ["path/to/interact-mcp/server.py", "--stdio"]
        }
    }
}

4. Replace path/to/interact-mcp with the actual path to your project directory
5. The Gradio UI should open automatically in your browser

MCP Tool

interact(message: str) -> str

The main tool provided by this server allows AI assistants to interact with users.

Parameters:

• message (str): The message to send to the user

Returns:

• str: The user's response to the message

Timeout:

• Default timeout is 5 minutes (300 seconds)
• Returns timeout message if no response is received

Building Executable

A PyInstaller spec file is included for creating standalone executables:

pyinstaller server.spec

This will create a dist/server executable that includes all necessary dependencies.

Technical Details

• Built with FastMCP framework
• Uses Gradio for the web interface
• Implements threading for concurrent web UI and MCP server operation
• Supports real-time updates with periodic refresh mechanism

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.