内容
# 多利巴尔 MCP 服务器
多利巴尔 MCP 提供了一个模型上下文协议（MCP）接口，用于多利巴尔 ERP/CRM。该项目镜像了 [`prestashop-mcp`](https://github.com/latinogino/prestashop-mcp) 的项目结构：一个异步 API 客户端，一个生产就绪的 STDIO 服务器，以及专注的文档。
**设计说明：** 虽然共享相同的架构，但该服务器实现了**专用搜索工具**（例如 `search_products_by_ref`、`resolve_product_ref`），而不是单一的统一 `get_` 工具。此设计选择确保通过多利巴尔的 SQL API 进行高效的服务器端过滤，防止代理意外加载数千条记录并超过上下文限制。
克劳德桌面和其他 MCP 感知工具可以使用服务器管理多利巴尔实例中的客户、产品、发票、订单和联系人。
请参阅捆绑的 [文档索引](docs/README.md)，深入了解配置、API 覆盖和贡献者工作流程。
## ✨ 功能
- **完整的 ERP 覆盖** – 用户、客户、产品、发票、订单、联系人、项目和原始 API 访问的 CRUD 工具。
- **高级搜索** – 产品、客户和项目的服务器端过滤，以最小化令牌使用和成本。
- **异步/等待 HTTP 客户端** – 高效的多利巴尔 API 包装器，具有结构化错误处理。
- **适用于 MCP 主机** – STDIO 传输与克劳德桌面开箱即用兼容。
- **与 prestashop-mcp 共享工作流** – 相同的开发人员人体工程学和文档结构在两个仓库中。
## ✅ 先决条件
- Python 3.8 或更新版本。
- 访问具有启用 REST API 和个人 API 令牌的多利巴尔安装。
## 📦 安装
### Linux / macOS
```bash
git clone https://github.com/latinogino/dolibarr-mcp.git
cd dolibarr-mcp
python3 -m venv venv_dolibarr
source venv_dolibarr/bin/activate
pip install -e .
# 可选的开发额外功能
pip install -e '.[dev]'
```
在虚拟环境激活时，使用 `which python` 记录 Python 可执行文件路径。克劳德桌面必须使用此解释器启动 MCP 服务器。
### Windows (PowerShell)
```powershell
git clone https://github.com/latinogino/dolibarr-mcp.git
Set-Location dolibarr-mcp
py -3 -m venv venv_dolibarr
./venv_dolibarr/Scripts/Activate.ps1
pip install -e .
# 可选的开发额外功能（在 PowerShell 中转义括号）
pip install -e .`[dev`]
```
在环境激活时运行 `Get-Command python`（或 `Get-Command python.exe`），并记录绝对路径。克劳德桌面应在虚拟环境中使用此解释器，例如 `C:\\path\\to\\dolibarr-mcp\\venv_dolibarr\\Scripts\\python.exe`。
### Docker（可选）
```bash
docker compose up -d
# 或
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
```
## ⚙️ 配置
### 环境变量
服务器从环境或 `.env` 文件中读取配置。`DOLIBARR_URL` 和 `DOLIBARR_SHOP_URL` 都接受为基本 API 地址。
| 变量 | 描述 |
| --- | --- |
| `DOLIBARR_URL` / `DOLIBARR_SHOP_URL` | 基本多利巴尔 API 端点，例如 `https://example.com/api/index.php`。自动处理尾部斜杠。 |
| `DOLIBARR_API_KEY` | 个人多利巴尔 API 令牌。 |
| `LOG_LEVEL` | 可选的日志详细程度（`INFO`、`DEBUG`、`WARNING` 等）。 |
| `MCP_TRANSPORT` | 要使用的传输：`stdio`（默认）或 `http` 用于可流式 HTTP。 |
| `MCP_HTTP_HOST` | 使用 HTTP 传输时要绑定的主机/接口（默认 `0.0.0.0`）。 |
| `MCP_HTTP_PORT` | 使用 HTTP 传输时要绑定的端口（默认 `8080`）。 |
示例 `.env`：
```env
DOLIBARR_URL=https://your-dolibarr.example.com/api/index.php
DOLIBARR_API_KEY=YOUR_API_KEY
LOG_LEVEL=INFO
```
### 克劳德桌面配置
将以下块添加到 `claude_desktop_config.json`，替换路径和凭据为您自己的值：
```json
{
"mcpServers": {
"dolibarr": {
"command": "C:\\path\\to\\dolibarr-mcp\\venv_dolibarr\\Scripts\\python.exe",
"args": ["-m", "dolibarr_mcp.dolibarr_mcp_server"],
"cwd": "C:\\path\\to\\dolibarr-mcp",
"env": {
"DOLIBARR_SHOP_URL": "https://your-dolibarr.example.com",
"DOLIBARR_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
保存配置后重启克劳德桌面。MCP 服务器从 Linux 或 macOS 主机启动时读取相同的环境变量。
## ▶️ 用法
### 启动 MCP 服务器
服务器默认通过 STDIO 通信，因此在虚拟环境中将其作为前台进程运行：
```bash
python -m dolibarr_mcp.dolibarr_mcp_server
```
日志写入 stderr 以避免干扰 MCP 协议。在克劳德桌面激活时保持进程运行。
### HTTP 流媒体模式（适用于 Open WebUI 或远程 MCP 客户端）
通过设置 `MCP_TRANSPORT=http`（和可选的 `MCP_HTTP_HOST` / `MCP_HTTP_PORT`）启用 HTTP 传输。这使服务器在没有 STDIO 的情况下运行，并公开与 Open WebUI 兼容的可流式 HTTP 传输：
```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 python -m dolibarr_mcp.dolibarr_mcp_server
```
然后将 Open WebUI 的 MCP 配置指向 `http://<host>:8080/`。MCP 协议标头（包括 `mcp-protocol-version`）由 Open WebUI 的 MCP 客户端自动处理。
### 测试多利巴尔凭证
在使用服务器连接到 MCP 主机之前，使用独立的连接性检查：
```bash
python -m dolibarr_mcp.test_connection --url https://your-dolibarr.example.com/api/index.php --api-key YOUR_API_KEY
```
当环境变量已经设置时，省略覆盖并运行 `python -m dolibarr_mcp.test_connection`。
## 🧪 开发
- 使用 `pytest` 运行测试套件（参见 [`docs/development.md`](docs/development.md) 了解覆盖率选项和 Docker 帮助程序）。
- 可编辑安装依赖于 `src/` 布局，并公开 `dolibarr-mcp` 控制台入口点以保持向后兼容。
- 仓库结构、工具和文档故意镜像 [`prestashop-mcp`](https://github.com/latinogino/prestashop-mcp)，以保持配套项目的一致性。
## 📄 许可证
在 [MIT 许可证](LICENSE) 下发布。
