@vectros-ai/mcp-server 0.11.0 → 0.12.0

package/dist/index.mjs

@@ -1,7 +1,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)
@@ -4611,7 +4611,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.
@@ -4937,25 +4937,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: "550e8400-e29b-41d4-a716-446655440000",
+   *         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,
@@ -4965,7 +4969,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(
@@ -4991,11 +4997,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");
   }
@@ -5363,7 +5374,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.
@@ -5821,7 +5832,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.
@@ -6265,7 +6276,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.
@@ -6278,7 +6289,8 @@ var IdentityClient = class {
    *     await client.identity.updateNamespace({
    *         namespace: "team",
    *         body: {
-   *             namespace: "team"
+   *             namespace: "team",
+   *             specificityRank: 1500
    *         }
    *     })
    */
@@ -6443,7 +6455,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.
@@ -6454,7 +6466,8 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.registerNamespace({
-   *         namespace: "team"
+   *         namespace: "team",
+   *         specificityRank: 1500
    *     })
    */
   registerNamespace(request, requestOptions) {
@@ -6571,7 +6584,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.
@@ -7442,7 +7455,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.
@@ -8033,6 +8046,8 @@ 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",
@@ -8079,16 +8094,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.
@@ -8232,7 +8252,7 @@ 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.
@@ -8301,7 +8321,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.
@@ -8603,8 +8623,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.12.0" : "dev",
+  sdk: true ? "0.37.0" : "dev"
 };
 
 // src/log.ts
@@ -9116,14 +9136,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).";
@@ -9131,7 +9151,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({
@@ -9147,7 +9167,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({