diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index f7147a4..0000000 --- a/docs/API.md +++ /dev/null @@ -1,753 +0,0 @@ - - -# API Reference - -All tools accept an optional `connection` parameter to target a specific named connection. If omitted, the default connection is used. - -All list tools accept optional pagination parameters: - -| Parameter | Type | Description | -|-----------|------|-------------| -| `limit` | number | Max results (default 100) | -| `page` | number | Page number (0-based) | -| `sortfield` | string | Field to sort by | -| `sortorder` | `"ASC"` / `"DESC"` | Sort direction | - -## Third Parties - -### `dolibarr_thirdparties_list` -List third parties (customers, suppliers, prospects). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `mode` | `"1"` / `"2"` / `"3"` / `"4"` | No | 1=customer, 2=prospect, 3=supplier, 4=customer+supplier | -| `search` | string | No | Search in name | -| `category` | number | No | Filter by category ID | - -### `dolibarr_thirdparty_get` -Get a single third party by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Third party ID | - -### `dolibarr_thirdparty_create` -Create a new third party. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `name` | string | Yes | Company or individual name | -| `client` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=neither, 1=customer, 2=prospect, 3=customer+prospect | -| `fournisseur` | `"0"` / `"1"` | No | 0=not supplier, 1=supplier | -| `email` | string | No | Email address | -| `phone` | string | No | Phone number | -| `address` | string | No | Street address | -| `zip` | string | No | Postal code | -| `town` | string | No | City | -| `country_id` | number | No | Country ID | - -### `dolibarr_thirdparty_update` -Update an existing third party. Only provided fields are changed. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Third party ID | -| `name` | string | No | Company or individual name | -| `email` | string | No | Email address | -| `phone` | string | No | Phone number | -| `address` | string | No | Street address | -| `zip` | string | No | Postal code | -| `town` | string | No | City | -| `country_id` | number | No | Country ID | - -### `dolibarr_thirdparty_delete` -Delete a third party. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Third party ID | - -## Invoices - -### `dolibarr_invoices_list` -List invoices. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | -| `search` | string | No | Search in ref or ref_client | - -### `dolibarr_invoice_get` -Get a single invoice by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | - -### `dolibarr_invoice_create` -Create a new invoice. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `socid` | number | Yes | Third party (customer) ID | -| `type` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=standard, 1=replacement, 2=credit note, 3=deposit | -| `date` | string | No | Invoice date (YYYY-MM-DD or Unix timestamp) | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -### `dolibarr_invoice_add_line` -Add a line item to an invoice. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | -| `desc` | string | Yes | Line description | -| `subprice` | number | Yes | Unit price (HT) | -| `qty` | number | Yes | Quantity | -| `tva_tx` | number | No | VAT rate (e.g. 20.0) | -| `product_id` | number | No | Product/service ID | - -### `dolibarr_invoice_validate` -Validate (finalize) a draft invoice. Changes status from draft to validated and assigns an invoice number. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | - -### `dolibarr_invoice_set_paid` -Mark an invoice as paid. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | -| `close_code` | string | No | Close code (e.g. `"bankorder"`, `"cash"`) | -| `close_note` | string | No | Close note | - -## Proposals (Quotes) - -### `dolibarr_proposals_list` -List commercial proposals. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"4"` | No | 0=draft, 1=validated, 2=signed, 3=not-signed, 4=billed | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | - -### `dolibarr_proposal_get` -Get a single proposal by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Proposal ID | - -### `dolibarr_proposal_create` -Create a new commercial proposal. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `socid` | number | Yes | Third party (customer) ID | -| `date` | string | No | Proposal date (YYYY-MM-DD or Unix timestamp) | -| `duree_validite` | number | No | Validity duration in days | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -### `dolibarr_proposal_add_line` -Add a line item to a proposal. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Proposal ID | -| `desc` | string | Yes | Line description | -| `subprice` | number | Yes | Unit price (HT) | -| `qty` | number | Yes | Quantity | -| `tva_tx` | number | No | VAT rate (e.g. 20.0) | -| `product_id` | number | No | Product/service ID | - -### `dolibarr_proposal_validate` -Validate a draft proposal. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Proposal ID | - -### `dolibarr_proposal_close` -Close a proposal (sign or refuse). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Proposal ID | -| `status` | `"2"` / `"3"` | Yes | 2=signed, 3=not signed (refused) | -| `note` | string | No | Close note | - -## Orders - -### `dolibarr_orders_list` -List customer orders. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"-1"` | No | 0=draft, 1=validated, 2=processing, 3=delivered, -1=cancelled | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | - -### `dolibarr_order_get` -Get a single order by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Order ID | - -### `dolibarr_order_create` -Create a new customer order. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `socid` | number | Yes | Third party (customer) ID | -| `date` | string | No | Order date (YYYY-MM-DD or Unix timestamp) | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -### `dolibarr_order_validate` -Validate a draft order. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Order ID | - -## Products / Services - -### `dolibarr_products_list` -List products and/or services. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `type` | `"0"` / `"1"` | No | 0=product, 1=service | -| `search` | string | No | Search in label or ref | -| `category` | number | No | Filter by category ID | -| `to_sell` | `"0"` / `"1"` | No | 1=for sale only | -| `to_buy` | `"0"` / `"1"` | No | 1=for purchase only | - -### `dolibarr_product_get` -Get a single product/service by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Product ID | - -### `dolibarr_product_create` -Create a new product or service. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `ref` | string | Yes | Product reference code | -| `label` | string | Yes | Product label/name | -| `type` | `"0"` / `"1"` | No | 0=product, 1=service (default 0) | -| `price` | number | No | Selling price (HT) | -| `price_ttc` | number | No | Selling price (TTC) | -| `tva_tx` | number | No | Default VAT rate | -| `description` | string | No | Description | -| `status` | `"0"` / `"1"` | No | 1=on sale, 0=not on sale | -| `status_buy` | `"0"` / `"1"` | No | 1=on purchase, 0=not on purchase | - -### `dolibarr_product_update` -Update a product or service. Only provided fields are changed. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Product ID | -| `ref` | string | No | Product reference code | -| `label` | string | No | Product label/name | -| `price` | number | No | Selling price (HT) | -| `description` | string | No | Description | -| `status` | `"0"` / `"1"` | No | On sale flag | -| `status_buy` | `"0"` / `"1"` | No | On purchase flag | - -### `dolibarr_product_stock` -Get stock levels for a product across all warehouses. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Product ID | - -## Contacts / Addresses - -### `dolibarr_contacts_list` -List contacts/addresses. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `search` | string | No | Search in name | -| `thirdparty_id` | number | No | Filter by third party ID | - -### `dolibarr_contact_get` -Get a single contact by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Contact ID | - -## Projects - -### `dolibarr_projects_list` -List projects. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=open, 2=closed | -| `search` | string | No | Search in title or ref | - -### `dolibarr_project_get` -Get a single project by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Project ID | - -### `dolibarr_project_create` -Create a new project. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `ref` | string | Yes | Project reference | -| `title` | string | Yes | Project title | -| `socid` | number | No | Third party ID | -| `description` | string | No | Project description | -| `date_start` | string | No | Start date (YYYY-MM-DD or Unix timestamp) | -| `date_end` | string | No | End date (YYYY-MM-DD or Unix timestamp) | - -## Tasks - -### `dolibarr_tasks_list` -List project tasks. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `project_id` | number | No | Filter by project ID | - -### `dolibarr_task_get` -Get a single task by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Task ID | - -## Users - -### `dolibarr_users_list` -List Dolibarr users. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `search` | string | No | Search in login name | - -### `dolibarr_user_get` -Get a single user by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | User ID | - -## Categories - -### `dolibarr_categories_list` -List categories. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `type` | `"product"` / `"supplier"` / `"customer"` / `"member"` / `"contact"` / `"project"` | No | Category type | -| `search` | string | No | Search in label | - -## Bank Accounts - -### `dolibarr_bankaccounts_list` -List bank accounts. No additional parameters (supports pagination). - -## Supplier Invoices - -### `dolibarr_supplier_invoices_list` -List supplier invoices. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status | -| `thirdparty_ids` | string | No | Comma-separated supplier IDs | - -## Supplier Orders - -### `dolibarr_supplier_orders_list` -List supplier orders (purchase orders). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` - `"5"`, `"9"` | No | 0=draft, 1=validated, 2=approved, 3=ordered, 4=partially received, 5=received, 9=cancelled | -| `thirdparty_ids` | string | No | Comma-separated supplier IDs | - -## Shipments - -### `dolibarr_shipments_list` -List shipments (expeditions). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=validated, 2=closed | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | - -### `dolibarr_shipment_get` -Get a single shipment by ID. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Shipment ID | - -### `dolibarr_shipment_create` -Create a new shipment. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `socid` | number | Yes | Third party (customer) ID | -| `origin_id` | number | No | Source order ID | -| `origin_type` | string | No | Source type (e.g. `"commande"`) | -| `date_delivery` | string | No | Delivery date | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -### `dolibarr_shipment_validate` -Validate a draft shipment. - -### `dolibarr_shipment_close` -Close a shipment (mark as delivered). - -## Contracts / Subscriptions - -### `dolibarr_contracts_list` -List contracts/subscriptions. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"4"` / `"5"` | No | 0=draft, 1=validated, 4=closed, 5=running | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | - -### `dolibarr_contract_get` -Get a single contract by ID. - -### `dolibarr_contract_create` -Create a new contract. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `socid` | number | Yes | Third party ID | -| `ref` | string | No | Contract reference | -| `date_contrat` | string | No | Contract date | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -### `dolibarr_contract_validate` -Validate a draft contract. - -## Interventions - -### `dolibarr_interventions_list` -List interventions (field service). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=validated, 2=billed | -| `thirdparty_ids` | string | No | Comma-separated third party IDs | - -### `dolibarr_intervention_get` -Get a single intervention by ID. - -## Expense Reports - -### `dolibarr_expensereports_list` -List expense reports. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | `"0"` / `"2"` / `"4"` / `"5"` / `"6"` / `"99"` | No | 0=draft, 2=validated, 4=cancelled, 5=approved, 6=paid, 99=refused | - -### `dolibarr_expensereport_get` -Get a single expense report by ID. - -### `dolibarr_expensereport_create` -Create a new expense report. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `fk_user_author` | number | Yes | User ID of the author | -| `date_debut` | string | Yes | Start date | -| `date_fin` | string | Yes | End date | -| `note_public` | string | No | Public note | -| `note_private` | string | No | Private note | - -## Tickets (Helpdesk) - -### `dolibarr_tickets_list` -List helpdesk tickets. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `status` | string | No | Filter by status | -| `search` | string | No | Search in subject | - -### `dolibarr_ticket_get` -Get a single ticket by ID. - -### `dolibarr_ticket_create` -Create a new helpdesk ticket. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `subject` | string | Yes | Ticket subject | -| `message` | string | Yes | Ticket message/description | -| `type_code` | string | No | Ticket type code | -| `category_code` | string | No | Ticket category code | -| `severity_code` | string | No | Ticket severity code | -| `socid` | number | No | Third party ID | -| `notify_tiers_at_create` | number | No | 1=notify third party on creation | - -## Agenda / Events - -### `dolibarr_agendaevents_list` -List agenda events. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `type` | string | No | Event type code | -| `status` | `"-1"` / `"0"` / `"50"` / `"100"` | No | -1=cancelled, 0=draft, 50=in progress, 100=done | -| `userassigned` | number | No | Filter by assigned user ID | - -### `dolibarr_agendaevent_get` -Get a single agenda event by ID. - -### `dolibarr_agendaevent_create` -Create a new agenda event. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `label` | string | Yes | Event label/title | -| `type_code` | string | Yes | Event type code (e.g. `"AC_RDV"`, `"AC_TEL"`, `"AC_OTH"`) | -| `datep` | string | Yes | Start date (YYYY-MM-DD HH:MM:SS or Unix timestamp) | -| `datef` | string | No | End date | -| `socid` | number | No | Third party ID | -| `contactid` | number | No | Contact ID | -| `fk_project` | number | No | Project ID | -| `userownerid` | number | No | Owner user ID | -| `note` | string | No | Event note | -| `percentage` | `"-1"` / `"0"` / `"50"` / `"100"` | No | Completion status | - -### `dolibarr_agendaevent_update` -Update an agenda event. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Event ID | -| `label` | string | No | Event label | -| `datep` | string | No | Start date | -| `datef` | string | No | End date | -| `percentage` | `"-1"` / `"0"` / `"50"` / `"100"` | No | Completion status | -| `note` | string | No | Event note | - -## Payments - -### `dolibarr_invoice_payments` -List payments for an invoice. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | - -### `dolibarr_invoice_add_payment` -Add a payment to an invoice. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Invoice ID | -| `datepaye` | string | Yes | Payment date | -| `paymentid` | number | Yes | Payment type ID (e.g. 4=bank transfer, 6=credit card) | -| `closepaidinvoices` | string | No | `"yes"` to auto-close fully paid invoices | -| `accountid` | number | No | Bank account ID | -| `num_payment` | string | No | Payment number/reference | -| `comment` | string | No | Payment comment | - -## Documents - -### `dolibarr_documents_list` -List documents attached to an object. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `modulepart` | string | Yes | Module name (e.g. `"facture"`, `"propal"`, `"commande"`, `"societe"`) | -| `id` | number | No | Object ID | -| `ref` | string | No | Object ref (alternative to ID) | - -### `dolibarr_document_download` -Download/get content of a document. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `modulepart` | string | Yes | Module name | -| `original_file` | string | Yes | Relative file path (e.g. `"FA2301-0001/FA2301-0001.pdf"`) | - -### `dolibarr_document_builddoc` -Generate/build a document (e.g. PDF invoice). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `modulepart` | string | Yes | Module name | -| `original_file` | string | Yes | Expected output filename | -| `doctemplate` | string | No | Document template name (e.g. `"crabe"`, `"sponge"`) | -| `langcode` | string | No | Language code (e.g. `"en_US"`, `"fr_FR"`) | - -## Members - -### `dolibarr_members_list` -List association members. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `typeid` | number | No | Filter by member type ID | -| `status` | `"0"` / `"1"` / `"-1"` / `"-2"` | No | 1=validated, 0=draft, -1=resigned, -2=excluded | -| `search` | string | No | Search in name | - -### `dolibarr_member_get` -Get a single member by ID. - -## Stock / Warehouses - -### `dolibarr_warehouses_list` -List warehouses. No additional parameters (supports pagination). - -### `dolibarr_stockmovements_list` -List stock movements. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `product_id` | number | No | Filter by product ID | -| `warehouse_id` | number | No | Filter by warehouse ID | - -### `dolibarr_stockmovement_create` -Create a stock movement (add/remove stock). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `product_id` | number | Yes | Product ID | -| `warehouse_id` | number | Yes | Warehouse ID | -| `qty` | number | Yes | Quantity (positive=add, negative=remove) | -| `type` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=increase, 1=decrease, 2=transfer increase, 3=transfer decrease | -| `label` | string | No | Movement label/reason | -| `inventorycode` | string | No | Inventory code | - -## Bank Accounts - -### `dolibarr_bankaccounts_list` -List bank accounts. No additional parameters (supports pagination). - -### `dolibarr_bankaccount_lines` -List transactions/lines for a bank account. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `id` | number | Yes | Bank account ID | - -## Categories - -### `dolibarr_categories_list` -List categories. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `type` | `"product"` / `"supplier"` / `"customer"` / `"member"` / `"contact"` / `"project"` | No | Category type | -| `search` | string | No | Search in label | - -### `dolibarr_category_get` -Get a single category by ID. - -### `dolibarr_category_create` -Create a new category. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `label` | string | Yes | Category label | -| `type` | string | Yes | Category type | -| `fk_parent` | number | No | Parent category ID (0 = root) | -| `description` | string | No | Category description | -| `color` | string | No | Category color (hex, e.g. `"ff0000"`) | - -## Users - -### `dolibarr_users_list` -List Dolibarr users. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `search` | string | No | Search in login name | - -### `dolibarr_user_get` -Get a single user by ID. - -### `dolibarr_user_create` -Create a new Dolibarr user. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `login` | string | Yes | Login/username | -| `lastname` | string | Yes | Last name | -| `firstname` | string | No | First name | -| `email` | string | No | Email address | -| `admin` | `"0"` / `"1"` | No | 0=user, 1=admin | -| `employee` | `"0"` / `"1"` | No | 1=is employee | - -## Setup / System - -### `dolibarr_setup_company` -Get company/entity information. No parameters. - -### `dolibarr_setup_dictionary` -Get dictionary entries (lookup tables). - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `type` | string | Yes | Dictionary type: `countries`, `regions`, `states`, `currencies`, `civilities`, `payment_types`, `shipping_methods`, `availability`, `order_methods`, `event_types`, `expense_report_types`, `ticket_types`, `ticket_severities`, `ticket_categories`, `units`, `legal_form`, `staff_range`, `typent` | - -### `dolibarr_setup_modules` -List enabled Dolibarr modules. No parameters. - -### `dolibarr_status` -Get Dolibarr instance status and version. No parameters. - -## Generic - -### `dolibarr_api_request` -Make a raw API request to any Dolibarr REST endpoint. - -| Parameter | Type | Required | Description | -|-----------|------|----------|-------------| -| `method` | `"GET"` / `"POST"` / `"PUT"` / `"DELETE"` | Yes | HTTP method | -| `endpoint` | string | Yes | API path (e.g. `"/thirdparties"`) | -| `body` | object | No | Request body for POST/PUT | -| `params` | object | No | Query parameters | - -### `dolibarr_list_connections` -List all configured connections. No parameters. - -## Revision History - -| Date | Version | Author | Notes | -| --- | --- | --- | --- | -| 2026-05-07 | 0.0.1 | jmiller | Initial API reference (44 tools) | -| 2026-05-07 | 0.1.0 | jmiller | Expanded to 89 tools — shipments, contracts, interventions, expense reports, tickets, agenda events, payments, documents, members, stock movements, contact CRUD, task CRUD with timespent, dictionaries, bank transactions | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index e8a07fc..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,118 +0,0 @@ - - -# Architecture - -## Overview - -dolibarr-api-mcp is a Model Context Protocol (MCP) server that bridges AI assistants (Claude Code, Cursor, etc.) with Dolibarr's built-in REST API. - -``` -AI Assistant <--> MCP (stdio) <--> DolibarrClient <--> Dolibarr REST API - /api/index.php -``` - -## Components - -### `src/index.ts` — Server Entry Point - -Registers all MCP tools with the `McpServer` from `@modelcontextprotocol/sdk`. Each tool maps to one or more Dolibarr API endpoints. Uses Zod schemas for input validation. - -Includes shared helpers: -- `formatResponse()` — normalizes Dolibarr error responses and success payloads into MCP text content -- `paginationQuery()` — builds `limit`, `page`, `sortfield`, `sortorder` query params -- `buildSqlFilter()` — constructs Dolibarr's `sqlfilters` parameter from structured clauses (supports AND/OR joins, proper escaping) -- `searchFilter()` — shortcut for `LIKE '%term%'` filters on a single field - -### `src/client.ts` — HTTP Client - -The `DolibarrClient` class handles all HTTP communication with Dolibarr instances: - -- Uses `node:https` / `node:http` for requests (not `fetch`) to support self-signed TLS certificates on Node.js 24+ -- Authenticates via `DOLAPIKEY` header (Dolibarr's native API key mechanism) -- Sends `Accept: application/json` and `Content-Type: application/json` -- Supports GET, POST, PUT, and DELETE methods - -### `src/config.ts` — Configuration Loader - -Loads connection details from `~/.dolibarr-api-mcp.json`. Supports multiple named connections with a configurable default. Respects the `DOLIBARR_API_MCP_CONFIG` environment variable for custom config paths. - -### `src/types.ts` — Type Definitions - -TypeScript interfaces for `DolibarrConnection`, `DolibarrConfig`, and `ApiResponse`. - -### `scripts/setup.mjs` — Interactive Setup - -Node.js script using `readline/promises` that walks users through creating the config file. Supports adding multiple connections incrementally. - -## Design Decisions - -### Why `node:https` instead of `fetch`? - -Node.js 24's built-in `fetch` (undici-based) does not honor `NODE_TLS_REJECT_UNAUTHORIZED=0` for self-signed certificate bypass. The classic `node:https` module with `rejectUnauthorized: false` works reliably across all Node.js versions. - -### Why `DOLAPIKEY` instead of Bearer tokens? - -Dolibarr's REST API authenticates via the `DOLAPIKEY` HTTP header, not OAuth or Bearer tokens. This is Dolibarr's native mechanism — each user has a per-user API key that inherits that user's permissions. There is no token expiration; keys persist until manually regenerated. - -### Why `PUT` instead of `PATCH`? - -Dolibarr's API uses `PUT` for updates (full or partial), not `PATCH`. The API accepts partial payloads via PUT — only the fields you send are updated. - -### Why `sqlfilters` with a builder? - -Dolibarr's API supports a custom `sqlfilters` query parameter that allows server-side filtering with SQL-like expressions (e.g. `(t.nom:like:'%acme%')`). The `buildSqlFilter()` helper: -- Handles single-quote escaping to prevent injection -- Supports combining multiple clauses with AND/OR -- Provides `searchFilter()` as a concise shortcut for the common `LIKE` pattern - -### Why per-connection API keys? - -Each Dolibarr instance requires its own API key scoped to a specific user. Multi-instance support is a core use case — managing staging, production, and dev ERP environments from a single MCP server. - -## Data Flow - -1. AI assistant sends a tool call via MCP stdio transport -2. `index.ts` validates parameters with Zod and resolves the connection -3. `DolibarrClient` constructs the API URL, attaches the `DOLAPIKEY` header, and makes the HTTP request -4. Response is parsed as JSON and returned as MCP tool output - -## API Module Coverage - -| Dolibarr Module | Tools | Endpoints | -|----------------|-------|-----------| -| Third Parties | 5 | `/thirdparties` | -| Invoices | 6 | `/invoices`, `/invoices/{id}/lines`, `/invoices/{id}/validate`, `/invoices/{id}/settopaid` | -| Proposals | 7 | `/proposals`, `/proposals/{id}/lines`, `/proposals/{id}/validate`, `/proposals/{id}/close` | -| Orders | 4 | `/orders`, `/orders/{id}/validate` | -| Products | 5 | `/products`, `/products/{id}/stock` | -| Contacts | 2 | `/contacts` | -| Projects | 3 | `/projects` | -| Tasks | 2 | `/tasks` | -| Users | 2 | `/users` | -| Categories | 1 | `/categories` | -| Bank Accounts | 1 | `/bankaccounts` | -| Supplier Invoices | 1 | `/supplierinvoices` | -| Supplier Orders | 1 | `/supplierorders` | -| Warehouses | 1 | `/warehouses` | -| Setup | 2 | `/setup/company`, `/status` | -| Generic | 2 | Any endpoint, connection listing | - -## Revision History - -| Date | Version | Author | Notes | -| --- | --- | --- | --- | -| 2026-05-07 | 0.0.1 | jmiller | Initial architecture document | diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md deleted file mode 100644 index 1558360..0000000 --- a/docs/INSTALLATION.md +++ /dev/null @@ -1,172 +0,0 @@ - - -# Installation - -## Prerequisites - -- **Node.js** 20.0.0 or later -- **npm** (included with Node.js) -- A Dolibarr ERP/CRM instance (v14+) with the REST API module enabled -- A Dolibarr API key (generated per-user or via Setup > Security) - -## Install - -```sh -git clone https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp.git -cd dolibarr-api-mcp -npm install -npm run build -npm run setup -``` - -The setup wizard will prompt for: - -1. **Connection name** — a label for this instance (e.g. `production`, `staging`) -2. **Dolibarr URL** — the base URL of the instance (e.g. `https://erp.example.com`) -3. **API key** — the Dolibarr API key for authentication -4. **TLS verification** — whether to skip certificate verification (for self-signed certs) - -Run `npm run setup` again to add more connections. - -## Enabling the Dolibarr REST API - -1. Log in to Dolibarr as an admin -2. Go to **Home > Setup > Modules/Applications** -3. Find **API/Web services (REST server)** in the list -4. Click the toggle to enable it -5. The API will be available at `https://your-dolibarr.com/api/index.php` - -## Generating an API Key - -### Per-User API Key (Recommended) - -1. Go to **Home > Users & Groups > Users** -2. Select the user that will be used for API access -3. On the user card, look for the **API key** field -4. Click **Generate** to create a key, or set one manually -5. Click **Save** - -The user's permissions determine what the API key can access. Use a dedicated API user with appropriate permissions for production. - -### System-Level API Key - -1. Go to **Home > Setup > Security > Tokens & API** -2. Generate or configure the system API key -3. This key has broader access — use with caution - -## Register with Claude Code - -Add to your global Claude Code config (`~/.claude.json`): - -```json -{ - "mcpServers": { - "dolibarr-api": { - "type": "stdio", - "command": "node", - "args": ["/path/to/dolibarr-api-mcp/dist/index.js"] - } - } -} -``` - -Or add to a project-level `.mcp.json`: - -```json -{ - "mcpServers": { - "dolibarr-api": { - "command": "node", - "args": ["/path/to/dolibarr-api-mcp/dist/index.js"] - } - } -} -``` - -Restart Claude Code after adding the server. - -## Configuration File - -The config is stored at `~/.dolibarr-api-mcp.json`: - -```json -{ - "defaultConnection": "production", - "connections": { - "production": { - "baseUrl": "https://erp.example.com", - "apiKey": "your-api-key" - }, - "staging": { - "baseUrl": "https://erp-staging.example.com", - "apiKey": "your-staging-key", - "insecure": true - } - } -} -``` - -| Field | Required | Description | -|-------|----------|-------------| -| `defaultConnection` | Yes | Name of the default connection | -| `connections` | Yes | Map of named connections | -| `baseUrl` | Yes | Dolibarr instance URL (no trailing slash) | -| `apiKey` | Yes | Dolibarr API key (`DOLAPIKEY` header auth) | -| `insecure` | No | Set `true` to skip TLS verification | - -You can also set the `DOLIBARR_API_MCP_CONFIG` environment variable to use a config file at a custom path. - -## Verification - -After setup, verify the server starts correctly: - -```sh -npm start -``` - -If configured correctly, the server will start listening on stdio. If the config is missing or invalid, it will print an error with instructions. - -You can also test the connection by asking Claude to run `dolibarr_status` — this calls the `/api/index.php/status` endpoint and returns the Dolibarr version. - -## Troubleshooting - -### "Failed to load config" error - -The config file `~/.dolibarr-api-mcp.json` is missing or malformed. Run `npm run setup` to create it. - -### "terminated" or connection errors - -- Verify the Dolibarr instance is reachable from your machine -- For self-signed certs, set `"insecure": true` in the connection config -- Ensure the API key is valid - -### "Access denied" or 403 errors - -- The API module may not be enabled in Dolibarr (see "Enabling the Dolibarr REST API" above) -- The API key user may lack permissions for the requested operation -- Check that the user has the correct roles in Dolibarr's permissions system - -### "Error 404" on certain endpoints - -- Some API endpoints require specific Dolibarr modules to be enabled (e.g. Projects module for `/projects`) -- Check **Setup > Modules** to ensure the relevant module is active - -## Revision History - -| Date | Version | Author | Notes | -| --- | --- | --- | --- | -| 2026-05-07 | 0.0.1 | jmiller | Initial installation guide | diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index f693732..0000000 --- a/docs/index.md +++ /dev/null @@ -1,17 +0,0 @@ - - -# dolibarr-api-mcp Documentation - -## Documents - -- [INSTALLATION.md](./INSTALLATION.md) — Prerequisites, install, setup wizard, Dolibarr API key generation, troubleshooting -- [ARCHITECTURE.md](./ARCHITECTURE.md) — Component overview, design decisions, data flow, API module coverage -- [API.md](./API.md) — Full MCP tool reference with parameter tables for all 45 tools - -## Root Documents - -- [README.md](../README.md) — Project overview, quick start, tool summary -- [CHANGELOG.md](../CHANGELOG.md) — Version history -- [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute, development workflow, commit conventions -- [SECURITY.md](../SECURITY.md) — Vulnerability reporting policy diff --git a/src/config.ts b/src/config.ts index 6a649ca..d7c8491 100644 --- a/src/config.ts +++ b/src/config.ts @@ -18,7 +18,7 @@ import { resolve } from 'node:path'; import { homedir } from 'node:os'; import type { DolibarrConfig, DolibarrConnection } from './types.js'; -const CONFIG_FILENAME = '.dolibarr-api-mcp.json'; +const CONFIG_FILENAME = '.mcp_mokocrm.json'; export async function loadConfig(): Promise { const config_path = process.env.DOLIBARR_API_MCP_CONFIG