mirror of
https://github.com/latinogino/dolibarr-mcp.git
synced 2026-04-21 01:32:40 +02:00
Merge pull request #3 from latinogino/codex/cleanup-unnecessary-files-and-scripts
Align structure with prestashop-mcp
This commit is contained in:
latinogino
@@ -7,10 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
- Clarified cross-platform installation instructions, including Visual Studio developer shell usage on Windows.
|
||||
- Trimmed runtime dependencies to match the actual imports and exposed developer extras for the test tooling.
|
||||
|
||||
## [1.1.0] - 2024-05-22
|
||||
|
||||
### Removed
|
||||
|
||||
100
README.md
100
README.md
@@ -1,99 +1,9 @@
|
||||
# Dolibarr MCP Server
|
||||
|
||||
A focused Model Context Protocol (MCP) server for managing a Dolibarr ERP/CRM instance.
|
||||
The MCP entry point lives in [`src/dolibarr_mcp/dolibarr_mcp_server.py`](src/dolibarr_mcp/dolibarr_mcp_server.py) and exposes
|
||||
Dolibarr management tools to MCP compatible clients such as Claude Desktop.
|
||||
|
||||
## Repository layout
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `src/dolibarr_mcp/` | MCP server, configuration helpers and CLI utilities |
|
||||
| `tests/` | Automated pytest suite covering configuration and client logic |
|
||||
| `api/` | Notes collected while analysing the Dolibarr REST API |
|
||||
|
||||
Everything else in the repository supports one of these three areas.
|
||||
|
||||
## Installation
|
||||
|
||||
### Linux / macOS
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/latinogino/dolibarr-mcp.git
|
||||
cd dolibarr-mcp
|
||||
|
||||
# Create and activate a virtual environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install the package in editable mode together with runtime dependencies
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
# Launch a Visual Studio developer shell so native extensions such as aiohttp can build
|
||||
vsenv
|
||||
|
||||
# Clone the repository
|
||||
git clone https://github.com/latinogino/dolibarr-mcp.git
|
||||
Set-Location dolibarr-mcp
|
||||
|
||||
# Create and activate a virtual environment
|
||||
py -3 -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
|
||||
# Install the package in editable mode together with runtime dependencies
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
> 💡 If you do not already have the Visual Studio developer PowerShell available, open the
|
||||
> **"Developer PowerShell for VS"** shortcut first. Inside that shell the `vsenv` command
|
||||
> initialises the Visual Studio build environment that `pip` needs to compile `aiohttp` and
|
||||
> other native wheels on Windows.
|
||||
|
||||
For contributors who need the development tooling (pytest, coverage, etc.) install the optional
|
||||
extras:
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
pip install -e '.[dev]'
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
pip install -e .`[dev`]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `.env` file (or set the variables in your MCP host application) with:
|
||||
|
||||
```env
|
||||
DOLIBARR_URL=https://your-dolibarr.example.com/api/index.php
|
||||
DOLIBARR_API_KEY=your_api_key
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
The [`Config` helper](src/dolibarr_mcp/config.py) loads these values, validates them and provides sensible
|
||||
warnings when something is missing.
|
||||
|
||||
## Running the server
|
||||
|
||||
The server communicates over STDIO as required by MCP. Start it with one of the following commands:
|
||||
|
||||
```bash
|
||||
# Use the Python module entry point
|
||||
python -m dolibarr_mcp
|
||||
|
||||
# Or use the CLI wrapper installed by the package
|
||||
python -m dolibarr_mcp.cli serve
|
||||
# Alias when installed as a package: dolibarr-mcp serve
|
||||
```
|
||||
|
||||
To check that Dolibarr credentials are working you can run:
|
||||
|
||||
```bash
|
||||
python -m dolibarr_mcp.cli test --url https://your-dolibarr.example.com/api/index.php --api-key YOUR_KEY
|
||||
@@ -101,8 +11,6 @@ python -m dolibarr_mcp.cli test --url https://your-dolibarr.example.com/api/inde
|
||||
|
||||
## Available tools
|
||||
|
||||
`dolibarr_mcp_server` registers a collection of MCP tools that cover common ERP workflows:
|
||||
|
||||
- **System** – `test_connection`, `get_status`
|
||||
- **Users** – `get_users`, `get_user_by_id`, `create_user`, `update_user`, `delete_user`
|
||||
- **Customers / Third parties** – `get_customers`, `get_customer_by_id`, `create_customer`, `update_customer`, `delete_customer`
|
||||
@@ -112,14 +20,6 @@ python -m dolibarr_mcp.cli test --url https://your-dolibarr.example.com/api/inde
|
||||
- **Contacts** – `get_contacts`, `get_contact_by_id`, `create_contact`, `update_contact`, `delete_contact`
|
||||
- **Raw API access** – `dolibarr_raw_api`
|
||||
|
||||
The implementation in [`dolibarr_client.py`](src/dolibarr_mcp/dolibarr_client.py) provides the underlying async HTTP
|
||||
operations, error handling and pagination helpers used by these tools.
|
||||
|
||||
## Development
|
||||
|
||||
- Run the automated test-suite with `pytest`.
|
||||
- The project is packaged with `pyproject.toml`; editable installs use the `src/` layout.
|
||||
- Additional API notes live in the [`api/`](api) directory if you need to extend the toolset.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
233
api/README.md
233
api/README.md
@@ -1,233 +0,0 @@
|
||||
# Dolibarr API Documentation - Complete Analysis
|
||||
## Instance Information: db.ginos.cloud
|
||||
|
||||
**Dolibarr Version:** 21.0.1
|
||||
**API Base URL:** https://db.ginos.cloud/api/index.php
|
||||
**Authentication:** DOLAPIKEY header
|
||||
**Response Format:** JSON
|
||||
|
||||
## ✅ Confirmed Working Endpoints
|
||||
|
||||
### 1. **Status Endpoint**
|
||||
- **URL:** `/status`
|
||||
- **Method:** GET
|
||||
- **Purpose:** API health check and version info
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"success": {
|
||||
"code": 200,
|
||||
"dolibarr_version": "21.0.1",
|
||||
"access_locked": "0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **Users Endpoint**
|
||||
- **URL:** `/users`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** User management
|
||||
- **Parameters:** limit, sortfield, sortorder
|
||||
- **Response:** Array of user objects with complete profile data
|
||||
- **Fields Include:** id, login, lastname, firstname, email, admin, status, etc.
|
||||
- **Status:** ✅ Fully functional with 4 users found
|
||||
|
||||
### 3. **Third Parties Endpoint** (Customers/Suppliers)
|
||||
- **URL:** `/thirdparties`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** Customer/supplier management
|
||||
- **Parameters:** limit, sortfield, sortorder, sqlfilters
|
||||
- **Response:** Array of third party objects
|
||||
- **Fields Include:** id, name, address, phone, email, status, type (client/supplier)
|
||||
- **Status:** ✅ Fully functional with 1 test customer found
|
||||
|
||||
### 4. **Products Endpoint**
|
||||
- **URL:** `/products`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** Product catalog management
|
||||
- **Parameters:** limit, sortfield, sortorder
|
||||
- **Response:** Array of product objects
|
||||
- **Status:** ✅ Accessible but currently empty
|
||||
|
||||
### 5. **Invoices Endpoint**
|
||||
- **URL:** `/invoices`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** Invoice management
|
||||
- **Parameters:** limit, status filtering
|
||||
- **Response:** Array of invoice objects
|
||||
- **Status:** ✅ Accessible but currently empty
|
||||
|
||||
### 6. **Orders Endpoint**
|
||||
- **URL:** `/orders`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** Order management
|
||||
- **Parameters:** limit, status filtering
|
||||
- **Response:** Array of order objects
|
||||
- **Status:** ✅ Accessible but currently empty
|
||||
|
||||
### 7. **Contacts Endpoint**
|
||||
- **URL:** `/contacts`
|
||||
- **Method:** GET, POST, PUT, DELETE
|
||||
- **Purpose:** Contact management
|
||||
- **Parameters:** limit, thirdparty filtering
|
||||
- **Response:** Array of contact objects
|
||||
- **Status:** ✅ Accessible but currently empty
|
||||
|
||||
## ❌ Non-Working/Problematic Endpoints
|
||||
|
||||
### 1. **Setup Endpoint**
|
||||
- **URL:** `/setup`
|
||||
- **Status:** ❌ 404 Not Found
|
||||
- **Note:** May require different path or parameters
|
||||
|
||||
### 2. **Documents Endpoint**
|
||||
- **URL:** `/documents`
|
||||
- **Status:** ❌ 400 Bad Request
|
||||
- **Note:** Requires specific parameters (modulepart, filename, etc.)
|
||||
|
||||
## 🔍 API Patterns Identified
|
||||
|
||||
### Standard Query Parameters
|
||||
All list endpoints support these parameters:
|
||||
- `limit`: Number of records to return (default: 100)
|
||||
- `sortfield`: Field to sort by
|
||||
- `sortorder`: ASC or DESC
|
||||
- `sqlfilters`: Advanced filtering using SQL-like syntax
|
||||
|
||||
### Authentication
|
||||
- **Header:** `DOLAPIKEY: your_api_key`
|
||||
- **Format:** Token-based authentication
|
||||
- **Permission:** Tied to user permissions in Dolibarr
|
||||
|
||||
### Response Structure
|
||||
- **Success:** Array of objects or single object
|
||||
- **Error:** JSON with error details
|
||||
- **HTTP Status Codes:** 200, 201, 400, 401, 403, 404, 500
|
||||
|
||||
### Data Structure Pattern
|
||||
All business objects share common fields:
|
||||
- `id`: Unique identifier
|
||||
- `ref`: Reference number
|
||||
- `status`/`statut`: Status code
|
||||
- `date_creation`: Creation timestamp
|
||||
- `user_creation_id`: Creator user ID
|
||||
- `note_public`/`note_private`: Notes
|
||||
- `array_options`: Custom fields
|
||||
|
||||
## 🏗️ Recommended MCP Server Structure
|
||||
|
||||
### Core Modules
|
||||
1. **Customer Management** (`/thirdparties`)
|
||||
- get_customers()
|
||||
- get_customer_by_id()
|
||||
- create_customer()
|
||||
- update_customer()
|
||||
- delete_customer()
|
||||
|
||||
2. **Product Management** (`/products`)
|
||||
- get_products()
|
||||
- get_product_by_id()
|
||||
- create_product()
|
||||
- update_product()
|
||||
- delete_product()
|
||||
|
||||
3. **Invoice Management** (`/invoices`)
|
||||
- get_invoices()
|
||||
- get_invoice_by_id()
|
||||
- create_invoice()
|
||||
- update_invoice()
|
||||
- delete_invoice()
|
||||
|
||||
4. **Order Management** (`/orders`)
|
||||
- get_orders()
|
||||
- get_order_by_id()
|
||||
- create_order()
|
||||
- update_order()
|
||||
- delete_order()
|
||||
|
||||
5. **Contact Management** (`/contacts`)
|
||||
- get_contacts()
|
||||
- get_contact_by_id()
|
||||
- create_contact()
|
||||
- update_contact()
|
||||
- delete_contact()
|
||||
|
||||
6. **User Management** (`/users`)
|
||||
- get_users()
|
||||
- get_user_by_id()
|
||||
- create_user()
|
||||
- update_user()
|
||||
- delete_user()
|
||||
|
||||
### Additional Endpoints to Explore
|
||||
Based on Dolibarr source code, these endpoints likely exist:
|
||||
- `/projects` - Project management
|
||||
- `/suppliers` - Supplier-specific operations
|
||||
- `/warehouses` - Inventory management
|
||||
- `/categories` - Category management
|
||||
- `/members` - Membership management
|
||||
- `/expensereports` - Expense reporting
|
||||
- `/tickets` - Support tickets
|
||||
- `/events` - Calendar events
|
||||
- `/proposals` - Commercial proposals
|
||||
- `/contracts` - Contract management
|
||||
- `/agenda` - Agenda/calendar
|
||||
- `/actioncomm` - Communication actions
|
||||
- `/shipments` - Shipping management
|
||||
- `/receptions` - Reception management
|
||||
- `/mrp` - Manufacturing Resource Planning
|
||||
- `/boms` - Bill of Materials
|
||||
- `/stockmovements` - Stock movements
|
||||
- `/bankaccounts` - Bank account management
|
||||
- `/payments` - Payment management
|
||||
- `/leaverequest` - Leave requests
|
||||
- `/salaries` - Salary management
|
||||
|
||||
## 🔬 Testing Methodology Used
|
||||
|
||||
1. **Connection Test:** Verified API accessibility with `/status` endpoint
|
||||
2. **Core Business Objects:** Tested major CRUD endpoints
|
||||
3. **Parameter Testing:** Verified filtering and pagination
|
||||
4. **Error Handling:** Documented error responses
|
||||
5. **Data Structure Analysis:** Analyzed response formats
|
||||
|
||||
## 📝 Next Steps for MCP Development
|
||||
|
||||
1. **Create Base MCP Server Structure**
|
||||
- Follow prestashop-mcp reference pattern
|
||||
- Implement dolibarr_client.py with all discovered endpoints
|
||||
- Create MCP server with proper tool definitions
|
||||
|
||||
2. **Implement Core Functions**
|
||||
- Start with working endpoints (users, thirdparties, products, invoices, orders)
|
||||
- Add comprehensive error handling
|
||||
- Include proper parameter validation
|
||||
|
||||
3. **Test and Expand**
|
||||
- Test all CRUD operations
|
||||
- Discover additional endpoints through testing
|
||||
- Add advanced features (filtering, pagination, etc.)
|
||||
|
||||
4. **Documentation and Deployment**
|
||||
- Create comprehensive README
|
||||
- Add Docker containerization
|
||||
- Implement proper logging and monitoring
|
||||
|
||||
## 🎯 Immediate Development Priority
|
||||
|
||||
**High Priority Endpoints (Confirmed Working):**
|
||||
1. Users management
|
||||
2. Customer/Third party management
|
||||
3. Product management
|
||||
4. Invoice management
|
||||
5. Order management
|
||||
|
||||
**Medium Priority (Need Parameter Research):**
|
||||
1. Document management
|
||||
2. Contact management
|
||||
3. Project management
|
||||
|
||||
**Low Priority (Discovery Required):**
|
||||
1. Setup/configuration endpoints
|
||||
2. Advanced modules (MRP, BOM, etc.)
|
||||
3. Integration-specific endpoints
|
||||
@@ -1,347 +0,0 @@
|
||||
# Dolibarr API Endpoints Reference
|
||||
## Live Testing Results from db.ginos.cloud
|
||||
|
||||
This document contains actual API responses and detailed endpoint specifications discovered through live testing of Dolibarr v21.0.1.
|
||||
|
||||
## Base Configuration
|
||||
- **Base URL:** `https://db.ginos.cloud/api/index.php`
|
||||
- **Authentication:** `DOLAPIKEY` header
|
||||
- **Content-Type:** `application/json`
|
||||
- **Dolibarr Version:** 21.0.1
|
||||
|
||||
---
|
||||
|
||||
## 1. Status Endpoint
|
||||
|
||||
### GET /status
|
||||
**Purpose:** API health check and version information
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/status" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": {
|
||||
"code": 200,
|
||||
"dolibarr_version": "21.0.1",
|
||||
"access_locked": "0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Users Endpoint
|
||||
|
||||
### GET /users
|
||||
**Purpose:** Retrieve users list
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `sortfield` (string): Field to sort by
|
||||
- `sortorder` (string): ASC or DESC
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/users?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response Example (User Object):**
|
||||
```json
|
||||
{
|
||||
"id": "1",
|
||||
"entity": "0",
|
||||
"ref": "1",
|
||||
"statut": "1",
|
||||
"status": "1",
|
||||
"lastname": "SuperAdmin",
|
||||
"firstname": null,
|
||||
"civility_id": null,
|
||||
"civility_code": null,
|
||||
"gender": null,
|
||||
"birth": "",
|
||||
"email": null,
|
||||
"personal_email": null,
|
||||
"admin": "1",
|
||||
"login": "admin",
|
||||
"datec": "",
|
||||
"datem": 1750000134,
|
||||
"datelastlogin": 1752054907,
|
||||
"datepreviouslogin": 1751957906,
|
||||
"iplastlogin": "87.187.51.28",
|
||||
"ippreviouslogin": "87.187.51.28",
|
||||
"office_phone": null,
|
||||
"office_fax": null,
|
||||
"user_mobile": null,
|
||||
"personal_mobile": null,
|
||||
"job": null,
|
||||
"signature": null,
|
||||
"address": null,
|
||||
"zip": null,
|
||||
"town": null,
|
||||
"employee": "1",
|
||||
"fk_user": null,
|
||||
"rights": {
|
||||
"user": {
|
||||
"user": {},
|
||||
"self": {},
|
||||
"user_advance": {},
|
||||
"self_advance": {},
|
||||
"group_advance": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Third Parties Endpoint (Customers/Suppliers)
|
||||
|
||||
### GET /thirdparties
|
||||
**Purpose:** Retrieve customers and suppliers
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `sortfield` (string): Field to sort by
|
||||
- `sortorder` (string): ASC or DESC
|
||||
- `sqlfilters` (string): Advanced filtering
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/thirdparties?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response Example (Third Party Object):**
|
||||
```json
|
||||
{
|
||||
"module": "societe",
|
||||
"id": "1",
|
||||
"entity": "1",
|
||||
"ref": "1",
|
||||
"status": "1",
|
||||
"name": "Test Customer MCP",
|
||||
"name_alias": "",
|
||||
"phone": "+1-555-0123",
|
||||
"phone_mobile": null,
|
||||
"fax": null,
|
||||
"email": "test@mcp-dolibarr.com",
|
||||
"url": null,
|
||||
"address": "123 Test Street",
|
||||
"zip": "12345",
|
||||
"town": "Test City",
|
||||
"country_id": null,
|
||||
"country_code": "",
|
||||
"state_id": null,
|
||||
"region_id": null,
|
||||
"date_creation": 1752005684,
|
||||
"date_modification": 1752005684,
|
||||
"user_creation_id": "4",
|
||||
"user_modification_id": "4",
|
||||
"tva_assuj": "1",
|
||||
"tva_intra": "",
|
||||
"client": "0",
|
||||
"prospect": 0,
|
||||
"fournisseur": "0",
|
||||
"code_client": null,
|
||||
"code_fournisseur": null,
|
||||
"remise_percent": 0,
|
||||
"remise_supplier_percent": "0",
|
||||
"note_public": null,
|
||||
"note_private": null,
|
||||
"idprof1": "",
|
||||
"idprof2": "",
|
||||
"idprof3": "",
|
||||
"idprof4": "",
|
||||
"idprof5": "",
|
||||
"idprof6": ""
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Products Endpoint
|
||||
|
||||
### GET /products
|
||||
**Purpose:** Retrieve product catalog
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `sortfield` (string): Field to sort by
|
||||
- `sortorder` (string): ASC or DESC
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/products?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[]
|
||||
```
|
||||
*Note: Currently empty in test instance*
|
||||
|
||||
---
|
||||
|
||||
## 5. Invoices Endpoint
|
||||
|
||||
### GET /invoices
|
||||
**Purpose:** Retrieve invoices
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `status` (string): Filter by invoice status
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/invoices?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[]
|
||||
```
|
||||
*Note: Currently empty in test instance*
|
||||
|
||||
---
|
||||
|
||||
## 6. Orders Endpoint
|
||||
|
||||
### GET /orders
|
||||
**Purpose:** Retrieve orders
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `status` (string): Filter by order status
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/orders?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[]
|
||||
```
|
||||
*Note: Currently empty in test instance*
|
||||
|
||||
---
|
||||
|
||||
## 7. Contacts Endpoint
|
||||
|
||||
### GET /contacts
|
||||
**Purpose:** Retrieve contacts
|
||||
|
||||
**Parameters:**
|
||||
- `limit` (int): Number of records to return
|
||||
- `thirdparty` (int): Filter by third party ID
|
||||
|
||||
**Request:**
|
||||
```bash
|
||||
curl -X GET "https://db.ginos.cloud/api/index.php/contacts?limit=5" \
|
||||
-H "DOLAPIKEY: your_api_key"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
[]
|
||||
```
|
||||
*Note: Currently empty in test instance*
|
||||
|
||||
---
|
||||
|
||||
## Common Response Patterns
|
||||
|
||||
### Success Response Structure
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"success": {
|
||||
"code": 200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response Structure
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": 404,
|
||||
"message": "Object not found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Standard Object Fields
|
||||
All business objects contain these common fields:
|
||||
- `id`: Unique identifier
|
||||
- `ref`: Reference number
|
||||
- `entity`: Entity ID (multi-company)
|
||||
- `status`/`statut`: Status code
|
||||
- `date_creation`: Creation timestamp
|
||||
- `date_modification`: Last modification timestamp
|
||||
- `user_creation_id`: Creator user ID
|
||||
- `user_modification_id`: Last modifier user ID
|
||||
- `note_public`: Public notes
|
||||
- `note_private`: Private notes
|
||||
- `array_options`: Custom fields
|
||||
|
||||
---
|
||||
|
||||
## HTTP Methods Support
|
||||
|
||||
| Endpoint | GET | POST | PUT | DELETE |
|
||||
|----------|-----|------|-----|--------|
|
||||
| /status | ✅ | ❌ | ❌ | ❌ |
|
||||
| /users | ✅ | ✅ | ✅ | ✅ |
|
||||
| /thirdparties | ✅ | ✅ | ✅ | ✅ |
|
||||
| /products | ✅ | ✅ | ✅ | ✅ |
|
||||
| /invoices | ✅ | ✅ | ✅ | ✅ |
|
||||
| /orders | ✅ | ✅ | ✅ | ✅ |
|
||||
| /contacts | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Authentication Details
|
||||
|
||||
### API Key Location
|
||||
The API key must be passed in the `DOLAPIKEY` header:
|
||||
```bash
|
||||
-H "DOLAPIKEY: 7cxAAO835BF7bXy6DsQ2j2a7nT6ectGY"
|
||||
```
|
||||
|
||||
### Permissions
|
||||
API access is tied to the user's permissions in Dolibarr. Ensure the API user has appropriate rights for the endpoints you wish to access.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps for MCP Implementation
|
||||
|
||||
Based on this testing, the MCP server should implement:
|
||||
|
||||
1. **Core CRUD Operations** for all confirmed endpoints
|
||||
2. **Parameter Validation** for limit, sorting, and filtering
|
||||
3. **Error Handling** for 4xx and 5xx responses
|
||||
4. **Response Normalization** to handle Dolibarr's response format
|
||||
5. **Authentication Management** via environment variables
|
||||
6. **Logging** for debugging and monitoring
|
||||
|
||||
## Additional Endpoints to Test
|
||||
|
||||
These endpoints should be tested in future development:
|
||||
- `/projects` - Project management
|
||||
- `/proposals` - Commercial proposals
|
||||
- `/contracts` - Contract management
|
||||
- `/categories` - Category management
|
||||
- `/warehouses` - Inventory management
|
||||
- `/payments` - Payment tracking
|
||||
- `/expensereports` - Expense management
|
||||
- `/documents` - Document management (with proper parameters)
|
||||
10
docs/README.md
Normal file
10
docs/README.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# Documentation
|
||||
|
||||
The Dolibarr MCP repository mirrors the documentation layout of the
|
||||
`prestashop-mcp` project. Start with the quickstart and branch into specialised
|
||||
guides as needed:
|
||||
|
||||
- [Quickstart](quickstart.md) – installation and first run instructions for Linux, macOS and Windows
|
||||
- [Configuration](configuration.md) – environment variables consumed by the server
|
||||
- [Development](development.md) – running tests, optional Docker assets and contributor workflow
|
||||
- [API Coverage](api-reference.md) – overview of the Dolibarr REST resources exposed via MCP tools
|
||||
83
docs/api-reference.md
Normal file
83
docs/api-reference.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Dolibarr API Coverage
|
||||
|
||||
This server wraps the Dolibarr REST API v21.0.1 that is exposed by an instance at
|
||||
`https://db.ginos.cloud/api/index.php`. The MCP tools use the following REST
|
||||
resources, mirroring the scope that the sibling `prestashop-mcp` project
|
||||
implements for PrestaShop.
|
||||
|
||||
## Authentication and Conventions
|
||||
|
||||
- **Header** – send the `DOLAPIKEY` header with the personal access token that is
|
||||
configured for your Dolibarr user.
|
||||
- **Content Type** – every request uses `application/json` payloads and
|
||||
responses.
|
||||
- **Pagination** – list endpoints accept the `limit`, `sortfield`, `sortorder`
|
||||
and `sqlfilters` query parameters.
|
||||
- **Identifiers** – Dolibarr returns both `id` (numeric) and `ref` (business
|
||||
reference) for most entities. The MCP tools expose both values to the client.
|
||||
|
||||
## Supported Resources
|
||||
|
||||
| Resource | Endpoint(s) | Tool group |
|
||||
| --------------- | --------------------------- | --------------------------------------- |
|
||||
| Status | `GET /status` | `get_status`, `test_connection` |
|
||||
| Users | `/users` | CRUD helpers under the *Users* group |
|
||||
| Third parties | `/thirdparties` | Customer CRUD operations |
|
||||
| Products | `/products` | Product CRUD operations |
|
||||
| Invoices | `/invoices` | Invoice CRUD operations |
|
||||
| Orders | `/orders` | Order CRUD operations |
|
||||
| Contacts | `/contacts` | Contact CRUD operations |
|
||||
| Raw passthrough | Any relative path | `dolibarr_raw_api` tool for quick tests |
|
||||
|
||||
Every endpoint supports create, read, update and delete operations unless noted
|
||||
otherwise. The Dolibarr instance that informed this reference currently contains
|
||||
live data for users, third parties and contacts; other modules respond with
|
||||
empty lists until records are created.
|
||||
|
||||
## Response Examples
|
||||
|
||||
### Status
|
||||
|
||||
```json
|
||||
{
|
||||
"success": {
|
||||
"code": 200,
|
||||
"dolibarr_version": "21.0.1",
|
||||
"access_locked": "0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Third Party
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "1",
|
||||
"ref": "1",
|
||||
"name": "Test Customer MCP",
|
||||
"status": "1",
|
||||
"address": "123 Test Street",
|
||||
"zip": "12345",
|
||||
"town": "Test City",
|
||||
"email": "test@mcp-dolibarr.com",
|
||||
"phone": "+1-555-0123",
|
||||
"date_creation": 1752005684,
|
||||
"user_creation_id": "4",
|
||||
"array_options": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Shape
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": 404,
|
||||
"message": "Not found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Dolibarr communicates detailed failure information in the `error` object. The
|
||||
client wrapper turns these payloads into Python exceptions with the same
|
||||
metadata so MCP hosts can display friendly error messages.
|
||||
33
docs/configuration.md
Normal file
33
docs/configuration.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Configuration
|
||||
|
||||
The Dolibarr MCP server reads configuration from environment variables. Use a
|
||||
`.env` file during development or configure the variables directly in the MCP
|
||||
host application that will launch the server.
|
||||
|
||||
| Variable | Description |
|
||||
| ------------------- | -------------------------------------------------------------- |
|
||||
| `DOLIBARR_URL` | Base API URL, e.g. `https://your-dolibarr.example.com/api/index.php` |
|
||||
| `DOLIBARR_API_KEY` | Personal Dolibarr API token assigned to your user |
|
||||
| `LOG_LEVEL` | Optional logging level (`INFO`, `DEBUG`, `WARNING`, …) |
|
||||
|
||||
## Example `.env`
|
||||
|
||||
```env
|
||||
DOLIBARR_URL=https://your-dolibarr.example.com/api/index.php
|
||||
DOLIBARR_API_KEY=your_api_key
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
The [`Config` class](../src/dolibarr_mcp/config.py) is built with
|
||||
`pydantic-settings`. It validates the values on load, applies alias support for
|
||||
legacy variable names and raises a descriptive error if placeholder credentials
|
||||
are detected.
|
||||
|
||||
## Testing credentials
|
||||
|
||||
Use the CLI helper to verify that the credentials are accepted by Dolibarr
|
||||
before wiring the server into your MCP host:
|
||||
|
||||
```bash
|
||||
python -m dolibarr_mcp.cli test --url https://your-dolibarr.example.com/api/index.php --api-key YOUR_KEY
|
||||
```
|
||||
48
docs/development.md
Normal file
48
docs/development.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Development
|
||||
|
||||
This project uses the same lightweight tooling philosophy as `prestashop-mcp`.
|
||||
The code lives under `src/`, tests under `tests/` and optional Docker assets are
|
||||
kept separate in `docker/`.
|
||||
|
||||
## Install development dependencies
|
||||
|
||||
```bash
|
||||
pip install -e '.[dev]'
|
||||
```
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
pip install -e .`[dev`]
|
||||
```
|
||||
|
||||
## Run the test suite
|
||||
|
||||
```bash
|
||||
pytest
|
||||
```
|
||||
|
||||
To gather coverage metrics:
|
||||
|
||||
```bash
|
||||
pytest --cov=src/dolibarr_mcp --cov-report=term-missing
|
||||
```
|
||||
|
||||
## Formatting and linting
|
||||
|
||||
The project intentionally avoids heavy linting dependencies. Follow the coding
|
||||
style already present in the repository and run the test-suite before opening a
|
||||
pull request.
|
||||
|
||||
## Docker tooling
|
||||
|
||||
Container assets live in `docker/`:
|
||||
|
||||
- `Dockerfile` – production-ready image for the MCP server
|
||||
- `docker-compose.yml` – local stack that spins up Dolibarr together with the MCP server
|
||||
|
||||
Build and run the container locally with:
|
||||
|
||||
```bash
|
||||
docker compose -f docker/docker-compose.yml up --build
|
||||
```
|
||||
60
docs/quickstart.md
Normal file
60
docs/quickstart.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Quickstart
|
||||
|
||||
Follow these steps to install and run the Dolibarr MCP server. The process
|
||||
mirrors the streamlined developer experience of the `prestashop-mcp` project.
|
||||
|
||||
## 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/latinogino/dolibarr-mcp.git
|
||||
cd dolibarr-mcp
|
||||
```
|
||||
|
||||
## 2. Create a virtual environment
|
||||
|
||||
### Linux / macOS
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
### Windows (Visual Studio Developer PowerShell)
|
||||
|
||||
```powershell
|
||||
vsenv
|
||||
py -3 -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
```
|
||||
|
||||
## 3. Install the package
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
For development and testing utilities add the optional extras:
|
||||
|
||||
```bash
|
||||
pip install -e '.[dev]'
|
||||
```
|
||||
|
||||
On Windows escape the brackets inside PowerShell:
|
||||
|
||||
```powershell
|
||||
pip install -e .`[dev`]
|
||||
```
|
||||
|
||||
## 4. Configure credentials
|
||||
|
||||
Create a `.env` file in the project root (see [`configuration.md`](configuration.md))
|
||||
or export the variables within your MCP host application.
|
||||
|
||||
## 5. Run the server
|
||||
|
||||
```bash
|
||||
python -m dolibarr_mcp.cli serve
|
||||
```
|
||||
|
||||
The command starts the STDIO based MCP server that Claude Desktop and other
|
||||
clients can communicate with.
|
||||
@@ -1,61 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Fixed Dolibarr MCP Server launcher.
|
||||
This script ensures the module can be found and launched correctly.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import logging
|
||||
from pathlib import Path
|
||||
|
||||
# Setup logging
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def setup_python_path():
|
||||
"""Add necessary directories to Python path."""
|
||||
script_dir = Path(__file__).resolve().parent
|
||||
|
||||
# Try different possible locations
|
||||
paths_to_try = [
|
||||
script_dir, # Current directory
|
||||
script_dir / 'src', # src subdirectory
|
||||
script_dir.parent, # Parent directory
|
||||
script_dir.parent / 'src', # Parent's src subdirectory
|
||||
]
|
||||
|
||||
for path in paths_to_try:
|
||||
if path.exists() and str(path) not in sys.path:
|
||||
sys.path.insert(0, str(path))
|
||||
logger.info(f"Added to Python path: {path}")
|
||||
|
||||
# Also check if we're in a virtual environment
|
||||
if hasattr(sys, 'real_prefix') or (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix):
|
||||
logger.info(f"Running in virtual environment: {sys.prefix}")
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
setup_python_path()
|
||||
|
||||
try:
|
||||
# Try to import and run the server
|
||||
from dolibarr_mcp.dolibarr_mcp_server import main as server_main
|
||||
logger.info("Successfully imported dolibarr_mcp server")
|
||||
server_main()
|
||||
except ImportError as e:
|
||||
logger.error(f"Failed to import dolibarr_mcp: {e}")
|
||||
logger.error("Trying alternative import...")
|
||||
try:
|
||||
# Try alternative import path
|
||||
from src.dolibarr_mcp.dolibarr_mcp_server import main as server_main
|
||||
logger.info("Successfully imported using alternative path")
|
||||
server_main()
|
||||
except ImportError as e2:
|
||||
logger.error(f"Failed with alternative import: {e2}")
|
||||
logger.error("Please ensure the dolibarr_mcp module is installed correctly.")
|
||||
logger.error("Try running: pip install -e . from the project root directory")
|
||||
sys.exit(1)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,61 +0,0 @@
|
||||
# Dolibarr MCP Tests
|
||||
|
||||
This directory contains the test suite for the Dolibarr MCP Server.
|
||||
|
||||
## Test Structure
|
||||
|
||||
- `test_config.py` - Configuration and environment tests
|
||||
- `test_dolibarr_client.py` - API client unit tests
|
||||
- `test_crud_operations.py` - Complete CRUD integration tests
|
||||
|
||||
## Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=src/dolibarr_mcp --cov-report=html
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/test_config.py
|
||||
|
||||
# Run with verbose output
|
||||
pytest -v
|
||||
|
||||
# Run specific test
|
||||
pytest tests/test_config.py::TestConfig::test_env_loading
|
||||
```
|
||||
|
||||
## Test Requirements
|
||||
|
||||
All test dependencies are included in the main `requirements.txt`:
|
||||
- pytest
|
||||
- pytest-asyncio
|
||||
- pytest-cov
|
||||
|
||||
## Environment Setup
|
||||
|
||||
Create a `.env` file in the root directory with test credentials:
|
||||
```
|
||||
DOLIBARR_URL=https://test.dolibarr.com
|
||||
DOLIBARR_API_KEY=test_api_key
|
||||
LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
## Writing Tests
|
||||
|
||||
Follow these patterns for consistency:
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from dolibarr_mcp import DolibarrClient
|
||||
|
||||
class TestDolibarrClient:
|
||||
@pytest.fixture
|
||||
def client(self):
|
||||
return DolibarrClient(url="https://test.com", api_key="test")
|
||||
|
||||
def test_example(self, client):
|
||||
assert client is not None
|
||||
```
|
||||
Reference in New Issue
Block a user