# ERPipe — MCP for Odoo

[![CI](https://github.com/erpipe-org/erpipe/actions/workflows/ci.yml/badge.svg)](https://github.com/erpipe-org/erpipe/actions/workflows/ci.yml)
[![npm @erpipe/core](https://img.shields.io/npm/v/@erpipe/core.svg)](https://www.npmjs.com/package/@erpipe/core)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
[![Hosted: free beta](https://img.shields.io/badge/hosted-free_beta-00a99d.svg)](https://erpipe.com/)
[![Hosted product](https://img.shields.io/badge/product-erpipe.com-e63973.svg)](https://erpipe.com/)

**ERPipe — hosted Odoo MCP gateway with human approval.** It is built by the maintainer of [`erpipe-org/mcp-odoo`](https://github.com/erpipe-org/mcp-odoo), formerly [`tuanle96/mcp-odoo`](https://github.com/tuanle96/mcp-odoo); the Python project remains the self-hosted server.

*Language: [English](README.md) · [日本語](README.ja.md)*

Open-source **TypeScript** building blocks for **remote MCP** access to [Odoo](https://www.odoo.com/).

| | |
|--|--|
| **This repo (MIT)** | Tool logic, transports, single-tenant self-host Worker example |
| **Hosted product** | Multi-tenant control plane + dashboard — [erpipe.com](https://erpipe.com/) (separate private repo). MCP endpoint: `https://mcp.erpipe.com/mcp` |

**Try it (real Odoo only):** [create a free beta workspace](https://erpipe.com/app/login), add one or more HTTPS Odoo instances, then connect ChatGPT, Codex CLI, Claude Code, Gemini CLI, Antigravity CLI, or Grok to the shared endpoint `https://mcp.erpipe.com/mcp`. Follow the [human setup recipe or copy a prompt for your AI agent](https://erpipe.com/docs/connector). There is no shared public sandbox.

## Why

- Talk to Odoo from ChatGPT, Codex CLI, Claude Code, Gemini CLI, Antigravity CLI, Grok, Cursor, and custom MCP agents over a stable URL shape
- Workers-safe XML-RPC + JSON-2 transports
- **Gated writes** (preview → approve → execute) with field policy
- Shared **27-tool + 7-prompt** core surface in `@erpipe/core` (D14 parity set of 23 plus `model_facts`, `read_attachment`, `render_report`, `get_current_context`). The hosted workspace adds multi-instance routing, lifecycle, webhook events, memory and approval controls. Use the dated [hosted catalog](https://erpipe.com/tools) for its current surface, and [docs/tools.md](docs/tools.md) for this repository.

## Status

| Milestone | State |
|-----------|--------|
| Hosted workspace `/mcp` contract | Implemented in the private cloud control plane |
| Self-host `/{slug}/mcp` example | Proven — see [SPIKE.md](SPIKE.md) |
| Core surface | **27 tools + 7 prompts + 5 resources** in `@erpipe/core` |
| Hosted surface | Current tool and prompt coverage: [hosted catalog](https://erpipe.com/tools), at `mcp.erpipe.com/mcp` |
| Pure parity harness | `npm run parity` — [PARITY.md](PARITY.md) |
| Live smoke (Odoo 16–20 Community) | `npm run smoke:live` — [SMOKE.md](SMOKE.md); Odoo 20 is a locally verified release candidate |

**Pins:**

| Package | Version |
|---------|---------|
| `agents` | `0.17.4` |
| `@cloudflare/workers-oauth-provider` | `0.8.2` |

## Packages

| Path | Name | Role |
|------|------|------|
| `packages/core` | `@erpipe/core` | Transports, tools, field policy — **no Workers imports** |
| `packages/xmlrpc` | `@erpipe/odoo-xmlrpc` | Fetch-based XML-RPC (Workers-safe) |
| `packages/worker-selfhost` | `@erpipe/worker-selfhost` | Single-tenant `McpAgent` + OAuth example |

## Requirements

- **Node.js ≥ 20** (CI uses 22 — [`.nvmrc`](.nvmrc))
- npm
- Optional: Cloudflare account for `deploy:selfhost`
- Optional: Odoo 16–20 Community for live smoke

The Odoo 20 candidate uses JSON-2 with a dedicated RPC API key. Local checks cover
reads, schema, aggregation, HR dates, attachments and gated writes, plus hosted
owner approval and the optional 20.0 Bridge. Enterprise, Odoo.sh, Odoo Online and
custom modules need separate qualification. PDF rendering requires the matching
Bridge; see [the tool limits](docs/tools.md#odoo-20-community-candidate).

## Install

```bash
npm install @erpipe/core @erpipe/odoo-xmlrpc
```

| Package | npm |
|---------|-----|
| `@erpipe/core` | [npmjs.com/package/@erpipe/core](https://www.npmjs.com/package/@erpipe/core) |
| `@erpipe/odoo-xmlrpc` | [npmjs.com/package/@erpipe/odoo-xmlrpc](https://www.npmjs.com/package/@erpipe/odoo-xmlrpc) |

Self-host Worker example stays in this monorepo only (`@erpipe/worker-selfhost` is private / not published).

### Develop from source

```bash
git clone https://github.com/erpipe-org/erpipe.git
cd erpipe
npm install
npm run build
npm run typecheck
npm test
```

## Quick start (self-host Worker)

```bash
npm run dev:selfhost
# Home: http://127.0.0.1:8787/
# MCP:  http://127.0.0.1:8787/default/mcp
```

Deploy:

```bash
# set secrets first — see packages/worker-selfhost/README.md
npm run deploy:selfhost
```

## Canonical MCP URLs

| Surface | URL shape | Notes |
|---------|-----------|--------|
| **Hosted product** | `https://erpipe.com/` | Dashboard and docs. MCP endpoint is separate (row below). |
| **Hosted MCP** | `https://mcp.erpipe.com/mcp` | One workspace OAuth app; Odoo-bound tools require an explicit `instance` key (`list_instances` to discover). |
| **Self-host example** | `https://<host>/{connection_slug}/mcp` | Single-tenant Worker demo in `@erpipe/worker-selfhost`. |

Hosted setup: [erpipe.com/docs/connector](https://erpipe.com/docs/connector) · compatibility: [erpipe.com/compatibility](https://erpipe.com/compatibility)

Reserved path segments (never use as a self-host connection id): `authorize`, `token`, `register`, `mcp`, `sse`, `.well-known`, `assets`, `health`, `app`, `admin`.

## Docs

| Doc | Topic |
|-----|--------|
| [docs/tools.md](docs/tools.md) | Full tool & prompt catalog |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup & PRs |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
| [CHANGELOG.md](CHANGELOG.md) | Releases |
| [SMOKE.md](SMOKE.md) | Live Odoo smoke |
| [PARITY.md](PARITY.md) | Python vs TS pure harness |
| [SPIKE.md](SPIKE.md) | Protocol contract notes |

## Architecture (high level)

```text
MCP client  ──OAuth + MCP──►  Worker (self-host or hosted)
                                  │
                                  ▼
                           @erpipe/core tools
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
             XmlRpcTransport              Json2Transport
                    │                           │
                    └──────────► Odoo ◄─────────┘
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Please read the [Code of Conduct](CODE_OF_CONDUCT.md).

## License

MIT — see [LICENSE](LICENSE).

"Odoo" is a trademark of Odoo S.A. ERPipe is not affiliated with Odoo S.A.