@mfdaves/okf-odoo 0.1.0 → 0.2.0-rc.1

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 CHANGED
@@ -2,6 +2,28 @@
2
2
 
3
3
  All notable changes to `@mfdaves/okf-odoo`. The format follows Keep a Changelog; versions follow SemVer.
4
4
 
5
+ ## 0.2.0-rc.1 — 2026-11-21
6
+
7
+ A release candidate, published under npm's `next` tag.
8
+
9
+ ### Added
10
+
11
+ - Tools `odoo_create` and `odoo_update` (data API operations `create` and `update`, scope `odoo.write`, `o3p_mcp` 1.43 or newer): create up to 20 records, or set fields of up to 100 records given by id, as the signed-in user, on the models the Odoo administrator opened for writing. They are announced with `readOnlyHint: false`; a refusal by Odoo itself carries Odoo's message in `details.message`.
12
+ - Tool `odoo_context` (data API operation `context`, `o3p_mcp` 1.42 or newer): the signed-in user, the language and time zone of the answers, the user's default company and all the user's companies, the current time in UTC and today's date in the user's time zone.
13
+
14
+ ### Changed
15
+
16
+ - `odoo_group`: `groupby` is optional; without it the answer is one group holding the totals over all matching records (`o3p_mcp` 1.42 or newer). Its description says that a date bucket is a period in the user's time zone whose start is given in UTC.
17
+ - The note on sharing in the descriptions of the tools that return record data says that knowledge written from the results is readable by every user who reads the bundle it is written into (before: by every MCP user), since a host can restrict a bundle to audiences.
18
+
19
+ ## 0.1.2 — 2026-11-15
20
+
21
+ No runtime change.
22
+
23
+ ### Changed
24
+
25
+ - The Release workflow publishes each version with `npm publish` through the trusted publisher, with npm provenance. 0.1.2 is the first version released this way and the first with npm provenance (0.1.0 was published by hand). 0.1.1 was staged with `npm stage publish` and never published.
26
+
5
27
  ## 0.1.0 — 2026-11-15
6
28
 
7
29
  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`.
package/README.md CHANGED
@@ -17,10 +17,10 @@ own: a host such as [`okf-mcp`](https://github.com/mfdaves/okf-mcp) loads it,
17
17
  validates the candidate bundle and publishes it through
18
18
  `okf producer preview` and `okf producer run`.
19
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.
20
+ It also ships an experimental tool pack with tools for live Odoo records
21
+ ([Odoo data tools](#odoo-data-tools-experimental)): seven that read and two
22
+ that create and update. Those never touch the metadata reader: they ask an
23
+ Odoo addon to run each call as the signed-in user.
24
24
 
25
25
  ## Requirements
26
26
 
@@ -221,18 +221,21 @@ reuse.
221
221
  ## Odoo data tools (experimental)
222
222
 
223
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:
224
+ experimental and may still change) seven read-only tools for live records and two that change them:
225
225
 
226
226
  | Tool | Data API operation | Purpose |
227
227
  | --- | --- | --- |
228
+ | `odoo_context` | `context` | The signed-in user, the language and time zone of the answers, the user's default company and all the user's companies, the current time and today's date in the user's time zone (needs `o3p_mcp` 1.42 or newer; an older server answers `unknown_op`) |
228
229
  | `odoo_find_models` | `models` | Find models the signed-in user may read, by name or label, paged with `offset` (`total`, `truncated`) |
229
230
  | `odoo_describe_model` | `describe` | The fields of a model as that user sees them, with whether each is stored, searchable, sortable and groupable |
230
231
  | `odoo_search` | `search` | Records matching a domain, with the requested fields (at most 200 per call) |
231
232
  | `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_group` | `group` | Grouped totals such as `amount_total:sum` and `__count` (at most 500 groups); without `groupby`, one group of totals over all matching records (`o3p_mcp` 1.42 or newer) |
234
+ | `odoo_create` | `create` | Create 1 to 20 records of a model as the signed-in user, on the models the Odoo administrator opened for writing (`o3p_mcp` 1.43 or newer) |
235
+ | `odoo_update` | `update` | Set fields of existing records, given by their ids (at most 100), all or none (`o3p_mcp` 1.43 or newer) |
233
236
  | `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
237
 
235
- Each tool requires the `odoo.read` scope, `odoo_sql` the `odoo.sql` scope. The tools do not read Odoo
238
+ Each tool requires the `odoo.read` scope, `odoo_sql` the `odoo.sql` scope, `odoo_create` and `odoo_update` the `odoo.write` scope; the two are announced as not read-only (`readOnlyHint: false`), `odoo_update` also as destructive. When Odoo itself refuses a change, their `query_error` carries Odoo's message for the user in `details.message` (at most 500 characters). The tools do not read Odoo
236
239
  directly: every call is a `POST {url}/o3p_mcp/api/v1/{op}` to the data API of
237
240
  the `o3p_mcp` Odoo addon, authenticated with the MCP server's
238
241
  resource-server client credentials (HTTP Basic) and carrying the signed-in
@@ -361,8 +364,9 @@ expecting exactly the denials of the table above.
361
364
 
362
365
  ## Release
363
366
 
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.
367
+ Releases go through the Release workflow, dispatched with a tag `vX.Y.Z`
368
+ that matches `package.json` and an npm dist tag (`next` for prereleases,
369
+ `latest` otherwise). After the same checks as CI, it publishes the package
370
+ with npm provenance through the trusted publisher configured on npm, without
371
+ a stored token. 0.1.0 was published by hand, because npm cannot configure a
372
+ trusted publisher for a package that does not exist yet.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mfdaves/okf-odoo",
3
- "version": "0.1.0",
3
+ "version": "0.2.0-rc.1",
4
4
  "description": "Odoo for Open Knowledge Format: a read-only metadata producer and an MCP tool pack for live Odoo data.",
5
5
  "homepage": "https://github.com/mfdaves/okf-odoo#readme",
6
6
  "repository": {
package/src/data-api.js CHANGED
@@ -9,7 +9,20 @@
9
9
  const { setTimeout: sleep } = require("node:timers/promises");
10
10
  const { OdooError, normalizeBaseUrl, postJson } = require("./odoo");
11
11
 
12
- const OPS = new Set(["models", "describe", "search", "read", "group", "sql"]);
12
+ const OPS = new Set([
13
+ "context",
14
+ "models",
15
+ "describe",
16
+ "search",
17
+ "read",
18
+ "group",
19
+ "sql",
20
+ "create",
21
+ "update",
22
+ ]);
23
+ // The operations that change records: Odoo's own refusal of a write comes
24
+ // with the message Odoo shows that user.
25
+ const WRITE_OPS = new Set(["create", "update"]);
13
26
  // PostgreSQL's own message about an SQL query, as the data API caps it.
14
27
  const MAX_SQL_MESSAGE = 500;
15
28
  // The host passes on detail strings of at most 200 characters.
@@ -36,12 +49,13 @@ const MESSAGES = {
36
49
  invalid_params: "Odoo refused the parameters.",
37
50
  invalid_client: "Odoo refused the connector's client credentials.",
38
51
  invalid_token: "The signed-in user's access token is not valid for Odoo.",
39
- insufficient_scope: "The signed-in user's access token does not allow reading Odoo data.",
40
- access_denied: "The signed-in user may not read this.",
52
+ insufficient_scope: "The signed-in user's access token does not allow this on Odoo data.",
53
+ access_denied: "The signed-in user may not read or change this.",
41
54
  unknown_op: "Odoo does not offer this operation.",
42
55
  unknown_model: "Odoo has no such model, or it is not exposed.",
43
56
  result_too_large: "The result is too large; ask for fewer records or fields.",
44
- query_error: "Odoo could not run the query; check field names, operators and values.",
57
+ query_error:
58
+ "Odoo could not run the query or refused the change; check field names, operators and values.",
45
59
  too_many_requests: "Too many queries are running for this user or server; try again shortly.",
46
60
  unavailable: "SQL queries are not available on this Odoo server right now.",
47
61
  timeout: "The query took too long.",
@@ -103,8 +117,10 @@ function oneLine(value, max) {
103
117
  // hint, all schema names and fixed texts. sql's query_error adds
104
118
  // PostgreSQL's answer (the sandbox holds only rows the user may read, and an
105
119
  // agent needs it to fix its query): a valid SQLSTATE, a 1-based position and
106
- // a message of at most 500 characters. A string holding the token or a
107
- // credential is dropped. Returns null when nothing remains.
120
+ // a message of at most 500 characters. create's and update's query_error
121
+ // adds Odoo's own message for the user, capped the same way. A string
122
+ // holding the token or a credential is dropped. Returns null when nothing
123
+ // remains.
108
124
  function errorDetails(value, op, code, hidden) {
109
125
  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
110
126
  const clean = (text, max) => {
@@ -127,6 +143,10 @@ function errorDetails(value, op, code, hidden) {
127
143
  : null;
128
144
  details.message = clean(value.message, MAX_SQL_MESSAGE);
129
145
  }
146
+ if (WRITE_OPS.has(op) && code === "query_error") {
147
+ const message = clean(value.message, MAX_SQL_MESSAGE);
148
+ if (message) details.message = message;
149
+ }
130
150
  return Object.keys(details).length ? details : null;
131
151
  }
132
152
 
package/src/schema.js CHANGED
@@ -2,7 +2,8 @@
2
2
 
3
3
  // Checks a value against the small JSON Schema subset the tool schemas use:
4
4
  // type, enum, properties, required, additionalProperties: false, items,
5
- // prefixItems, min/maxItems, min/maxLength, pattern, minimum/maximum, anyOf.
5
+ // prefixItems, min/maxItems, min/maxLength, pattern, minimum/maximum, anyOf,
6
+ // min/maxProperties and propertyNames with a pattern.
6
7
  // Returns the path of the first violation, or null. The path names schema
7
8
  // properties and array positions only, never a value or an unknown key.
8
9
 
@@ -46,6 +47,19 @@ function violation(schema, value, path = "") {
46
47
  }
47
48
  }
48
49
  if (typeOf(value) === "object") {
50
+ const keys = Object.keys(value);
51
+ if (schema.minProperties !== undefined && keys.length < schema.minProperties)
52
+ return path || "/";
53
+ if (schema.maxProperties !== undefined && keys.length > schema.maxProperties)
54
+ return path || "/";
55
+ if (schema.propertyNames?.pattern) {
56
+ const names = new RegExp(schema.propertyNames.pattern, "u");
57
+ const limit = schema.propertyNames.maxLength ?? Number.POSITIVE_INFINITY;
58
+ // The caller's own key is not echoed.
59
+ if (keys.some((key) => !names.test(key) || key.length > limit)) {
60
+ return `${path}/(unexpected property)`;
61
+ }
62
+ }
49
63
  for (const key of schema.required || []) {
50
64
  if (!Object.hasOwn(value, key)) return `${path}/${key}`;
51
65
  }
package/src/tool-pack.js CHANGED
@@ -16,7 +16,7 @@ function createOdooToolPack(dependencies = {}) {
16
16
  for (const tool of TOOLS) {
17
17
  tools[tool.name] = Object.freeze({
18
18
  description: tool.description,
19
- annotations: Object.freeze(annotations(tool.title)),
19
+ annotations: Object.freeze(annotations(tool.title, tool.writes)),
20
20
  inputSchema: tool.inputSchema,
21
21
  outputSchema: tool.outputSchema,
22
22
  scope: tool.scope || SCOPE,
package/src/tools.js CHANGED
@@ -93,12 +93,14 @@ function objectSchema(properties, required) {
93
93
  return { type: "object", properties, required, additionalProperties: false };
94
94
  }
95
95
 
96
- function annotations(title) {
96
+ // `writes` is "create" or "update" for a tool that changes Odoo records: it
97
+ // is not read-only, not repeatable, and an update replaces existing values.
98
+ function annotations(title, writes) {
97
99
  return {
98
100
  title,
99
- readOnlyHint: true,
100
- destructiveHint: false,
101
- idempotentHint: true,
101
+ readOnlyHint: !writes,
102
+ destructiveHint: writes === "update",
103
+ idempotentHint: !writes,
102
104
  openWorldHint: true,
103
105
  };
104
106
  }
@@ -106,9 +108,9 @@ function annotations(title) {
106
108
  const RIGHTS =
107
109
  "Odoo runs every call as the signed-in user: results contain only what that user may read under Odoo's access rights and record rules, so another user may see different records.";
108
110
  // Results follow one user's Odoo access, knowledge written from them is read
109
- // by everyone.
111
+ // by everyone who reads the bundle it is written into.
110
112
  const SHARING =
111
- "These results are limited to the signed-in user's own Odoo access, but knowledge written from them is readable by every MCP user: record conclusions and aggregates, not personal or confidential values (names of individuals, salaries, health or contact details) that other readers could not see in Odoo.";
113
+ "These results are limited to the signed-in user's own Odoo access, but knowledge written from them is readable by every user who reads the bundle it is written into: record conclusions and aggregates, not personal or confidential values (names of individuals, salaries, health or contact details) that other readers could not see in Odoo.";
112
114
  const FIELD_FLAGS =
113
115
  "Filter only on fields odoo_describe_model marks searchable, sort only on sortable ones and group only on groupable ones.";
114
116
  const EXPLAINED =
@@ -116,7 +118,86 @@ const EXPLAINED =
116
118
  const LOOK_UP_FIRST =
117
119
  "Before searching, look up the model in the generated `odoo` knowledge bundle (its models/<model> concept lists the fields, relations and access rules) or call odoo_describe_model, so that you use real field names.";
118
120
 
121
+ // Field values of a record to create or to change.
122
+ const VALUES = {
123
+ type: "object",
124
+ minProperties: 1,
125
+ maxProperties: 200,
126
+ propertyNames: { pattern: "^[a-z_][a-z0-9_]*$", maxLength: 128 },
127
+ description:
128
+ 'Field values by field name, for fields odoo_describe_model marks writable: text, numbers and booleans as JSON; a date as "YYYY-MM-DD" and a date-time as "YYYY-MM-DD HH:MM:SS" in UTC; a selection by its key; a many2one by the related record\'s id; a many2many as a list of record ids. false empties a field.',
129
+ };
130
+ const COMPANY = {
131
+ type: "integer",
132
+ minimum: 1,
133
+ description:
134
+ "Id of the company to work in, one of the user's companies (see odoo_context); default: the user's default company.",
135
+ };
136
+ const WRITTEN = {
137
+ type: "object",
138
+ properties: {
139
+ records: {
140
+ type: "array",
141
+ items: {
142
+ type: "object",
143
+ properties: { id: { type: "integer" }, display_name: { type: "string" } },
144
+ required: ["id"],
145
+ },
146
+ },
147
+ },
148
+ required: ["records"],
149
+ };
150
+ const WRITE_RULES =
151
+ "Odoo applies the signed-in user's own rights, and accepts writes only on the models the administrator opened: odoo_describe_model tells both (access, and writable on each field). Read-only, computed and related fields, one2many lines, files and images cannot be set; a status changes through Odoo's own buttons, not by setting the field.";
152
+ const WRITE_ERRORS =
153
+ "Nothing is written when any part is refused. access_denied, invalid_params and unknown_record name the field and a hint; when Odoo itself refuses the change (query_error), details.message is Odoo's explanation for the user.";
154
+
119
155
  const TOOLS = [
156
+ {
157
+ name: "odoo_context",
158
+ op: "context",
159
+ title: "Who and where am I in Odoo",
160
+ description: [
161
+ "Tell who the signed-in Odoo user is and in which setting the other tools answer: the user (id, name, login), the language and time zone of the answers, the user's default company and all the user's companies, the current time in UTC (now) and today's date in the user's time zone (today).",
162
+ 'Call it once before questions about "my" records (filter on the user\'s id), about relative dates such as today or this month, or about one company.',
163
+ "It takes no arguments and tells nothing about other users. A server with o3p_mcp older than 1.42 answers unknown_op.",
164
+ ].join(" "),
165
+ inputSchema: objectSchema({}, []),
166
+ outputSchema: {
167
+ type: "object",
168
+ properties: {
169
+ user: {
170
+ type: "object",
171
+ properties: {
172
+ id: { type: "integer" },
173
+ name: { type: "string" },
174
+ login: { type: "string" },
175
+ },
176
+ required: ["id", "name"],
177
+ },
178
+ lang: { type: "string" },
179
+ tz: { type: "string" },
180
+ company: {
181
+ type: "object",
182
+ properties: { id: { type: "integer" }, name: { type: "string" } },
183
+ required: ["id", "name"],
184
+ },
185
+ companies: {
186
+ type: "array",
187
+ items: {
188
+ type: "object",
189
+ properties: { id: { type: "integer" }, name: { type: "string" } },
190
+ required: ["id", "name"],
191
+ },
192
+ },
193
+ now: { type: "string" },
194
+ today: { type: "string" },
195
+ },
196
+ required: ["user", "tz", "company", "companies"],
197
+ },
198
+ params: () => ({}),
199
+ result: objectResult,
200
+ },
120
201
  {
121
202
  name: "odoo_find_models",
122
203
  op: "models",
@@ -299,7 +380,8 @@ const TOOLS = [
299
380
  FIELD_FLAGS,
300
381
  EXPLAINED,
301
382
  'groupby lists fields; a date field needs a granularity: "date:month" (day, week, month, quarter, year, or hour for date-times). aggregates are written "field:function": sum, avg, min or max on numeric fields, count or count_distinct on stored fields, and "__count" counts records. Example: groupby ["partner_id"], aggregates ["amount_total:sum", "__count"], order "amount_total:sum desc".',
302
- "Each group carries its groupby values and aggregates: a relation as [id, display name], a date bucket as [start, label].",
383
+ "Leave groupby out for one group holding the totals over all matching records.",
384
+ "Each group carries its groupby values and aggregates: a relation as [id, display name], a date bucket as [start, label]. A date bucket is a period in the user's time zone (see odoo_context) and start is its beginning in UTC, which can fall on the day before: read the period from the label.",
303
385
  "The domain has the same syntax as in odoo_search, with paths of at most 4 fields. At most 500 groups.",
304
386
  `${RIGHTS} Totals therefore cover only the records the user may read.`,
305
387
  SHARING,
@@ -315,9 +397,9 @@ const TOOLS = [
315
397
  pattern: "^[a-z_][a-z0-9_]*(:(hour|day|week|month|quarter|year))?$",
316
398
  maxLength: 140,
317
399
  },
318
- minItems: 1,
319
400
  maxItems: 5,
320
- description: 'Fields to group by, for example ["partner_id", "date:month"].',
401
+ description:
402
+ 'Fields to group by, for example ["partner_id", "date:month"]; leave out for totals only.',
321
403
  },
322
404
  aggregates: {
323
405
  type: "array",
@@ -338,7 +420,7 @@ const TOOLS = [
338
420
  description: "At most 500; default 80.",
339
421
  },
340
422
  },
341
- ["model", "groupby", "aggregates"],
423
+ ["model", "aggregates"],
342
424
  ),
343
425
  outputSchema: {
344
426
  type: "object",
@@ -348,6 +430,68 @@ const TOOLS = [
348
430
  params: (args) => ({ domain: [], limit: 80, ...args }),
349
431
  result: objectResult,
350
432
  },
433
+ {
434
+ name: "odoo_create",
435
+ op: "create",
436
+ scope: "odoo.write",
437
+ writes: "create",
438
+ title: "Create Odoo records",
439
+ description: [
440
+ "Create 1 to 20 records of one Odoo model as the signed-in user; the answer lists the new records with their ids and display names.",
441
+ WRITE_RULES,
442
+ "Before calling it, tell the user exactly what you are about to create, and check with odoo_search that the record does not exist already.",
443
+ WRITE_ERRORS,
444
+ ].join(" "),
445
+ inputSchema: objectSchema(
446
+ {
447
+ model: MODEL,
448
+ records: {
449
+ type: "array",
450
+ items: VALUES,
451
+ minItems: 1,
452
+ maxItems: 20,
453
+ description: "The records to create, each an object of field values.",
454
+ },
455
+ company: COMPANY,
456
+ },
457
+ ["model", "records"],
458
+ ),
459
+ outputSchema: WRITTEN,
460
+ params: (args) => ({ ...args }),
461
+ result: objectResult,
462
+ },
463
+ {
464
+ name: "odoo_update",
465
+ op: "update",
466
+ scope: "odoo.write",
467
+ writes: "update",
468
+ title: "Change Odoo records",
469
+ description: [
470
+ "Set fields of existing records of one Odoo model, given by their ids (at most 100), as the signed-in user. Every record gets the same values, and all are changed or none.",
471
+ WRITE_RULES,
472
+ 'On a many2many field a list of ids replaces the linked records; { "add": [ids], "remove": [ids] } changes them.',
473
+ "Read the records first (odoo_search or odoo_read) and tell the user exactly which records and fields you are about to change. A record that does not exist and one the user may not read are refused alike (unknown_record).",
474
+ WRITE_ERRORS,
475
+ ].join(" "),
476
+ inputSchema: objectSchema(
477
+ {
478
+ model: MODEL,
479
+ ids: {
480
+ type: "array",
481
+ items: { type: "integer", minimum: 1 },
482
+ minItems: 1,
483
+ maxItems: 100,
484
+ description: "Ids of the records to change.",
485
+ },
486
+ values: VALUES,
487
+ company: COMPANY,
488
+ },
489
+ ["model", "ids", "values"],
490
+ ),
491
+ outputSchema: WRITTEN,
492
+ params: (args) => ({ ...args }),
493
+ result: objectResult,
494
+ },
351
495
  {
352
496
  name: "odoo_sql",
353
497
  op: "sql",