@vectros-ai/mcp-server 0.11.0 → 0.13.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 
-// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
+// node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -2432,7 +2432,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/access-log");
   }
   /**
-   * Lists all of your scoped API keys (`ssk_*`) across both your live and test environments. Revoked keys are excluded. Requires the `keys:r` scope.
+   * Lists your scoped API keys (`ssk_*`) in your credential's own environment — a live key lists live keys, a test key lists test keys. Revoked keys are excluded. Requires the `keys:r` scope.
    *
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
@@ -2815,7 +2815,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
+   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope, and applies the same `identityOverrides` bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
    *
    * @param {Vectros.CreateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3233,7 +3233,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:u` scope.
+   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its `identityOverrides` are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (`sk_`) is exempt. Requires the `profiles:u` scope.
    *
    * @param {Vectros.UpdateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3306,7 +3306,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. Requires the `profiles:d` scope.
+   * Deletes an access profile. Within about five minutes (the access-profile cache lifetime), token minting for this principal in this context will be denied. If you use a scoped credential and the profile carries `identityOverrides`, you may only delete it when you hold those values yourself — deleting a profile removes its identity, so the same bound applies as when clearing it. A profile with no `identityOverrides` is unaffected, and a root API key (`sk_`) is exempt. Requires the `profiles:d` scope.
    *
    * @param {Vectros.DeleteAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4160,7 +4160,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/token");
   }
   /**
-   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `admin:users` scope.
+   * Invite a new member to one of your app contexts by email. Creates a pending user with a pre-resolved access profile (their permissions on accept) and signs an invitation token. This call is idempotent on the combination of context and email: re-inviting the same email in the same context rotates the token and resends the invitation rather than creating a duplicate — this requires the `users:r` and `users:u` scopes in addition to `users:c`, because resending rotates a credential on an existing invitation and invalidates any link already sent. Without them the collision returns 409 instead, with no invitation details and no change to the outstanding invitation. Returns HTTP 201 on a new invite or a successful resend. Returns 409 if that email already belongs to an active or suspended member of the app context, or already has an identity elsewhere in your account (an email can currently belong to only one tenant per account, i.e. your test and live environments cannot share an email). When `sendEmail` is false, the response includes the raw token and a ready-to-use accept link so you can deliver the invitation through your own email provider. Requires the `users:c` scope.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4231,7 +4231,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/invite");
   }
   /**
-   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Requires the `admin:users` scope.
+   * Resend an outstanding invitation, identified by its email and app context. Rotates the invitation token and extends its expiry, then (when `sendEmail` is true) re-delivers the email. Rotating the token invalidates any previously issued link for this invitation, so only the newest link works. The invitee's pending permissions are left unchanged. Because this rotates a credential on an existing invitation, it requires the `users:c`, `users:r` and `users:u` scopes.
    *
    * @param {Vectros.CreateInviteRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4565,7 +4565,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-   *         startFrom: "doc_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listDocuments(request = {}, requestOptions) {
@@ -4613,7 +4613,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents");
   }
   /**
-   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope.
+   * Creates a document from a raw text string and queues it for asynchronous indexing so it becomes searchable. Optionally supply an `externalId` to make the create idempotent — if a document with the same `externalId` already exists in your context, that existing document is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing document was returned) tells the two apart. To overwrite an existing document's content instead of returning it unchanged, set `?upsert=true` (this also requires the `documents:u` scope). Requires the `documents:c` scope to create. Being returned the existing document on a collision is a read of that document's data and additionally requires the `documents:r` scope — a credential holding `documents:c` alone receives a `400` ("already exists") on collision instead of the document.
    *
    * @param {Vectros.IngestDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4875,6 +4875,7 @@ var DocumentsClient = class {
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -4922,6 +4923,8 @@ var DocumentsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -4939,25 +4942,29 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/documents/{id}");
   }
   /**
-   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
+   * Finds documents of a given type by field value. Supported fields: `externalId` (the document's first-class external identifier — no schema declaration required) and any field declared as a lookup field on the bound schema. A lookup on a sensitive field is rejected here because the value would appear in the URL query string; use POST /v1/documents/lookup (the request-body variant) for a sensitive field instead. `type`'s schema resolves with basedOn-aware shadowing: your own `userId`- or `scope`-owned variant if you have one, otherwise the shared base — for a scoped credential the owner is always your own token identity; `userId`/`scope` here only apply as an explicit owner selector for a root API key. Results are paginated: set `limit` for the page size and feed the returned `nextCursor` back as `startFrom` to fetch the next page. The response is a `{data, nextCursor}` envelope. Requires the `documents:r` scope.
    *
    * @param {Vectros.LookupDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.documents.lookupDocuments({
    *         type: "invoice",
    *         field: "po_number",
    *         value: "PO-1001",
    *         prefix: "PO-2024",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
+   *         userId: "550e8400-e29b-41d4-a716-446655440000",
+   *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    *     })
    */
   lookupDocuments(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupDocuments(request, requestOptions));
   }
   async __lookupDocuments(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order } = request;
+    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, order, userId, scope } = request;
     const _queryParams = {
       type: type_,
       field,
@@ -4967,7 +4974,9 @@ var DocumentsClient = class {
       prefix,
       startFrom,
       limit,
-      order: order != null ? order : void 0
+      order: order != null ? order : void 0,
+      userId,
+      scope
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -4993,11 +5002,16 @@ var DocumentsClient = class {
       return { data: _response.body, rawResponse: _response.rawResponse };
     }
     if (_response.error.reason === "status-code") {
-      throw new VectrosError({
-        statusCode: _response.error.statusCode,
-        body: _response.error.body,
-        rawResponse: _response.rawResponse
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/lookup");
   }
@@ -5317,7 +5331,7 @@ var FoldersClient = class {
    *         parentFolderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "fld_prev123"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listFolders(request = {}, requestOptions) {
@@ -5365,7 +5379,7 @@ var FoldersClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/folders");
   }
   /**
-   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope.
+   * Creates a folder to organize your documents and records. If `parentFolderId` is omitted, the folder is created under your context's default root folder. Folder creation is idempotent by (slug + parent): if a folder with the same slug already exists under the same parent, that existing folder is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing folder was returned) tells the two apart. To overwrite an existing folder's mutable fields instead of returning it unchanged, set `?upsert=true` (this also requires the `folders:u` scope). Requires the `folders:c` scope to create. Being returned the existing folder on a collision is a read of that folder's data and additionally requires the `folders:r` scope — a credential holding `folders:c` alone receives a `400` ("already exists") on collision instead of the folder.
    *
    * @param {Vectros.CreateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5494,6 +5508,7 @@ var FoldersClient = class {
    * @param {Vectros.UpdateFolderRequest} request
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -5538,6 +5553,8 @@ var FoldersClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -5620,6 +5637,7 @@ var FoldersClient = class {
    * @param {FoldersClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -5667,6 +5685,8 @@ var FoldersClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -5754,7 +5774,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.listEntities({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listEntities(request, requestOptions) {
@@ -5823,7 +5844,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/entities/{namespace}");
   }
   /**
-   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope.
+   * Creates a new entity in the given namespace. This call is idempotent on `externalId` within the namespace: if an entity with the same `externalId` already exists, the existing record is returned instead of creating a duplicate (`created: false`, HTTP 200). To overwrite an existing entity's content instead of returning it unchanged, set `?upsert=true` (also requires the `entities:u:<namespace>` scope). The namespace must be entity-backed (`org`/`client`, or registered via `POST /v1/namespaces`). Requires the `entities:c:<namespace>` scope to create. Being returned the existing entity on a collision is a read of that entity's data and additionally requires the `entities:r:<namespace>` scope — a credential holding `entities:c:<namespace>` alone receives a `400` ("already in use") on collision instead of the entity.
    *
    * @param {Vectros.CreateEntityRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6267,7 +6288,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces/{namespace}");
   }
   /**
-   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
+   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`, `specificityRank`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
    *
    * @param {Vectros.UpdateNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6280,7 +6301,8 @@ var IdentityClient = class {
    *     await client.identity.updateNamespace({
    *         namespace: "team",
    *         body: {
-   *             namespace: "team"
+   *             namespace: "team",
+   *             specificityRank: 1500
    *         }
    *     })
    */
@@ -6445,7 +6467,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces");
   }
   /**
-   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
+   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Also requires `specificityRank`, an explicit, account-unique position in the specificity order used to break recordType schema-resolution ties. Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
    *
    * @param {Vectros.NamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6456,7 +6478,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.registerNamespace({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         specificityRank: 1500
    *     })
    */
   registerNamespace(request, requestOptions) {
@@ -6516,7 +6539,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.listUsers({
    *         externalId: "usr_12345",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000",
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl",
    *         type: "person_v1",
    *         field: "team",
    *         value: "engineering",
@@ -6573,7 +6596,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users");
   }
   /**
-   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope.
+   * Creates a user identity in your account. The operation is idempotent on `externalId`: if a user with the same `externalId` already exists, the existing record is returned instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing user was returned) tells the two apart. To overwrite an existing user's mutable fields (email, status, payload, schema binding) instead of returning it unchanged, set `?upsert=true` (this also requires the `users:u` scope). Requires the `users:c` scope to create. Being returned the existing user on a collision is a read of that user's data and additionally requires the `users:r` scope — a credential holding `users:c` alone receives a `400` ("already exists") on collision instead of the user.
    *
    * @param {Vectros.CreateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6697,11 +6720,12 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/{id}");
   }
   /**
-   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
+   * Updates mutable fields on an existing user (such as email, status, payload, or schema binding). The `type` field is immutable after creation, and `email` cannot be changed while an invitation to that user is still outstanding — revoke the invitation, or invite the new address instead. This endpoint also activates an invited user: a PUT that moves a PENDING user to ACTIVE and carries `inviteToken`, `externalSubject`, and `emailVerifiedAttestation=true` completes the invitation. Requires the `users:u` scope.
    *
    * @param {Vectros.UpdateUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -6746,6 +6770,8 @@ var IdentityClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -7393,7 +7419,7 @@ var RecordsClient = class {
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "group:eng-team",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listRecords(request = {}, requestOptions) {
@@ -7444,7 +7470,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records");
   }
   /**
-   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope.
+   * Creates a new record of a given type. The `payload` is validated against that type's schema before the record is stored. Identify the type by sending `typeName`, `schemaId`, or both (they must agree); if you send only `schemaId`, the type is taken from that schema. Optionally supply an `externalId` to make the create idempotent — if a record with the same `externalId` already exists in your context, that existing record is returned unchanged instead of a duplicate being created. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing record was returned) tells the two apart. To overwrite an existing record's content instead of returning it unchanged, set `?upsert=true` (this also requires the `records:u:<type>` scope). Requires the `records:c:<type>` scope to create. Being returned the existing record on a collision is a read of that record's data and additionally requires the `records:r:<type>` scope — a credential holding `records:c:<type>` alone receives a `400` ("already exists") on collision instead of the record.
    *
    * @param {Vectros.CreateRecordRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7581,6 +7607,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -7629,6 +7656,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -7710,6 +7739,7 @@ var RecordsClient = class {
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -7760,6 +7790,8 @@ var RecordsClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 409:
@@ -7777,7 +7809,15 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PATCH", "/v1/records/{id}");
   }
   /**
-   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields. Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. Requires the `records:r:<type>` scope.
+   * Finds records by the value of a lookup field declared on the type's schema. Provide exactly one lookup mode: `value` (exact match), `from`+`to` (inclusive range, ascending by value), or `prefix` (string fields only, ascending). Range and prefix lookups are not supported on a sensitive field, because its value is stored as a blind index and has no sortable order. An exact-`value` lookup on a sensitive field is also rejected on this GET endpoint — the value must not appear in the URL — so use the `POST /v1/records/lookup` body variant for sensitive fields.
+   *
+   * A `value` lookup can additionally be narrowed to a window of the lookup field's **sort key** using `sortFrom` and/or `sortTo` (inclusive) — for example, one session's records created since a timestamp. The sort key is whatever the schema declares as that lookup's `sortBy` (`createdAt` by default, `lastUpdated`, or another field), and bounds are given in that field's own units — epoch milliseconds for the two timestamp options. **Records that have no value for the sorted field are never included in a bounded window** — they are ordered ahead of every record that does have one, and a `sortFrom`/`sortTo` window only ever selects from records carrying a value. The sorted field does not have to be `required`.
+   *
+   * Narrowing is available on any lookup field your schema declares for fast equality lookup, and on `externalId` — which is always ordered by creation time, so its bounds are epoch milliseconds whatever the schema says. It is rejected (`400`) for a field declared with `rangeEnabled`, for a field declared beyond the schema's fast-lookup budget, for a lookup whose `sortBy` names a sensitive field (a sensitive value is stored as a blind index and has no order), and for a window whose start is after its end. Ownership fields are not lookup fields on this endpoint at all — see the `field` parameter.
+   *
+   * While paging a narrowed lookup, keep every other parameter identical. The cursor is valid only for the exact query that returned it — changing `order`, `sortFrom`, `sortTo`, or dropping them altogether, is rejected rather than silently resumed at a position that means something different in the new query.
+   *
+   * Results are paginated: set `limit` for the page size and pass the returned `nextCursor` back as `startFrom` for the next page. **Keep paging until `nextCursor` is null** — a page can come back empty or shorter than `limit` while more results remain, so an empty page is not the end of the results. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.LookupRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7789,22 +7829,40 @@ var RecordsClient = class {
    *         type: "intake_form",
    *         field: "email",
    *         value: "jane@example.com",
+   *         values: ["open"],
    *         prefix: "jane",
-   *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   lookupRecords(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__lookupRecords(request, requestOptions));
   }
   async __lookupRecords(request, requestOptions) {
-    const { type: type_, field, value, from: from_, to, prefix, startFrom, limit, includePayload, order } = request;
+    const {
+      type: type_,
+      field,
+      value,
+      values,
+      from: from_,
+      to,
+      prefix,
+      sortFrom,
+      sortTo,
+      startFrom,
+      limit,
+      includePayload,
+      order
+    } = request;
     const _queryParams = {
       type: type_,
       field,
       value,
+      values,
       from: from_,
       to,
       prefix,
+      sortFrom,
+      sortTo,
       startFrom,
       limit,
       includePayload,
@@ -7848,7 +7906,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/records/lookup");
   }
   /**
-   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant. Requires the `records:r:<type>` scope.
+   * Body-based equivalent of `GET /v1/records/lookup`. Use this when looking up by a sensitive field: the value travels in the request body (and is blind-indexed server-side) instead of in the URL query string, so it never lands in access, CDN, or proxy logs. The GET variant rejects an exact-value lookup on a sensitive field and directs you here. Non-sensitive exact-value, range (`from`+`to`), and prefix lookups also work here, as does narrowing a `value` lookup by the field's sort key with `sortFrom`/`sortTo` — see the GET variant for what the sort key is and when narrowing by it is available. Returns the same `{data, nextCursor}` envelope and uses the same pagination as the GET variant; keep paging until `nextCursor` is null rather than stopping on an empty page. Requires the `records:r:<type>` scope.
    *
    * @param {Vectros.RecordLookupRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8035,13 +8093,15 @@ var SchemasClient = class {
    * @param {Vectros.ListSchemasRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
+   *
    * @example
    *     await client.schemas.listSchemas({
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         scope: "org:6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         surface: "document",
    *         recordType: "intake_form",
-   *         startFrom: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+   *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
   listSchemas(request = {}, requestOptions) {
@@ -8081,16 +8141,21 @@ var SchemasClient = class {
       return { data: _response.body, rawResponse: _response.rawResponse };
     }
     if (_response.error.reason === "status-code") {
-      throw new VectrosError({
-        statusCode: _response.error.statusCode,
-        body: _response.error.body,
-        rawResponse: _response.rawResponse
-      });
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas");
   }
   /**
-   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:w` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:w` scope.
+   * Defines a new record type with optional field definitions, validation rules, and lookup indexes. Idempotent by `typeName` within the same ownership scope: re-creating an existing `typeName` returns the existing schema rather than failing. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing schema was returned) tells the two apart. To reconcile an existing schema to the submitted shape instead of returning it unchanged, set `?upsert=true` (this also requires the `schemas:u` scope; only legal schema changes are applied — migration-locked changes are rejected). Requires the `schemas:c` scope to create. Being returned the existing schema on a collision is a read of that schema's data and additionally requires the `schemas:r` scope — a credential holding `schemas:c` alone receives a `400` ("already in use") on collision instead of the schema.
    *
    * @param {Vectros.CreateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8234,12 +8299,13 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/schemas/{id}");
   }
   /**
-   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Requires the `schemas:w` scope.
+   * Updates a record schema. Fields you omit are preserved; `typeName` is immutable and cannot be changed. Collection fields (`fields`, `lookupFields`, `renderHints`, `capabilities`) are replaced in full when supplied. Requires the `schemas:u` scope.
    *
    * @param {Vectros.UpdateSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
@@ -8288,6 +8354,8 @@ var SchemasClient = class {
       switch (_response.error.statusCode) {
         case 400:
           throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
         case 429:
@@ -8303,7 +8371,7 @@ var SchemasClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/schemas/{id}");
   }
   /**
-   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. Requires the `schemas:w` scope.
+   * Permanently deletes a record schema. The request is refused with 409 if records of this type still exist — delete those records first, since every record must reference a live schema. A lineage base (a schema other schemas declare `basedOn`) also cannot be deleted while any such variant still exists — delete the variant schema(s) first. Requires the `schemas:d` scope.
    *
    * @param {Vectros.DeleteSchemaRequest} request
    * @param {SchemasClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8605,8 +8673,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.11.0" : "dev",
-  sdk: true ? "0.36.0" : "dev"
+  mcpServer: true ? "0.13.0" : "dev",
+  sdk: true ? "0.38.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -8649,7 +8717,9 @@ async function resolveIdentity({
   const derived = {
     status: "ok",
     environment: deriveEnvironment(environment),
-    principalType: derivePrincipalType(apiKey)
+    principalType: derivePrincipalType(apiKey),
+    mcpServerVersion: BUILD_INFO.mcpServer,
+    sdkVersion: BUILD_INFO.sdk
   };
   if (!apiKey || !environment) {
     log.debug({ component: "identity", mode: "derived-only" }, "identity derived (no fetch)");
@@ -8677,7 +8747,13 @@ async function resolveIdentity({
       );
     }
   }
-  const merged = { ...derived, ...extended, status: "ok" };
+  const merged = {
+    ...derived,
+    ...extended,
+    status: "ok",
+    mcpServerVersion: derived.mcpServerVersion,
+    sdkVersion: derived.sdkVersion
+  };
   log.debug(
     {
       component: "identity",
@@ -8999,14 +9075,23 @@ import { z as z2 } from "zod";
 function pageItems(page) {
   return page.data ?? [];
 }
+var MAX_PAGES = 100;
+var MAX_ROWS = 1e6;
 async function drainPages(fetchPage) {
   const all = [];
   let startFrom;
+  let pages = 0;
   for (; ; ) {
     const page = await fetchPage(startFrom);
-    if (page.data?.length) all.push(...page.data);
+    pages++;
+    if (page.data?.length) for (const item of page.data) all.push(item);
     const next = page.nextCursor;
     if (!next) break;
+    if (pages > MAX_PAGES || all.length > MAX_ROWS) {
+      throw new Error(
+        `drainPages: exceeded the runaway guard (${all.length} rows over ${pages} pages, limits ${MAX_ROWS}/${MAX_PAGES}) without the cursor going null. Refusing to return a partial result \u2014 the backend may be returning empty pages with a live cursor.`
+      );
+    }
     startFrom = next;
   }
   return all;
@@ -9017,14 +9102,23 @@ var MCP_DEFAULT_LIMIT2 = 3;
 var MCP_MAX_LIMIT2 = 100;
 var inputSchema2 = {
   type: z2.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
-  // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
+  // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | values | from+to | prefix.
   field: z2.string().optional().describe(
-    'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.)'
+    'Lookup mode: name of the lookup-indexed field to query by. `externalId` is always queryable \u2014 e.g. `{type:"control", field:"externalId", value:"ctrl-scoped-key"}` finds the record you created under that externalId. (record_get / record_update also accept externalId directly.) For a SCHEMA-declared composite lookup \u2014 check list_schemas\' lookupFields for a fieldNames entry, not any two fields you pick \u2014 give those field names comma-joined in the declared order (e.g. "status,area"). Use `values` to match on several of those fields at once, or `value` to match on just the FIRST field named (equivalent to a one-element `values`); range/prefix are not valid on a composite field.'
+  ),
+  value: z2.string().optional().describe(
+    "Lookup mode (equality): exact-match value for `field`. Also valid when `field` names a SCHEMA-declared composite lookup \u2014 matches just the first named field, grouping by the rest (equivalent to `values` with one entry)."
+  ),
+  values: z2.array(z2.string()).min(1).max(3).optional().describe(
+    'Lookup mode (composite equality): only valid against a lookup the SCHEMA declares over several fields together (a fieldNames entry in list_schemas \u2014 you cannot combine two ordinary single-field lookups this way). One value per field, in the order the schema declares them (e.g. field="status,area", values=["open","billing"]). Mutually exclusive with `value`; a single-element array is exactly `value` written uniformly. Supplying FEWER values than the lookup declares is allowed \u2014 as long as they\'re a leading run of its fields \u2014 and returns records grouped by the fields left unspecified; `order` then sorts within each group, not across them. Record lookups only (not documents/users/entities).'
   ),
-  value: z2.string().optional().describe("Lookup mode (equality): exact-match value for `field`."),
   from: z2.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
   to: z2.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
   prefix: z2.string().optional().describe("Lookup mode (prefix): match values starting with this. String, non-sensitive fields only."),
+  sortFrom: z2.string().optional().describe(
+    "Lookup mode (equality/composite only): inclusive lower bound on the lookup field's sort key, narrowing a `value`/`values` match to a window instead of paging the whole match. Give the bound in the sort field's own units (epoch milliseconds for `createdAt`/`lastUpdated`). With `values`, requires every value be supplied (no grouping) for one continuous ordering. Not valid with `from`/`to`/`prefix`."
+  ),
+  sortTo: z2.string().optional().describe("Lookup mode (equality/composite only): inclusive upper bound on the sort key; pairs with `sortFrom`."),
   order: z2.enum(["asc", "desc"]).optional().describe(
     "Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc` \u2014 use `desc` with a range/prefix lookup to get the most-recent / highest values first (e.g. latest-N). Ignored in list mode."
   ),
@@ -9041,54 +9135,106 @@ var inputSchema2 = {
 var recordQuery = ({ client, log }) => ({
   name: "record_query",
   title: "Record query (list or lookup)",
-  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId` or `scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected from the arguments present.",
+  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `values` (exact, composite \u2014 one value per field; a single-element array is the same as `value`), `from`+`to` (range), or `prefix`. `values` with more than one entry, or a comma-joined `field`, ONLY works for a lookup the schema itself declared over several fields together \u2014 check list_schemas' lookupFields for a fieldNames entry, then pass those field names comma-joined as `field`; `from`/`to`/`prefix` are not valid there. Works on sensitive fields too. Optionally narrow an exact match to a window with `sortFrom`/`sortTo`.\n  \u2022 List by type: omit `field`; optionally filter by `userId` or `scope` (`namespace:value`).\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. A composite lookup given fewer than its full field count returns records grouped by the unspecified fields, ordered within each group. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
     const type = args.type;
     const field = args.field;
     const value = args.value;
+    const values = args.values;
     const from = args.from;
     const to = args.to;
     const prefix = args.prefix;
+    const sortFrom = args.sortFrom;
+    const sortTo = args.sortTo;
     const startFrom = args.startFrom;
+    if (!field && (value !== void 0 || values !== void 0 || from !== void 0 || to !== void 0 || prefix !== void 0 || sortFrom !== void 0 || sortTo !== void 0)) {
+      return toolError(
+        "record_query",
+        new Error(
+          "'value'/'values'/'from'/'to'/'prefix'/'sortFrom'/'sortTo' require 'field' \u2014 without it, list mode runs and silently ignores them. Pass 'field' to run a lookup, or drop these to list by type."
+        )
+      );
+    }
     try {
       let page;
       if (field) {
+        const fieldNames = field.split(",").map((f) => f.trim()).filter(Boolean);
+        const normalizedField = fieldNames.join(",");
+        const isCompositeField = fieldNames.length > 1;
         const hasEquality = value !== void 0;
+        const hasComposite = values !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
         const hasPrefix = prefix !== void 0;
-        const modes = Number(hasEquality) + Number(hasRange) + Number(hasPrefix);
+        const modes = Number(hasEquality) + Number(hasComposite) + Number(hasRange) + Number(hasPrefix);
         if (modes === 0) {
           return toolError(
             "record_query",
             new Error(
-              `lookup on field '${field}' needs one of: 'value' (exact), 'from'+'to' (range), or 'prefix'.`
+              `lookup on field '${field}' needs one of: 'value' (exact), 'values' (composite exact), 'from'+'to' (range), or 'prefix'.`
             )
           );
         }
         if (modes > 1) {
           return toolError(
             "record_query",
-            new Error("'value', 'from'/'to', and 'prefix' are mutually exclusive \u2014 provide exactly one.")
+            new Error(
+              "'value', 'values', 'from'/'to', and 'prefix' are mutually exclusive \u2014 provide exactly one."
+            )
           );
         }
         if (hasRange && !(from !== void 0 && to !== void 0)) {
           return toolError("record_query", new Error("range lookup requires both 'from' and 'to'."));
         }
+        if (isCompositeField && (hasRange || hasPrefix)) {
+          return toolError(
+            "record_query",
+            new Error(
+              `'field' names ${fieldNames.length} fields ('${normalizedField}') \u2014 a composite lookup is exact-match only ('value' or 'values'), not 'from'/'to'/'prefix'.`
+            )
+          );
+        }
+        if (hasComposite && values.length > fieldNames.length) {
+          return toolError(
+            "record_query",
+            new Error(
+              `'values' has ${values.length} entries but 'field' names only ${fieldNames.length} field(s) ('${normalizedField}') \u2014 supply at most one value per field, in order (fewer only as a leading run).`
+            )
+          );
+        }
+        if (sortFrom !== void 0 || sortTo !== void 0) {
+          if (!(hasEquality || hasComposite)) {
+            return toolError(
+              "record_query",
+              new Error("'sortFrom'/'sortTo' narrow a 'value' or 'values' match only \u2014 not 'from'/'to'/'prefix'.")
+            );
+          }
+          if (hasComposite && values.length < fieldNames.length) {
+            return toolError(
+              "record_query",
+              new Error(
+                `'sortFrom'/'sortTo' with 'values' requires a value for every field named in 'field' (got ${values.length} of ${fieldNames.length}) \u2014 a partial/grouped match has no single continuous ordering to window.`
+              )
+            );
+          }
+        }
         page = await client.records.lookupRecordsByBody({
           type,
-          field,
+          field: normalizedField,
           value,
+          values,
           from,
           to,
           prefix,
+          sortFrom,
+          sortTo,
           order: args.order,
           startFrom,
           limit
         });
         log.debug(
-          { tool: "record_query", mode: "lookup", type, field, returned: pageItems(page).length },
+          { tool: "record_query", mode: "lookup", type, field: normalizedField, returned: pageItems(page).length },
           "record_query lookup ok"
         );
       } else {
@@ -9121,14 +9267,14 @@ var record_query_default = recordQuery;
 import { z as z3 } from "zod";
 
 // src/tools/resolve-external-id.ts
-function validateSelector(sel, entity) {
+function validateSelector(sel, entity, fieldName) {
   const hasId = sel.id !== void 0 && sel.id !== "";
   const hasExt = sel.externalId !== void 0 && sel.externalId !== "";
   if (hasId && hasExt) {
-    return `Provide either id or externalId (not both) to identify the ${entity}.`;
+    return `Provide either ${fieldName} or externalId (not both) to identify the ${entity}.`;
   }
   if (!hasId && !hasExt) {
-    return `Provide id, or externalId + type, to identify the ${entity}.`;
+    return `Provide ${fieldName}, or externalId + type, to identify the ${entity}.`;
   }
   if (hasExt && (sel.type === void 0 || sel.type === "")) {
     return "type is required when selecting by externalId (externalId is unique within a type).";
@@ -9136,7 +9282,7 @@ function validateSelector(sel, entity) {
   return void 0;
 }
 async function resolveRecordIdByExternalId(client, sel) {
-  const err = validateSelector(sel, "record");
+  const err = validateSelector(sel, "record", "id");
   if (err) return { error: err };
   if (sel.id) return { id: sel.id };
   const page = await client.records.lookupRecordsByBody({
@@ -9152,7 +9298,7 @@ async function resolveRecordIdByExternalId(client, sel) {
   return { id: items[0].id };
 }
 async function resolveDocumentIdByExternalId(client, sel) {
-  const err = validateSelector(sel, "document");
+  const err = validateSelector(sel, "document", "documentId");
   if (err) return { error: err };
   if (sel.id) return { id: sel.id };
   const page = await client.documents.lookupDocumentsByBody({
@@ -10027,7 +10173,7 @@ var inputSchema18 = {
 var currentIdentity = ({ log, apiKey, environment }) => ({
   name: "current_identity",
   title: "Current identity (tenant + principal scope)",
-  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Use this when the user asks 'what can you do here?' or 'what tenant am I in?'. Calls GET /v1/ping under the hood.",
+  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
   inputSchema: inputSchema18,
   handler: async () => {
     try {
@@ -10505,7 +10651,7 @@ var identityResource = ({ log, apiKey, environment }) => ({
   name: "identity",
   uri: "vectros://identity",
   title: "Current identity (tenant + principal scope)",
-  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }). The /v1/ping backing call ships this extended shape today.",
+  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }), plus mcpServerVersion and sdkVersion (this build's own version and the bundled @vectros-ai/sdk version). The /v1/ping backing call ships the extended shape today; the version fields are always client-derived.",
   mimeType: "application/json",
   read: async () => {
     const identity = await resolveIdentity({ log, apiKey, environment });