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

🚀 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.

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

Step 2: Setup Agents in Cursor

1. Open Two Tabs: Create two separate chat tabs in Cursor
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