odoo-mpm-plugin/README.md

# odoo-mpm-plugin

MPM Odoo ERP plugin for Claude Cowork — connects to mpmedia.odoo.com via XML-RPC with proxy-aware transport.

**Version:** 0.4.0
**Author:** Message Point Media
**Repo:** https://git.mpm.to/mpm/odoo-mpm-plugin
**CoWork Project:** CW-003 — Odoo V19 MCP Bridge

---

## Overview

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, Project (full CRUD + milestones + subtasks + chatter + followers + stages), Helpdesk, Purchase, Inventory, Employees, eLearning, 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.

---

## Skills

| Skill | What It Does |
|---|---|
| `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", "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", "course", "training", "elearning", "lesson", "slide", "quiz", "enroll", "enrollment", "publish course", "create course", "add lesson" |

---

## Tools Reference

| Module | Tools |
|---|---|
| **Credentials** | `setup_odoo_credentials`, `clear_odoo_credentials` |
| **Products** | `search_products`, `get_product`, `get_product_stock` |
| **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` |
| **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`, `mark_crm_lead_lost`, `list_crm_lost_reasons` |
| **Project — Core** | `list_projects`, `get_project`, `search_tasks`, `get_task`, `create_task`, `update_task`, `list_task_stages` |
| **Project — CRUD** | `create_project`, `update_project`, `archive_project` |
| **Project — Milestones** | `list_milestones`, `create_milestone`, `update_milestone` |
| **Project — Task Chatter** | `post_task_message`, `get_task_messages` |
| **Project — Subtasks** | `get_task_subtasks`, `create_subtask` |
| **Project — Lifecycle** | `archive_task` |
| **Project — Followers** | `add_task_follower`, `remove_task_follower` |
| **Project — Stages** | `create_task_stage`, `update_task_stage` |
| **Helpdesk** | `search_helpdesk_tickets`, `get_helpdesk_ticket`, `create_helpdesk_ticket`, `update_helpdesk_ticket`, `list_helpdesk_teams` |
| **Purchase** | `search_purchase_orders`, `get_purchase_order` |
| **Inventory** | `search_inventory`, `get_stock_moves`, `list_internal_locations` |
| **Employees** | `search_employees`, `get_employee`, `list_departments` |
| **eLearning — Courses** | `search_courses`, `get_course`, `create_course`, `update_course`, `publish_course` |
| **eLearning — Slides** | `list_course_slides`, `get_slide`, `create_slide`, `update_slide`, `publish_slide`, `reorder_slides` |
| **eLearning — Quiz** | `get_quiz_questions`, `add_quiz_question`, `generate_quiz` |
| **eLearning — Enrollment** | `get_course_enrollment`, `enroll_in_course`, `bulk_enroll`, `send_course_invitation` |
| **eLearning — Media** | `set_course_cover`, `set_slide_cover`, `link_drive_document`, `add_course_resource` |
| **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
`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**


### Projects Module (v0.4.0)
15 new tools completing full project lifecycle management.

**Project CRUD:** Create projects with configurable visibility (`employees` / `portal` / `followers`), update metadata, archive/restore.

**Milestones:** Full CRUD on `project.milestone`. `update_milestone(is_reached=True)` marks complete; `list_milestones` filters to open by default.

**Task chatter:** `post_task_message` posts comments or internal notes to a task's chatter thread (`comment` vs `internal` message_type). `get_task_messages` returns the full message history.

**Subtasks:** `get_task_subtasks` returns all direct children of a task. `create_subtask` links a new task to a parent and inherits the parent's project if none specified.

**Followers:** `add_task_follower` / `remove_task_follower` accept either `partner_ids` or `user_ids` — user IDs are resolved to partner IDs automatically before calling `message_subscribe` / `message_unsubscribe`.

**Stage management:** `create_task_stage` creates a kanban column and links it to one or more projects. `update_task_stage` supports incremental `add_project_ids` / `remove_project_ids` without replacing the full association list.

---

### eLearning Module (v0.3.0)
22 tools across 5 groups for building and managing internal, reseller, and end-client courses.

**Slide types:** `pdf` (Drive link), `youtube_video`, `vimeo_video`, `infographic`, `webpage` (native HTML article)

**Google Drive policy:** All image and document operations use the Google Workspace MCP connector when available. The skill never asks the user to construct or copy Drive URLs unless the connector is absent.

**Audience tiers** via course settings:
- Internal employees: `visibility=members`, `enroll=invite`, `enroll_group_names=['Internal Users']`
- Resellers: `visibility=connected`, `enroll=public`
- End-clients: `visibility=public`, `enroll=public`

**Onboarding hook:** `enroll_in_course` and `bulk_enroll` are designed to be called by the project management plugin to automatically enroll new customers in courses on contract/onboarding events.

**Quiz generation:** Read course content → Claude generates questions → call `generate_quiz` to write all at once.

### 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.

### 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.

---

## Setup Instructions

Full install guide: [MPM Odoo Plugin — Install Guide](https://docs.google.com/document/d/1t0J_r6IT3OsK5W4hdklizshxmZ_yb4S7mNnRouud4BYxA/edit)

**Quick summary:**

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 — Mac/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`. Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`.
3. **Restart Claude Desktop** — Quit and relaunch. `uv` auto-installs Python dependencies (`keyring`) on first start.
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.
5. **Connect** — In CoWork, type "Set up my Odoo credentials". Claude will prompt for your Odoo login email and API key.
6. **Verify** — Ask Claude: "List my Odoo projects". A project list confirms full connectivity.

### Setup Checklist
- [ ] Plugin installed (URL or `.plugin` file)
- [ ] `uv` installed and in terminal PATH
- [ ] Claude restarted after install
- [ ] Odoo API key generated (No Limit expiration)
- [ ] `setup_odoo_credentials` completed
- [ ] "List my Odoo projects" returns data

---

## Connection Details

| Field | Value |
|---|---|
| Instance | mpmedia.odoo.com |
| Database | mpmedia-odoo-sh-main-13285275 |
| Transport | stdio via `uv` |
| Auth | Personal API key in OS keystore (`odoo-mpm` service) |
| MCP server name | `odoo-mpm` |

---

## Workflow Notes

- Before updating a task or ticket stage, call `list_task_stages` or `get_stage_ids` 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 HTML — use basic HTML formatting when creating or updating.
- Before calling `mark_crm_lead_lost`, call `list_crm_lost_reasons` to show the user available reasons.
- Before calling `cancel_sale_orders`, verify orders are in `draft` or `sent` state — the tool will reject anything else with a clear error.

---

## Requirements

- [uv](https://github.com/astral-sh/uv) — Python package and environment manager
- `mcp[cli]` — installed automatically by uv on first run
- `keyring` — installed automatically by uv on first run

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| MCP server won't start | Confirm `uv` is installed: `which uv` |
| "Credentials not configured" | Run `setup_odoo_credentials` |
| Authentication failed | Rotate Odoo API key; run `clear_odoo_credentials` then `setup_odoo_credentials` |
| Keychain prompt on first use | Normal — allow it |
| `cancel_sale_orders` refused | Check order state — only `draft`/`sent` allowed |