@mfdaves/okf-odoo 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,36 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@mfdaves/okf-odoo`. The format follows Keep a Changelog; versions follow SemVer.
4
+
5
+ ## 0.1.0 — 2026-11-15
6
+
7
+ First release: a Producer API v1 producer that reads Odoo 18, 19 and 20 metadata over the JSON-2 API or JSON-RPC and returns an OKF v0.2 bundle to a host such as `okf-mcp`.
8
+
9
+ ### Added
10
+
11
+ - JSON-2 client limited to `fields_get`, `read` and `search_read` with explicit field lists, bearer API key over `https` (plain `http` only for a loopback host), optional `X-Odoo-Database`, timeouts, paging by id, a 32 MiB response limit enforced while the body streams, and fixed error codes (`invalid_api_key`, `access_denied`, `model_not_found`, `json2_unavailable`, `invalid_request`, `server_error`, `timeout`, `aborted`, `connection_failed`).
12
+ - JSON-RPC client for Odoo 18 (`api: jsonrpc`): `execute_kw` on `/jsonrpc` with the database, the user id resolved once through `authenticate` with the new `login` key, and the API key as password; the same allowlist, refusals, http rule, size limit and abort handling as JSON-2, with errors mapped by exception name only (`jsonrpc_unavailable` when the endpoint is missing). A redirect to the login page reads as a missing endpoint.
13
+ - Version detection from the installed version of `base`, with one field allowlist per supported version (18, 19, 20) and `unsupported_odoo_version` otherwise.
14
+ - Catalog reader for installed modules and dependencies, models, fields and selection values, access entries (`ir.access` on Odoo 20, `ir.model.access` and `ir.rule` on Odoo 18 and 19, one shape), groups, menus and window actions, scheduled jobs, reports and server actions, with one field allowlist per Odoo model.
15
+ - Producer configuration with a required `apiKeyEnv`, because the host hands a producer only the secrets its configuration names.
16
+ - `sections` to select what is read; a section the key cannot read fails with `access_denied` and the section name.
17
+ - `modules.include` / `modules.exclude` and `otherModules: summary | none`.
18
+ - One escaping module for every string read from Odoo, with explicit contexts (inline text, line-start text, code span with a delimiter longer than any backtick run, table cell, link text), checked against a hostile corpus with okf-mcp's parser.
19
+ - Renderer for `index.md`, `modules/`, `models/`, `groups/` and `apps/` concepts with the relation types `defined_in`, `extended_by`, `references`, `depends_on`, `implies` and `opens`; deterministic output so an unchanged database republishes nothing, and file names that stay distinct on case-insensitive file systems and never take the reserved `index.md` or `log.md`.
20
+ - Tests on responses recorded from Odoo 18, 19 and 20, a mock smoke through okf-mcp's producer host, and live gates (`live:shape`, `live:smoke`) against a disposable Odoo in Docker.
21
+ - Experimental tool pack `okfToolPack` (okf-mcp tool-pack API v1) with `odoo_find_models`, `odoo_describe_model`, `odoo_search`, `odoo_read` and `odoo_group`: read-only calls to the `o3p_mcp` data API in Odoo as the resource server, with the signed-in user's token as the subject, strict input schemas, bounded error codes and the same transport hardening as the producer client.
22
+ - Model concepts render one2many and many2many fields as "not stored (no column)" instead of "stored", and mark fields "not searchable" (neither stored nor searchable through a method, read from `ir.model.fields.selectable`) or "not groupable" where the metadata shows it; fixtures re-recorded on Odoo 18, 19 and 20 for the new field.
23
+ - Tool errors forward the data API's `details` (`field`, `reason`, `hint`, single-line, at most 200 characters) for every operation; `odoo_find_models` takes `offset` and reports `total` and `truncated`; `odoo_describe_model`'s output schema lists `stored`, `searchable`, `sortable` and `groupable`, and the descriptions tell the agent to filter, sort and group only on fields marked so and to look for a public counterpart when a model is denied.
24
+ - `odoo_search`, `odoo_read`, `odoo_group` and `odoo_sql` remind the agent that results follow the signed-in user's Odoo access while knowledge written from them is readable by every MCP user, so it should record conclusions and aggregates rather than personal or confidential values.
25
+ - Domains in the tool pack no longer accept `child_of` and `parent_of`, which the data API refuses; descriptions say that text conditions on a relation match the related record's display name and that models hiding part of a record may refuse filters on non-public fields.
26
+ - `odoo_sql` (scope `odoo.sql`): one read-only SQL statement through the data API's `sql` operation, limit 1–1000 (default 100), with an output schema for columns, rows, truncation, elapsed time and copied tables; `query_error` passes PostgreSQL's `sqlstate`, `position` and `message` (at most 500 characters) on in `details`; new codes `too_many_requests` and `unavailable`. `odoo_describe_model` documents the model's `table` when the server returns it.
27
+ - Tool pack tools declare `requiresSubjectToken: true`; argument errors carry the offending parameter in `details` (`field`, `path`); the default per-call timeout is 25 s, below okf-mcp's 30 s.
28
+ - The tool pack's schemas follow the data API's limits: aggregates `sum`, `avg`, `min`, `max`, `count`, `count_distinct` and `__count` only, field paths of at most 4 fields, plain field names in search orders; descriptions state the group value formats and that `odoo_read` silently leaves out missing or unreadable ids.
29
+ - A call the data API refuses with `too_many_requests` (the user's SQL slots or the sandbox's connections all taken) waits and is sent again, after 250 ms, 500 ms, then every second, for up to 12 s and never past the point that leaves the last attempt 5 s of the call's `timeoutMs`; the wait happens in the host and holds no Odoo worker. A refusal that outlasts it carries a hint to send the queries one after another, and `odoo_sql`'s description says so.
30
+
31
+ ### Known issues
32
+
33
+ - Odoo 18 and 19 do not record the groups of fields defined in code (`ir.model.fields.groups` stays empty), so on those versions model concepts state that field groups are not available.
34
+ - Odoo 18 does not record which models are abstract; their kind reads "model or abstract model".
35
+ - The tool pack targets okf-mcp's tool-pack API v1, which is experimental; its shape may still change.
36
+ - `okf-mcp` reports every producer exception as `producer_execution_failed`, so the `access_denied` code and section reach the user only when `generate()` is called directly.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 OKF contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,368 @@
1
- # Temporary Holding Version
1
+ # okf-odoo
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `okf-odoo` reads the technical metadata of an Odoo 18, 19 or 20 database
4
+ over Odoo's JSON-2 API (Odoo 19 and later) or JSON-RPC (Odoo 18) and
5
+ produces an Open Knowledge Format v0.2 bundle with explicit generation
6
+ provenance.
7
+
8
+ It documents installed modules and their dependencies, models with their
9
+ fields and selection values, access rights and record rules, groups and the
10
+ groups they imply, top-level menus down to the models their window actions
11
+ open, scheduled jobs, reports and, on request, server actions. It never reads
12
+ business records, system parameter values or server-action code, and never
13
+ calls a method that writes.
14
+
15
+ The package is a Producer API v1 producer. It has no command line of its
16
+ own: a host such as [`okf-mcp`](https://github.com/mfdaves/okf-mcp) loads it,
17
+ validates the candidate bundle and publishes it through
18
+ `okf producer preview` and `okf producer run`.
19
+
20
+ It also ships an experimental tool pack with read-only tools for live Odoo
21
+ records ([Odoo data tools](#odoo-data-tools-experimental)). Those never touch
22
+ the metadata reader: they ask an Odoo addon to run each query as the
23
+ signed-in user.
24
+
25
+ ## Requirements
26
+
27
+ - Node.js 22 or newer and `@mfdaves/okf-mcp` 0.13.0-rc.1 or newer
28
+ (Producer API v1 and, for the data tools, tool-pack API v1), published
29
+ under npm's `next` tag.
30
+ - Odoo 18, 19 or 20. On 19 and 20 the producer uses the JSON-2 endpoint
31
+ `/json/2/<model>/<method>` from the `rpc` module, which Odoo installs
32
+ automatically. Odoo 18 has no JSON-2 API; set `api: jsonrpc` and the
33
+ producer calls `execute_kw` on `/jsonrpc` with the user's login, resolved
34
+ once per run, and the API key as password. The protocol is configured,
35
+ never guessed.
36
+ - An Odoo API key (as the user interface creates them, or with the `rpc`
37
+ scope) of a user allowed to read the selected sections.
38
+
39
+ ## API key and access rights
40
+
41
+ What a key can read depends on its user's groups. Group names shown in the
42
+ tables are resolved through `res.groups` and `ir.model.data`, so every
43
+ section that shows groups reads those too. Every run also reads the installed
44
+ version of `base`, which any internal user can, to pick the field names of
45
+ that Odoo version. Measured on Odoo 18, 19 and 20:
46
+
47
+ | Section | Odoo models read | Lowest group that can read it |
48
+ | --- | --- | --- |
49
+ | `modules` | `ir.module.module`, `ir.module.module.dependency` | Internal user (Settings on Odoo 18, where only administrators read module dependencies) |
50
+ | `models` | `ir.model`, `ir.model.data`, `ir.model.fields`, `ir.model.fields.selection`, `res.groups` | Administration: Access Rights |
51
+ | `access` | `ir.access` (Odoo 20) or `ir.model.access` and `ir.rule` (Odoo 18 and 19), `res.groups`, `ir.model.data` | Administration: Access Rights |
52
+ | `groups` | `res.groups`, `ir.model.data` | Administration: Access Rights |
53
+ | `reports` | `ir.actions.report`, `res.groups`, `ir.model.data` | Administration: Access Rights |
54
+ | `menus` | `ir.ui.menu`, `ir.actions.act_window`, `res.groups`, `ir.model.data` | Administration: Settings |
55
+ | `crons` | `ir.cron` | Administration: Settings |
56
+ | `serverActions` | `ir.actions.server` (name, model, type, binding, groups), `res.groups`, `ir.model.data` | Administration: Settings |
57
+
58
+ The default sections include `menus` and `crons`, so the full catalog needs
59
+ the API key of a Settings administrator. Use a dedicated technical user for
60
+ it rather than a person's account:
61
+
62
+ 1. Create an internal user, for example `okf-reader`, and give it
63
+ *Administration: Settings*.
64
+ 2. Sign in as that user and create an API key from the user's preferences
65
+ (*Account Security*). A Settings administrator may choose a key without
66
+ an expiry date.
67
+ 3. Put the key in an environment variable of the process that runs the host.
68
+ Configuration names the variable, never the key.
69
+
70
+ A key whose user cannot read a selected section fails the run with
71
+ `access_denied` and the section's name. The producer never drops a section
72
+ silently; remove the section from `sections` to publish without it.
73
+
74
+ ## Install
75
+
76
+ Install the producer next to the host in the project that owns the bundle:
77
+
78
+ ```bash
79
+ npm install @mfdaves/okf-mcp@next @mfdaves/okf-odoo
80
+ ```
81
+
82
+ ## Configure
83
+
84
+ Declare the bundle, the relation types the producer emits, and the producer
85
+ in `okf.project.yaml`:
86
+
87
+ ```yaml
88
+ project: Odoo catalog
89
+ bundles:
90
+ - id: odoo
91
+ root: okf/odoo
92
+ relationTypes:
93
+ - defined_in
94
+ - extended_by
95
+ - references
96
+ - implies
97
+ - opens
98
+ producers:
99
+ - name: odoo
100
+ type: odoo
101
+ package: "@mfdaves/okf-odoo"
102
+ bundle: odoo
103
+ config:
104
+ url: https://odoo.example.com
105
+ database: production
106
+ apiKeyEnv: ODOO_API_KEY # on Odoo 18 add: api: jsonrpc, login: okf-reader
107
+ source: odoo-production
108
+ modules:
109
+ include: ["x_*"]
110
+ ```
111
+
112
+ `depends_on`, the sixth relation type the producer emits, is built into
113
+ `okf-mcp`.
114
+
115
+ | Key | Default | Meaning |
116
+ | --- | --- | --- |
117
+ | `url` | required | Base URL of the Odoo server without credentials, query or fragment. It must use `https`, except for a loopback host (`localhost`, `127.0.0.0/8`, `[::1]`), because the API key travels as a bearer token. |
118
+ | `api` | `json2` | `json2` for Odoo 19 and 20, `jsonrpc` for Odoo 18 (JSON-RPC also works on 19 and 20). |
119
+ | `database` | none; required with `jsonrpc` | With `json2`, sent as the `X-Odoo-Database` header and needed when the server hosts several databases; with `jsonrpc`, the database of every call. |
120
+ | `login` | required with `jsonrpc`, refused with `json2` | Login of the API key's user, used once per run to resolve its user id. |
121
+ | `apiKeyEnv` | required | Name of the environment variable that holds the API key. The host hands a producer only the variables its configuration names. |
122
+ | `source` | `odoo` | Stable, non-secret alias used in `odoo://` resource locators and in the index title. |
123
+ | `lang` | `en_US` | Language of labels, help texts and menu names. |
124
+ | `sections` | all but `serverActions` | Which parts of the catalog to read: `modules`, `models`, `access`, `groups`, `menus`, `crons`, `reports`, `serverActions`. `access`, `crons`, `reports` and `serverActions` are tables on model concepts and require `models`. |
125
+ | `modules.include` | every installed module | Module names to document in full; `*` matches any characters. |
126
+ | `modules.exclude` | none | Module names never documented, applied after `include`. |
127
+ | `otherModules` | `summary` | What happens to installed modules that `modules.include` does not select: `summary` renders a module concept without their own models, `none` leaves them out. |
128
+
129
+ A model is documented when one of the modules that define or extend it is
130
+ selected. Models created in the database, which belong to no module, are
131
+ documented only when `modules.include` is not set. Odoo cannot tell standard
132
+ modules from custom ones (manifest authors vary), so the selection is always
133
+ by name.
134
+
135
+ ## Run
136
+
137
+ ```bash
138
+ export ODOO_API_KEY=…
139
+ okf --project okf.project.yaml producer preview odoo
140
+ okf --project okf.project.yaml producer run odoo --write --actor process:odoo-refresh
141
+ ```
142
+
143
+ `preview` reads the catalog and reports the publication diff without writing.
144
+ `run` publishes it. The host compares each file with the published one
145
+ ignoring `generated.at`, so a database whose metadata did not change reports
146
+ every file `unchanged`. The receipt's `summary` counts modules, models,
147
+ fields, access entries, groups, applications, scheduled jobs, reports, server
148
+ actions and files.
149
+
150
+ `okf-mcp` reports any exception from a producer as `producer_execution_failed`.
151
+ The specific code (`access_denied` with its `section`, `invalid_api_key`,
152
+ `model_not_found`, `json2_unavailable`, `jsonrpc_unavailable`,
153
+ `unsupported_odoo_version`, `timeout`, `connection_failed`) is on the error
154
+ `generate()` throws when it is called directly. Pointing `api: json2` at
155
+ Odoo 18 reports `json2_unavailable`.
156
+
157
+ ## Output
158
+
159
+ ```text
160
+ index.md links to every concept below
161
+ modules/<name>.md installed version (and the version on disk when it differs), category,
162
+ dependencies, models defined and extended
163
+ models/<model>.md fields, selection values, access, scheduled jobs, reports, server actions
164
+ groups/<xmlid>.md implied groups, groups implying it, access on documented models
165
+ apps/<xmlid>.md a top-level menu, its submenus and the models they open
166
+ .okf-producer.json written by the host: owned paths and digests
167
+ ```
168
+
169
+ The properties column of a field table marks one2many and many2many fields
170
+ as "not stored (no column)", although Odoo reflects them as stored, and adds
171
+ "not searchable" for a field that is neither stored nor has a search method
172
+ (`ir.model.fields.selectable`) and "not groupable" for a one2many or a field
173
+ that is neither stored nor related. These hints follow from the metadata;
174
+ on Odoo 20 a field computed in SQL may still be searched and grouped, and
175
+ the data tools' `odoo_describe_model` reports the exact flags for a user.
176
+
177
+ Field-level groups come from `ir.model.fields.groups`. Odoo 20 records them
178
+ for every field; Odoo 18 and 19 leave them empty for fields defined in code,
179
+ so on those versions each model concept states that field groups are not
180
+ available instead of showing every field as unrestricted. Odoo 18 does not
181
+ record which models are abstract, so their kind reads "model or abstract
182
+ model", and it groups access groups by application category, shown as
183
+ *Application* where 19 and 20 show the *Privilege*.
184
+
185
+ Groups and menus created in the database have no XML id and are named
186
+ `group-<id>` and `menu-<id>`. A name made of anything but lowercase letters,
187
+ digits, `_`, `.` and `-` gets a short hash appended to its file name, so two
188
+ names that differ only by case stay apart on case-insensitive file systems.
189
+ The same applies to `index` and `log`, whose file names OKF reserves. Typed relations: a model is `defined_in` the
190
+ module that registered it first and `extended_by` the others, and
191
+ `references` the models its relational fields point to; a module
192
+ `depends_on` its dependencies; a group `implies` other groups; an application
193
+ `opens` the models of its window actions. A relation or link is emitted only
194
+ when its target is part of the bundle.
195
+
196
+ Every concept carries `generated.by` (`okf-odoo/<version>`) and
197
+ `generated.at`, a `resource` such as `odoo://<source>/sale.order`, and
198
+ `sources` naming the Odoo models the metadata was read from. The server
199
+ address, database name and API key never appear in the output.
200
+
201
+ ## Producer API
202
+
203
+ ```js
204
+ const { okfProducer } = require("@mfdaves/okf-odoo");
205
+
206
+ const result = await okfProducer.generate({
207
+ bundleId: "odoo",
208
+ generatedAt: new Date().toISOString(),
209
+ config: { url: "https://odoo.example.com", apiKeyEnv: "ODOO_API_KEY" },
210
+ getSecret: (name) => process.env[name],
211
+ });
212
+ ```
213
+
214
+ The descriptor declares API version 1, OKF version 0.2, id `odoo` and its
215
+ relation types. `validateConfig()` returns the normalised configuration and
216
+ one diagnostic per invalid key. `generate()` returns sorted
217
+ `{ path, content }` files and the numeric summary; it writes nothing.
218
+ `readCatalog()`, `buildBundle()` and `createOdooClient()` are exported for
219
+ reuse.
220
+
221
+ ## Odoo data tools (experimental)
222
+
223
+ `okfToolPack` gives an MCP host such as `okf-mcp` (tool-pack API v1, which is
224
+ experimental and may still change) six read-only tools for live records:
225
+
226
+ | Tool | Data API operation | Purpose |
227
+ | --- | --- | --- |
228
+ | `odoo_find_models` | `models` | Find models the signed-in user may read, by name or label, paged with `offset` (`total`, `truncated`) |
229
+ | `odoo_describe_model` | `describe` | The fields of a model as that user sees them, with whether each is stored, searchable, sortable and groupable |
230
+ | `odoo_search` | `search` | Records matching a domain, with the requested fields (at most 200 per call) |
231
+ | `odoo_read` | `read` | Records by id (at most 100) |
232
+ | `odoo_group` | `group` | Grouped totals such as `amount_total:sum` and `__count` (at most 500 groups) |
233
+ | `odoo_sql` | `sql` | One read-only `SELECT`, `VALUES` or `TABLE` statement on the database tables, over only the rows and fields the user may read (at most 1000 rows; default 100) |
234
+
235
+ Each tool requires the `odoo.read` scope, `odoo_sql` the `odoo.sql` scope. The tools do not read Odoo
236
+ directly: every call is a `POST {url}/o3p_mcp/api/v1/{op}` to the data API of
237
+ the `o3p_mcp` Odoo addon, authenticated with the MCP server's
238
+ resource-server client credentials (HTTP Basic) and carrying the signed-in
239
+ user's access token as the subject. The addon checks the token and runs the
240
+ query as that user, so Odoo's access rights, record rules and the addon's
241
+ denylist decide what comes back. The tools therefore work only when the host
242
+ serves MCP over HTTP with users signing in through Odoo; without a subject
243
+ token they fail with `subject_token_required`.
244
+
245
+ ```yaml
246
+ toolPacks:
247
+ - package: "@mfdaves/okf-odoo"
248
+ config:
249
+ url: https://odoo.example.com
250
+ clientIdEnv: O3P_MCP_CLIENT_ID
251
+ clientSecretEnv: O3P_MCP_CLIENT_SECRET
252
+ ```
253
+
254
+ | Key | Default | Meaning |
255
+ | --- | --- | --- |
256
+ | `url` | required | Base URL of the Odoo server; `https`, or `http` for a loopback host only. |
257
+ | `clientIdEnv` | required | Environment variable holding the resource-server client id. |
258
+ | `clientSecretEnv` | required | Environment variable holding the resource-server client secret. |
259
+ | `timeoutMs` | `25000` | Time limit per call, including any wait for a busy server, 1000 to 120000 ms. Keep it below the host's own limit (okf-mcp: the `timeoutMs` of the `toolPacks` entry, 30 s by default), or the host answers `tool_pack_timeout` before the pack can report `timeout`. |
260
+
261
+ When the data API explains a refusal, the tool error's `details` carry its
262
+ `field`, `reason` and `hint` (schema names and fixed texts, each at most 200
263
+ characters, dropped if they hold the token or a credential), so an agent can
264
+ correct its call; `odoo_sql`'s `query_error` adds PostgreSQL's answer.
265
+
266
+ A call refused with `too_many_requests` (all of the user's SQL slots, or all
267
+ of the sandbox's connections, are taken by running queries) is not failed at
268
+ once: the pack waits 250 ms, 500 ms, then one second between attempts and
269
+ sends it again, for up to 12 s and only while the last attempt keeps at least
270
+ 5 s of `timeoutMs`. Agents that send several queries at once get them run one
271
+ after another. A refusal that lasts longer reaches the agent with a hint to
272
+ send its queries one after another.
273
+
274
+ Every tool declares `requiresSubjectToken: true`, so the host lists it only
275
+ where a signed-in user's token exists. Arguments are checked against each
276
+ tool's input schema before any request; an `invalid_arguments` error carries
277
+ `details.field` (the offending parameter) and `details.path` so an agent can
278
+ correct its call.
279
+
280
+ `odoo_sql` returns `{ columns: [{ name, type }], rows, truncated, elapsedMs,
281
+ tables: [{ name, model, rows }] }`: numbers for numeric columns, ISO 8601
282
+ strings for dates and times, seconds for intervals, `\x…` hexadecimal for
283
+ `bytea`. The Odoo addon copies only the readable rows and the named columns
284
+ of the tables a query names into a separate sandbox and runs the query
285
+ there, so its errors cannot reveal anything else: a `query_error` from
286
+ `odoo_sql` carries PostgreSQL's answer in `details` (`sqlstate`, 1-based
287
+ `position`, `message` of at most 500 characters; `0A000` for a statement
288
+ other than one `SELECT`, `42601` for a syntax error, `42P01` for a table
289
+ that is unknown, hidden or not readable alike). A message that contains the
290
+ token or a credential is dropped. The description tells an agent to name
291
+ columns rather than `SELECT *` and to take table and column names from the
292
+ `odoo` knowledge bundle or `odoo_describe_model`.
293
+
294
+ Errors are bounded codes with fixed messages: the data API's own
295
+ (`invalid_params`, `invalid_client`, `invalid_token`, `insufficient_scope`,
296
+ `access_denied`, `unknown_op`, `unknown_model`, `result_too_large`,
297
+ `query_error`, `timeout`, and for `odoo_sql` `too_many_requests` and
298
+ `unavailable`) and the connector's (`invalid_arguments`,
299
+ `subject_token_required`, `client_credentials_unavailable`, `invalid_config`,
300
+ `data_api_unavailable`, `connection_failed`, `invalid_response`, `aborted`,
301
+ `server_error`). Odoo's error text, the user's token and the client
302
+ credentials never appear in a result or an error. The tool descriptions ask
303
+ an agent to consult the generated `odoo` knowledge bundle, or
304
+ `odoo_describe_model`, before it searches.
305
+
306
+ ## Security boundary
307
+
308
+ - Only `fields_get`, `read` and `search_read` can be called, each read names
309
+ its fields, and `ir.config_parameter` is refused by the client.
310
+ - Every field requested is listed in one allowlist per Odoo model
311
+ (`FIELDS` in `src/catalog.js`); record counts, scheduling timestamps,
312
+ server-action code and webhook URLs are not in it.
313
+ - Text read from Odoo is written through one escaping module
314
+ (`src/markdown.js`) with a context per position: inline text, line-start
315
+ text, code span, table cell and link text. Labels, help texts, domains and
316
+ names therefore read back as the same text and cannot add links, images,
317
+ HTML, headings, lists, fences or table columns.
318
+ - Error messages carry a fixed text per code, never the server's response.
319
+ - Responses are read as a stream and abandoned once they pass 32 MiB.
320
+ - The API key is read from the environment variable the host hands over and
321
+ is never rendered.
322
+
323
+ ## Development
324
+
325
+ ```bash
326
+ npm install
327
+ npm test
328
+ npm run lint
329
+ npm run format:check
330
+ npm run smoke
331
+ npm run self:validate
332
+ npm run pack:check
333
+ ```
334
+
335
+ The unit tests replay responses recorded from Odoo 18 (JSON-RPC), 19 and 20
336
+ (JSON-2) with
337
+ `base` and `sale` installed (`test/fixtures/odoo-<version>/calls.json`) and
338
+ compare the result with committed snapshots; `UPDATE_SNAPSHOTS=1 npm test`
339
+ rewrites them. `npm run smoke` and `npm run self:validate` need the sibling
340
+ `../okf-mcp` checkout; the smoke publishes the recordings through okf-mcp's
341
+ producer host and checks that a second run is unchanged.
342
+
343
+ The live gates run against a disposable Odoo in Docker (ports 18068 for 18,
344
+ 18069 for 19 and 18070 for 20). The script prints the protocol, the logins
345
+ and the API keys of two technical users:
346
+
347
+ ```bash
348
+ scripts/live-odoo.sh up 19 > odoo.env # holds the API keys; ignored by Git
349
+ set -a; . ./odoo.env; set +a
350
+ OKF_ODOO_LIVE_TEST=1 npm run live:shape
351
+ OKF_ODOO_LIVE_TEST=1 npm run live:smoke
352
+ npm run live:record # re-record test/fixtures/odoo-19
353
+ scripts/live-odoo.sh down
354
+ ```
355
+
356
+ `live:shape` compares the server's field types, requests and row shapes with
357
+ the recorded fixture. `live:smoke` publishes through `okf producer preview`
358
+ and `run` with the package linked into a project, checks the second run is
359
+ unchanged, and reads each section with the key of an Access Rights manager,
360
+ expecting exactly the denials of the table above.
361
+
362
+ ## Release
363
+
364
+ Releases are published by the Release workflow from a dispatched tag with
365
+ npm provenance, through the trusted publisher configured on npm. npm cannot
366
+ configure a trusted publisher for a package that does not exist yet, so the
367
+ first version is published once by hand (`npm publish --access public`) and
368
+ the trusted publisher is configured afterwards.
@@ -0,0 +1,11 @@
1
+ ---
2
+ okf_version: "0.2"
3
+ ---
4
+
5
+ # okf-odoo reference
6
+
7
+ - [Product overview](overview/okf-odoo.md)
8
+ - [Configuration](reference/configuration.md)
9
+ - [Access rights per section](reference/access-rights.md)
10
+ - [Generated bundle](reference/output.md)
11
+ - [Odoo data tools](reference/data-tools.md)
@@ -0,0 +1,51 @@
1
+ ---
2
+ id: okf://okf-odoo/overview/okf-odoo
3
+ type: OKF Product
4
+ title: okf-odoo
5
+ description: Read-only Odoo metadata producer for deterministic Open Knowledge Format bundles.
6
+ tags: [okf, odoo, producer, metadata]
7
+ relations:
8
+ - type: configured_by
9
+ target: repo://src/odoo.js
10
+ - type: configured_by
11
+ target: repo://src/catalog.js
12
+ - type: configured_by
13
+ target: repo://src/render.js
14
+ - type: configured_by
15
+ target: repo://src/producer.js
16
+ - type: checked_by
17
+ target: repo://test/catalog.test.js
18
+ - type: checked_by
19
+ target: repo://test/render.test.js
20
+ - type: checked_by
21
+ target: repo://test/live-shape.test.js
22
+ - type: related_to
23
+ target: okf://okf-odoo/reference/configuration
24
+ - type: related_to
25
+ target: okf://okf-odoo/reference/access-rights
26
+ - type: related_to
27
+ target: okf://okf-odoo/reference/output
28
+ ---
29
+
30
+ # okf-odoo
31
+
32
+ `okf-odoo` reads the technical catalog of an Odoo 18, 19 or 20 database over
33
+ the JSON-2 API or, for Odoo 18, JSON-RPC: installed modules, models, fields and selection values, access
34
+ rights and record rules, groups, menus and the models they open, scheduled
35
+ jobs, reports and, on request, server actions. It never reads business
36
+ records, system parameter values or server-action code, and only calls
37
+ `fields_get`, `read` and `search_read` with an explicit field list.
38
+
39
+ The package is a Producer API v1 producer without a command line. A host such
40
+ as `okf-mcp` loads it by its package name, hands it the API key from an
41
+ environment variable, validates the candidate files and publishes them. The
42
+ JSON-2 client, the catalog reader, the renderer and the producer descriptor
43
+ are separate modules.
44
+
45
+ Version differences are handled in the catalog reader, which reads the
46
+ installed version of `base` and uses that version's field names: Odoo 18
47
+ groups access groups by application category and records neither abstract
48
+ models nor the kind of translation, and Odoo 20 merges access
49
+ rights and record rules into `ir.access`, and stores the index kind of a field
50
+ where Odoo 19 stores a boolean. The rendered output is a pure function of the
51
+ catalog, so an unchanged database republishes no file.
@@ -0,0 +1,33 @@
1
+ ---
2
+ id: okf://okf-odoo/reference/access-rights
3
+ type: OKF Reference
4
+ title: okf-odoo access rights per section
5
+ description: The Odoo group a key's user needs to read each okf-odoo section, measured on Odoo 18, 19 and 20.
6
+ tags: [okf, odoo, security]
7
+ relations:
8
+ - type: configured_by
9
+ target: repo://src/catalog.js
10
+ - type: checked_by
11
+ target: repo://scripts/live-smoke.js
12
+ ---
13
+
14
+ # Access rights per section
15
+
16
+ Measured on Odoo 18, 19 and 20 with `base` and `sale` installed. Group names
17
+ are resolved through `res.groups` and `ir.model.data`, so every section that
18
+ shows groups needs Access Rights at least.
19
+
20
+ - Internal user: `modules` (`ir.module.module`,
21
+ `ir.module.module.dependency`); on Odoo 18 the dependencies need Settings.
22
+ Every run also reads the version of `base`, which any internal user can.
23
+ - Administration: Access Rights: `models` (`ir.model`, `ir.model.data`,
24
+ `ir.model.fields`, `ir.model.fields.selection`), `access` (`ir.access`, or
25
+ `ir.model.access` and `ir.rule` on Odoo 18 and 19), `groups` (`res.groups`) and
26
+ `reports` (`ir.actions.report`).
27
+ - Administration: Settings: `menus` (`ir.actions.act_window`), `crons`
28
+ (`ir.cron`) and `serverActions` (`ir.actions.server`).
29
+
30
+ The default sections include `menus` and `crons`, so the full catalog needs a
31
+ Settings administrator's key; a dedicated technical user is recommended. A
32
+ section the key cannot read fails the run with `access_denied` naming the
33
+ section instead of publishing less.
@@ -0,0 +1,41 @@
1
+ ---
2
+ id: okf://okf-odoo/reference/configuration
3
+ type: OKF Reference
4
+ title: okf-odoo configuration
5
+ description: Producer configuration keys accepted by okf-odoo and their defaults.
6
+ tags: [okf, odoo, configuration]
7
+ relations:
8
+ - type: configured_by
9
+ target: repo://src/producer.js
10
+ - type: checked_by
11
+ target: repo://test/producer.test.js
12
+ ---
13
+
14
+ # Configuration
15
+
16
+ The producer configuration lives under `producers[].config` in
17
+ `okf.project.yaml`. Unknown keys are rejected.
18
+
19
+ - `url` (required): base URL of the Odoo server without credentials, query or
20
+ fragment; `https`, or `http` for a loopback host only.
21
+ - `api` (default `json2`): `json2` for Odoo 19 and 20, `jsonrpc` for Odoo 18.
22
+ - `database`: database name; the `X-Odoo-Database` header with `json2`,
23
+ required and part of every call with `jsonrpc`.
24
+ - `login`: login of the API key's user; required with `jsonrpc`, refused with
25
+ `json2`.
26
+ - `apiKeyEnv` (required): environment variable holding the API key; the host
27
+ hands a producer only the variables its configuration names.
28
+ - `source` (default `odoo`): alias used in `odoo://` resource locators.
29
+ - `lang` (default `en_US`): language of labels and menu names.
30
+ - `sections` (default every section but `serverActions`): `modules`,
31
+ `models`, `access`, `groups`, `menus`, `crons`, `reports`,
32
+ `serverActions`. `access`, `crons`, `reports` and `serverActions` require
33
+ `models`.
34
+ - `modules.include` and `modules.exclude`: module names, with `*` matching
35
+ any characters, selecting the modules documented in full. A model is
36
+ documented when a selected module defines or extends it.
37
+ - `otherModules` (default `summary`): `summary` renders the other installed
38
+ modules without their models, `none` leaves them out.
39
+
40
+ The project must declare the relation types `defined_in`, `extended_by`,
41
+ `references`, `implies` and `opens`; `depends_on` is built into `okf-mcp`.
@@ -0,0 +1,38 @@
1
+ ---
2
+ id: okf://okf-odoo/reference/data-tools
3
+ type: OKF Reference
4
+ title: okf-odoo data tools
5
+ description: Read-only Odoo data and SQL tools that okf-odoo offers to an MCP host as an experimental tool pack.
6
+ tags: [okf, odoo, mcp, tools]
7
+ relations:
8
+ - type: configured_by
9
+ target: repo://src/tool-pack.js
10
+ - type: configured_by
11
+ target: repo://src/tools.js
12
+ - type: configured_by
13
+ target: repo://src/data-api.js
14
+ - type: checked_by
15
+ target: repo://test/tool-pack.test.js
16
+ ---
17
+
18
+ # Odoo data tools
19
+
20
+ `okfToolPack` (tool-pack API version 1, id `odoo`) offers `odoo_find_models`,
21
+ `odoo_describe_model`, `odoo_search`, `odoo_read` and `odoo_group`, each with
22
+ the scope `odoo.read`, and `odoo_sql` with the scope `odoo.sql`: one
23
+ read-only statement over only the rows and fields the user may read, whose
24
+ `query_error` carries PostgreSQL's `sqlstate`, `position` and `message`.
25
+
26
+ Each tool posts to `{url}/o3p_mcp/api/v1/{op}` of the `o3p_mcp` Odoo addon
27
+ with the MCP server's resource-server credentials as HTTP Basic and the
28
+ signed-in user's access token as the subject. The addon runs the operation as
29
+ that user, so results contain only what the user may read. Without a subject
30
+ token, which exists only over HTTP, a tool fails with
31
+ `subject_token_required`.
32
+
33
+ Configuration: `url` (https, or http for a loopback host), `clientIdEnv` and
34
+ `clientSecretEnv` (environment-variable names), optional `timeoutMs` (25 s
35
+ by default, which must stay below the host's own per-call limit).
36
+ Arguments are checked against strict input schemas before a request; errors
37
+ are bounded codes with fixed messages, and neither Odoo's text nor the token
38
+ or credentials reach a result or an error.
@@ -0,0 +1,35 @@
1
+ ---
2
+ id: okf://okf-odoo/reference/output
3
+ type: OKF Reference
4
+ title: okf-odoo generated bundle
5
+ description: Concept paths, relation types and provenance of the bundle okf-odoo generates.
6
+ tags: [okf, odoo, output]
7
+ relations:
8
+ - type: configured_by
9
+ target: repo://src/render.js
10
+ - type: checked_by
11
+ target: repo://test/render.test.js
12
+ ---
13
+
14
+ # Generated bundle
15
+
16
+ - `index.md` links every generated concept.
17
+ - `modules/<name>.md`: version, category, dependencies, models defined and
18
+ extended.
19
+ - `models/<model>.md`: fields and selection values, and when selected the
20
+ access entries, scheduled jobs, reports and server actions of the model.
21
+ - `groups/<xmlid>.md`: implied groups, the groups implying it and its access
22
+ on documented models.
23
+ - `apps/<xmlid>.md`: a top-level menu, its submenus and the models their
24
+ window actions open.
25
+
26
+ Relation types: `defined_in` (model to the module that registered it first),
27
+ `extended_by` (model to the other modules), `references` (model to the models
28
+ its relational fields target), `depends_on` (module to module), `implies`
29
+ (group to group) and `opens` (application to model). Relations and links are
30
+ emitted only when the target is generated.
31
+
32
+ Each concept carries `generated.by`, `generated.at`, a `resource` such as
33
+ `odoo://<source>/sale.order` and `sources` naming the Odoo models read. Paths
34
+ and ordering are stable and `generated.at` is the only time value, so an
35
+ unchanged database republishes no file.