@norbix.ai/mcp 0.2.1 → 0.3.0

package/README.md

@@ -165,8 +165,8 @@ NORBIX_HUB_URL=https://hub.norbix.ai norbix-mcp --http --port 3010
 `norbix_get_integrations`, `norbix_get_integration`, `norbix_save_integration`,
 `norbix_test_integration`, `norbix_get_marketplace_integrations`,
 `norbix_save_marketplace_integration`, `norbix_get_database_schemas`,
-`norbix_find_documents`, `norbix_insert_document`, `norbix_update_document`,
-`norbix_get_taxonomy_terms`, `norbix_get_roles`, `norbix_get_policies`,
+`norbix_find_documents`, `norbix_find_one_document`, `norbix_insert_document`,
+`norbix_update_document`, `norbix_get_taxonomy_terms`, `norbix_get_roles`, `norbix_get_policies`,
 `norbix_get_logs`, `norbix_list_service_api_keys`.
 
 Typical flow the model follows for anything not curated:
@@ -192,7 +192,7 @@ The scheduler module switch (`enableScheduler` / `disableScheduler`) is `PUT`.
 
 ## Database tools
 
-Five shortcuts cover the everyday database work. Everything else in the
+Six shortcuts cover the everyday database work. Everything else in the
 Database module (95 endpoints: schemas and drafts, records, taxonomies and
 terms, triggers, aggregates, database integrations) is reached with the
 generic trio.
@@ -200,13 +200,14 @@ generic trio.
 | Tool | SDK method | Route | Input |
 | --- | --- | --- | --- |
 | `norbix_get_database_schemas` | `hub.database.getDatabaseSchemas` | `GET /{version}/database/schemas` | `body` (paging) |
-| `norbix_find_documents` | `api.database.find` | `GET /{version}/database/collections/{collectionName}` | `body`: `collectionName`, `filter` (JSON string), `sortBy`, `pageSize`, … |
+| `norbix_find_documents` | `api.database.find` | `GET /{version}/database/collections/{collectionName}` | `collectionName`, `filter?`, `sortBy?`, `sortOrder?`, `pageSize?`, `startingAfter?`, `endingBefore?`, `expandReferences?`, `databaseIntegrationId?`, `body?` (any other `FindRequest` field) |
+| `norbix_find_one_document` | `api.database.findOne` | `GET /{version}/database/collections/{collectionName}/{id}` | `collectionName`, `id`, `expandReferences?`, `databaseIntegrationId?` |
 | `norbix_insert_document` | `api.database.insertOne` | `POST /{version}/database/collections/{collectionName}` | `collectionName`, `document`, `databaseIntegrationId?` |
-| `norbix_update_document` | `api.database.updateOne` | `PUT /{version}/database/collections/{collectionName}/{id}` | `collectionName`, `id`, `update`, `databaseIntegrationId?` |
+| `norbix_update_document` | `api.database.updateOne` | `PUT /{version}/database/collections/{collectionName}/{id}` | `collectionName`, `id`, `update`, `arrayFilters?`, `databaseIntegrationId?` |
 | `norbix_get_taxonomy_terms` | `api.database.findTerms` | `GET /{version}/database/taxonomies/{taxonomyName}/terms` | `taxonomyName`, `filter?`, `pageSize?`, `sortDescending?`, `databaseIntegrationId?` |
 
 The Api record endpoints expect the document, the update and the filter as a
-JSON **string**. The three newer shortcuts accept an object or a string and
+JSON **string**. The typed shortcuts accept an object or a string and
 send the string, so this works in one call:
 
 ```json
@@ -225,6 +226,31 @@ A `$` operator in it (`$set`, `$inc`, …) is refused with
 filter `{}` is refused (`CM-ERRORS-DATABASE-037`) unless the body also has
 `allRecords: true`.
 
+**References.** A `user`, `role`, `taxonomy` (term), `collection` or `file`
+field stores ids. Pass `expandReferences: true` to `norbix_find_documents` or
+`norbix_find_one_document` and each such field comes back as
+`{ "id": "…", "display": … }` (an array of them when the field is multiple):
+
+```json
+{ "name": "norbix_find_one_document", "arguments": {
+  "collectionName": "posts", "id": "…", "expandReferences": true } }
+```
+
+```json
+{ "author": { "id": "usr_…", "display": "Jane Doe" },
+  "tags":   [ { "id": "6650…", "display": { "title": { "en": "News" }, "slug": "news" } },
+              { "id": "6651…", "display": null } ] }
+```
+
+`display` is the target's `displayField` (a user property, a role name, a
+term's title and slug, a record's chosen field). It is `null` when the target
+is gone **or** when your API key may not read the target — the two cases look
+the same on purpose. Default is off: the stored ids only.
+
+**Arrays inside a document.** `norbix_update_document` takes `arrayFilters`
+for positional paths: `update: { "items.$[i].qty": 2 }` with
+`arrayFilters: [ { "i.sku": "A1" } ]`.
+
 For anything else, search the `database` group:
 
 - `norbix_search_endpoints({ query: "taxonomy term", group: "database" })`
@@ -275,6 +301,12 @@ is written as `feat(...)` with a `Breaking: <what>` line in the body (a
 is the source of truth for the version; release notes are on the GitHub
 Releases page.
 
+The commit analyzer reads only the **start** of each subject, so a step
+number goes at the end (`feat(database): expand references — step 2`),
+never in front of the type: `[2] feat(database): …` is read as "no
+release". Pull request 10 (the schema-content contract) shipped that way
+and needed this follow-up commit to publish 0.3.0.
+
 ## Security notes
 
 - The server can do exactly what the API key can do — nothing more. Scope the

package/dist/manifest/dtos.api.json

@@ -1183,6 +1183,11 @@
     "type": "{ [index: string]: string }",
     "optional": true
    },
+   {
+    "name": "slug",
+    "type": "string",
+    "optional": true
+   },
    {
     "name": "description",
     "type": "string",
@@ -1283,6 +1288,11 @@
     "type": "{ [index: string]: string }",
     "optional": true
    },
+   {
+    "name": "slug",
+    "type": "string",
+    "optional": true
+   },
    {
     "name": "description",
     "type": "string",
@@ -1791,6 +1801,16 @@
     "name": "translateOptions",
     "type": "IReadOnlyDictionary<string, string>",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "string",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
    }
   ]
  },
@@ -1811,6 +1831,31 @@
     "name": "multipleOf",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
+ },
+ "CurrencyDefaultDto": {
+  "base": null,
+  "fields": [
+   {
+    "name": "value",
+    "type": "number",
+    "optional": false
+   },
+   {
+    "name": "currency",
+    "type": "string",
+    "optional": false
    }
   ]
  },
@@ -1821,12 +1866,38 @@
     "name": "allowedCurrencies",
     "type": "IReadOnlyList<string>",
     "optional": true
+   },
+   {
+    "name": "multipleOf",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "minimum",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maximum",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "default",
+    "type": "CurrencyDefaultDto",
+    "optional": true
    }
   ]
  },
  "BooleanFieldDto": {
   "base": "JsonSchemaFieldDto",
-  "fields": []
+  "fields": [
+   {
+    "name": "default",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
  },
  "DateFieldDto": {
   "base": "JsonSchemaFieldDto",
@@ -1840,6 +1911,11 @@
     "name": "maximum",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -1855,6 +1931,16 @@
     "name": "maximum",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
    }
   ]
  },
@@ -1870,7 +1956,23 @@
  },
  "TagsFieldDto": {
   "base": "JsonSchemaFieldDto",
-  "fields": []
+  "fields": [
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "default",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
  },
  "FileFieldDto": {
   "base": "JsonSchemaFieldDto",
@@ -1879,6 +1981,26 @@
     "name": "storages",
     "type": "IReadOnlyList<string>",
     "optional": true
+   },
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "allowedFileType",
+    "type": "string",
+    "optional": true
+   },
+   {
+    "name": "maxSizeMb",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -1894,6 +2016,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -1924,6 +2051,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -1934,6 +2066,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -1949,6 +2086,61 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "default",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
+ },
+ "ObjectFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "properties",
+    "type": "IReadOnlyList<JsonSchemaFieldDto>",
+    "optional": false
+   },
+   {
+    "name": "required",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
+ },
+ "ArrayFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "items",
+    "type": "JsonSchemaFieldDto",
+    "optional": false
+   },
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "uniqueItems",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
+ },
+ "JsonFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "maxBytes",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -2535,6 +2727,26 @@
    }
   ]
  },
+ "GetFileByIdResponse": {
+  "base": "ResponseBase",
+  "fields": [
+   {
+    "name": "file",
+    "type": "FileResourceRefDto",
+    "optional": true
+   },
+   {
+    "name": "isPublic",
+    "type": "boolean",
+    "optional": true
+   },
+   {
+    "name": "publicUrl",
+    "type": "string",
+    "optional": true
+   }
+  ]
+ },
  "GetFileInfoResponse": {
   "base": "ResponseBase",
   "fields": [
@@ -3986,6 +4198,11 @@
     "name": "sortOrder",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "expandReferences",
+    "type": "boolean",
+    "optional": false
    }
   ]
  },
@@ -4006,6 +4223,11 @@
     "name": "databaseIntegrationId",
     "type": "string",
     "optional": true
+   },
+   {
+    "name": "expandReferences",
+    "type": "boolean",
+    "optional": false
    }
   ]
  },
@@ -4036,6 +4258,11 @@
     "name": "pagingArgs",
     "type": "PagingArgs",
     "optional": true
+   },
+   {
+    "name": "expandReferences",
+    "type": "boolean",
+    "optional": false
    }
   ]
  },
@@ -4131,6 +4358,11 @@
     "name": "update",
     "type": "string",
     "optional": false
+   },
+   {
+    "name": "arrayFilters",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -4156,6 +4388,11 @@
     "name": "update",
     "type": "string",
     "optional": false
+   },
+   {
+    "name": "arrayFilters",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -4274,6 +4511,21 @@
    }
   ]
  },
+ "GetFileByIdRequest": {
+  "base": "CodeMashRequestBase",
+  "fields": [
+   {
+    "name": "filesIntegrationId",
+    "type": "string",
+    "optional": false
+   },
+   {
+    "name": "id",
+    "type": "string",
+    "optional": false
+   }
+  ]
+ },
  "GetFileInfoRequest": {
   "base": "CodeMashRequestBase",
   "fields": [

package/dist/manifest/dtos.hub.json

@@ -10660,6 +10660,11 @@
     "type": "{ [index: string]: string }",
     "optional": true
    },
+   {
+    "name": "slug",
+    "type": "string",
+    "optional": true
+   },
    {
     "name": "description",
     "type": "string",
@@ -10760,6 +10765,11 @@
     "type": "{ [index: string]: string }",
     "optional": true
    },
+   {
+    "name": "slug",
+    "type": "string",
+    "optional": true
+   },
    {
     "name": "description",
     "type": "string",
@@ -12623,6 +12633,11 @@
     "type": "string",
     "optional": false
    },
+   {
+    "name": "env",
+    "type": "string",
+    "optional": true
+   },
    {
     "name": "eventName",
     "type": "string",
@@ -12743,6 +12758,11 @@
     "type": "string",
     "optional": true
    },
+   {
+    "name": "env",
+    "type": "string",
+    "optional": false
+   },
    {
     "name": "meta",
     "type": "IReadOnlyDictionary<string, string>",
@@ -15322,6 +15342,16 @@
     "name": "translateOptions",
     "type": "IReadOnlyDictionary<string, string>",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "string",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
    }
   ]
  },
@@ -15342,6 +15372,31 @@
     "name": "multipleOf",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
+ },
+ "CurrencyDefaultDto": {
+  "base": null,
+  "fields": [
+   {
+    "name": "value",
+    "type": "number",
+    "optional": false
+   },
+   {
+    "name": "currency",
+    "type": "string",
+    "optional": false
    }
   ]
  },
@@ -15352,12 +15407,38 @@
     "name": "allowedCurrencies",
     "type": "IReadOnlyList<string>",
     "optional": true
+   },
+   {
+    "name": "multipleOf",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "minimum",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maximum",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "default",
+    "type": "CurrencyDefaultDto",
+    "optional": true
    }
   ]
  },
  "BooleanFieldDto": {
   "base": "JsonSchemaFieldDto",
-  "fields": []
+  "fields": [
+   {
+    "name": "default",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
  },
  "DateFieldDto": {
   "base": "JsonSchemaFieldDto",
@@ -15371,6 +15452,11 @@
     "name": "maximum",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -15386,6 +15472,16 @@
     "name": "maximum",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "default",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "unique",
+    "type": "boolean",
+    "optional": true
    }
   ]
  },
@@ -15401,7 +15497,23 @@
  },
  "TagsFieldDto": {
   "base": "JsonSchemaFieldDto",
-  "fields": []
+  "fields": [
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "default",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
  },
  "FileFieldDto": {
   "base": "JsonSchemaFieldDto",
@@ -15410,6 +15522,26 @@
     "name": "storages",
     "type": "IReadOnlyList<string>",
     "optional": true
+   },
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "allowedFileType",
+    "type": "string",
+    "optional": true
+   },
+   {
+    "name": "maxSizeMb",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -15425,6 +15557,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -15455,6 +15592,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -15465,6 +15607,11 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "displayField",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -15480,6 +15627,61 @@
     "name": "multiple",
     "type": "boolean",
     "optional": false
+   },
+   {
+    "name": "default",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
+ },
+ "ObjectFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "properties",
+    "type": "IReadOnlyList<JsonSchemaFieldDto>",
+    "optional": false
+   },
+   {
+    "name": "required",
+    "type": "IReadOnlyList<string>",
+    "optional": true
+   }
+  ]
+ },
+ "ArrayFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "items",
+    "type": "JsonSchemaFieldDto",
+    "optional": false
+   },
+   {
+    "name": "minItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "maxItems",
+    "type": "number",
+    "optional": true
+   },
+   {
+    "name": "uniqueItems",
+    "type": "boolean",
+    "optional": true
+   }
+  ]
+ },
+ "JsonFieldDto": {
+  "base": "JsonSchemaFieldDto",
+  "fields": [
+   {
+    "name": "maxBytes",
+    "type": "number",
+    "optional": true
    }
   ]
  },
@@ -16744,6 +16946,26 @@
    }
   ]
  },
+ "GetFileByIdResponse": {
+  "base": "ResponseBase",
+  "fields": [
+   {
+    "name": "file",
+    "type": "FileResourceRefDto",
+    "optional": true
+   },
+   {
+    "name": "isPublic",
+    "type": "boolean",
+    "optional": true
+   },
+   {
+    "name": "publicUrl",
+    "type": "string",
+    "optional": true
+   }
+  ]
+ },
  "GetFolderFilesResponse": {
   "base": "ResponseBase",
   "fields": [
@@ -22845,6 +23067,11 @@
     "name": "sortOrder",
     "type": "number",
     "optional": true
+   },
+   {
+    "name": "expandReferences",
+    "type": "boolean",
+    "optional": false
    }
   ]
  },
@@ -22865,6 +23092,11 @@
     "name": "databaseIntegrationId",
     "type": "string",
     "optional": true
+   },
+   {
+    "name": "expandReferences",
+    "type": "boolean",
+    "optional": false
    }
   ]
  },
@@ -22995,6 +23227,11 @@
     "name": "update",
     "type": "string",
     "optional": false
+   },
+   {
+    "name": "arrayFilters",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -23020,6 +23257,11 @@
     "name": "update",
     "type": "string",
     "optional": false
+   },
+   {
+    "name": "arrayFilters",
+    "type": "string",
+    "optional": true
    }
   ]
  },
@@ -23513,6 +23755,21 @@
    }
   ]
  },
+ "GetFileById": {
+  "base": "CodeMashRequestBase",
+  "fields": [
+   {
+    "name": "filesIntegrationId",
+    "type": "string",
+    "optional": false
+   },
+   {
+    "name": "id",
+    "type": "string",
+    "optional": false
+   }
+  ]
+ },
  "GetFolderFiles": {
   "base": "CodeMashListPaginationRequestBase",
   "fields": [

package/dist/manifest/endpoints.json

@@ -3578,6 +3578,17 @@
   "pathParams": [],
   "scope": "project"
  },
+ {
+  "surface": "hub",
+  "group": "files",
+  "method": "getFileById",
+  "requestDto": "GetFileById",
+  "responseDto": "GetFileByIdResponse",
+  "path": "/{version}/files/item/by-id",
+  "verb": "GET",
+  "pathParams": [],
+  "scope": "project"
+ },
  {
   "surface": "hub",
   "group": "files",
@@ -7185,6 +7196,20 @@
   ],
   "scope": "project"
  },
+ {
+  "surface": "api",
+  "group": "files",
+  "method": "getFileById",
+  "requestDto": "GetFileByIdRequest",
+  "responseDto": "GetFileByIdResponse",
+  "path": "/{version}/files/{filesIntegrationId}/by-id/{id}",
+  "verb": "GET",
+  "pathParams": [
+   "filesIntegrationId",
+   "id"
+  ],
+  "scope": "project"
+ },
  {
   "surface": "api",
   "group": "files",

package/dist/server.js

@@ -72,7 +72,6 @@ export const curated = [
     { name: 'norbix_get_marketplace_integrations', surface: 'hub', group: 'code', method: 'getMarketplaceIntegrations', description: 'List marketplace integrations of the project.' },
     { name: 'norbix_save_marketplace_integration', surface: 'hub', group: 'code', method: 'saveMarketplaceIntegration', description: 'Create or update a marketplace integration.' },
     { name: 'norbix_get_database_schemas', surface: 'hub', group: 'database', method: 'getDatabaseSchemas', description: 'List database collection schemas of the project.' },
-    { name: 'norbix_find_documents', surface: 'api', group: 'database', method: 'find', description: 'Query documents in a database collection (filter, sort, projection, paging).' },
     { name: 'norbix_get_roles', surface: 'hub', group: 'membership', method: 'getRoles', description: 'List membership roles of the project.' },
     { name: 'norbix_get_policies', surface: 'hub', group: 'membership', method: 'getPolicies', description: 'List membership policies of the project.' },
     { name: 'norbix_get_logs', surface: 'hub', group: 'logs', method: 'getLogs', description: 'Query project logs.' },
@@ -106,6 +105,69 @@ export function buildServer(handle) {
         .string()
         .optional()
         .describe('Database integration id; omit for the project default database.');
+    const expandReferences = z
+        .boolean()
+        .optional()
+        .describe('true = every reference field (user, role, taxonomy term, collection record, file) comes back as { id, display } — an array of them when the field is multiple. display is the target’s displayField (a term: { title, slug? }); null when the target is missing or your key may not read it. Default false = the stored ids only.');
+    server.registerTool('norbix_find_documents', {
+        title: 'norbix_find_documents',
+        description: 'Query documents in a database collection: MongoDB filter, sort, cursor paging, optional reference expansion. [GET /{version}/database/collections/{collectionName}]',
+        inputSchema: {
+            collectionName: z.string().describe('Collection (schema) name, e.g. "products".'),
+            filter: jsonValue.optional().describe('MongoDB filter (object or JSON string), e.g. { "price": { "$gt": 5 } }.'),
+            sortBy: z.string().optional().describe('Field to sort by.'),
+            sortOrder: z.number().int().optional().describe('1 = ascending, -1 = descending.'),
+            pageSize: z.number().int().min(1).max(1000).optional(),
+            startingAfter: z.string().optional().describe('Cursor paging: id of the last document of the previous page.'),
+            endingBefore: z.string().optional().describe('Cursor paging: id of the first document of the next page.'),
+            expandReferences,
+            databaseIntegrationId: integrationId,
+            body: z
+                .record(z.unknown())
+                .optional()
+                .describe('Any other FindRequest field (schemaVersion, pagingArgs, …). The named inputs above win over the same key here.'),
+        },
+    }, async ({ collectionName, filter, sortBy, sortOrder, pageSize, startingAfter, endingBefore, expandReferences: expand, databaseIntegrationId, body }) => {
+        try {
+            return json(await invoke(handle.client, 'api', 'database', 'find', {
+                ...(body ?? {}),
+                collectionName,
+                ...(filter !== undefined ? { filter: asJson(filter) } : {}),
+                ...(sortBy !== undefined ? { sortBy } : {}),
+                ...(sortOrder !== undefined ? { sortOrder } : {}),
+                ...(pageSize !== undefined ? { pageSize } : {}),
+                ...(startingAfter !== undefined ? { startingAfter } : {}),
+                ...(endingBefore !== undefined ? { endingBefore } : {}),
+                ...(expand !== undefined ? { expandReferences: expand } : {}),
+                ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.registerTool('norbix_find_one_document', {
+        title: 'norbix_find_one_document',
+        description: 'Get one document by id, with optional reference expansion. [GET /{version}/database/collections/{collectionName}/{id}]',
+        inputSchema: {
+            collectionName: z.string().describe('Collection (schema) name.'),
+            id: z.string().describe('Document id.'),
+            expandReferences,
+            databaseIntegrationId: integrationId,
+        },
+    }, async ({ collectionName, id, expandReferences: expand, databaseIntegrationId }) => {
+        try {
+            return json(await invoke(handle.client, 'api', 'database', 'findOne', {
+                collectionName,
+                id,
+                ...(expand !== undefined ? { expandReferences: expand } : {}),
+                ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
     server.registerTool('norbix_insert_document', {
         title: 'norbix_insert_document',
         description: 'Insert one document into a database collection. Returns the new id. [POST /{version}/database/collections/{collectionName}]',
@@ -133,14 +195,18 @@ export function buildServer(handle) {
             collectionName: z.string().describe('Collection (schema) name.'),
             id: z.string().describe('Document id.'),
             update: jsonValue.describe('The fields to change as a plain document, e.g. { "field": "value" } (object or JSON string). No $ operators.'),
+            arrayFilters: jsonValue
+                .optional()
+                .describe('MongoDB arrayFilters for positional paths in update, e.g. update { "items.$[i].qty": 2 } with arrayFilters [ { "i.sku": "A1" } ] (array or JSON string).'),
             databaseIntegrationId: integrationId,
         },
-    }, async ({ collectionName, id, update, databaseIntegrationId }) => {
+    }, async ({ collectionName, id, update, arrayFilters, databaseIntegrationId }) => {
         try {
             return json(await invoke(handle.client, 'api', 'database', 'updateOne', {
                 collectionName,
                 id,
                 update: asJson(update),
+                ...(arrayFilters !== undefined ? { arrayFilters: asJson(arrayFilters) } : {}),
                 ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
             }));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norbix.ai/mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Norbix MCP server — manage projects, integrations, databases, membership, notifications and every other Norbix Hub/API endpoint from Claude, Cursor, VS Code, Windsurf or any MCP client.",
   "author": "UAB Isidos",
   "license": "MIT",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@norbix.ai/ts": "^4.11.0",
+    "@norbix.ai/ts": "^4.14.0",
     "express": "^4.21.2",
     "zod": "^3.24.0"
   },