# odoo-agent-mcp

A **version-agnostic MCP server + code-comprehension engine** that gives AI agents
(Claude Code / Claude Desktop / Cursor / any MCP client) full command of *any* Odoo
app on *any* Odoo version — its data, its schema, its source code, and how the two
relate.

It answers, for developers and operations teams alike:

- *What data is in the DB, and how do model classes map to tables and columns?*
- *What code is where, how does the backend work, and how do modules inherit each other?*
- *Show me a flowchart of the system / a user flow.*
- *Where would a change break things? Help me implement a feature or fix a bug.*

---

## Why this exists (the two-domain problem)

Almost every existing Odoo AI tool covers only **Domain A — live data & metadata**
(reachable over Odoo's API). Very few touch **Domain B — the source code**
(what the backend actually is). Real developer/ops command needs *both*, and they
come from different places: Domain A from the running server, Domain B from the
repository. This project fuses them.

See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design and
[REUSE_MAP.md](REUSE_MAP.md) for how this relates to existing open-source Odoo MCP/LLM
projects.

---

## Capability tiers (graceful degradation)

The server probes each instance at connect time and advertises only the tools it can
honour, so one codebase serves a locked SaaS tenant and a self-hosted repo alike.

| Tier | Requires | Unlocks |
|------|----------|---------|
| **TIER_0** | API credentials only (works on locked Odoo Online) | Data CRUD, model/field metadata, **model↔table↔column mapping**, relationship graph |
| **TIER_1** | Companion module `odoo_agent_bridge` installed | Deep introspection endpoint, safe-method catalogue |
| **TIER_2** | Read access to the module source repo (self-hosted / Odoo.sh) | **Source AST analysis, `_inherit` graphs, flowcharts, source↔DB drift detection, feature/bug workflows** |

---

## Supported Odoo versions

Odoo **13 → 19+**. The ORM surface (`search`, `read`, `fields_get`, `execute_kw`,
`ir.model*`) is stable across these versions; only the wire protocol differs, and that
is isolated behind a transport adapter:

| Odoo version | Default transport |
|--------------|-------------------|
| 13 – 18 | XML-RPC (fallback: JSON-RPC) |
| 19+ | JSON-2 (`POST /json/2/<model>/<method>`, bearer API key) |

> XML-RPC / JSON-RPC endpoints are deprecated in Odoo 19 and scheduled for removal
> (SaaS ~19.1, on-prem/Odoo.sh ~20–22). JSON-2 is implemented now so the tool outlives
> that removal.

---

## Install

```bash
python -m venv .venv
# Windows PowerShell:  .venv\Scripts\Activate.ps1
# bash:                source .venv/bin/activate
pip install -e ".[dev]"
```

## Configure

Copy `.env.example` to `.env` and fill in:

```
ODOO_URL=https://my-instance.odoo.com
ODOO_DB=my_database
ODOO_USERNAME=admin
ODOO_API_KEY=xxxxxxxx        # API key (required for JSON-2 / Odoo 19+)
# ODOO_PASSWORD=...          # legacy auth for <=18 if no API key
ODOO_SOURCE_PATH=/path/to/addons   # optional -> unlocks TIER_2 code intel
```

## Run as an MCP server

```bash
odoo-agent-mcp                     # stdio transport (Claude Desktop / Code)
```

Register in an MCP client (e.g. Claude Code `.mcp.json`):

```json
{
  "mcpServers": {
    "odoo": { "command": "odoo-agent-mcp" }
  }
}
```

---

## Testing

```bash
pytest                       # unit tests — run anywhere, no Odoo needed
pytest -m e2e                # live end-to-end — REQUIRES the Docker matrix below
docker compose -f docker/docker-compose.yml up -d   # Odoo 15/17/19 + Postgres
```

> **Honest status:** unit tests (mapping engine, AST engine, transport factory, tier
> logic) run and pass in this environment. The live e2e suite needs a running Odoo; it
> is written and **skips automatically** when no server is reachable. See
> `tests/e2e/README.md`. TODO markers flag every path that is not yet live-verified.

---

## Status

`v0.1.0` — foundation: transport layer, tier detection, mapping engine,
code-comprehension engine, MCP wiring, companion-module skeleton, unit tests.
Roadmap in [ARCHITECTURE.md](ARCHITECTURE.md).