# Qwen3 MCP Server

A Model Context Protocol (MCP) server ecosystem providing access to multiple AI models optimized for different tasks: code generation, vision analysis, and complex reasoning.

## 🚀 Quick Start

```bash
# Automated setup
./setup.sh

# Start default server
python src/main.py

# Or use ephemeral model switching
ask-qwen3 "Write a Python function"    # Code generation
ask-vision "Analyze this image"        # Visual analysis  
ask-ministral "Solve this equation"     # Complex reasoning
```

## 📚 Documentation

### Essential Guides
- **[Setup Guide](docs/SETUP.md)** - Complete installation and configuration
- **[Usage Guide](docs/USAGE.md)** - Workflows, examples, and best practices  
- **[Models Reference](docs/MODELS.md)** - Model capabilities and configurations
- **[Agent Guide](AGENTS.md)** - Warp agent integration guidance

### Quick Navigation
- 🏗️ **Getting Started**: [Setup Guide](docs/SETUP.md) → [Usage Guide](docs/USAGE.md)
- 🤖 **Model Selection**: See [Models Reference](docs/MODELS.md#model-selection-guide)
- 🔧 **Troubleshooting**: Check [Setup Guide](docs/SETUP.md#troubleshooting) or [Usage Guide](docs/USAGE.md#troubleshooting-usage-issues)
- 🎯 **Specific Tasks**: Browse [Usage Guide](docs/USAGE.md#workflows-and-use-cases)

## 🌟 Features

### Multi-Model Ecosystem
- **Qwen3-Coder-Next**: Code generation, debugging, technical writing
- **Qwen3-VL-8B**: Image analysis, UI review, document OCR
- **Qwen3-30B**: Complex reasoning with thinking mode
- **Ministral-3-14B**: Mathematical reasoning and logical analysis

### Flexible Hosting
- **Ollama**: Local model serving (recommended)
- **HTTP API**: Remote model endpoints 
- **Transformers**: Direct model loading
- **Ephemeral Switching**: Dynamic model selection

### Developer Experience
- **MCP Compliance**: Full Model Context Protocol support
- **Shell Integration**: Quick aliases and commands
- **Warp Integration**: Native Warp agent support
- **Multi-Transport**: stdio and HTTP transports
- **Thinking Mode**: Detailed reasoning visualization

## 🎯 Use Cases

| Task | Recommended Model | Command |
|------|-------------------|--------|
| Code Review | Qwen3-Coder | `ask-qwen3 "Review this code"` |
| UI Analysis | Qwen3-Vision | `ask-vision "Analyze this screenshot"` |
| Math Problems | Ministral | `ask-ministral "Solve step-by-step"` |
| System Design | Qwen3-30B | `python src/main.py --enable-thinking` |
| Document OCR | Qwen3-Vision | `ask-vision "Extract text from image"` |
| Algorithm Design | Qwen3-Coder | `ask-qwen3 "Implement data structure"` |

## ⚡ Quick Commands

### Model Switching
```bash
mcp-qwen3     # Code-focused development
mcp-vision    # Visual analysis tasks
mcp-ministral # Reasoning and mathematics
mcp-all       # Enable all models
mcp-clean     # Reset to clean state
```

### One-Shot Tasks
```bash
ask-qwen3 "Write a REST API endpoint"
ask-vision "What's wrong with this UI?"
ask-ministral "Prove this theorem"
```

### Server Management
```bash
# Start with specific model
python src/main.py --model-method ollama --ollama-model qwen3:30b-a3b

# Start with HTTP endpoint
python src/main.py --model-method http --http-model qwen/qwen3-coder-next

# Enable debug logging
python src/main.py --log-level DEBUG
```

## 🔧 System Requirements

- **Python**: 3.10+ (3.12+ recommended)
- **Memory**: 16GB+ RAM (32GB+ for 30B model)
- **Network**: Access to HTTP endpoints or Ollama service
- **OS**: macOS, Linux, Windows
- **Optional**: CUDA-compatible GPU for Transformers method

## 🚦 Health Check

```bash
# Check system status
mcp-list

# Test specific model
ask-ministral "Hello, are you working?"

# Verify endpoints
curl -s http://localhost:1234/v1/models
```

## 📁 Project Structure

```
qwen3-mcp-server/
├── docs/                  # 📚 Comprehensive documentation
│   ├── SETUP.md          # Installation and configuration
│   ├── USAGE.md          # Usage patterns and examples
│   └── MODELS.md         # Model reference and capabilities
├── src/                   # 🔧 Core implementation
│   ├── main.py           # Entry point and CLI
│   ├── server.py         # MCP server implementation  
│   ├── model_interface.py # Model hosting abstractions
│   └── config.py         # Configuration management
├── config/                # ⚙️ Model configurations
│   ├── qwen3-coder-http.json
│   ├── qwen3-vl-8b-http.json
│   └── ministral-3-14b-reasoning-http.json
├── scripts/               # 🤖 Automation scripts
│   └── switch-model.sh   # Model switching logic
├── AGENTS.md             # 🤖 Warp agent guidance
├── setup.sh              # 🚀 Automated setup
└── requirements.txt      # 📦 Python dependencies


## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- [Qwen Team](https://github.com/QwenLM) for the Qwen3 models  
- [Ollama](https://ollama.ai/) for local model hosting
- [Mistral AI](https://mistral.ai/) for the Ministral reasoning model