diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fc26f6..61fa38a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,32 @@ # Changelog -All notable changes to the Dolibarr MCP Server will be documented in this file. +All notable changes to the Dolibarr MCP Server are documented here. The project +follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and adopts the +[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added +- Restored README.md and CHANGELOG.md after merge conflicts while preserving the streamlined structure shared with `prestashop-mcp`. +- Documented platform-specific setup covering Linux/macOS shells, Windows Visual Studio `vsenv`, and the Docker workflow. + +### Changed +- Reconciled feature and tool descriptions so they capture both the detailed ERP coverage and the new documentation bundle layout. +- Clarified configuration guidance around `pydantic-settings`, environment variables, and `.env` files. + +### Removed +- Obsolete references to legacy helper scripts and superseded documentation variants that were dropped during the repository cleanup. + +## [1.1.0] - 2024-05-22 + +### Removed +- Legacy helper scripts, installers, and manual test programs that duplicated the automated test-suite. +- Alternative server implementations (`simple_client`, `standalone_server`, `ultra_simple_server`) in favour of the single `dolibarr_mcp_server`. +- Redundant documentation fragments and variant requirements files that no longer reflected the current project layout. + +### Changed +- Rewrote the README to highlight the streamlined structure and provide concise installation/run instructions. +- Clarified that `dolibarr_mcp_server.py` is the definitive MCP entry point. ## [Unreleased] @@ -25,44 +48,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 This release represents a complete restructuring of the Dolibarr MCP Server to match the clean architecture of prestashop-mcp. ### Added -- Professional README.md with comprehensive documentation -- Structured test suite in `tests/` directory -- Clean configuration management -- Docker support for easy deployment -- Comprehensive CRUD operations for all Dolibarr entities +- Professional README.md with comprehensive documentation. +- Structured test suite in `tests/` directory. +- Clean configuration management. +- Docker support for easy deployment. +- Comprehensive CRUD operations for all Dolibarr entities. ### Changed -- Complete repository restructuring to match prestashop-mcp pattern -- Simplified dependencies in requirements.txt -- Cleaned up package structure in `src/dolibarr_mcp/` -- Updated pyproject.toml with proper metadata -- Streamlined .gitignore file +- Complete repository restructuring to match prestashop-mcp pattern. +- Simplified dependencies in requirements.txt. +- Cleaned up package structure in `src/dolibarr_mcp/`. +- Updated pyproject.toml with proper metadata. +- Streamlined .gitignore file. ### Removed -- Outdated prototype assets from the first public release +- Outdated prototype assets from the first public release. ### Technical Improvements -- Single, focused MCP server implementation -- Clean separation of concerns -- Better error handling -- Improved logging -- Async/await architecture throughout +- Single, focused MCP server implementation. +- Clean separation of concerns. +- Better error handling. +- Improved logging. +- Async/await architecture throughout. ## [0.5.0] - 2024-01-20 ### Added -- Initial Dolibarr API integration -- Basic CRUD operations for customers, products, invoices -- MCP server implementation -- Docker configuration +- Initial Dolibarr API integration. +- Basic CRUD operations for customers, products, invoices. +- MCP server implementation. +- Docker configuration. ## [0.1.0] - 2024-01-15 ### Added -- Initial project setup -- Basic repository structure -- License and documentation +- Initial project setup. +- Basic repository structure. +- License and documentation. --- -**Note**: This changelog focuses on the major restructuring in v1.0.0 to align with prestashop-mcp's clean architecture. +**Note**: Entries prior to v1.0.0 summarise the historical evolution of the project and are retained for context. diff --git a/README.md b/README.md index 9d3df4d..9f78446 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,140 @@ # Dolibarr MCP Server -## Repository layout +Dolibarr MCP is a focused Model Context Protocol (MCP) server that exposes the +most useful Dolibarr ERP/CRM operations to AI copilots. The repository mirrors +the clean layout used by [`prestashop-mcp`](https://github.com/latinogino/prestashop-mcp): +a single production-ready server implementation, an async HTTP client, and a +self-contained documentation bundle. | Path | Purpose | | --- | --- | +This MCP server enables complete management of your Dolibarr ERP/CRM through AI +tools such as Claude Desktop. With specialised tools you can manage customers, +products, invoices, orders, contacts, and system administration tasks from a +single MCP endpoint. + +## πŸ“š Documentation + +All user and contributor guides live in [`docs/`](docs/README.md): + +- [Quickstart](docs/quickstart.md) – installation and first run instructions for Linux, macOS, and Windows +- [Configuration](docs/configuration.md) – environment variables and secrets consumed by the server +- [Development](docs/development.md) – test workflow, linting, and Docker helpers +- [API Reference](docs/api-reference.md) – Dolibarr REST resources and corresponding MCP tools + +## ✨ Features + +- **πŸ’Ό Complete ERP/CRM Management** – Tools for customers, products, invoices, orders, and contacts +- **⚑ Async/Await Architecture** – Modern, high-performance HTTP client and server +- **πŸ›‘οΈ Comprehensive Error Handling** – Robust validation and structured responses +- **🐳 Docker Support** – Optional container workflow for local experimentation and deployment +- **πŸ”§ Production-Ready** – Automated tests and configuration management powered by `pydantic-settings` + +## πŸ›  Available tools + +`dolibarr_mcp_server` registers MCP tools that map to common Dolibarr workflows. +See the [API reference](docs/api-reference.md) for full details. + +- **System** – `test_connection`, `get_status`, and `dolibarr_raw_api` +- **Users** – CRUD helpers for Dolibarr users +- **Customers / Third Parties** – CRUD helpers for partners +- **Products** – CRUD helpers for product catalogue entries +- **Invoices** – CRUD helpers for invoices +- **Orders** – CRUD helpers for customer orders +- **Contacts** – CRUD helpers for contact records + +The async implementation in [`dolibarr_client.py`](src/dolibarr_mcp/dolibarr_client.py) +handles authentication, pagination, and error handling for all endpoints. + +## πŸ“¦ Installation + +### Linux / macOS + +```bash +git clone https://github.com/latinogino/dolibarr-mcp.git +cd dolibarr-mcp +python3 -m venv .venv +source .venv/bin/activate +pip install -e . +``` + +Install development extras (pytest, formatting, type-checking) when needed: + +```bash +pip install -e '.[dev]' +``` + +### Windows (Visual Studio `vsenv`) + +1. Launch the **x64 Native Tools Command Prompt for VS** or **Developer PowerShell for VS** (`vsenv`). +2. Create a virtual environment: `py -3 -m venv .venv`. +3. Activate it: `call .venv\\Scripts\\activate.bat` (Command Prompt) or `.\\.venv\\Scripts\\Activate.ps1` (PowerShell). +4. Install the package: `pip install -e .`. +5. Install development extras when required: `pip install -e .[dev]` (PowerShell requires escaping brackets: ``pip install -e .`[dev`]``). +6. Note the Python path (`where python`) for integration with Claude Desktop or other MCP hosts. + +### Docker + +```bash +# Using Docker Compose (recommended) +docker compose up -d + +# Or build and run directly +docker build -t dolibarr-mcp . +docker run -d \ + -e DOLIBARR_URL=https://your-dolibarr.example.com/api/index.php \ + -e DOLIBARR_API_KEY=YOUR_API_KEY \ + dolibarr-mcp +``` + +## βš™οΈ Configuration + +Set the following environment variables (they may live in a `.env` file): + +- `DOLIBARR_URL` – Dolibarr API endpoint, e.g. `https://example.com/api/index.php` +- `DOLIBARR_API_KEY` – personal Dolibarr API token +- `LOG_LEVEL` – optional logging verbosity (defaults to `INFO`) + +[`Config`](src/dolibarr_mcp/config.py) is built with `pydantic-settings` and +supports loading from the environment, `.env` files, and CLI overrides. See the +[configuration guide](docs/configuration.md) for a full matrix and troubleshooting tips. + +## ▢️ Running the server + +Dolibarr MCP communicates with hosts over STDIO. Once configured, launch the +server with: + +```bash +python -m dolibarr_mcp.cli serve +``` + +You can validate credentials and connectivity using the built-in test command +before wiring it into a host: + +```bash +python -m dolibarr_mcp.cli test --url https://example.com/api/index.php --api-key YOUR_TOKEN +``` + +## πŸ€– Using with Claude Desktop + +Add an entry to `claude_desktop_config.json` that points to your virtual +environment’s Python executable and the `dolibarr_mcp.cli` module. After +installation, verify the executable path with `which python` (Linux/macOS) or +`where python` (Windows `vsenv`). Restart Claude Desktop so it picks up the new +MCP server. + +## πŸ§ͺ Development workflow + +- Run the test-suite with `pytest` (see [development docs](docs/development.md) + for coverage flags and Docker helpers). +- Editable installs rely on the `src/` layout and expose the `dolibarr-mcp` + console entry point. +- Contributions follow the same structure and documentation conventions as + `prestashop-mcp` to keep the twin projects in sync. + +## πŸ“„ License +======= ```bash python -m dolibarr_mcp.cli test --url https://your-dolibarr.example.com/api/index.php --api-key YOUR_KEY ```