dsh-odoo

English | 繁體中文 | 简体中文 | 日本語

dsh-odoo is a free, open-source, read-only DeepSeek Harness plugin for the Odoo external API. It lets an agent inspect Odoo business data — contacts, quotations, sales orders, invoices, project tasks, leads, stock — without changing Odoo state. One opt-in tool can create a strictly limited draft record, and it is not even registered unless you enable it.

✅ Verified against Odoo 18 on 2026-08-27 — the official odoo:18 image reporting server_version 18.0-20260817. Most compatibility assumptions were checked on a live server; the results, and what is still unverified, are in docs/live-verification.md: only Odoo 18 was tested (8–17 and 19 were not), and only a Docker image reached directly — behind a reverse proxy, Odoo Online and Odoo.sh remain untested. The plugin speaks JSON-RPC only and needs /jsonrpc to be reachable (see Transport). When something breaks, please report the Odoo version and serie, how it is deployed (Odoo Online, Odoo.sh, self-hosted, container, and which reverse proxy sits in front), and the full output of odoo_server_info.

Tools

Tool	Purpose
odoo_server_info	Read the server version and the authenticated user id.
odoo_describe_model	List the queryable fields of one allow-listed model.
odoo_search_read	Run a restricted search_read on one allow-listed model.
odoo_create_draft	Create one draft record. Requires allowWrite: true; otherwise it is never registered.

Transport

This plugin speaks JSON-RPC 2.0 to POST {baseUrl}/jsonrpc, so your Odoo server must expose that endpoint (it is provided by the web module). If the endpoint is missing, redirected, or intercepted by a proxy, every tool fails with a TRANSPORT_UNSUPPORTED error that says so. XML-RPC is not implemented.

Model availability

The 14 allow-listed models are not guaranteed to exist on every Odoo. Only the base models are always present; the rest come from business modules a stock Odoo does not install.

Module	Allow-listed models	Installed by default
base	res.partner, res.users, res.company	yes
product	product.product, product.template	no
sale / sale_management	sale.order, sale.order.line	no
purchase	purchase.order	no
account	account.move, account.move.line	no
project	project.project, project.task	no
crm	crm.lead	no
stock	stock.quant	no

On a stock Odoo 18 with no business modules, querying sale.order fails with ODOO_VALIDATION_ERROR carrying the upstream reason Object sale.order doesn't exist. Call odoo_describe_model first to confirm a model is available on your instance.

Requirements

• DeepSeek Harness with compatible @deepseek-ai/dsh-tools APIs
• Node.js 22.19 or newer in the 22.x line, or Node.js 24 or newer
• Bun 1.3.5 or newer when installing from GitHub source or developing locally
• An Odoo URL, database name, login, and API key (or password) with access to the models you query

Configuration

Environment variables are recommended so credentials do not appear in a profile patch:

export ODOO_URL='https://odoo.example.com'
export ODOO_DB='production'
export ODOO_USERNAME='integration@example.com'
export ODOO_API_KEY='your-api-key'

Plugin config takes precedence over environment variables:

Config	Environment fallback	Default
baseUrl	ODOO_URL	required
db	ODOO_DB	required
username	ODOO_USERNAME	required
apiKey	ODOO_API_KEY	required
companyId	ODOO_COMPANY_ID	unset
allowWrite	none (deliberately)	false
locale	none	en (en / zh-TW / zh-CN / ja)
defaultLimit	none	20 (1–100)
requestTimeoutMs	none	30000 (1–300000)
maxResponseBytes	none	1000000 (1–52428800)

Credentials are only required when a tool actually runs: installing the plugin without filling them in does not break profile loading. locale switches tool and parameter descriptions; tool names and error messages always stay in English.

Safety

• Read-only by default. No write, unlink, or workflow actions exist in this release.
• Model allow list. Queries are limited to 14 standard models: res.partner, res.users, res.company, product.product, product.template, sale.order, sale.order.line, purchase.order, account.move, account.move.line, project.project, project.task, crm.lead, stock.quant.
• No relational traversal. Domain field names may not contain dots. To filter by a related record, query the related model first and then filter with ('partner_id','in',[ids]). This keeps the allow list an actual capability boundary instead of a suggestion.
• No binary fields. Fields whose Odoo type is binary are rejected, and default field sets never include one.
• Bounded responses. Default fields per model, limit ≤ 100, offset + limit ≤ 10000, single string values truncated at 2000 characters, and a hard byte cap on every response.
• Only non-archived records are returned; the active_test context is not exposed.
• Draft creation is opt-in and fixed. sale.order is always created with state=draft; project.task may not specify state or stage_id, so Odoo applies its own default stage. Only an allow-listed subset of fields is accepted, and one-to-many commands are rejected.

Non-goals for 0.1

• No business wrapper tools (list_customers, list_quotations, …). They depend on field assumptions that cannot be verified without a live Odoo, and a wrong assumption returns an empty result instead of an error — the worst failure mode for an agent. Deferred to 0.2.
• No updates, deletions, or workflow transitions; no attachments or report generation.
• No XML-RPC transport, no model discovery, no multi-database switching, no cursor pagination.

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build

scripts/smoke-odoo.sh runs a manual end-to-end check against a real server; it is deliberately excluded from CI.

License

MIT