Content
# Solo MCP - 智能多角色协作平台
[](https://python.org)
[](LICENSE)
[](https://pypi.org/project/solo-mcp/)
[](tests/)
[](https://github.com/psf/black)
[](CONTRIBUTING.md)
A smart multi-role collaboration system based on Model Context Protocol (MCP) to improve project development efficiency by simulating the collaboration of different professional roles. Solo MCP enables solo developers to gain the wisdom of team collaboration and achieve higher quality software development.
## ✨ Core Features
### 🎭 Intelligent Role System
- **Multi-Role Simulation**: Intelligently simulate professional roles such as product manager, architect, developer, and test engineer
- **Dynamic Role Assignment**: Automatically select the most suitable role combination based on the task type
- **Role Collaboration**: Intelligent dialogue and decision negotiation between different roles
### 🧠 Advanced Memory Management
- **Persistent Storage**: Long-term memory and quick retrieval of project knowledge
- **Context Awareness**: Intelligently recommend relevant historical information based on the current task
- **Learning Ability**: Learn best practices and common patterns from project history
### 🔄 Intelligent Task Orchestration
- **Automatic Task Decomposition**: Decompose complex projects into manageable subtasks
- **Conflict Detection**: Identify and resolve potential conflicts between tasks
- **Priority Management**: Intelligently prioritize tasks based on project goals
### 📊 Comprehensive Context Analysis
- **Code Understanding**: Deeply analyze project structure, dependencies, and code quality
- **Document Parsing**: Automatically extract and organize project documentation information
- **Environment Awareness**: Identify development environment, toolchain, and configuration
### 🚀 Standardized Integration
- **MCP Protocol**: Based on the Model Context Protocol standard to ensure compatibility
- **Plugin Architecture**: Support custom tools and extensions
- **API Friendly**: Provide complete REST API and Python SDK
## 🚀 Quick Start
### Environment Requirements
- Python 3.11+
- 8GB+ RAM (recommended)
- Supported operating systems: Windows, macOS, Linux
### Installation
#### Method 1: Install from PyPI (Recommended)
```bash
# Install Solo MCP
pip install solo-mcp
# Verify installation
solo-mcp --version
# Start MCP Server
solo-mcp-server
```
#### Method 2: Install from Source Code
```bash
# Clone the project
git clone https://github.com/CHANGGELY/solo-mcp.git
cd solo-mcp
# Create a virtual environment (recommended to use Python 3.11)
python -m venv venv311
# Activate the virtual environment
# Windows
venv311\Scripts\activate
# macOS/Linux
source venv311/bin/activate
# Upgrade pip
python -m pip install --upgrade pip
# Install dependencies
pip install -r requirements.txt
# Install interactive feedback enhanced MCP
pip install mcp-feedback-enhanced
# Verify installation
python -m pytest tests/test_basic.py
```
### Basic Usage
```bash
# View version information
solo-mcp --version
# Start the Solo MCP server
solo-mcp-server
# Start the server with configuration
solo-mcp --server --config custom_config.toml
# Or run from source
python -m solo_mcp
# Run the interactive example
python examples/demo.py
```
## 📖 Usage Examples
### 1. Role Planning Example
```python
from solo_mcp.tools.roles import RolesTool
# Create role tool
roles_tool = RolesTool()
# Evaluate the roles needed for the project
result = roles_tool.evaluate(
goal="开发一个电商网站",
stack="Python, FastAPI, React, PostgreSQL"
)
print(result) # 输出推荐的角色列表
```
### 2. Task Assignment Example
```python
from solo_mcp.config import SoloConfig
from solo_mcp.tools.orchestrator import OrchestratorTool
# Load configuration
config = SoloConfig.load()
# Create orchestration tool
orchestrator = OrchestratorTool(config)
# Run a round of collaboration
result = orchestrator.run_round(
goal="实现用户认证功能",
stack="Python, FastAPI, JWT"
)
print(result) # 输出任务分配和执行结果
```
### 3. Memory Management Example
```python
from solo_mcp.config import SoloConfig
from solo_mcp.tools.memory import MemoryTool
# Load configuration
config = SoloConfig.load()
# Create memory tool
memory_tool = MemoryTool(config)
# Store project information
memory_id = memory_tool.store(
content="用户认证采用JWT token机制",
memory_type="technical",
context={"module": "authentication", "priority": "high"}
)
# Retrieve relevant information
result = memory_tool.load(
query="JWT认证",
memory_type="technical"
)
print(f"找到 {len(result)} 条相关记忆")
```
## 🏗️ Project Architecture
```
solo_mcp/
├── tools/ # 核心工具模块
│ ├── roles.py # 角色规划与管理
│ ├── orchestrator.py # 多角色任务编排
│ ├── memory.py # 智能记忆管理
│ ├── context.py # 上下文收集与处理
│ ├── learning.py # 学习引擎
│ ├── adaptive.py # 自适应优化器
│ └── __init__.py
├── config.py # 配置管理
├── server.py # MCP 服务器
├── main.py # 主入口文件
└── __init__.py
tests/ # 测试文件
├── test_basic.py # 基础功能测试
├── test_roles.py # 角色系统测试
├── test_orchestrator.py # 编排系统测试
├── test_memory.py # 记忆系统测试
└── test_context.py # 上下文系统测试
memory/ # 持久化记忆存储
├── memories/ # 记忆数据文件
├── cache/ # 缓存文件
└── index/ # 索引文件
examples/ # 使用示例
├── demo.py # 基础演示
├── advanced_usage.py # 高级用法
└── integration_test.py # 集成测试
docs/ # 文档
├── api.md # API 文档
├── architecture.md # 架构说明
└── deployment.md # 部署指南
```
## 🧪 Running Tests
```bash
# Run all tests
pytest
# Run a specific test file
pytest tests/test_roles.py
# Run tests and display coverage
pytest --cov=solo_mcp
```
## 🔧 Configuration
The project supports configuration via environment variables and configuration files:
### Environment Variable Configuration
```bash
# Set memory storage path
export SOLO_MCP_MEMORY_PATH="./custom_memory"
# Set log level
export SOLO_MCP_LOG_LEVEL="DEBUG"
# Set cache size
export SOLO_MCP_CACHE_SIZE="1000"
# Set maximum number of memories
export SOLO_MCP_MAX_MEMORIES="10000"
# Set learning engine switch
export SOLO_MCP_ENABLE_LEARNING="true"
```
### Configuration File
Create a `config.json` file for detailed configuration:
```json
{
"memory": {
"max_memories": 10000,
"cache_size": 1000,
"enable_learning": true,
"relevance_threshold": 0.3
},
"orchestrator": {
"max_concurrent_tasks": 5,
"conflict_detection": true,
"auto_optimization": true
},
"roles": {
"default_roles": ["analyst", "developer", "designer", "tester"],
"enable_dynamic_roles": true
}
}
```
#### Integrate Interactive Feedback Enhanced MCP
Add the `mcpServers` configuration in `config.json` to enable interactive feedback enhanced MCP:
```json
"mcpServers": {
"mcp-feedback-enhanced": {
"command": "uvx",
"args": ["mcp-feedback-enhanced@latest"],
"timeout": 600,
"autoApprove": ["interactive_feedback"]
}
}
```
> Tip: `autoApprove` can be adjusted according to requirements to automatically approve the list of tools.
## 🤝 Contribution Guide
We welcome contributions of all kinds! Whether it's reporting bugs, suggesting new features, or submitting code improvements.
### Development Environment Setup
1. **Fork and Clone the Repository**
```bash
git clone https://github.com/your-username/solo-mcp.git
cd solo-mcp
```
2. **Set Up the Development Environment**
```bash
# Create a virtual environment
python -m venv venv311
source venv311/bin/activate # Linux/macOS
# Or venv311\Scripts\activate # Windows
# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt # If it exists
# Install pre-commit hooks
pre-commit install
```
3. **Run Tests**
```bash
# Run all tests
python -m pytest
# Run a specific test
python -m pytest tests/test_basic.py
# Generate coverage report
python -m pytest --cov=solo_mcp --cov-report=html
```
### Contribution Process
1. **Create an Issue**
- Report bugs or suggest new features
- Use the corresponding Issue template
- Provide a detailed description and reproduction steps
2. **Development Process**
```bash
# Create a feature branch
git checkout -b feature/amazing-feature
# Develop...
# Run tests to ensure code quality
python -m pytest
# Commit changes
git add .
git commit -m "feat: add amazing feature"
# Push to your fork
git push origin feature/amazing-feature
```
3. **Submit a Pull Request**
- Use a clear title and description
- Associate with the relevant Issue
- Ensure all tests pass
- Request code review
### Code Style
- **Code Style**: Follow PEP 8 standards
- **Type Annotations**: Use Python type hints
- **Docstrings**: Use Google-style docstrings
- **Tests**: New features must include corresponding tests
- **Commit Messages**: Use [Conventional Commits](https://www.conventionalcommits.org/) format
### Commit Message Format
```
type(scope): description
[optional body]
[optional footer]
```
Types include:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation update
- `style`: Code formatting
- `refactor`: Code refactoring
- `test`: Test related
- `chore`: Changes to the build process or auxiliary tools
### Development Specifications
- Use [Black](https://github.com/psf/black) for code formatting
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) coding standards
- Add corresponding tests for new features
- Update relevant documentation
### Code Formatting
```bash
# Format code
black solo_mcp/ tests/
# Check code style
black --check solo_mcp/ tests/
```
## 🗺️ Roadmap
### Near-Term Goals (v1.1)
- [ ] Add more predefined role types
- [ ] Implement vectorized search for the memory system
- [ ] Optimize task scheduling algorithms
- [ ] Add performance monitoring and metrics
- [ ] Improve API documentation
### Mid-Term Goals (v1.5)
- [ ] Implement distributed memory storage
- [ ] Add a web management interface
- [ ] Support plugin system
- [ ] Integrate more AI models
- [ ] Add real-time collaboration features
### Long-Term Goals (v2.0)
- [ ] Support multi-language SDK
- [ ] Cloud deployment solution
- [ ] Enterprise-level security features
- [ ] Advanced analysis and reporting
- [ ] Automated DevOps integration
## 🐛 Issue Feedback
If you find any issues or have suggestions for improvement, please:
1. Check [Issues](https://github.com/CHANGGELY/solo-mcp/issues) to see if there are any related issues
2. If not, create a new Issue and provide detailed information:
- Problem description
- Reproduction steps
- Expected behavior
- System environment information
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Model Context Protocol](https://github.com/modelcontextprotocol) - Provides a powerful context protocol foundation
- [sentence-transformers](https://github.com/UKPLab/sentence-transformers) - Provides excellent text embedding capabilities
- Support from all contributors and users
---
**Solo MCP** - Making AI collaborative development simple and powerful 🚀
