Content
# MCASys — Multi-Agent Collaboration System v2.1
<p align="center">
<img src="docs/screenshots/architecture.svg" alt="MCASys System Architecture" width="960">
</p>
<p align="center">
<strong>Production-grade Multi-Agent Collaboration Framework</strong> · REST API + WebSocket · Workbench IDE · Skills · MCP · LLM Integration
</p>
<p align="center">
<img src="https://img.shields.io/badge/Python-3.9+-3776AB?logo=python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/FastAPI-0.115+-009688?logo=fastapi&logoColor=white" alt="FastAPI">
<img src="https://img.shields.io/badge/LLM-DeepSeek_V3.2-8B5CF6?logo=openai&logoColor=white" alt="DeepSeek">
<img src="https://img.shields.io/badge/MCP-Protocol-FF6B6B?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMSAxNy45M2MtMy45NS0uNDktNy0zLjg1LTctNy45MyAwLS40MS4wMy0uODEuMDgtMS4yMUw5IDE0djFjMCAxLjEuOSAyIDIgMnYyLjkzem01LjktMi4zYy0uMjYtLjgxLTEtMS4zOS0xLjktMS4zOWgtMXYtM2MwLS41NS0uNDUtMS0xLTFIOHYtMmgyYy41NSAwIDEtLjQ1IDEtMVY3aDJjMS4xIDAgMi0uOSAyLTJ2LS40MWMyLjkzIDEuMTkgNSA0LjA2IDUgNy40MSAwIDIuMDgtLjggMy45Ny0yLjEgNS4zM3oiLz48L3N2Zz4=" alt="MCP">
<img src="https://img.shields.io/badge/License-MIT-green" alt="MIT">
</p>
---
## Overview
**MCASys** is a complete multi-agent collaboration framework that integrates **Skills**, **MCP Protocol**, and **DeepSeek-V3.2 LLM**, providing a production-grade REST API + WebSocket + beautiful Dark Mode multi-interface.
> Reference Architecture: kimi-cli (Python EventBus), kimi-code (TypeScript Kaos/Swarm), ScriptForge (Java Retry/DI)
---
## Interface Screenshots
<p align="center">
<img src="docs/screenshots/dashboard.svg" alt="Dashboard" width="400">
<img src="docs/screenshots/workbench.svg" alt="Workbench" width="400">
<img src="docs/screenshots/config.svg" alt="Config" width="400">
<img src="docs/screenshots/architecture.svg" alt="Architecture" width="400">
</p>
From left to right, top to bottom: Dashboard · Workbench IDE · System Configuration · Five-layer Architecture Diagram
---
## New Features (v2.1)
### 🧠 LLM Large Model Integration
- **Silicon Flow API** driven, default DeepSeek-V3.2
- Multi-model support: DeepSeek-R1, Qwen2.5-72B, GLM-4, etc.
- Web-side configuration, save and take effect immediately (hot loading), no need to restart
- Agent automatically senses LLM availability, intelligent reasoning vs simulation fallback
### 🖥️ Workbench IDE (Workbench)
- Three-column IDE layout: step tree + editing area + agent dialogue
- 7-step workflow visualization (initialization → analysis → distribution → execution → retraction → review → completion)
- Embedded AI Chat (connected to DeepSeek-V3.2), supporting multi-turn dialogue
- Bottom draggable output log panel + status bar
### ⚙️ System Configuration Center
- **LLM Configuration**: API Key input (password box + show/hide switch), model drop-down selection, temperature slider, Max Token
- **MCP Management**: server table CRUD, test connection, STDIO/HTTP dual mode
- **Skills Browse**: card grid + details pop-up (including process diagram and prompt words)
- **System Information**: version number, online agent, event subscription, API Key status
### 🧩 Skills System
- Three-level hierarchical coverage: built-in → user-level → project-level
- `SkillManager.discover_skills()` automatic discovery and loading
- 3 built-in skills: `code-review`, `data-analysis`, `workflow-orchestration`
- Agent automatically matches skills and injects system prompts when started
### 🔌 MCP Protocol
- `MCPClientManager`: STDIO subprocess + HTTP dual transmission
- `MCPServer`: MCASys exposes 5 MCP tools
- JSON-RPC 2.0 complete implementation: initialize → tools/list → tools/call
---
## Quick Start
### Prerequisites
- Python 3.9+
- (Optional) Silicon Flow API Key → [siliconflow.cn](https://siliconflow.cn) registration and acquisition
### Installation & Launch
```bash
# Clone project
git clone https://github.com/lxy3837/MultiCoopAgentSystem
cd MCASys
# Install dependencies
pip install -r requirements.txt
# Launch service
$env:MCASYS_API_KEY = "mcasys-default-key" # PowerShell
python run_fastapi.py
```
### Configure LLM (optional but recommended)
Open browser → http://localhost:8000/config → Fill in Silicon Flow API Key → Save
Or through environment variables:
```bash
$env:SILICONFLOW_API_KEY = "sk-xxxxxxxxxxxxx"
```
### Access Entrance
| Address | Function |
|:--|:--|
| http://localhost:8000 | Dashboard |
| http://localhost:8000/workbench | Workbench IDE |
| http://localhost:8000/config | System Configuration |
| http://localhost:8000/docs | Swagger API Documentation |
---
## System Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Frontend：Dashboard · Workbench · Config · Streamlit │
├─────────────────────────────────────────────────────────┤
│ FastAPI REST API + WebSocket Gateway (20+ Endpoints) │
├─────────────────────────────────────────────────────────┤
│ Core Engine：EventBus · Scheduler · Swarm · DI · Kaos │
├─────────────────────────────────────────────────────────┤
│ Agent Layer：Coordinator · Executor · Analyzer │
│ + LLM (DeepSeek-V3.2) · Skills (3) · MCP │
├─────────────────────────────────────────────────────────┤
│ Infrastructure：SQLite · MCP Server · SiliconFlow API │
└─────────────────────────────────────────────────────────┘
```
---
## Project Structure
```
MCASys/
├── app.py # FastAPI main entry (20+ endpoints + WebSocket + Chat)
├── main.py # Agent system initialization
├── run_fastapi.py # Uvicorn launch script
├── requirements.txt
│
├── core/ # Core infrastructure layer
│ ├── event_bus.py # Asynchronous publish/subscribe event bus
│ ├── runtime.py # Global runtime context (DB + Bus + Scheduler + LLM)
│ ├── scheduler.py # Background task scheduling cycle
│ ├── llm.py # ★ Silicon Flow API client (DeepSeek-V3.2)
│ ├── database.py # SQLAlchemy asynchronous database
│ ├── models.py # ORM model
│ ├── repository.py # Repository data access layer
│ ├── security.py # API Key authentication
│ ├── result.py # AgentResult unified return type
│ ├── retry.py # RetryTemplate generic retry framework
│ ├── swarm.py # SwarmBatch parallel batch scheduling
│ ├── stream_tracker.py # StreamTracker step flow tracking
│ ├── di.py # DI container
│ ├── lock.py # Server file mutex lock
│ └── kaos/ # Environment abstraction layer (local/remote)
│
├── agents/ # Agent implementation
│ ├── base_agent.py # Agent base class (including LLM attributes)
│ └── specialized_agents/
│ ├── coordinator_agent.py # Coordinator Agent (AI task planning)
│ ├── executor_agent.py # Executor Agent
│ └── analyzer_agent.py # Analyzer Agent
│
├── mcp/ # ★ MCP protocol implementation
│ ├── __init__.py
│ ├── types.py # Pydantic type definition
│ ├── config.py # Configuration management (config/mcp.json)
│ ├── client.py # Client (STDIO + HTTP)
│ └── server.py # Local MCP server (5 tools)
│
├── skills/ # ★ Skills system
│ ├── __init__.py
│ ├── base.py # Skill / Flow / FlowRunner
│ ├── manager.py # Three-level discovery loader
│ ├── flow.py # Mermaid/D2 process diagram parsing
│ └── builtin/
│ ├── code_review/SKILL.md
│ ├── data_analysis/SKILL.md
│ └── workflow_orchestration/SKILL.md
│
├── collaboration/ # Collaboration logic
│ ├── conflict_resolver.py
│ ├── state_manager.py
│ └── task_allocation.py
│
├── frontend/ # Web page
│ ├── index.html # Dashboard
│ ├── styles.css # Global Dark Mode style
│ ├── app.js # Front-end logic
│ ├── config.html # ★ System configuration page
│ ├── workbench.html # ★ Workbench IDE
│ └── workbench/
│ ├── workbench.css
│ └── workbench.js
│
├── config/ # Configuration file
│ ├── config.py # Pydantic configuration class
│ ├── config.yaml # YAML configuration (including LLM)
│ └── mcp.json # MCP server configuration
│
├── data/ # Data & Knowledge base
├── utils/ # Tool functions
├── tests/ # Test cases
└── docs/
└── screenshots/ # ★ Architecture diagram & screenshots
├── architecture.svg
└── dashboard_full.png
```
---
## API Endpoints
All `/api/v1/*` endpoints require Bearer Token: `Authorization: Bearer <key>`
### System & Configuration
| Method | Path | Description |
|:--|:--|:--|
| GET | `/` | Dashboard |
| GET | `/workbench` | ★ Workbench |
| GET | `/config` | ★ Configuration page |
| GET | `/docs` | Swagger API |
| GET/PUT | `/api/v1/config/llm` | ★ LLM configuration read/write |
### LLM Chat
| Method | Path | Description |
|:--|:--|:--|
| POST | `/api/v1/chat` | ★ LLM dialogue (multi-turn) |
| GET | `/api/v1/chat/status` | ★ LLM availability status |
### Agent & Task
| Method | Path | Description |
|:--|:--|:--|
| GET | `/api/v1/agents` | Agent list |
| GET/POST | `/api/v1/agents/{id}` | Agent management |
| GET/POST/PUT/DELETE | `/api/v1/tasks` | Task CRUD |
### Skills & MCP
| Method | Path | Description |
|:--|:--|:--|
| GET | `/api/v1/skills` | ★ Skill list |
| GET | `/api/v1/skills/{name}` | ★ Skill details |
| POST | `/api/v1/skills/reload` | ★ Reload skills |
| GET/POST/DELETE | `/api/v1/mcp/servers` | ★ MCP servers |
| POST | `/api/v1/mcp/servers/{name}/connect` | ★ Test connection |
### WebSocket
| Protocol | Path | Description |
|:--|:--|:--|
| WS | `/ws/events` | Real-time event stream push |
---
## Example Usage
### Create Task (via API)
```bash
curl -X POST http://localhost:8000/api/v1/tasks \
-H "Authorization: Bearer mcasys-default-key" \
-H "Content-Type: application/json" \
-d '{"name": "Data Analysis", "task_type": "analysis"}'
```
### WebSocket Real-time Listening
```javascript
const ws = new WebSocket('ws://localhost:8000/ws/events');
ws.onmessage = (e) => {
const event = JSON.parse(e.data);
console.log(event.type, event.data);
};
```
### LLM Dialogue
```bash
curl -X POST http://localhost:8000/api/v1/chat \
-H "Authorization: Bearer mcasys-default-key" \
-H "Content-Type: application/json" \
-d '{"message": "Please help me analyze the performance bottleneck of this code"}'
```
### Using AgentResult + LLM in Code
```python
from core.result import AgentResult
from core.llm import get_llm_client
llm = get_llm_client()
async def analyze_data(filepath: str) -> AgentResult:
try:
data = read_csv(filepath)
# Intelligent analysis using LLM
report = await llm.chat(
prompt=f"Analyze the following data: {data.describe()}",
system_prompt="You are a professional data analyst"
)
return AgentResult.ok(data={"analysis": report})
except Exception as e:
return AgentResult.fail(error=str(e))
```
---
## Skill System Details
### Three-Level Hierarchical Coverage
```
skills/
├── builtin/ # Level 1: Built-in (lowest priority)
│ ├── code_review/
│ ├── data_analysis/
│ └── workflow_orchestration/
├── %USERPROFILE%/.mcasys/skills/ # Level 2: User-level
└── .mcasys/skills/ # Level 3: Project-level (highest priority)
```
### SKILL.md Format
```markdown
# Skill Name
description: Brief description
type: standard | flow
agent: coordinator | executor | analyzer | all
when_to_use: Trigger conditions
tools:
- tool_a
- tool_b
## SystemPrompt
This is the system prompt injected into LLM...
## Flow (only for flow type)
```mermaid
graph TD
A[Start] --> B{Judgment}
B -->|Yes| C[Execute]
B -->|No| D[Skip]
```
```
---
## MCP Protocol Details
### Exposed MCP Tools
| Tool | Description |
|:--|:--|
| `system_info` | Get system information (version, agent count) |
| `agent_status` | Query agent status |
| `task_create` | Create task |
| `task_list` | Get task list |
| `task_status` | Query task status |
### Connecting to MCASys MCP Server
```json
{
"mcpServers": {
"mcasys": {
"command": "python",
"args": ["-m", "mcp.server"]
}
}
}
```
---
## Environment Variables
| Variable | Description | Default Value |
|:--|:--|:--|
| `MCASYS_API_KEY` | Service API authentication key | Automatically generated |
| `SILICONFLOW_API_KEY` | Silicon flow API key | — |
| `SILICONFLOW_MODEL` | Default LLM model | `deepseek-ai/DeepSeek-V3.2` |
| `SILICONFLOW_BASE_URL` | LLM API address | `https://api.siliconflow.cn/v1` |
| `MCASYS_PORT` | Service port | `8000` |
| `MCASYS_HOST` | Binding address | `0.0.0.0` |
---
## Architecture Comparison
Core patterns borrowed from reference projects:
| Source | Borrowed Pattern | MCASys Implementation |
|:--|:--|:--|
| **kimi-cli** (Python) | EventBus / Runtime / Scheduler | `core/event_bus.py`, `core/runtime.py`, `core/scheduler.py` |
| **kimi-code** (TS) | Kaos / Swarm / Lock / DI | `core/kaos/`, `core/swarm.py`, `core/lock.py`, `core/di.py` |
| **ScriptForge** (Java) | AgentResult / RetryTemplate / StreamTracker / Workbench | `core/result.py`, `core/retry.py`, `core/stream_tracker.py`, `frontend/workbench` |
| **MCP Protocol** | STDIO + HTTP transmission / JSON-RPC 2.0 | `mcp/client.py`, `mcp/server.py` |
| **KLIP-8** | Skills hierarchical coverage strategy | `skills/manager.py` |
---
## Running Tests
```bash
pytest tests/ -v
```
---
## License
MIT License · [GitHub](https://github.com/lxy3837/MultiCoopAgentSystem) · v2.1
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available