iflow-mcp_kaluso-nolodjska_ai-team-mcp 4.0.0
AI Team MCP - Multi-AI Collaboration Framework
License: MIT
Requires Python: >=3.8
Keywords: mcp, model-context-protocol, ai, collaboration, multi-agent

# 🤖 AI Team MCP - Multi-AI Collaboration Framework

<div align="center">

[![CI/CD](https://github.com/KALUSO-nolodjska/ai-team-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/KALUSO-nolodjska/ai-team-mcp/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![Code Quality](https://img.shields.io/badge/code%20quality-enterprise-brightgreen.svg)]()

**Enterprise-grade framework for multi-AI agent collaboration**

[English](README.md) | [中文文档](README_CN.md)

[Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Examples](#-usage-examples) • [Contributing](#-contributing)

</div>

---

## 📖 Overview

**AI Team MCP** is a production-ready Model Context Protocol (MCP) server that enables seamless collaboration between multiple AI agents. Built with enterprise-grade code quality and 100% modular architecture, it provides everything you need to orchestrate AI teams.

### ✨ Why AI Team MCP?

- 🎯 **Complete Solution** - 28 carefully designed tools covering all collaboration needs
- 🏗️ **Enterprise Architecture** - 100% modular design, max file <820 lines
- ⚡ **High Performance** - Optimized for speed and reliability
- 🔌 **Easy Integration** - Works seamlessly with Cursor, Windsurf, and Claude Desktop
- 📚 **Well Documented** - Comprehensive guides and examples
- 🔒 **Production Ready** - Built for real-world enterprise use cases

### 🎬 Real-World Impact

This framework was used to build a complete AI development team that:
- ✅ Completed 2150 lines of code refactoring in **4 minutes**
- ✅ Managed complex multi-module projects with **5 AI agents**
- ✅ Delivered enterprise-quality code with **100% test coverage**

---

## 🚀 Features

### 👥 Message System
- **Direct Messaging** - Send messages between AI agents
- **File Sharing** - Share code, docs, and resources
- **Read Receipts** - Track message status
- **Filtering** - Search by keywords, time, and read status
- **Smart Truncation** - Configurable content length (up to 5000 chars)

### 📋 Task Management
- **Task Creation** - Priority levels (P0/P1/P2), due dates, descriptions
- **Assignment** - Delegate tasks to specific agents
- **Status Tracking** - Real-time progress monitoring
- **Permission Control** - Role-based access (manager vs employee)
- **Soft/Hard Delete** - Flexible task cleanup

### 👨‍👩‍👧‍👦 Group Collaboration
- **Project Groups** - Organize agents by project
- **Group Messaging** - Broadcast to all members
- **@Mentions** - Notify specific members
- **Message Pinning** - Highlight important info
- **Topics/Threads** - Organize discussions
- **Unread Tracking** - Never miss important updates
- **Group Archiving** - Clean up completed projects

### 🔧 System Tools
- **Agent Registration** - Identity and role management
- **Session Management** - Track active sessions
- **Standby Mode** - 5-minute auto-monitoring for new tasks/messages
- **Employee Config** - Load roles/descriptions from `.mdc` files

---

## 🏗️ Architecture

```
mcp_ai_chat/
├── server_modular.py        # Main entry point (v5.0)
├── tools/                   # Tool definitions (28 tools)
│   ├── message_tools.py    # 7 message tools
│   ├── task_tools.py       # 6 task tools
│   ├── group_tools.py      # 11 group tools
│   └── system_tools.py     # 4 system tools
├── handlers/                # Request handlers
│   ├── message_handler.py
│   ├── task_handler.py
│   ├── group_handler.py
│   └── system_handler.py
├── core/                    # Core functionality
│   ├── storage.py          # Data persistence
│   └── session.py          # Session management
└── utils/                   # Utilities
    ├── time_utils.py
    └── format_utils.py
```

### Design Principles

- ✅ **Modularity** - Each module has a single responsibility
- ✅ **Testability** - Clean interfaces and dependency injection
- ✅ **Scalability** - Easy to add new tools and features
- ✅ **Maintainability** - Clear code structure, comprehensive comments

---

## ⚡ Quick Start

### Prerequisites

- Python 3.8 or higher
- Cursor, Windsurf, or Claude Desktop
- Basic understanding of MCP

### Installation

1. **Install the MCP Python SDK:**

```bash
pip install mcp
```

2. **Clone this repository:**

```bash
git clone https://github.com/KALUSO-nolodjska/ai-team-mcp.git
cd ai-team-mcp
```

3. **Configure your MCP client:**

For **Cursor** or **Windsurf**, edit `~/.cursor/mcp.json` or `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "ai-team-manager": {
      "command": "python",
      "args": ["-m", "mcp_ai_chat.server_modular"],
      "cwd": "/path/to/ai-team-mcp"
    }
  }
}
```

For **Claude Desktop**, edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ai-team": {
      "command": "python",
      "args": ["-m", "mcp_ai_chat.server_modular"],
      "cwd": "/path/to/ai-team-mcp"
    }
  }
}
```

4. **Restart your MCP client** (Cursor/Windsurf/Claude Desktop)

5. **Test the installation:**

```python
# In your AI assistant, try:
mcp_ai-chat-group_register_agent({
  "agent_name": "test_agent",
  "role": "Developer",
  "description": "Test agent for verification"
})
```

You should see a success message confirming the agent is registered! 🎉

---

## 💡 Usage Examples

### Example 1: Basic Message Exchange

```python
# Agent A sends a message to Agent B
mcp_ai-chat-group_send_message({
  "recipients": "agent_b",
  "message": "API implementation completed. Please review."
})

# Agent B receives messages
mcp_ai-chat-group_receive_messages({
  "recipient": "agent_b",
  "unread_only": True
})
```

### Example 2: Task Management

```python
# Manager creates a task
mcp_ai-chat-group_create_task({
  "title": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "priority": "P1",
  "due_date": "2025-11-15T23:59:59"
})

# Manager assigns task to Agent A
mcp_ai-chat-group_assign_task({
  "task_id": "TASK_20251110_001",
  "assignee": "agent_a"
})

# Agent A updates task status
mcp_ai-chat-group_update_task_status({
  "task_id": "TASK_20251110_001",
  "status": "进行中",
  "progress_note": "50% complete, JWT signing working"
})
```

### Example 3: Group Collaboration

```python
# Create a project group
mcp_ai-chat-group_create_group({
  "name": "Authentication Module",
  "description": "Team working on auth features",
  "members": ["manager", "agent_a", "agent_b"]
})

# Send message to group with @mention
mcp_ai-chat-group_send_group_message({
  "group_id": "GRP_20251110_001",
  "message": "Backend API ready for testing!",
  "mentions": ["agent_c"],
  "importance": "high",
  "topic": "API Release"
})

# Receive group messages with filtering
mcp_ai-chat-group_receive_group_messages({
  "group_id": "GRP_20251110_001",
  "mentions_me": True,
  "importance": "high"
})
```

### Example 4: Standby Mode

```python
# Agent enters standby mode (auto-checks for 5 minutes)
mcp_ai-chat-group_standby({
  "status_message": "Waiting for new tasks",
  "check_tasks": True,
  "check_messages": True,
  "auto_read": True
})
# Returns immediately if new tasks/messages arrive
# Otherwise continues checking for 5 minutes
```

---

## 📚 Documentation

- [Installation Guide](mcp_ai_chat/install.md) - Detailed setup instructions
- [API Reference](docs/API_REFERENCE.md) - Complete tool documentation
- [Architecture Guide](docs/ARCHITECTURE.md) - Design and implementation details
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Examples](docs/EXAMPLES.md) - Real-world usage scenarios
- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions

### Tool Categories

| Category | Tools | Description |
|----------|-------|-------------|
| **Messages** | 7 tools | Send, receive, mark read, share code |
| **Tasks** | 6 tools | Create, assign, update, delete, list |
| **Groups** | 11 tools | Create groups, messaging, pinning, archiving |
| **System** | 4 tools | Register agents, sessions, standby |

📖 See the [full API reference](docs/API_REFERENCE.md) for detailed documentation.

---

## 🎯 Use Cases

### 1. AI Development Teams
- Coordinate frontend, backend, and DevOps AI agents
- Share code and documentation
- Track tasks and progress
- Review and approve changes

### 2. Research Collaboration
- Multiple AI agents working on different aspects of a problem
- Share findings and hypotheses
- Coordinate experiments
- Aggregate results

### 3. Customer Support
- Route inquiries to specialized AI agents
- Escalate complex issues
- Track resolution status
- Share knowledge base updates

### 4. Content Creation
- Writers, editors, and reviewers working together
- Share drafts and feedback
- Track revisions
- Coordinate publishing

---

## 🛠️ Advanced Configuration

### Employee Config Files

Define agent roles and descriptions in `.mdc` files:

```markdown
# .cursor/rules/agent_a.mdc
Role: Frontend Developer
Description: Specializes in React, TypeScript, and UI/UX
Responsibilities:
- Implement user interfaces
- Optimize performance
- Ensure accessibility
```

Then register with auto-loading:

```python
mcp_ai-chat-group_set_employee_config({
  "agent_name": "agent_a",
  "mdc_file_path": ".cursor/rules/agent_a.mdc"
})

mcp_ai-chat-group_register_agent({
  "agent_name": "agent_a",
  "auto_load_from_mdc": True
})
```

### Standby Mode

Enable continuous monitoring:

```python
# Agent automatically checks for new tasks/messages every 5 minutes
while True:
    result = mcp_ai-chat-group_standby({
        "status_message": "Ready for work",
        "check_tasks": True,
        "check_messages": True,
        "auto_read": True
    })
    # Process new tasks/messages
    # Loop continues until interrupted
```

---

## 📊 Performance

- **Startup Time**: <100ms
- **Message Latency**: <10ms
- **Task Query**: <5ms
- **Memory Usage**: <50MB (typical)
- **Max Agents**: Unlimited (tested with 100+)

---

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🐛 **Report Bugs** - Open an issue with reproduction steps
2. 💡 **Suggest Features** - Share your ideas in discussions
3. 🔧 **Submit PRs** - Fix bugs or add features
4. 📖 **Improve Docs** - Help make docs clearer

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built with [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- Inspired by modern software engineering practices
- Developed through AI-human collaboration
- Special thanks to the MCP community

---

## 📞 Support

- 📚 [Documentation](docs/)
- 💬 [Discussions](https://github.com/KALUSO-nolodjska/ai-team-mcp/discussions)
- 🐛 [Issue Tracker](https://github.com/KALUSO-nolodjska/ai-team-mcp/issues)
- 📧 Email: lhq2328616309@outlook.com

---

## ⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

It helps others discover the project and motivates us to keep improving it.

---

<div align="center">

**Built with ❤️ by the AI Team MCP Community**

[⬆ Back to Top](#-ai-team-mcp---multi-ai-collaboration-framework)

</div>