@dforge-core/dforge-mcp 0.2.2 → 0.2.4

package/package.json

@@ -1,48 +1,48 @@
 {
-	"name": "@dforge-core/dforge-mcp",
-	"version": "0.2.2",
-	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
-	"license": "MIT",
-	"homepage": "https://github.com/iash44/dForge-core",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
-	},
-	"bin": {
-		"dforge-mcp": "dist/server.js",
-		"dforge-install-skills": "scripts/install-skills.mjs"
-	},
-	"files": [
-		"dist/",
-		"docs/",
-		"resources/",
-		"skills/",
-		"scripts/install-skills.mjs",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"main": "dist/server.js",
-	"engines": {
-		"node": ">=18"
-	},
-	"scripts": {
-		"build": "tsup",
-		"sync-schemas": "node scripts/vendor-schemas.cjs",
-		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run",
-		"install-skills": "node scripts/install-skills.mjs"
-	},
-	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.10",
-		"@dforge-core/metadata": "^0.0.12",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"zod": "^4.4.3"
-	},
-	"devDependencies": {
-		"@types/node": "^22.20.1",
-		"tsup": "^8.5.1",
-		"typescript": "^6.0.3",
-		"vitest": "^3.2.7"
-	}
+  "name": "@dforge-core/dforge-mcp",
+  "version": "0.2.4",
+  "description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
+  "license": "MIT",
+  "homepage": "https://github.com/iash44/dForge-core",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
+  },
+  "bin": {
+    "dforge-mcp": "dist/server.js",
+    "dforge-install-skills": "scripts/install-skills.mjs"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "resources/",
+    "skills/",
+    "scripts/install-skills.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/server.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "sync-schemas": "node scripts/vendor-schemas.cjs",
+    "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "install-skills": "node scripts/install-skills.mjs"
+  },
+  "dependencies": {
+    "@dforge-core/dforge-cli": "^0.2.12",
+    "@dforge-core/metadata": "^0.0.13",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.7"
+  }
 }

package/resources/docs/dsl-reference.md

@@ -288,6 +288,68 @@ Fractional-unit arithmetic.
 [token_expires_at] = addMinutes(now(), 15)
 ```
 
+### Current user
+
+#### `currentUserId() → long`, `userId → long`
+The acting user's tenant user ID. Two spellings for the same value — `userId` is
+a **bare identifier**, `currentUserId()` is the call form. Both are always
+available; use whichever reads better.
+
+```dsl
+[approved_by_id] = userId
+[created_by_id] = currentUserId()
+notify(userId, 'Done')
+```
+
+`userId()` — the value spelled as a call — is **rejected at compile time**:
+
+```
+'userId' is a value, not a function — write 'userId' without parentheses, or 'currentUserId()'
+```
+
+`CURRENT_USER_ID()` is **not** available in `execute:` — it is a *formula* function,
+valid in `canExecute:`, formula columns, filters and reports, exactly like
+`TODAY()`/`NOW()` vs `now()`. Same split, same reason: `execute:` is JavaScript,
+the rest is the formula engine.
+
+#### 64-bit ids are BigInt
+
+JS numbers are doubles (53 mantissa bits); dForge ids are 58-bit snowflakes. Any
+`long` outside ±2^53 — user ids, PKs, FKs — reaches the script as a JS **BigInt**,
+so ids stay exact through reads, writes and comparisons. Smaller `int8` values
+(counters, quantities) stay ordinary numbers, so arithmetic on them is unchanged.
+
+```dsl
+[copy] = [owner_id]                            # exact round-trip
+[is_mine] = currentUserId() == [last_updated_by]   # exact — both sides BigInt
+[label] = '' + [owner_id]                      # "200650220910936067"
+```
+
+Two operations throw instead of rounding silently:
+
+```dsl
+[x] = [owner_id] + 1               # Cannot mix BigInt and other types
+[x] = Number([owner_id]) + 1       # explicit — and accepts the rounding
+
+[x] = JSON.stringify([owner_id])   # Do not know how to serialize a BigInt
+[payload] = { id: [owner_id] }     # assign the object; jsonb writes the number
+```
+
+Never write a large id as a bare numeric literal — the literal itself rounds
+before the comparison runs:
+
+| Comparison | Result |
+|---|---|
+| `[owner_id] == 200650220910936067` | ❌ literal rounded to `…064` |
+| `[owner_id] == '200650220910936067'` | ✅ string coerces to BigInt |
+| `[owner_id] == 200650220910936067n` | ✅ BigInt literal |
+| `[owner_id] === '200650220910936067'` | ❌ strict equality, different types |
+
+For "who did this", prefer the platform audit columns (`created_by` /
+`last_updated_by`) — filled server-side, no script involved. For ownership
+predicates in `canExecute:` or a formula column, use `CURRENT_USER_ID()`, which
+the server translates to an exact `::bigint` SQL literal.
+
 ### Messaging & notifications
 
 #### `info(message, opts?)`, `warn(message, opts?)`
@@ -459,6 +521,16 @@ var det = detectDocument(data.raw_text)     // { profile: 'proc.bill_of_lading',
 if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: det.profile }) }
 ```
 
+#### `applyProfile(json, profile) → object`
+Map an already-extracted JSON payload through a registered extraction profile's
+field schema, without re-running OCR. Use when the raw JSON came from somewhere
+other than `ocrExtract()` — a webhook payload, a stored response, a re-process of
+an earlier extraction.
+
+```dsl
+var mapped = applyProfile(tryParseJson([raw_payload]), 'proc.bill_of_lading')
+```
+
 ### Utility
 
 #### `entityLink(entityCd, record, description?) → link value`

package/resources/schemas/data-views.schema.json

@@ -492,7 +492,20 @@
 				},
 				"o": {
 					"type": "string",
-					"description": "Operator: eq, neq, =, !=, gt, gtEq, grEq, lt, ltEq, in, nIn, like, isNull, isNotNull, etc."
+					"enum": [
+						"=", "eq", "!=", "notEq",
+						">", "gr", ">=", "grEq", "<", "less", "<=", "lessEq",
+						"eqRef",
+						"contains", "!contains", "nContain",
+						"start", "!start", "nStart",
+						"end", "!end", "nEnd",
+						"mask", "!mask", "nMask",
+						"null", "empty", "!null", "nEmpty",
+						"in", "!in", "nIn",
+						"between", "btw", "!between", "nBetween",
+						"f", "func"
+					],
+					"description": "Operator. Closed set — this is exactly what the server's FilterBuilder translates, and an operator outside it is rejected at install. Symbolic forms and their word aliases are equivalent ('=' / 'eq', '!=' / 'notEq', '>' / 'gr', '>=' / 'grEq', '<' / 'less', '<=' / 'lessEq'); a leading '!' negates, with 'n'-prefixed spellings as the alias ('!in' / 'nIn'). Null checks are 'null' / 'empty' and '!null' / 'nEmpty' (NOT 'isNull' / 'isNotNull'); substring matching is 'contains' (NOT 'like'). 'eqRef' compares against another column (v = column code), 'f' / 'func' takes v = {fn: 'isToday' | 'isYesterday' | 'isThisWeek' | 'isThisMonth' | 'isThisYear' | 'isPast' | 'isFuture' | 'isCurrentUser'}."
 				},
 				"v": {
 					"description": "Comparison value. Scalars, arrays (for in/nIn), or parameter references like '@param_code'."
@@ -506,8 +519,8 @@
 			"properties": {
 				"g": {
 					"type": "string",
-					"enum": ["and", "or"],
-					"description": "Group combinator"
+					"enum": ["and", "or", "!and", "nAnd", "!or", "nOr"],
+					"description": "Group combinator. '!and' / '!or' negate the whole group ('nAnd' / 'nOr' are the alias spellings). Closed set — an unknown combinator is rejected at install (at query time it would silently fall back to AND)."
 				},
 				"i": {
 					"type": "array",

package/resources/schemas/folders.schema.json

@@ -87,7 +87,23 @@
 			"required": ["c", "o"],
 			"properties": {
 				"c": { "type": "string" },
-				"o": { "type": "string" },
+				"o": {
+					"type": "string",
+					"enum": [
+						"=", "eq", "!=", "notEq",
+						">", "gr", ">=", "grEq", "<", "less", "<=", "lessEq",
+						"eqRef",
+						"contains", "!contains", "nContain",
+						"start", "!start", "nStart",
+						"end", "!end", "nEnd",
+						"mask", "!mask", "nMask",
+						"null", "empty", "!null", "nEmpty",
+						"in", "!in", "nIn",
+						"between", "btw", "!between", "nBetween",
+						"f", "func"
+					],
+					"description": "Operator — same closed set as data_views.json. Null checks are 'null' / '!null' (NOT 'isNull' / 'isNotNull'); substring matching is 'contains' (NOT 'like'). An operator outside this set is rejected at install; at query time it would be dropped, widening the row filter it was meant to enforce."
+				},
 				"v": {}
 			},
 			"additionalProperties": false
@@ -96,7 +112,7 @@
 			"type": "object",
 			"required": ["g", "i"],
 			"properties": {
-				"g": { "type": "string", "enum": ["and", "or"] },
+				"g": { "type": "string", "enum": ["and", "or", "!and", "nAnd", "!or", "nOr"] },
 				"i": {
 					"type": "array",
 					"items": { "$ref": "#/$defs/filter" }

package/resources/schemas/reports.schema.json

@@ -366,7 +366,23 @@
 			"required": ["c", "o"],
 			"properties": {
 				"c": { "type": "string" },
-				"o": { "type": "string" },
+				"o": {
+					"type": "string",
+					"enum": [
+						"=", "eq", "!=", "notEq",
+						">", "gr", ">=", "grEq", "<", "less", "<=", "lessEq",
+						"eqRef",
+						"contains", "!contains", "nContain",
+						"start", "!start", "nStart",
+						"end", "!end", "nEnd",
+						"mask", "!mask", "nMask",
+						"null", "empty", "!null", "nEmpty",
+						"in", "!in", "nIn",
+						"between", "btw", "!between", "nBetween",
+						"f", "func"
+					],
+					"description": "Operator — same closed set as data_views.json. Null checks are 'null' / '!null' (NOT 'isNull' / 'isNotNull'); substring matching is 'contains' (NOT 'like'). An operator outside this set is rejected at install; at query time it would be dropped, silently widening the dataset."
+				},
 				"v": {}
 			},
 			"additionalProperties": false
@@ -375,7 +391,7 @@
 			"type": "object",
 			"required": ["g", "i"],
 			"properties": {
-				"g": { "type": "string", "enum": ["and", "or"] },
+				"g": { "type": "string", "enum": ["and", "or", "!and", "nAnd", "!or", "nOr"] },
 				"i": {
 					"type": "array",
 					"items": { "$ref": "#/$defs/filter" }

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -224,14 +224,31 @@ var queued = select('comm.message', {
 | `getFileBase64(fileFieldValue)` | String | Read a file from storage and return its content as a base64-encoded string. Use with `callApi()` to send files to AI APIs. Max 10 MB. Example: `getFileBase64([document_file])`. |
 | `getFileUrl(fileFieldValue)` | String | Generate a temporary signed download URL (relative path) for a file field. Use in email templates or notifications — not for `callApi()`. |
 | `getSecret('secret_cd')` | String | Retrieve a decrypted secret value (API keys, tokens). Secrets are managed in the admin UI. |
+| `getFileInfo(fileFieldValue)` | Object \| null | File metadata for a file field. |
+| `download(url, fileName?)` | — | Fetch a URL into tenant storage. |
+| `callService('name', { args })` | Any | Invoke a registered host service. |
+
+### Files, settings, document extraction
+
+| Function | Returns | Description |
+|---|---|---|
+| `getSetting('setting_cd')` | Any | Read a module setting, resolved through the folder chain (current folder → parents → module default). |
+| `ocrExtract(fileField, endpointBaseUrl, schema?, opts?)` | Object | Run OCR extraction against a document. `opts.profile` selects a registered extraction profile, e.g. `{ profile: 'proc.bill_of_lading' }`. |
+| `detectDocument(rawText)` | Object \| null | Score text against reachable extraction profiles; returns the best match `{ profile, docType, score }` or `null`. |
+| `applyProfile(json, 'module.profile_cd')` | Object | Map already-extracted JSON through a profile's field schema, without re-running OCR. |
 
 ### Utilities
 
 | Function | Returns | Description |
 |---|---|---|
 | `now()` | DateTime | Current date/time. Use for `date`, `datetime`, and `timestamp` fields. **Lowercase** — this is the execute-block date function. |
-| `IF(condition, trueVal, falseVal)` | Any | Ternary helper. |
 | `addDays(date, n)` | Date | Add `n` days to a date, e.g. `addDays(now(), 30)`. |
+| `addMinutes(date, n)` | DateTime | Add `n` minutes, e.g. `addMinutes(now(), 15)`. |
+| `addSeconds(date, n)` | DateTime | Add `n` seconds. |
+| `currentUserId()` | Long | The acting user's tenant user ID. |
+| `userId` | Long | Same value as `currentUserId()`, as a **bare identifier — no parentheses**. `userId()` is a compile error; there is no `current_user_id()`. |
+| `flush()` | — | Flush pending writes so a following read sees them. |
+| `tryParseJson(value)` | Any \| null | Parse JSON, returning `null` on failure instead of throwing. |
 | `nextNumber('entity')` | String | Generate next value from a number sequence. Usually not needed — platform auto-fills on `insert()`. Use for pre-generating numbers. |
 | `callProc('proc_name', { args })` | Result | Call a stored procedure. Args are passed as named parameters. |
 | `entityLink('entityCd', record, description?)` | Link value | Build a clickable link to any entity record, for storing in an `entitylink` (jsonb) column. `record` is a row object (e.g. the result of `insert()` or `getRecord()`); its PK columns are read and stored as **strings**, so snowflake/cuid ids (> 2^53) stay exact. The entity is resolved at build time and stored **by id** — `entity_cd` is only unique per module, so always pass a qualified code (`'fin.invoice'`). Omit `description` and the link is captioned with the entity's `toString` against `record`; an explicit `description` wins. |
@@ -243,6 +260,32 @@ var queued = select('comm.message', {
 > columns, and other formula contexts; use `now()` everywhere inside `execute:`. (Uppercase `NOW()`
 > is also fine *inside a raw SQL string* passed to `query()`, because that's SQL, not JS.)
 
+> **`IF()` is formula-only too.** It was previously listed here as a ternary helper — that was
+> wrong. `IF(cond, a, b)` is a **formula-engine** function, valid in `canExecute:` and formula
+> columns, and **undefined in `execute:`** (install fails with `'IF' is not defined`). Inside
+> `execute:` use the JavaScript conditional operator: `var x = cond ? a : b`.
+
+> **64-bit ids are BigInt in `execute:`.** JS numbers are doubles (53 mantissa bits) and dForge
+> ids are 58-bit snowflakes, so any `long` outside ±2^53 — user ids, PKs, FKs — reaches the script
+> as a JS **BigInt**. Ids stay exact through reads, writes and comparisons, including
+> `currentUserId() == [last_updated_by]`. Smaller `int8` values (counters, quantities) stay
+> ordinary numbers, so arithmetic on them is unchanged.
+>
+> Two operations throw rather than round silently, each with a working form:
+> `[owner_id] + 1` → use `Number([owner_id]) + 1` (explicit, and accepts the rounding);
+> `JSON.stringify([owner_id])` → assign the object instead (`[payload] = { id: [owner_id] }`),
+> which serializes correctly on the write path.
+>
+> Never write a large id as a bare numeric literal — the literal itself rounds before the
+> comparison runs. `[owner_id] == 2006…067` is **false**; quote it (`== '2006…067'`) or suffix
+> it with `n` (`== 2006…067n`). Comparing two id columns needs neither.
+>
+> For "who did this", the platform audit columns (`created_by` / `last_updated_by`) remain the
+> better answer — filled server-side, no script involved. For ownership predicates use
+> **`CURRENT_USER_ID()`** in `canExecute:` or a formula column — a *formula-engine* function
+> (undefined in `execute:`) that the server translates to an exact `::bigint` SQL literal.
+
+
 ## Real examples from the codebase
 
 ### Simple field update (status transition)

package/skills/dforge-mcp-author/references/reports.md

@@ -61,7 +61,7 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
     "query": {
         "entityCd": "opportunity",
         "columns": ["stage", "amount", "close_date", "customer.name"],
-        "filter": { "c": "stage", "o": "ne", "v": "Closed Lost" },
+        "filter": { "c": "stage", "o": "!=", "v": "Closed Lost" },
         "sort": [ { "c": "close_date", "d": "desc" } ]
     },
     "columnsDef": { "amount": { "label": "Deal Value" }, "customer.name": { "label": "Account" } }