README.md•18.3 kB
# Fusion 360 MCP - Multi-Model AI Integration
**FusionMCP** is a comprehensive Model Context Protocol (MCP) integration layer that connects Autodesk Fusion 360 with multiple AI backends (Ollama, OpenAI, Google Gemini, and Anthropic Claude) to enable AI-powered parametric CAD design through natural language.
## 🎯 Features
- 🤖 **Multi-Model Support**: Seamlessly switch between Ollama, OpenAI GPT-4o, Google Gemini, and Claude 3.5
- 🔄 **Intelligent Routing**: Automatic fallback chain when primary model fails
- 📐 **Parametric Design**: AI understands and generates parametric CAD operations
- 🛡️ **Safety First**: Built-in validation for dimensions, units, and geometric feasibility
- 💾 **Context Caching**: Conversation and design state persistence (JSON/SQLite)
- 🎨 **Fusion 360 Integration**: Native add-in for seamless workflow
- ⚡ **Async Architecture**: Fast, non-blocking operations with retry logic
- 📊 **Structured Logging**: Detailed logs with Loguru
## 📋 Table of Contents
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
- [Model Comparison](#model-comparison)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Fusion 360 User │
│ ↓ │
│ ┌─────────────────────────┐ │
│ │ Fusion 360 Add-in │ │
│ │ - UI Dialog │ │
│ │ - Action Executor │ │
│ │ - Network Client │ │
│ └──────────┬──────────────┘ │
│ ↓ HTTP/REST │
│ ┌─────────────────────────┐ │
│ │ MCP Server (FastAPI) │ │
│ │ - Router │ │
│ │ - Schema Validation │ │
│ │ - Context Cache │ │
│ └──────────┬──────────────┘ │
│ ↓ │
│ ┌───────────────┴───────────────────┐ │
│ ↓ ↓ ↓ ↓ │
│ ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │
│ │ Ollama │ │ OpenAI │ │ Gemini │ │ Claude │ │
│ │ (Local) │ │ API │ │ API │ │ API │ │
│ └─────────┘ └──────────┘ └────────┘ └──────────┘ │
│ │
│ System Prompt (FusionMCP Personality) │
│ ↓ │
│ Structured JSON Actions → Fusion 360 │
└─────────────────────────────────────────────────────────────┘
```
### Component Overview
1. **Fusion 360 Add-in** (`fusion_addin/`)
- Python-based Fusion 360 add-in
- Captures user intent and design context
- Executes structured CAD actions
- Real-time UI feedback
2. **MCP Server** (`mcp_server/`)
- FastAPI-based REST server
- Routes requests to appropriate LLM
- Validates and normalizes responses
- Caches conversation history
3. **LLM Clients** (`mcp_server/llm_clients/`)
- Unified interface for all models
- Provider-specific implementations
- Automatic retry and error handling
4. **System Prompt** (`prompts/system_prompt.md`)
- Defines FusionMCP personality
- Enforces JSON output format
- Provides action schema templates
## 🚀 Installation
### Prerequisites
- **Python 3.11+** (for MCP server)
- **Autodesk Fusion 360** (2025 version recommended)
- **At least one LLM provider**:
- [Ollama](https://ollama.ai) (local, free)
- [OpenAI API Key](https://platform.openai.com)
- [Google AI API Key](https://makersuite.google.com/app/apikey)
- [Anthropic API Key](https://console.anthropic.com)
### Step 1: Clone Repository
```bash
git clone https://github.com/yourusername/fusion360-mcp.git
cd fusion360-mcp
```
### Step 2: Install Python Dependencies
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Or install in development mode
pip install -e .
```
### Step 3: Configure Environment
Create `config.json` from example:
```bash
cp examples/example_config.json config.json
```
Edit `config.json` with your API keys:
```json
{
"ollama_url": "http://localhost:11434",
"openai_api_key": "sk-proj-...",
"gemini_api_key": "AIza...",
"claude_api_key": "sk-ant-...",
"default_model": "openai:gpt-4o-mini",
"mcp_host": "127.0.0.1",
"mcp_port": 9000
}
```
**Alternative**: Use environment variables (`.env` file):
```bash
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...
CLAUDE_API_KEY=sk-ant-...
```
### Step 4: Install Fusion 360 Add-in
1. Copy `fusion_addin/` folder to Fusion 360 add-ins directory:
- **Windows**: `%APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\`
- **macOS**: `~/Library/Application Support/Autodesk/Autodesk Fusion 360/API/AddIns/`
2. Rename to `FusionMCP`:
```bash
cp -r fusion_addin "/Users/YOUR_USER/Library/Application Support/Autodesk/Autodesk Fusion 360/API/AddIns/FusionMCP"
```
3. Restart Fusion 360
4. Open Fusion 360 → **Scripts and Add-Ins** → **Add-Ins** tab → Select **FusionMCP** → **Run**
## 🎬 Quick Start
### 1. Start MCP Server
```bash
# Activate virtual environment
source venv/bin/activate
# Start server
python -m mcp_server.server
```
Expected output:
```
INFO | Logger initialized with level INFO
INFO | Cache initialized: json
INFO | System prompt loaded
INFO | Initialized MCP Router with providers: ['ollama', 'openai', 'gemini', 'claude']
INFO | MCP Server started on 127.0.0.1:9000
```
### 2. Test Server (Optional)
```bash
curl -X POST http://127.0.0.1:9000/mcp/command \
-H "Content-Type: application/json" \
-d '{
"command": "ask_model",
"params": {
"provider": "openai",
"model": "gpt-4o-mini",
"prompt": "Create a 20mm cube"
},
"context": {
"active_component": "RootComponent",
"units": "mm",
"design_state": "empty"
}
}'
```
### 3. Use in Fusion 360
1. Open Fusion 360
2. Click **Scripts and Add-Ins** → **Add-Ins** → **FusionMCP** → **Run**
3. Click **MCP Assistant** button in toolbar
4. Enter natural language command:
- "Create a 20mm cube"
- "Design a mounting bracket with 4 holes"
- "Make a cylindrical shaft 10mm diameter, 50mm long"
## ⚙️ Configuration
### Full Configuration Options
```json
{
// API Configuration
"ollama_url": "http://localhost:11434",
"openai_api_key": "sk-proj-...",
"gemini_api_key": "AIza...",
"claude_api_key": "sk-ant-...",
// Model Selection
"default_model": "openai:gpt-4o-mini",
"fallback_chain": [
"openai:gpt-4o-mini",
"gemini:gemini-1.5-flash-latest",
"ollama:llama3"
],
// Server Settings
"mcp_host": "127.0.0.1",
"mcp_port": 9000,
"allow_remote": false,
// Logging
"log_level": "INFO",
"log_dir": "logs",
// Caching
"cache_enabled": true,
"cache_type": "json", // or "sqlite"
"cache_path": "context_cache.json",
// Timeouts and Retries
"timeout_seconds": 30,
"max_retries": 3,
"retry_delay": 1.0,
// Available Models
"models": {
"ollama": {
"available": ["llama3", "mistral", "codellama"],
"default": "llama3"
},
"openai": {
"available": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
"default": "gpt-4o-mini"
},
"gemini": {
"available": ["gemini-1.5-pro-latest", "gemini-1.5-flash-latest"],
"default": "gemini-1.5-flash-latest"
},
"claude": {
"available": ["claude-3-5-sonnet-20241022"],
"default": "claude-3-5-sonnet-20241022"
}
}
}
```
## 💡 Usage Examples
### Example 1: Simple Geometry
**Prompt**: "Create a 20mm cube"
**Generated Action**:
```json
{
"action": "create_box",
"params": {
"width": 20,
"height": 20,
"depth": 20,
"unit": "mm"
},
"explanation": "Creating a 20mm cubic box",
"safety_checks": ["dimensions_positive", "units_valid"]
}
```
### Example 2: Complex Design
**Prompt**: "Design a mounting bracket 100x50mm with 4 M5 mounting holes"
**Generated Action Sequence**:
```json
{
"actions": [
{
"action": "create_box",
"params": {"width": 100, "height": 50, "depth": 5, "unit": "mm"},
"explanation": "Create base plate"
},
{
"action": "create_hole",
"params": {"diameter": 5.5, "position": {"x": 10, "y": 10}, "unit": "mm"},
"explanation": "M5 clearance hole (10mm edge offset)"
},
// ... 3 more holes
],
"total_steps": 5
}
```
### Example 3: Parametric Design
**Prompt**: "Create a shaft with diameter 2x of length"
```json
{
"clarifying_questions": [
{
"question": "What is the shaft length?",
"context": "Need length to calculate diameter (diameter = 2 × length)",
"suggestions": ["50mm", "100mm", "Custom"]
}
]
}
```
## 📡 API Reference
### Endpoints
#### POST `/mcp/command`
Execute MCP command.
**Request Body**:
```json
{
"command": "ask_model",
"params": {
"provider": "openai",
"model": "gpt-4o-mini",
"prompt": "User prompt here",
"temperature": 0.7,
"max_tokens": 2000
},
"context": {
"active_component": "RootComponent",
"units": "mm",
"design_state": "empty"
}
}
```
**Response**:
```json
{
"status": "success",
"message": "Action generated successfully",
"actions_to_execute": [...],
"llm_response": {...}
}
```
#### GET `/health`
Health check.
**Response**:
```json
{
"status": "healthy",
"providers": ["ollama", "openai", "gemini", "claude"],
"cache_enabled": true
}
```
#### GET `/models`
List available models.
**Response**:
```json
{
"models": {
"ollama": ["llama3", "mistral"],
"openai": ["gpt-4o", "gpt-4o-mini"],
"gemini": ["gemini-1.5-pro-latest"],
"claude": ["claude-3-5-sonnet-20241022"]
}
}
```
#### GET `/history?limit=10`
Get conversation history.
**Response**:
```json
{
"conversations": [...],
"actions": [...]
}
```
### Supported Actions
| Action | Description | Required Params |
|--------|-------------|-----------------|
| `create_box` | Create rectangular box | `width`, `height`, `depth`, `unit` |
| `create_cylinder` | Create cylinder | `radius`, `height`, `unit` |
| `create_sphere` | Create sphere | `radius`, `unit` |
| `create_hole` | Create hole | `diameter`, `position`, `unit` |
| `extrude` | Extrude profile | `profile`, `distance`, `unit` |
| `fillet` | Round edges | `edges`, `radius`, `unit` |
| `apply_material` | Apply material | `material_name` |
## 🔬 Model Comparison
| Feature | Ollama (Local) | OpenAI GPT-4o | Google Gemini | Claude 3.5 |
|---------|---------------|---------------|---------------|------------|
| **Cost** | Free | $$ | $ | $$$ |
| **Speed** | Fast | Medium | Fast | Medium |
| **Offline** | ✅ Yes | ❌ No | ❌ No | ❌ No |
| **JSON Mode** | Limited | ✅ Native | Good | Good |
| **Reasoning** | Good | Excellent | Very Good | Excellent |
| **Geometry** | Good | Very Good | Excellent | Very Good |
| **Creative** | Good | Excellent | Very Good | Good |
| **Best For** | Privacy, Offline | Creative designs | Spatial reasoning | Safety validation |
### Recommended Workflows
1. **Creative Design**: OpenAI GPT-4o → Claude (validation)
2. **Geometric Precision**: Gemini → OpenAI
3. **Privacy-First**: Ollama (all tasks)
4. **Cost-Optimized**: Gemini Flash → Ollama (fallback)
## 🛠️ Development
### Project Structure
```
fusion360-mcp/
├── mcp_server/ # MCP Server
│ ├── server.py # FastAPI app
│ ├── router.py # Request routing
│ ├── schema/ # Pydantic models
│ ├── llm_clients/ # LLM implementations
│ └── utils/ # Utilities
├── fusion_addin/ # Fusion 360 Add-in
│ ├── main.py # Entry point
│ ├── ui_dialog.py # UI components
│ ├── fusion_actions.py # Action executor
│ └── utils/network.py # Network client
├── prompts/ # System prompts
├── examples/ # Example configs
├── tests/ # Test suite
├── requirements.txt # Dependencies
└── README.md # This file
```
### Running Tests
```bash
# Run all tests
pytest tests/ -v
# Run specific test file
pytest tests/test_mcp_server.py -v
# Run with coverage
pytest tests/ --cov=mcp_server --cov-report=html
```
### Adding New LLM Provider
1. Create client in `mcp_server/llm_clients/new_provider_client.py`:
```python
class NewProviderClient:
async def generate(self, model, prompt, system_prompt, temperature, max_tokens):
# Implementation
return {
"provider": "new_provider",
"model": model,
"output": "...",
"json": {...},
"tokens_used": 123
}
```
2. Register in `router.py`:
```python
if config.new_provider_api_key:
self.clients["new_provider"] = NewProviderClient(...)
```
### Code Style
- **PEP8** compliant
- **Type annotations** required
- **Docstrings** for all functions/classes
- **Async/await** for I/O operations
## 🐛 Troubleshooting
### Common Issues
#### 1. Server Won't Start
**Error**: `Address already in use`
**Solution**: Change port in `config.json`:
```json
{"mcp_port": 9001}
```
#### 2. Fusion Add-in Not Visible
**Solution**:
- Verify add-in is in correct folder
- Check `FusionMCP.manifest` exists
- Restart Fusion 360
- Check **Scripts and Add-Ins** → **Add-Ins** tab
#### 3. API Key Errors
**Error**: `401 Unauthorized`
**Solution**:
- Verify API key in `config.json`
- Check key has proper permissions
- Try environment variables instead
#### 4. Ollama Connection Failed
**Error**: `Connection refused`
**Solution**:
```bash
# Check Ollama is running
ollama list
# Start Ollama service
ollama serve
```
#### 5. JSON Parsing Errors
**Solution**:
- Check system prompt is loaded
- Verify model supports JSON mode
- Use temperature < 0.8 for better structure
- Enable `json_mode=True` in OpenAI client
### Debug Mode
Enable verbose logging:
```json
{"log_level": "DEBUG"}
```
Check logs in `logs/mcp_server.log`
### Health Check
```bash
# Check server health
curl http://127.0.0.1:9000/health
# List available models
curl http://127.0.0.1:9000/models
# View conversation history
curl http://127.0.0.1:9000/history?limit=5
```
## 🧪 Testing the System
### Manual CLI Test
```bash
curl -X POST http://127.0.0.1:9000/mcp/command \
-H "Content-Type: application/json" \
-d @examples/example_command.json
```
### Python Test Script
```python
import requests
command = {
"command": "ask_model",
"params": {
"provider": "openai",
"model": "gpt-4o-mini",
"prompt": "Create a 10mm cube"
},
"context": {
"units": "mm",
"design_state": "empty"
}
}
response = requests.post("http://127.0.0.1:9000/mcp/command", json=command)
print(response.json())
```
## 🤝 Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request
### Development Setup
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Run linting
ruff check mcp_server/
black mcp_server/
```
## 📄 License
MIT License - see [LICENSE](LICENSE) file
## 🙏 Acknowledgments
- Autodesk Fusion 360 API
- FastAPI framework
- Anthropic, OpenAI, Google for LLM APIs
- Ollama for local LLM support
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/fusion360-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/fusion360-mcp/discussions)
- **Documentation**: [Wiki](https://github.com/yourusername/fusion360-mcp/wiki)
## 🗺️ Roadmap
- [ ] WebSocket streaming for real-time chat
- [ ] Vision model support (CAD screenshot analysis)
- [ ] Multi-agent orchestration
- [ ] Generative Design API integration
- [ ] Geometry export to Markdown/docs
- [ ] Fusion 360 UI palette integration
- [ ] 3D preview before execution
- [ ] Undo/redo action history
- [ ] Cloud deployment support
---
**Built with ❤️ for the Fusion 360 and AI community**