mcp-server-agent-comm

KhaiHuynhVN/mcp-server-agent-comm

3.3

If you are the rightful owner of mcp-server-agent-comm and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A sophisticated multi-agent communication framework that enables seamless collaboration between AI agents through MCP (Model Context Protocol) tools.

Agent Communication System

A sophisticated multi-agent communication framework that enables seamless collaboration between AI agents through MCP (Model Context Protocol) tools, with support for real-time message routing, admin control, and dual-language operation.

🌟 Features

  • Multi-Agent Communication: Enable Agent 1 and Agent 2 to communicate efficiently
  • Admin Control System: Absolute priority commands with SOURCE tag authority
  • Real-time Message Routing: Smart delivery and manual routing options
  • Dual Language Support: Vietnamese and English rule sets
  • Advanced UI Controller: Comprehensive interface for message management
  • File & Image Attachments: Support for mixed content communication
  • Workspace-Aware: Intelligent path processing for different workspaces

📋 Prerequisites

  • Python
  • MCP-compatible AI environment (e.g., Claude, Cursor)
  • Git for repository cloning

⚙️ Installation

1. Clone Repository

git clone https://github.com/your-repo/mcp-server-agent-comm.git
cd mcp-server-agent-comm

2. Install Dependencies

pip install -r requirements.txt

3. MCP Server Configuration

Add the following configuration to your MCP settings:

{
  "agent_chat_1": {
    "command": "python",
    "args": ["E:/MCP-servers-github/Utils/mcp_server_agent1.py"],
    "stdio": true,
    "enabled": true
  },
  "agent_chat_2": {
    "command": "python",
    "args": ["E:/MCP-servers-github/Utils/mcp_server_agent2.py"],
    "stdio": true,
    "enabled": true
  }
}

Note: Update the path E:/MCP-servers-github/Utils/ to match your actual installation directory.

📚 Rule Configuration

Language Options

Choose one of the rule files based on your preferred language:

  • Vietnamese: rule_for_AI_VI.txt
  • English: rule_for_AI_EN.txt

Setup in Cursor

  1. Open Cursor settings
  2. Navigate to "Rules for AI" section
  3. Copy and paste the content of your chosen rule file
  4. Save the configuration

image

🚀 Usage

Step 1: Start Controller UI

Open your terminal/command prompt and run:

python E:\MCP-servers-github\Utils\main_controller.py

Note: Replace E:\MCP-servers-github\Utils\ with your actual installation path.

The Controller UI will open, allowing you to monitor and control agent communication.

image

Feature "AI Chat" -> user can chat with all waiting agent.

image

Step 2: Setup Agents in Cursor

  1. Open Two Tabs: Create two separate chat tabs in Cursor image
  2. Tab 1 - Agent 1: Type activation command to start Agent 1
  3. Tab 2 - Agent 2: Type activation command to start Agent 2
  4. Execute Tools: Allow AI to call the MCP server agent chat tools
  5. Monitor Controller: Check Controller UI for registered agents
  6. Route Messages: Use Controller UI to manage message delivery

Activation Commands

For AI Interaction Mode:
  • Vietnamese: start ai_interaction
  • English: start ai_interaction
For Agent Communication Mode:
  • Vietnamese: start agent chat 1 or start agent chat 2
  • English: start agent chat 1 or start agent chat 2

Communication Flow

  1. Agent Registration: Agents register with their respective tools
  2. Message Routing: Controller UI manages message delivery
  3. Priority System: Admin commands (SOURCE=admin) have absolute priority
  4. Collaboration: Agents discuss and confirm execution plans for admin tasks

Detailed Workflow

Initial Setup:
  1. Start Controller UI with python main_controller.py
  2. Open Cursor with two chat tabs
  3. Activate Agent 1 in Tab 1: start agent chat 1
  4. Activate Agent 2 in Tab 2: start agent chat 2
  5. Verify both agents appear in Controller UI "Waiting Agents" section
Message Communication:
  1. Send message from Agent 1 (will appear in message queue)
  2. Use Controller UI to route message to Agent 2
  3. Agent 2 receives and can respond
  4. Continue conversation through Controller UI routing
Admin Controls:
  • Send admin messages with absolute priority
  • Use "Smart Delivery" for automatic routing
  • Monitor real-time agent status
  • Clear data when needed

Admin Controls

  • Absolute Authority: Admin messages override all agent activities
  • Smart Delivery: Automatic routing to available agents
  • Manual Routing: Precise control over message delivery
  • Real-time Monitoring: Live status of waiting agents and message queue

🏗️ Project Structure

Utils/
├── agent_comm/
│   ├── core/                    # Core system components
│   │   ├── config_manager.py    # Configuration management
│   │   ├── flow_manager.py      # Message flow control
│   │   ├── message_handler.py   # Message processing
│   │   └── state_manager.py     # System state management
│   ├── ui/                      # User interface components
│   │   ├── controller_ui.py     # Main controller interface
│   │   └── styles.py           # UI styling
│   ├── chat_ui/                # Chat interface system
│   └── shared_data/            # Persistent data storage
├── mcp_server_agent1.py        # Agent 1 MCP server
├── mcp_server_agent2.py        # Agent 2 MCP server
├── rule_for_AI_VI.txt          # Vietnamese rules
├── rule_for_AI_EN.txt          # English rules
└── README.md                   # This file

🎯 Key Components

Agent Chat Tools

  • mcp_agent_chat_1_agent_chat_1_tool: Communication tool for Agent 1
  • mcp_agent_chat_2_agent_chat_2_tool: Communication tool for Agent 2

Controller Features

  • Message queue management
  • Agent status monitoring
  • Smart delivery system
  • File and image attachment support
  • Real-time refresh capability

Rule System

  • SOURCE Tag Authority: admin = absolute priority, agent = standard
  • Initialization Rules: Keyword-based activation system
  • Workflow Compliance: Mandatory tool recall and thinking blocks
  • Language Consistency: Vietnamese or English throughout communication

🔧 Advanced Features

Message Types

  • Text Messages: Standard communication
  • File Attachments: Document and code sharing
  • Image Support: Visual content communication
  • Mixed Content: Combined text, files, and images

Priority System

  • Admin Commands: Immediate execution, override all activities
  • Agent Messages: Standard peer-to-peer communication
  • Collaboration Required: Agents must discuss admin task execution

UI Controller

  • Real-time Updates: 1.5-second refresh intervals
  • Multi-selection: Batch operations on messages
  • Smart Routing: Automatic agent selection
  • Status Tracking: Comprehensive system monitoring

🐛 Troubleshooting

Common Issues

  1. MCP Server Not Starting

    • Verify Python path in configuration
    • Check file permissions
    • Ensure all dependencies are installed

  2. Agents Not Communicating

    • Confirm both agents are registered
    • Check controller UI for waiting agents
    • Verify rule file is properly configured

  3. Message Queue Issues

    • Use "Clear All Data" in controller UI
    • Restart MCP servers
    • Check shared_data directory permissions

💡 Related Projects:

https://github.com/KhaiHuynhVN/MCP-Server_AI-interaction