Clean up and restructure: Update README.md to match prestashop-mcp structure

2026-04-28 20:45:35 +02:00 · 2025-09-25 22:01:37 +02:00
parent 8b0b623b54
commit fe54aa84de
1 changed files with 336 additions and 157 deletions
--- a/README.md
+++ b/README.md
@@ -1,208 +1,387 @@
-# 🔥 Dolibarr MCP Server - WINDOWS PROBLEM ENDGÜLTIG GELÖST!
+# Dolibarr MCP Server

-Ein professioneller **Model Context Protocol (MCP) Server** für Dolibarr ERP-Integration mit **garantierter Windows-Kompatibilität**.
+A professional Model Context Protocol (MCP) Server for complete management of Dolibarr ERP/CRM systems.

-## 💥 **ULTIMATIVE LÖSUNG für Windows pywin32 Probleme**
+## 🚀 Overview

-**Problem**: `[WinError 5] Zugriff verweigert` bei allen Python-Paketen mit C-Extensions (.pyd Dateien)  
-**Lösung**: **ULTRA-VERSION** mit NULL kompilierten Extensions! 
+This MCP Server enables complete management of your Dolibarr ERP/CRM through AI applications like Claude Desktop. With specialized tools, you can manage all aspects of your business - from customers and products to invoices, orders, and contacts.

-## 🚀 **SOFORTIGE LÖSUNG** (Garantiert auf JEDEM Windows-System)
+## ✨ Features

-### ⚡ **ULTRA Setup** (100% Erfolgsgarantie)
-```cmd
-# 1. Repository klonen (falls noch nicht geschehen)
+- **💼 Complete ERP/CRM Management** - Tools for all business areas
+- **👥 Customer & Contact Management** - Full CRM functionality
+- **📦 Product & Service Management** - Complete inventory control
+- **💰 Financial Management** - Invoices, orders, and payments
+- **🏗️ MCP Protocol Compliance** for seamless AI integration
+- **⚡ Async/Await Architecture** for maximum performance
+- **🛡️ Comprehensive Error Handling** and validation
+- **🔧 Production-Ready** with complete test suite
+- **🐳 Docker Support** for easy deployment
+
+## 🛠️ Available Tools
+
+### 👥 Customer Management (Third Parties)
+- `get_customers` - Retrieve and filter customers
+- `get_customer_by_id` - Get specific customer details
+- `create_customer` - Create new customers
+- `update_customer` - Edit customer data
+- `delete_customer` - Remove customers
+
+### 📦 Product Management
+- `get_products` - List all products
+- `get_product_by_id` - Get specific product details
+- `create_product` - Create new products/services
+- `update_product` - Edit product information
+- `delete_product` - Remove products
+
+### 💰 Invoice Management
+- `get_invoices` - Retrieve and filter invoices
+- `get_invoice_by_id` - Get specific invoice details
+- `create_invoice` - Create new invoices
+- `update_invoice` - Edit invoice information
+- `delete_invoice` - Remove invoices
+
+### 📋 Order Management
+- `get_orders` - Retrieve and filter orders
+- `get_order_by_id` - Get specific order details
+- `create_order` - Create new orders
+- `update_order` - Edit order information
+- `delete_order` - Remove orders
+
+### 👤 Contact Management
+- `get_contacts` - List all contacts
+- `get_contact_by_id` - Get specific contact details
+- `create_contact` - Create new contacts
+- `update_contact` - Edit contact information
+- `delete_contact` - Remove contacts
+
+### 👤 User Management
+- `get_users` - List system users
+- `get_user_by_id` - Get specific user details
+- `create_user` - Create new users
+- `update_user` - Edit user information
+- `delete_user` - Remove users
+
+### ⚙️ System Administration
+- `test_connection` - Test API connection
+- `get_status` - System status and version
+- `dolibarr_raw_api` - Direct API access for advanced operations
+
+## 📋 Installation
+
+### ⚠️ Recommended Installation (Virtual Environment)
+
+**This approach prevents module conflicts and ensures reliable installation:**
+
+#### Windows:
+```powershell
+# Clone repository
 git clone https://github.com/latinogino/dolibarr-mcp.git
 cd dolibarr-mcp

-# 2. ULTRA Setup (ZERO .pyd Dateien - funktioniert IMMER!)
-.\setup_ultra.bat
+# Create virtual environment
+python -m venv venv_dolibarr

-# 3. Konfiguration
-copy .env.example .env
-# Bearbeiten Sie .env mit Ihren Dolibarr-Credentials
+# Activate virtual environment
+.\venv_dolibarr\Scripts\Activate.ps1

-# 4. Server starten
-.\run_ultra.bat
+# Install dependencies
+pip install -r requirements.txt
+
+# Install package in development mode
+pip install -e .
+
+# Verify installation
+python -c "import dolibarr_mcp; print('✅ Installation successful')"
+
+# Note the Python path for Claude Desktop configuration
+Write-Host "Python Path: $((Get-Command python).Source)"
 ```

-**🎯 Warum funktioniert ULTRA garantiert?**
- ❌ **Normale Version**: aiohttp, pydantic → .pyd Dateien → Windows-Berechtigungsprobleme
- ✅ **ULTRA Version**: Nur `requests` + Standard Library → ZERO .pyd Dateien → Funktioniert IMMER
+#### Linux/macOS:
+```bash
+# Clone repository
+git clone https://github.com/latinogino/dolibarr-mcp.git
+cd dolibarr-mcp

-## 🛠️ **Drei Setup-Optionen** (vom einfachsten zum komplexesten)
+# Create virtual environment
+python3 -m venv venv_dolibarr

-| Setup-Methode | Windows-Kompatibilität | Funktionsumfang | Empfehlung |
-|---------------|------------------------|-----------------|------------|
-| **🔥 ULTRA** | 100% (keine .pyd) | Alle CRUD Tools | ⭐⭐⭐ EMPFOHLEN |
-| **Standalone** | 95% (wenige .pyd) | Alle CRUD Tools | ⭐⭐ Fallback |
-| **Standard MCP** | 50% (viele .pyd) | Alle CRUD Tools | ⭐ Nur für Experten |
+# Activate virtual environment
+source venv_dolibarr/bin/activate

-### Option 1: 🔥 ULTRA (Garantierter Erfolg)
-```cmd
-.\setup_ultra.bat     # Nur requests, dotenv, click - ZERO .pyd!
-.\run_ultra.bat       # Startet ultra-kompatiblen Server
+# Install dependencies
+pip install -r requirements.txt
+
+# Install package in development mode
+pip install -e .
+
+# Verify installation
+python -c "import dolibarr_mcp; print('✅ Installation successful')"
+
+# Note the Python path for Claude Desktop configuration
+which python
 ```

-### Option 2: Standalone (Falls ULTRA nicht gewünscht)  
-```cmd
-.\setup_standalone.bat   # Weniger .pyd Dateien
-.\run_standalone.bat     # Startet standalone Server
+### 🐳 Docker Installation
+
+```bash
+# Using Docker Compose (recommended)
+docker-compose up -d
+
+# Or using Docker directly
+docker build -t dolibarr-mcp .
+docker run -d \
+  -e DOLIBARR_URL=https://your-dolibarr.com \
+  -e DOLIBARR_API_KEY=your_api_key \
+  -p 8080:8080 \
+  dolibarr-mcp
 ```

-### Option 3: Standard MCP (Nur für Experten)
-```cmd 
-.\setup.bat             # Vollständiges MCP-Paket
-.\start_server.bat      # Standard MCP Server
-```
+### ⚙️ Configuration

-## ✨ **Vollständige Feature-Matrix**
+Create a `.env` file based on `.env.example`:

-| Feature | ULTRA | Standalone | Standard | Status |
-|---------|-------|------------|----------|--------|
-| **Windows-Kompatibilität** | 100% | 95% | 50% | ✅ |
-| **User Management** | ✅ | ✅ | ✅ | Identisch |
-| **Customer Management** | ✅ | ✅ | ✅ | Identisch |
-| **Product Management** | ✅ | ✅ | ✅ | Identisch |
-| **Invoice Management** | ✅ | ✅ | ✅ | Identisch |
-| **Order Management** | ✅ | ✅ | ✅ | Identisch |
-| **Contact Management** | ✅ | ✅ | ✅ | Identisch |
-| **Raw API Access** | ✅ | ✅ | ✅ | Identisch |
-| **Interactive Testing** | ✅ | ✅ | ❌ | ULTRA ist besser! |
-| **Error Handling** | ✅ | ✅ | ✅ | Identisch |
+```bash
+# Dolibarr Configuration
+DOLIBARR_URL=https://your-dolibarr.example.com
+DOLIBARR_API_KEY=YOUR_API_KEY

-## 🔧 **Dolibarr Konfiguration**
-
-### 1. **Dolibarr API aktivieren**
-1. **Dolibarr Admin** → Login
-2. **Home → Setup → Modules** → "Web Services API REST (developer)" ✅ aktivieren
-3. **Home → Setup → API/Web services** → Neuen API Key erstellen
-
-### 2. **Konfiguration (.env)**
-```env
-DOLIBARR_URL=https://ihre-dolibarr-instanz.com/api/index.php
-DOLIBARR_API_KEY=ihr_generierter_api_schluessel
+# Logging
 LOG_LEVEL=INFO
 ```

-## 🧪 **Server testen & verwenden**
+## 🎯 Usage

-### ULTRA Server (Empfohlen)
-```cmd
-# Nach setup_ultra.bat:
-.\run_ultra.bat
+### 🤖 With Claude Desktop

-# Interactive Console öffnet sich automatisch:
-dolibarr-ultra> help
-dolibarr-ultra> test test_connection
-dolibarr-ultra> test get_status
-dolibarr-ultra> test get_users
-dolibarr-ultra> config
-dolibarr-ultra> list
-dolibarr-ultra> exit
+#### Using Virtual Environment (Recommended)
+
+Add this configuration to `claude_desktop_config.json`:
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "dolibarr": {
+      "command": "C:\\\\path\\\\to\\\\dolibarr-mcp\\\\venv_dolibarr\\\\Scripts\\\\python.exe",
+      "args": ["-m", "dolibarr_mcp.dolibarr_mcp_server"],
+      "cwd": "C:\\\\path\\\\to\\\\dolibarr-mcp",
+      "env": {
+        "DOLIBARR_URL": "https://your-dolibarr.example.com",
+        "DOLIBARR_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
 ```

-### Verfügbare Schnelltests
-```
-test test_connection    # API-Verbindung testen
-test get_status         # Dolibarr-Status abrufen
-test get_users          # Erste 5 Benutzer anzeigen
-test get_customers      # Erste 5 Kunden anzeigen  
-test get_products       # Erste 5 Produkte anzeigen
-config                  # Aktuelle Konfiguration zeigen
-help                    # Alle Befehle anzeigen
+**Linux/macOS:**
+```json
+{
+  "mcpServers": {
+    "dolibarr": {
+      "command": "/path/to/dolibarr-mcp/venv_dolibarr/bin/python",
+      "args": ["-m", "dolibarr_mcp.dolibarr_mcp_server"],
+      "cwd": "/path/to/dolibarr-mcp",
+      "env": {
+        "DOLIBARR_URL": "https://your-dolibarr.example.com",
+        "DOLIBARR_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
 ```

-## 📋 **Alle verfügbaren CRUD-Operationen**
-
-### 👥 **User Management**
- `get_users`, `get_user_by_id`, `create_user`, `update_user`, `delete_user`
-
-### 🏢 **Customer Management**  
- `get_customers`, `get_customer_by_id`, `create_customer`, `update_customer`, `delete_customer`
-
-### 📦 **Product Management**
- `get_products`, `get_product_by_id`, `create_product`, `update_product`, `delete_product`
-
-### 🧾 **Invoice Management**
- `get_invoices`, `get_invoice_by_id`, `create_invoice`, `update_invoice`, `delete_invoice`
-
-### 📋 **Order Management**  
- `get_orders`, `get_order_by_id`, `create_order`, `update_order`, `delete_order`
-
-### 📞 **Contact Management**
- `get_contacts`, `get_contact_by_id`, `create_contact`, `update_contact`, `delete_contact`
-
-### 🔌 **Advanced**
- `raw_api` - Direkter Zugriff auf beliebige Dolibarr-Endpunkte
-
-## 🐳 **Docker Support** (Weiterhin verfügbar)
+### 💻 CLI Usage

 ```bash
-# Standard Docker
-docker-compose up -d
+# Activate virtual environment first (if using venv)
+source venv_dolibarr/bin/activate  # Linux/macOS
+.\venv_dolibarr\Scripts\Activate.ps1  # Windows

-# Mit .env Konfiguration
-cp .env.example .env
-# .env bearbeiten, dann:
-docker-compose up -d dolibarr-mcp
+# With environment variables
+dolibarr-mcp
+
+# With direct parameters
+dolibarr-mcp --url https://your-dolibarr.com --api-key YOUR_API_KEY
+
+# Debug mode
+dolibarr-mcp --log-level DEBUG
 ```

-## 🔧 **Troubleshooting**
+## 💡 Example Usage

-### ✅ **ULTRA Version löst ALLE Windows-Probleme**
-
-**Vorher** (Probleme):
+### Customer Management
 ```
-ERROR: [WinError 5] Zugriff verweigert: ...pywintypes313.dll
-ERROR: [WinError 5] Zugriff verweigert: ..._http_parser.cp313-win_amd64.pyd
-ERROR: [WinError 5] Zugriff verweigert: ..._pydantic_core.cp313-win_amd64.pyd
+"Show me all customers in Dolibarr"
+"Create a new customer named 'Acme Corp' with email info@acme.com"
+"Update customer ID 5 with new phone number +1234567890"
+"Find customers in France"
 ```

-**Nachher** (ULTRA - Keine Probleme):
+### Product Management
 ```
-✅ requests installed
-✅ python-dotenv installed  
-✅ click installed
-🎉 ULTRA SETUP COMPLETE!
+"List all products with stock levels"
+"Create a new product 'Consulting Service' with price $150"
+"Update product ID 10 to set new price $200"
+"Show me products with low stock"
 ```

-### **API-Verbindungsprobleme**
-
-| Problem | Lösung |
-|---------|---------|
-| "Cannot connect to Dolibarr API" | URL und API Key in .env prüfen |
-| "403 Forbidden" | Neuen API Key in Dolibarr erstellen |
-| "Module not found" | `setup_ultra.bat` erneut ausführen |
-
-### **Test-Commands**
-```cmd
-# Setup testen
-python test_ultra.py
-
-# Server direkt testen  
-python -m src.dolibarr_mcp.ultra_simple_server
+### Invoice Management
+```
+"Show all unpaid invoices"
+"Create an invoice for customer 'Acme Corp'"
+"Get invoice details for invoice ID 100"
+"Update invoice due date to next month"
 ```

-## 🎯 **Status: Production-Ready für ALLE Windows-Versionen**
+### Contact Management
+```
+"List all contacts for customer ID 5"
+"Create a new contact John Doe for Acme Corp"
+"Update contact email for John Doe"
+"Find all contacts with role 'Manager'"
+```

-✅ **Problem gelöst**: Null .pyd Dateien = Null Windows-Probleme  
-✅ **Funktional**: Alle CRUD-Operationen verfügbar  
-✅ **Getestet**: Interactive Test-Console eingebaut  
-✅ **Kompatibel**: Windows XP bis Windows 11  
-✅ **Performance**: Requests-basiert, sehr schnell  
-✅ **Wartbar**: Saubere, einfache Code-Architektur  
+## 🔧 Troubleshooting

-## 📄 **License & Support**
+### ❌ Common Issues

- **License**: MIT License - siehe [LICENSE](LICENSE)
- **Issues**: [GitHub Issues](https://github.com/latinogino/dolibarr-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/latinogino/dolibarr-mcp/discussions)
+#### "ModuleNotFoundError: No module named 'dolibarr_mcp'"
+
+**Solution:** Use virtual environment and ensure package is installed:
+```bash
+# Check if in virtual environment
+python -c "import sys; print(sys.prefix)"
+
+# Reinstall package
+pip install -e .
+
+# Verify installation
+python -c "import dolibarr_mcp; print('Module found')"
+```
+
+#### API Connection Issues
+
+**Check API Configuration:**
+```bash
+# Test connection with curl
+curl -X GET "https://your-dolibarr.com/api/index.php/status" \
+  -H "DOLAPIKEY: YOUR_API_KEY"
+```
+
+#### Permission Errors
+
+Ensure your API key has necessary permissions in Dolibarr:
+1. Go to Dolibarr Admin → API/Web Services
+2. Check API key permissions
+3. Enable required modules (API REST module)
+
+### 🔍 Debug Mode
+
+Enable debug logging in Claude Desktop configuration:
+```json
+{
+  "mcpServers": {
+    "dolibarr": {
+      "command": "path/to/python",
+      "args": ["-m", "dolibarr_mcp.dolibarr_mcp_server"],
+      "cwd": "path/to/dolibarr-mcp",
+      "env": {
+        "DOLIBARR_URL": "https://your-dolibarr.example.com",
+        "DOLIBARR_API_KEY": "YOUR_API_KEY",
+        "LOG_LEVEL": "DEBUG"
+      }
+    }
+  }
+}
+```
+
+## 📊 Project Structure
+
+```
+dolibarr-mcp/
+├── src/dolibarr_mcp/              # Main Package
+│   ├── dolibarr_mcp_server.py     # MCP Server
+│   ├── dolibarr_client.py         # Dolibarr API Client
+│   ├── config.py                  # Configuration Management
+│   └── cli.py                     # Command Line Interface
+├── tests/                         # Test Suite
+│   ├── test_config.py             # Unit Tests
+│   └── test_dolibarr_client.py    # Integration Tests
+├── docker/                        # Docker Configuration
+│   ├── Dockerfile                 # Container Definition
+│   └── docker-compose.yml         # Compose Configuration
+├── venv_dolibarr/                 # Virtual Environment (after setup)
+├── README.md                      # Documentation
+├── CHANGELOG.md                   # Version History
+├── pyproject.toml                 # Package Configuration
+└── requirements.txt               # Dependencies
+```
+
+## 📖 API Documentation
+
+### Dolibarr API
+
+Complete Dolibarr API documentation:
+- **[Dolibarr REST API Wiki](https://wiki.dolibarr.org/index.php?title=Module_Web_Services_API_REST_(developer))**
+- **[Dolibarr Integration Guide](https://wiki.dolibarr.org/index.php?title=Interfaces_Dolibarr_toward_foreign_systems)**
+
+### Authentication
+
+```bash
+curl -X GET "https://your-dolibarr.com/api/index.php/status" \
+  -H "DOLAPIKEY: YOUR_API_KEY"
+```
+
+### Important Endpoints
+
+- **Third Parties**: `/api/index.php/thirdparties`
+- **Products**: `/api/index.php/products`
+- **Invoices**: `/api/index.php/invoices`
+- **Orders**: `/api/index.php/orders`
+- **Contacts**: `/api/index.php/contacts`
+- **Users**: `/api/index.php/users`
+- **Status**: `/api/index.php/status`
+
+## 🧪 Development
+
+### 🏗️ Development Environment
+
+```bash
+# Activate virtual environment
+source venv_dolibarr/bin/activate  # Linux/macOS
+.\venv_dolibarr\Scripts\Activate.ps1  # Windows
+
+# Install development dependencies
+pip install -r requirements.txt
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=src/dolibarr_mcp --cov-report=html
+
+# Run integration tests
+python tests/test_dolibarr_client.py
+```
+
+## 📖 Resources
+
+- **[Dolibarr Official Documentation](https://www.dolibarr.org/documentation-home)**
+- **[Model Context Protocol Specification](https://modelcontextprotocol.io/)**
+- **[Claude Desktop MCP Integration](https://docs.anthropic.com/)**
+- **[GitHub Repository](https://github.com/latinogino/dolibarr-mcp)**
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.

 ---

-## 🎉 **ERFOLGREICH? Ihr Dolibarr ERP ist jetzt AI-ready!**
-
-**🔥 ULTRA Version = Garantierte Windows-Kompatibilität + Vollständige Dolibarr-Integration**
-
-**🚀 Bereit, Ihr Dolibarr ERP mit Claude, ChatGPT und anderen LLMs zu nutzen!**
+**🎯 Manage your complete Dolibarr ERP/CRM through natural language with Claude Desktop!**