Vijay-Nirmal/WebInteractMCP

WebInteractMCP

Transform any web application into an MCP server with real-time two-way communication

WebInteractMCP is an innovative MCP (Model Context Protocol) ecosystem that enables any web application to become an MCP server, allowing chatbots and other MCP clients to control client sessions and complete intended actions on behalf of users.

Imagine an LLM-powered chatbot not just talking about actions, but directly performing them on your website for the user in real-time. It allows Large Language Models to use pre-defined tools to control a user's session securely and complete tasks.

📢 Check out the preview version available now! This project is in active development. Expect breaking changes in future releases as we evolve toward version 1.0.0

🚀 Overview

WebInteractMCP consists of two tightly integrated components that work together to create a seamless MCP experience:

• 📚 @web-interact-mcp/client - TypeScript library for client-side integration
• 🖥️ WebInteractMCPServer - Ready to deploy Docker MCP server image for protocol handling

✨ Key Features

• 🔧 Support full MCP Tool protocol - including tool discovery, invocation, and all type of response Text, Image, Audio others
• 🔄 Real-time Communication - Robust bidirectional communication using SignalR which support WebSockets, ServerSentEvents, LongPolling
• 🛠️ Dynamic Tool Registration - Configure tools with simple JSON files
• 🎯 Session-based Control - Per-user session management for secure isolation
• 🌐 Framework Agnostic - Works with any JavaScript framework (React, Angular, Vue, etc.)
• ⚡ Production Ready - Comprehensive error handling and performance optimization
• 🔧 Simple Configuration - Easy setup with JSON-based tool definitions
• 📦 Docker Support - Ready-to-use Docker image for easy deployment
• 📄 Page-specific Tools - Define tools that can interact with specific pages or elements
• 🎨 Visual Feedback - Provides visual feedback for tool execution and user actions

🎬 Demo

https://github.com/user-attachments/assets/bf9d15a6-fa4a-40a0-8543-cb0fd92bffac

Click to view the demonstration of WebInteractMCP transforming a web application into an MCP server

🏗️ Architecture

sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 Website
    participant C as 📦 @web-interact-mcp/client
    participant CB as 🤖 MCP Client<br/>(ChatBot Server)
    participant MS as 🖥️ WebInteractMCPServer

    %% Styling
    Note over U,MS: WebInteractMCP Communication Flow
    
    rect rgba(135, 206, 235, 0.1)
        Note over U,MS: 🚀 Session Initialization Phase
        U->>+W: 💬 Opens chat session
        W->>+C: 🔧 Initialize MCP session
        C->>+MS: 🔗 Establish 2-way connection<br/>(SignalR WebSocket)
        MS-->>-C: ✅ Connection established
        C->>+MS: 🛠️ Send tools configuration
        MS-->>-C: 🆔 Return session ID
        C-->>-W: 📋 Provide session ID
        W-->>-U: 🟢 Session ready
    end

    rect rgba(144, 238, 144, 0.1)
        Note over U,MS: 📝 Task Processing Phase
        U->>+W: ⌨️ Enters task/query
        W->>+CB: 📤 Send request with session ID
        CB->>+MS: 🔌 Connect & register tools
        MS-->>-CB: 🛠️ Return available tools
        CB->>CB: 🧠 LLM processes task<br/>& selects tools
    end
    
    rect rgba(255, 182, 193, 0.1)
        Note over U,MS: ⚡ Tool Execution Phase
        CB->>+MS: 🎯 Invoke tool with parameters
        MS->>+C: 📨 Forward tool invocation
        C->>+W: 🖱️ Execute actions<br/>(DOM manipulation, clicks)
        W-->>-C: 📊 Return execution result
        C-->>-MS: 📤 Send tool response
        MS-->>-CB: 📥 Forward response to LLM
        CB->>+W: 🎨 Return processed result
        W-->>-U: 📺 Display response
    end

🚀 Quick Start

1. Install the Client Library

# Install the stable version (Not yet available)
npm install @web-interact-mcp/client

# Or install the latest preview version
npm install @web-interact-mcp/client@preview

2. Configure Your Tools

Create a mcp-tools.json file:

[
  {
    "toolId": "click-button",
    "title": "Click Button",
    "description": "Clicks a specific button on the page",
    "mode": "silent",
    "steps": [
      {
        "targetElement": "#submit-btn",
        "action": { "type": "click", "element": "#submit-btn" }
      }
    ]
  }
]

3. Initialize in Your Web App

import { createWebInteractMCPController } from '@web-interact-mcp/client';

const controller = createWebInteractMCPController();
await controller.loadTools('/mcp-tools.json');
await controller.createSession('http://localhost:8080');

4. Run the MCP Server

# Using Docker (Recommended)
docker run -p 8080:8080 vijaynirmalpon/web-interact-mcp-server:latest

# Or build from source
cd server/WebInteractMCPServer
dotnet run

📁 Project Structure

WebInteractMCP/
├── lib/web-interact-mcp/           # TypeScript MCP Library
│   ├── src/                       # Source code
│   └── README.md                  # Library documentation
├── server/WebInteractMCPServer/    # .NET MCP Server
│   ├── Program.cs                 # Server entry point
│   └── README.md                  # Server documentation
├── sample/                        # Reference implementations
│   └── angular-dotnetnet-semantic-kernel/

🎯 Use Cases

• Automated Testing - Control web applications for E2E testing
• User Onboarding - Create guided tours and tutorials
• Process Automation - Automate repetitive web-based tasks
• Accessibility - Provide AI-powered navigation assistance
• Data Entry - Automate form filling and data collection

🔧 Technology Stack

⚠️ Development Status

Initial preview version will be published soon. This project is in active development and has not yet reached version 1.0.

• ✅ Core functionality is working
• ✅ Production-ready components available
• 🚀 Check out the preview version available now
• ⚠️ Breaking changes expected in future releases
• ⚠️ API is subject to change before 1.0 release

Feel free to use it in your projects, but be prepared for potential breaking changes as we approach the initial preview release.

📖 Documentation

• - Complete TypeScript library documentation
• - MCP server configuration and deployment

🤝 Contributing

We welcome contributions! Please see our for development standards and workflow.

Development Workflow

# Setup
npm install
cd lib/web-interact-mcp && npm install
cd sample/angular-dotnetnet-semantic-kernel && npm install

# Start development environment with sample app
cd sample/angular-dotnetnet-semantic-kernel
npm run start:server    # Web Interact MCP server
npm run start:client    # .NET client backend sample app
npm run start           # Angular frontend sample app

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Links

• GitHub Issues - Report bugs or request features
• Discussions - Community discussions

Built with ❤️ for the MCP ecosystem