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.1.3
**Author:** Message Point Media
**Repo:** https://git.alwisp.com/jason/odoo-mpm-plugin
**CoWork Project:** CW-003 — Odoo V19 MCP Bridge

---

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

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 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" |

---

## 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` |
| **Contacts** | `search_contacts`, `get_contact`, `create_contact` |
| **Sales** | `search_sales_orders`, `get_sales_order`, `create_sales_order` |
| **CRM** | `search_crm_leads`, `get_crm_lead`, `create_crm_lead`, `update_crm_lead`, `list_crm_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` |
| **Purchase** | `search_purchase_orders`, `get_purchase_order` |
| **Inventory** | `search_inventory`, `get_stock_moves`, `list_internal_locations` |
| **Employees** | `search_employees`, `get_employee`, `list_departments` |
| **Utilities** | `odoo_search`, `odoo_get_record` |

### Knowledge Article Icon Support (v0.1.3)

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

Browse and copy emojis at: **https://emojipedia.org**

---

## 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.alwisp.com/jason/odoo-mpm-plugin`. Or install from the `.plugin` file (ask Bryan for current build).
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** — Dependencies download automatically on first launch (a few seconds).
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.
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

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

---

## Connection Details

| Field | Value |
|---|---|
| Instance | mpmedia.odoo.com |
| Database | mpmedia-odoo-sh-main-13285275 |
| Transport | XML-RPC (proxy-aware) |
| Auth | Personal API key via OS keystore |
| MCP server | `odoo-mpm` (runs via `uv`) |

---

## 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 `odoo_search` to confirm valid stage IDs.
- Knowledge article bodies are stored as 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.
- IDs returned from search tools can be passed directly to `get_*` tools for full details.

---

## Requirements

- Claude Desktop (Cowork mode)
- [`uv`](https://astral.sh/uv) — Python package manager
- macOS Keychain / Windows Credential Manager / Linux Secret Service
- Personal Odoo API key (see Setup Instructions)

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| MCP server won't start | Confirm `uv` is installed (`which uv`) |
| "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 |
| Keychain prompt on first use | Normal — allow it, credentials are stored securely |
| Need to rotate key | Run `clear_odoo_credentials`, generate a new key in Odoo, then run `setup_odoo_credentials` again |