mpm/odoo-mpm-plugin
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: update README to v0.2.0 — new tools, cancel guard, Gitea URL

Browse Source
This commit is contained in:
mpmedia
2026-05-28 12:41:49 -05:00
parent 6d97d34923
commit 0f60ba2119
1 changed files with 41 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -36
View File
@@ -2,7 +2,7 @@
MPM Odoo ERP plugin for Claude Cowork — connects to mpmedia.odoo.com via XML-RPC with proxy-aware transport. MPM Odoo ERP plugin for Claude Cowork — connects to mpmedia.odoo.com via XML-RPC with proxy-aware transport.
**Version:** 0.1.3 **Version:** 0.2.0
**Author:** Message Point Media **Author:** Message Point Media
**Repo:** https://git.mpm.to/mpm/odoo-mpm-plugin **Repo:** https://git.mpm.to/mpm/odoo-mpm-plugin
**CoWork Project:** CW-003 — Odoo V19 MCP Bridge **CoWork Project:** CW-003 — Odoo V19 MCP Bridge
@@ -11,7 +11,7 @@ MPM Odoo ERP plugin for Claude Cowork — connects to mpmedia.odoo.com via XML-R
## Overview ## Overview
This plugin bridges Claude Cowork to MPM's Odoo V19 ERP instance at mpmedia.odoo.com. It runs a local MCP server (`odoo-mpm`) via `uv` that exposes read/write access across 11 modules: Products, Knowledge, Contacts, Sales, CRM, Projects, Helpdesk, Purchase, Inventory, Employees, and Utilities. This plugin bridges Claude Cowork to MPM's Odoo ERP instance at mpmedia.odoo.com. It runs a local MCP server (`odoo-mpm`) via `uv` that exposes read/write access across 12 modules: Products, Knowledge (with Templates), Contacts, Sales, CRM, Projects, Helpdesk, Purchase, Inventory, Employees, and Utilities.
Credentials are personal — each user authenticates with their own Odoo API key, stored securely in the OS keystore (macOS Keychain / Windows Credential Manager / Linux Secret Service). Keys are never written to disk. Credentials are personal — each user authenticates with their own Odoo API key, stored securely in the OS keystore (macOS Keychain / Windows Credential Manager / Linux Secret Service). Keys are never written to disk.
@@ -21,7 +21,7 @@ Credentials are personal — each user authenticates with their own Odoo API key
| Skill | What It Does | | Skill | What It Does |
|---|---| |---|---|
| `odoo` | Full access to MPM's Odoo instance. Triggers on: "in Odoo", "our products", "the knowledge base", "find a contact", "sales order", "opportunity", "project tasks", "helpdesk ticket", "purchase order", "stock", "inventory", "employee", "what stage is", "create a task", "update the ticket", "set icon", "article icon", "emoji icon" | | `odoo` | Full read/write access to MPM's Odoo instance. Triggers on: "in Odoo", "our products", "the knowledge base", "find a contact", "sales order", "opportunity", "project tasks", "helpdesk ticket", "purchase order", "stock", "inventory", "employee", "what stage is", "create a task", "update the ticket", "set icon", "article icon", "emoji icon", "cancel quotation", "cancel quote", "archive", "mark lost", "bulk update", "how many records", "count of", "stage id for", "resolve stage", "search with filters", "filter by", "lost reasons" |
--- ---
@@ -32,21 +32,30 @@ Credentials are personal — each user authenticates with their own Odoo API key
| **Credentials** | `setup_odoo_credentials`, `clear_odoo_credentials` | | **Credentials** | `setup_odoo_credentials`, `clear_odoo_credentials` |
| **Products** | `search_products`, `get_product`, `get_product_stock` | | **Products** | `search_products`, `get_product`, `get_product_stock` |
| **Knowledge** | `search_knowledge_articles`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article` | | **Knowledge** | `search_knowledge_articles`, `get_knowledge_article`, `create_knowledge_article`, `update_knowledge_article` |
| **Knowledge Templates** | `search_knowledge_templates`, `get_knowledge_template`, `list_knowledge_template_categories` |
| **Contacts** | `search_contacts`, `get_contact`, `create_contact` | | **Contacts** | `search_contacts`, `get_contact`, `create_contact` |
| **Sales** | `search_sales_orders`, `get_sales_order`, `create_sales_order` | | **Sales** | `search_sales_orders`, `get_sales_order`, `create_sales_order`, `cancel_sale_orders`, `cancel_and_archive_quotations` |
| **CRM** | `search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages` | | **CRM** | `search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_stages`, `mark_crm_lead_lost`, `list_crm_lost_reasons` |
| **Project** | `list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages` | | **Project** | `list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages` |
| **Helpdesk** | `search_helpdesk_tickets`, `get_helpdesk_ticket`, `create_helpdesk_ticket`, `update_helpdesk_ticket`, `list_helpdesk_teams` | | **Helpdesk** | `search_helpdesk_tickets`, `get_helpdesk_ticket`, `create_helpdesk_ticket`, `update_helpdesk_ticket`, `list_helpdesk_teams` |
| **Purchase** | `search_purchase_orders`, `get_purchase_order` | | **Purchase** | `search_purchase_orders`, `get_purchase_order` |
| **Inventory** | `search_inventory`, `get_stock_moves`, `list_internal_locations` | | **Inventory** | `search_inventory`, `get_stock_moves`, `list_internal_locations` |
| **Employees** | `search_employees`, `get_employee`, `list_departments` | | **Employees** | `search_employees`, `get_employee`, `list_departments` |
| **Utilities** | `odoo_search`, `odoo_get_record` | | **Utilities** | `odoo_search`, `odoo_get_record`, `odoo_search_read`, `get_record_count`, `bulk_update_records`, `archive_records`, `get_stage_ids`, `call_odoo_method` |
### Knowledge Article Icon Support (v0.1.3) ### Knowledge Article Icon Support
`create_knowledge_article`, `update_knowledge_article`, and `get_knowledge_article` all support an `icon` parameter — a Unicode emoji (e.g. `"⚙️"`, `"🔌"`, `"🖥️"`) that sets the article's icon in the KB tree. Browse emojis at: **https://emojipedia.org**
`create_knowledge_article` and `update_knowledge_article` both accept an optional `icon` parameter — a single Unicode emoji string (e.g. `"⚙️"`, `"🔌"`, `"🖥️"`) that sets the article's icon in the KB tree view. `get_knowledge_article` now returns the `icon` field. Passing an empty string or omitting the parameter leaves the existing icon unchanged. ### Sales Cancellation Safety Guard
`cancel_sale_orders` and `cancel_and_archive_quotations` **only operate on orders in Quotation (draft) or Quotation Sent (sent) state**. Both tools pre-validate all IDs and raise a named error listing any orders in other states before touching anything. Confirmed Sale Orders cannot be cancelled via Claude.
Browse and copy emojis at: **https://emojipedia.org** ### Utility Tools (v0.2.0)
- **`odoo_search_read`** — preferred for efficient queries: full domain filter + return only specified fields. Avoids token bloat vs. `odoo_get_record`.
- **`get_record_count`** — count matching records without fetching data. Use before bulk operations.
- **`bulk_update_records`** — set one or more fields on a list of IDs in a single API call. Works for stages, custom Studio fields (`x_studio_*`), status flags.
- **`archive_records`** — soft-delete via `active=False`. For `sale.order`, cancel first.
- **`get_stage_ids`** — resolve stage names to IDs with case-insensitive exact matching across `crm.stage`, `project.task.type`, `helpdesk.stage`.
- **`call_odoo_method`** — escape hatch for any model method not covered by other tools.
--- ---
@@ -56,22 +65,19 @@ Full install guide: [MPM Odoo Plugin — Install Guide](https://docs.google.com/
**Quick summary:** **Quick summary:**
1. **Install the plugin** — Claude Desktop: Settings → Plugins → Add Plugin → paste `https://git.mpm.to/mpm/odoo-mpm-plugin`. Or install from the `.plugin` file (ask Bryan for current build). 1. **Install the plugin** — Claude Desktop: Settings → Plugins → Add Plugin → paste `https://git.mpm.to/mpm/odoo-mpm-plugin`. Or double-click the `.plugin` file from the [CW-003 Drive folder](https://drive.google.com/drive/folders/1RYRUFKAltyp9nxcz203_TSD8eAABcuw5).
2. **Verify `uv` is installed** — Run `which uv` in terminal. If missing: 2. **Verify `uv` is installed** — Run `which uv` in terminal. If missing — Mac/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`. Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`.
- Mac/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh` 3. **Restart Claude Desktop** — Quit and relaunch. `uv` auto-installs Python dependencies (`keyring`) on first start.
- Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` 4. **Generate a personal Odoo API key** — Odoo → Avatar → My Profile → Account Security → API Keys → New API Key → set expiration to **No Limit**. Copy immediately — not shown again.
3. **Restart Claude Desktop** — Dependencies download automatically on first launch (a few seconds). 5. **Connect** — In CoWork, type "Set up my Odoo credentials". Claude will prompt for your Odoo login email and API key.
4. **Generate your Odoo API key** — Log in to [mpmedia.odoo.com](https://mpmedia.odoo.com) → Avatar → My Profile → Account Security → API Keys → New API Key. Label it `Claude Cowork`. Set expiration to **No Limit**. Copy the key immediately — it will not be shown again. 6. **Verify** — Ask Claude: "List my Odoo projects". A project list confirms full connectivity.
5. **Connect Claude to Odoo** — In chat, say "Set up my Odoo credentials". Provide your Odoo login email and API key. Claude stores them in your OS keystore and verifies the connection. Done once per machine.
6. **Verify** — Ask Claude: "List my Odoo projects." A project list confirms a successful connection.
### Setup Checklist ### Setup Checklist
- [ ] Plugin installed (URL or `.plugin` file) - [ ] Plugin installed (URL or `.plugin` file)
- [ ] `uv` installed and available in terminal - [ ] `uv` installed and in terminal PATH
- [ ] Claude restarted after install - [ ] Claude restarted after install
- [ ] Odoo API key generated (No Limit expiration) - [ ] Odoo API key generated (No Limit expiration)
- [ ] `setup_odoo_credentials` run and confirmed - [ ] `setup_odoo_credentials` completed
- [ ] "List my Odoo projects" returns data - [ ] "List my Odoo projects" returns data
--- ---
@@ -82,28 +88,27 @@ Full install guide: [MPM Odoo Plugin — Install Guide](https://docs.google.com/
|---|---| |---|---|
| Instance | mpmedia.odoo.com | | Instance | mpmedia.odoo.com |
| Database | mpmedia-odoo-sh-main-13285275 | | Database | mpmedia-odoo-sh-main-13285275 |
| Transport | XML-RPC (proxy-aware) | | Transport | stdio via `uv` |
| Auth | Personal API key via OS keystore | | Auth | Personal API key in OS keystore (`odoo-mpm` service) |
| MCP server | `odoo-mpm` (runs via `uv`) | | MCP server name | `odoo-mpm` |
--- ---
## Workflow Notes ## Workflow Notes
- When looking up items by number (e.g. "S00901", "P00195"), use `search_sales_orders` or `search_purchase_orders` with that as the query. - Before updating a task or ticket stage, call `list_task_stages` or `get_stage_ids` to confirm valid stage IDs.
- Before updating a task or ticket stage, call `list_task_stages` or `odoo_search` to confirm valid stage IDs. - Use `odoo_search_read` for any query where you only need specific fields — more efficient than `odoo_get_record`.
- Knowledge article bodies are stored as HTML — use basic HTML formatting when creating or updating. - Knowledge article bodies are HTML — use basic HTML formatting when creating or updating.
- When setting KB article icons, browse https://emojipedia.org, copy the emoji character, and pass it to the `icon` parameter. - Before calling `mark_crm_lead_lost`, call `list_crm_lost_reasons` to show the user available reasons.
- IDs returned from search tools can be passed directly to `get_*` tools for full details. - Before calling `cancel_sale_orders`, verify orders are in `draft` or `sent` state — the tool will reject anything else with a clear error.
--- ---
## Requirements ## Requirements
- Claude Desktop (Cowork mode) - [uv](https://github.com/astral-sh/uv) — Python package and environment manager
- [`uv`](https://astral.sh/uv) — Python package manager - `mcp[cli]` — installed automatically by uv on first run
- macOS Keychain / Windows Credential Manager / Linux Secret Service - `keyring` — installed automatically by uv on first run
- Personal Odoo API key (see Setup Instructions)
--- ---
@@ -111,8 +116,8 @@ Full install guide: [MPM Odoo Plugin — Install Guide](https://docs.google.com/
| Symptom | Fix | | Symptom | Fix |
|---|---| |---|---|
| MCP server won't start | Confirm `uv` is installed (`which uv`) | | MCP server won't start | Confirm `uv` is installed: `which uv` |
| "Credentials not configured" | Run `setup_odoo_credentials` | | "Credentials not configured" | Run `setup_odoo_credentials` |
| Tool errors on contacts or CRM | Ensure you have v0.1.2+ — earlier versions had field compatibility issues | | Authentication failed | Rotate Odoo API key; run `clear_odoo_credentials` then `setup_odoo_credentials` |
| Keychain prompt on first use | Normal — allow it, credentials are stored securely | | Keychain prompt on first use | Normal — allow it |
| Need to rotate key | Run `clear_odoo_credentials`, generate a new key in Odoo, then run `setup_odoo_credentials` again | | `cancel_sale_orders` refused | Check order state — only `draft`/`sent` allowed |