From 25b24af5f85f050f7c460cc5c4458d31a3bf6436 Mon Sep 17 00:00:00 2001 From: latinogino <154024559+latinogino@users.noreply.github.com> Date: Thu, 10 Jul 2025 12:06:54 +0200 Subject: [PATCH] docs: Add comprehensive README with full documentation --- README.md | 388 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 386 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 671e2c4..576e47a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,386 @@ -# dolibarr-mcp -Dolibarr MCP Server +# Dolibarr MCP Server + +Professional Model Context Protocol (MCP) server for comprehensive Dolibarr ERP integration with full CRUD operations and business intelligence capabilities. + +[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) +[![MCP Compatible](https://img.shields.io/badge/MCP-1.0.0-orange.svg)](https://modelcontextprotocol.io) + +## πŸš€ Features + +### Complete ERP Management +- **Customer/Third Party Management**: Full CRUD operations for customers and suppliers +- **Product Catalog**: Comprehensive product management with inventory tracking +- **Invoice Management**: Create, update, and track invoices with line items +- **Order Processing**: Complete order lifecycle management +- **Contact Management**: Maintain detailed contact records +- **User Administration**: User account and permissions management + +### Professional Grade +- **Asynchronous Operations**: High-performance async/await architecture +- **Error Handling**: Comprehensive error handling with detailed logging +- **Type Safety**: Full type hints with Pydantic validation +- **CLI Interface**: Professional command-line tools for testing and management +- **Raw API Access**: Direct access to any Dolibarr API endpoint + +### MCP Integration +- **Tool-based Architecture**: Each operation exposed as an MCP tool +- **Schema Validation**: Proper input/output schema validation +- **Response Formatting**: Structured JSON responses +- **Error Propagation**: Meaningful error messages and status codes + +## πŸ“‹ Prerequisites + +- Python 3.8 or higher +- Dolibarr instance with API enabled +- Dolibarr API key with appropriate permissions + +## πŸ› οΈ Installation + +### From Source + +```bash +# Clone the repository +git clone https://github.com/latinogino/dolibarr-mcp.git +cd dolibarr-mcp + +# Install in development mode +pip install -e . + +# Or install dependencies directly +pip install -r requirements.txt +``` + +### Using pip (when published) + +```bash +pip install dolibarr-mcp +``` + +## βš™οΈ Configuration + +### Environment Variables + +Create a `.env` file in your project directory: + +```bash +# Copy the example file +cp .env.example .env +``` + +Edit the `.env` file with your Dolibarr configuration: + +```env +# Dolibarr API Configuration +DOLIBARR_URL=https://your-dolibarr-instance.com/api/index.php +DOLIBARR_API_KEY=your_dolibarr_api_key_here + +# Logging Configuration +LOG_LEVEL=INFO +``` + +### Dolibarr API Setup + +1. **Enable the API module** in Dolibarr: + - Go to Home β†’ Setup β†’ Modules + - Enable "Web Services API REST (developer)" + +2. **Create an API key**: + - Go to Home β†’ Setup β†’ API/Web services + - Create a new API key for your user + - Ensure the user has appropriate permissions + +3. **Test the API**: + ```bash + curl -X GET "https://your-dolibarr-instance.com/api/index.php/status" \ + -H "DOLAPIKEY: your_api_key_here" + ``` + +## πŸš€ Usage + +### Command Line Interface + +Test your connection: +```bash +dolibarr-mcp test +``` + +Test with specific credentials: +```bash +dolibarr-mcp test --url "https://your-instance.com/api/index.php" --api-key "your_key" +``` + +Start the MCP server: +```bash +dolibarr-mcp serve +``` + +### As an MCP Server + +The server exposes comprehensive tools for Dolibarr management: + +#### System Tools +- `test_connection` - Test API connectivity +- `get_status` - Get system status and version + +#### Customer Management +- `get_customers` - List customers/third parties +- `get_customer_by_id` - Get specific customer details +- `create_customer` - Create new customer +- `update_customer` - Update existing customer +- `delete_customer` - Delete customer + +#### Product Management +- `get_products` - List products +- `get_product_by_id` - Get specific product details +- `create_product` - Create new product +- `update_product` - Update existing product +- `delete_product` - Delete product + +#### Invoice Management +- `get_invoices` - List invoices +- `get_invoice_by_id` - Get specific invoice details +- `create_invoice` - Create new invoice with line items +- `update_invoice` - Update existing invoice +- `delete_invoice` - Delete invoice + +#### Order Management +- `get_orders` - List orders +- `get_order_by_id` - Get specific order details +- `create_order` - Create new order +- `update_order` - Update existing order +- `delete_order` - Delete order + +#### Contact Management +- `get_contacts` - List contacts +- `get_contact_by_id` - Get specific contact details +- `create_contact` - Create new contact +- `update_contact` - Update existing contact +- `delete_contact` - Delete contact + +#### User Management +- `get_users` - List users +- `get_user_by_id` - Get specific user details +- `create_user` - Create new user +- `update_user` - Update existing user +- `delete_user` - Delete user + +#### Raw API Access +- `dolibarr_raw_api` - Make direct API calls to any endpoint + +### Programmatic Usage + +```python +import asyncio +from dolibarr_mcp import Config, DolibarrClient + +async def main(): + config = Config.from_env() + + async with DolibarrClient(config) as client: + # Get customers + customers = await client.get_customers(limit=10) + print(f"Found {len(customers)} customers") + + # Create a new customer + new_customer = await client.create_customer( + name="Test Company", + email="test@company.com", + phone="+1-555-0123" + ) + print(f"Created customer: {new_customer}") + + # Get products + products = await client.get_products(limit=5) + print(f"Found {len(products)} products") + +asyncio.run(main()) +``` + +## πŸ—οΈ Architecture + +### Project Structure + +``` +dolibarr-mcp/ +β”œβ”€β”€ src/dolibarr_mcp/ +β”‚ β”œβ”€β”€ __init__.py # Package exports +β”‚ β”œβ”€β”€ config.py # Configuration management +β”‚ β”œβ”€β”€ cli.py # Command line interface +β”‚ β”œβ”€β”€ dolibarr_client.py # API client implementation +β”‚ └── dolibarr_mcp_server.py # MCP server implementation +β”œβ”€β”€ tests/ # Test suite +β”œβ”€β”€ api/ # API documentation +β”œβ”€β”€ pyproject.toml # Project configuration +β”œβ”€β”€ requirements.txt # Dependencies +└── README.md # This file +``` + +### API Client Architecture + +The `DolibarrClient` provides: + +- **Async Context Manager**: Proper session management +- **Error Handling**: Custom `DolibarrAPIError` exceptions +- **Request/Response Logging**: Detailed debugging information +- **Type Safety**: Full type hints for all methods +- **Flexible Configuration**: Environment-based configuration + +### MCP Server Architecture + +The MCP server follows the official MCP specification: + +- **Tool Registration**: Each operation is a registered tool +- **Schema Validation**: Input/output validation using JSON schemas +- **Error Propagation**: Meaningful error responses +- **Async Operation**: Non-blocking request handling + +## πŸ§ͺ Testing + +Run the test suite: + +```bash +# Install test dependencies +pip install pytest pytest-asyncio pytest-cov + +# Run tests +pytest + +# Run with coverage +pytest --cov=src/dolibarr_mcp +``` + +Test specific functionality: + +```bash +# Test API connection +dolibarr-mcp test + +# Test with verbose output +dolibarr-mcp test --verbose +``` + +## πŸ“ API Reference + +### Configuration + +The `Config` class manages all configuration: + +```python +from dolibarr_mcp import Config + +# From environment variables +config = Config.from_env() + +# Manual configuration +config = Config( + dolibarr_url="https://your-instance.com/api/index.php", + api_key="your_api_key", + log_level="DEBUG" +) +``` + +### Client Usage + +```python +from dolibarr_mcp import DolibarrClient, Config + +config = Config.from_env() + +async with DolibarrClient(config) as client: + # All operations here + pass +``` + +### Error Handling + +```python +from dolibarr_mcp import DolibarrAPIError + +try: + result = await client.get_customers() +except DolibarrAPIError as e: + print(f"API Error: {e.message}") + print(f"Status Code: {e.status_code}") + print(f"Response Data: {e.response_data}") +``` + +## 🐳 Docker Support (Coming Soon) + +Docker containerization is planned for the second phase of development: + +```bash +# Build image +docker build -t dolibarr-mcp . + +# Run container +docker run -p 8080:8080 --env-file .env dolibarr-mcp +``` + +## 🀝 Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Development Setup + +```bash +# Clone your fork +git clone https://github.com/yourusername/dolibarr-mcp.git +cd dolibarr-mcp + +# Install in development mode +pip install -e ".[dev]" + +# Install pre-commit hooks +pre-commit install + +# Run tests +pytest +``` + +## πŸ“„ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## πŸ™ Acknowledgments + +- [Dolibarr](https://www.dolibarr.org/) - The amazing open-source ERP/CRM +- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification +- [Anthropic](https://www.anthropic.com/) - For the MCP standard + +## πŸ“ž Support + +- πŸ“– [Documentation](https://github.com/latinogino/dolibarr-mcp#readme) +- πŸ› [Issue Tracker](https://github.com/latinogino/dolibarr-mcp/issues) +- πŸ’¬ [Discussions](https://github.com/latinogino/dolibarr-mcp/discussions) + +## πŸ—ΊοΈ Roadmap + +### Phase 1 (Current) βœ… +- [x] Core MCP server implementation +- [x] Full CRUD operations for main entities +- [x] Professional error handling +- [x] CLI interface +- [x] Comprehensive documentation + +### Phase 2 (Next) +- [ ] Docker containerization +- [ ] Advanced filtering and search +- [ ] Webhook support +- [ ] Performance optimization +- [ ] Extended API coverage + +### Phase 3 (Future) +- [ ] Web UI for management +- [ ] Multi-instance support +- [ ] Caching layer +- [ ] Metrics and monitoring +- [ ] Plugin system + +--- + +**Built with ❀️ for the Dolibarr community**