README.md•4.35 kB
## MCP Odoo — Middleware (TypeScript)
Mục đích
- Một MCP (middleware) nhỏ viết bằng TypeScript để kết nối tới Odoo (XML-RPC) và expose API HTTP cho các tác vụ phổ biến:
- Truy vấn Lead (crm.lead)
- Truy vấn Customer (res.partner)
- Truy vấn Activities (mail.activity)
Kiến trúc ngắn gọn
- `src/odooService.ts` : wrapper XML-RPC cho Odoo (authenticate + execute_kw + helpers).
- `src/server.ts` : Express API endpoints cho các truy vấn.
- `bin/workers-mcp.CMD` và `bin/workers-mcp.js` : launcher để gọi `dist/server.js` theo kiểu mà orchestrator (ví dụ Claude worker runner) yêu cầu.
Yêu cầu
- Node.js (>= 18 recommended)
- npm
Cấu hình (environment)
- Copy file `.env.example` -> `.env` rồi điền các giá trị sau:
- URL_ODOO: URL Odoo (ví dụ https://app.x-or.cloud)
- PORT_ODOO: port (thường 443)
- DBNAME_ODOO: tên database Odoo
- USERNAME_ODOO: username Odoo
- PASSWORD_ODOO: password Odoo
- MCP_PORT: (tuỳ chọn) port để server nghe, default 3000
- (Tuỳ chọn nếu dùng LLM/Discord) LLM_API_KEY, LLM_MODEL, DISCORD_WEBHOOK_URL
Cài đặt & build
1. Cài dependency và build TypeScript:
```powershell
cd "C:\Project\MCP Odoo"
npm install
npm run build
```
2. Sau khi build sẽ có `dist/server.js`.
Chạy server (local/test)
- Chạy trực tiếp:
```powershell
node dist/server.js
```
- Hoặc dùng launcher CMD (nếu bạn muốn truyền args theo format orchestrator):
```powershell
& "C:\Project\MCP Odoo\bin\workers-mcp.CMD" run mcp-demo https://mcp-demo.mcpdemo.workers.dev "C:\Project\MCP Odoo"
```
Chạy production (gợi ý)
- Dùng PM2 (cross-platform):
```powershell
npm install -g pm2
pm2 start dist/server.js --name mcp-odoo -- run mcp-demo https://mcp-demo.mcpdemo.workers.dev "C:\Project\MCP Odoo"
pm2 save
```
- Hoặc trên Windows dùng nssm để tạo service chạy node `dist/server.js`.
MCP launcher / tích hợp với orchestrator
- Trong một số hệ thống, orchestrator sẽ gọi một command kèm args giống ví dụ bạn đưa. Project này cung cấp hai file trong `bin/`:
- `workers-mcp.CMD` : shim cho Windows, chạy `dist/server.js` với các arg.
- `workers-mcp.js` : launcher Node.js (UNIX/Windows friendly).
- Ví dụ cấu hình orchestrator (JSON):
```json
{
"mcpServers": {
"mcp-demo": {
"command": "C:\\Project\\MCP\\mcp-demo\\bin\\workers-mcp.CMD",
"args": [
"run",
"mcp-demo",
"https://mcp-demo.mcpdemo.workers.dev",
"C:\\Project\\MCP\\mcp-demo"
],
"env": {}
}
}
}
```
Ghi chú: bạn có thể thay đổi `command` để trỏ trực tiếp tới `node dist/server.js` nếu thích.
Endpoints hiện có
- GET /mcp/leads?limit=10&offset=0
- query params: domain (JSON-encoded), fields (JSON-encoded), limit, offset
- GET /mcp/customers?limit=10
- GET /mcp/activities?limit=10
Ví dụ gọi:
```powershell
curl "http://localhost:3000/mcp/leads?limit=5"
```
Bảo mật
- Không commit `.env` hoặc API keys vào git. `.gitignore` đã được thêm.
- Đặt biến môi trường trên server (System Environment) khi chạy như service.
Troubleshooting
- Nếu thiếu `dist/server.js`: chạy `npm run build`.
- Nếu lỗi kết nối Odoo: kiểm tra `URL_ODOO`, `DBNAME_ODOO`, username/password, và network/firewall.
- Nếu orchestrator không tìm thấy `workers-mcp.CMD`: sửa `command` trỏ tới `bin\\workers-mcp.CMD` trong repo hoặc copy shim vào `node_modules\\.bin`.
Các việc tiếp theo (gợi ý)
- Thêm endpoint health `/mcp/health` để orchestrator kiểm tra trạng thái.
- Thêm caching cho uid Odoo để tránh authenticate mỗi lần gọi.
- Thêm adapter LLM (OpenAI/Claude) nếu muốn xử lý văn bản/tóm tắt; hoặc tích hợp Discord webhook (đã có code mẫu trước đó nếu bạn cần tôi phục hồi).
Liên hệ
- Nếu muốn tôi thêm `/mcp/health` và đọc args từ launcher (MCP name / public URL / root), nói "thêm health"; tôi sẽ cập nhật và build.
# MCP Odoo TypeScript Client
Simple TypeScript wrapper to query Leads, Customers, and Activities from an Odoo instance via XML-RPC.
Usage:
- Copy `.env.example` to `.env` and fill values.
- npm install
- npm run build
- npm start