@vectros-ai/mcp-server 0.10.0 → 0.11.0

package/dist/cli.js

@@ -26,7 +26,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/server.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 
-// node_modules/@vectros-ai/sdk/dist/index.mjs
+// ../../node_modules/@vectros-ai/sdk/dist/index.mjs
 var __defProp2 = Object.defineProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -61,6 +61,7 @@ __export(api_exports, {
   FileUploadRequest: () => FileUploadRequest,
   ForbiddenError: () => ForbiddenError,
   IdentityLookupRequest: () => IdentityLookupRequest,
+  IndexFailure: () => IndexFailure,
   InternalServerError: () => InternalServerError,
   ListEntitiesRequestOrder: () => ListEntitiesRequestOrder,
   ListUsersRequestOrder: () => ListUsersRequestOrder,
@@ -582,6 +583,17 @@ var IdentityLookupRequest;
     Desc: "desc"
   };
 })(IdentityLookupRequest || (IdentityLookupRequest = {}));
+var IndexFailure;
+((IndexFailure2) => {
+  IndexFailure2.Code = {
+    SourceUnavailable: "SOURCE_UNAVAILABLE",
+    TextIndexFailed: "TEXT_INDEX_FAILED",
+    EmbeddingFailed: "EMBEDDING_FAILED",
+    IndexingFailed: "INDEXING_FAILED",
+    VectorLimitExceeded: "VECTOR_LIMIT_EXCEEDED",
+    Internal: "INTERNAL"
+  };
+})(IndexFailure || (IndexFailure = {}));
 var ModelDataVersionResponse;
 ((ModelDataVersionResponse2) => {
   ModelDataVersionResponse2.ChangeType = {
@@ -4098,7 +4110,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user, organization, or client. Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
+   * Creates a short-lived JWT bearer token restricted to specific actions and, optionally, to a particular user or identity entity (in any namespace). Use this to hand a narrowly-scoped credential to a browser or downstream service so it never sees your root API key. Only callable with a root API key (`sk_*`).
    *
    * @param {Vectros.TokenRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4315,7 +4327,7 @@ var ComplianceClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Submits a right-to-erasure request for a single end-subject (a user, client, or organization). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
+   * Submits a right-to-erasure request for a single end-subject (a user, or an identity entity in any namespace). Erasure removes exactly the data the subject solely owns across the declared contexts, plus the subject's identity and lookup rows. It never touches another account's data and never cascades into another subject's data. The request is asynchronous: it returns 202 with a `requestId`; poll `GET /v1/erasure-requests/{id}` until the job completes to obtain the completion certificate. Requires a root API key — a scoped credential is rejected with 403.
    *
    * @param {Vectros.ErasureRequest} request
    * @param {ComplianceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8611,8 +8623,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.10.0" : "dev",
-  sdk: true ? "0.35.0" : "dev"
+  mcpServer: true ? "0.11.0" : "dev",
+  sdk: true ? "0.36.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -8819,31 +8831,45 @@ async function consumeStream(stream, onProgress) {
 }
 
 // src/tools/errors.ts
+function asErrorBody(body) {
+  if (body && typeof body === "object") return body;
+  return void 0;
+}
 function toolError(toolName, err, docPointer) {
   let summary = `${toolName} failed`;
   let detail = String(err);
+  let errorCode;
+  let requestId;
   if (err instanceof StreamError) {
     summary = `${toolName} stream error`;
     detail = err.message;
   } else if (err instanceof Error) {
     const e = err;
     detail = e.message;
+    const body = asErrorBody(e.body);
+    if (body) {
+      if (typeof body.message === "string" && body.message.trim().length > 0) detail = body.message;
+      if (typeof body.errorCode === "string" && body.errorCode.length > 0) errorCode = body.errorCode;
+      if (typeof body.requestId === "string" && body.requestId.length > 0) requestId = body.requestId;
+    }
     if (e.statusCode) {
-      summary = `${toolName} failed: HTTP ${e.statusCode}`;
+      summary = `${toolName} failed: HTTP ${e.statusCode}${errorCode ? ` (${errorCode})` : ""}`;
     } else if (e.name && e.name !== "Error") {
       summary = `${toolName} failed: ${e.name}`;
     }
   }
-  const pointer = docPointer ? `
+  const trailer = (errorCode ? `
+errorCode: ${errorCode}` : "") + (requestId ? `
+requestId: ${requestId}` : "") + (docPointer ? `
 
-See: ${docPointer}` : "";
+See: ${docPointer}` : "");
   return {
     isError: true,
     content: [
       {
         type: "text",
         text: `${summary}
-${detail}${pointer}`
+${detail}${trailer}`
       }
     ]
   };
@@ -8920,7 +8946,7 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: "Search your tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/scope), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller's scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:\"OR\".",
+  description: 'Search your tenant\'s indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/scope), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller\'s scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword (BM25) leg matched nothing (all textScores 0) \u2014 typically the default PHRASE mode finding no contiguous match for a long natural-language query. Loosen the keyword leg: shorten the query to its key terms, or set textMode "AND" (all terms, higher precision) or "OR" (any term, broad recall).',
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -9172,7 +9198,7 @@ var inputSchema3 = {
 var recordGet = ({ client, log }) => ({
   name: "record_get",
   title: "Get a record by id or externalId",
-  description: "Fetch a single structured record, including the full payload. Select it EITHER by its Vectros `id` (e.g. from record_query / hybrid_search) OR by your own `externalId` + `type` \u2014 the same key you passed to record_create, resolved for you (no manual record_query lookup needed). Very large payloads are truncated to protect the agent context window.",
+  description: "Fetch a single structured record, including the full payload. Select it EITHER by its Vectros `id` (e.g. from record_query / hybrid_search) OR by your own `externalId` + `type` \u2014 the same key you passed to record_create, resolved for you (no manual record_query lookup needed). Very large payloads are truncated to protect the agent context window. The response carries the record's processing `indexStatus`; when it is FAILED an `indexFailure.code` explains whether the content is still searchable (e.g. VECTOR_LIMIT_EXCEEDED keeps keyword search vs INDEXING_FAILED = not findable at all) \u2014 branch on the `code`, not the message.",
   inputSchema: inputSchema3,
   handler: async (args) => {
     const id = args.id;
@@ -9210,7 +9236,7 @@ var import_zod4 = require("zod");
 var inputSchema4 = {
   type: import_zod4.z.string().min(1, "type is required").describe('Record type / schema name (e.g. "task"). Must match an existing schema \u2014 see list_schemas.'),
   fields: import_zod4.z.record(import_zod4.z.string(), import_zod4.z.unknown()).describe(
-    "The record payload \u2014 a JSON object of field\u2192value, validated against the type schema. Call list_schemas to learn required fields, types, and enum values."
+    "The record payload \u2014 a JSON object of field\u2192value, validated against the type schema. Call list_schemas to learn required fields, types, and enum values. Every number must fall within the signed 64-bit range (a value outside it, or with >38 significant digits, is refused with a 400 naming the field) \u2014 send a larger whole number (e.g. a big external id) as a STRING, which stores it exactly and supports exact-match lookup."
   ),
   externalId: import_zod4.z.string().optional().describe(
     "Stable caller-supplied id. Immutable; unique per type. Re-creating with the same externalId returns the existing record (idempotent) \u2014 use it to make creates safely retryable."
@@ -9228,7 +9254,7 @@ var inputSchema4 = {
 var recordCreate = ({ client, log }) => ({
   name: "record_create",
   title: "Create a record",
-  description: "Create a structured record of a given type. Provide `type` and `fields` (the payload, validated against the type schema \u2014 call list_schemas first to learn required fields and enums). Idempotent by `externalId`. Requires the key to allow records:c.",
+  description: "Create a structured record of a given type. Provide `type` and `fields` (the payload, validated against the type schema \u2014 call list_schemas first to learn required fields and enums). Idempotent by `externalId`. Requires the key to allow records:c (and records:r to receive the existing record on a collision).",
   inputSchema: inputSchema4,
   handler: async (args) => {
     const type = args.type;
@@ -9586,7 +9612,7 @@ function isNotAvailable(err) {
 var documentGet = ({ client, log }) => ({
   name: "document_get",
   title: "Get document metadata (and optionally text)",
-  description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). Text is available for every text-ingested document and for file-ingested documents unless they were uploaded with `storeText: false` (extracted text discarded after indexing) \u2014 then `textAvailable: false` is set; the original file is still retrievable via `includeDownloadUrl`. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`.",
+  description: "Fetch metadata for a single document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). Text is available for every text-ingested document and for file-ingested documents unless they were uploaded with `storeText: false` (extracted text discarded after indexing) \u2014 then `textAvailable: false` is set; the original file is still retrievable via `includeDownloadUrl`. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns the full document metadata, including its lifecycle `status` (ACTIVE, or ARCHIVED when soft-retracted from search \u2014 restorable via document_update) and its processing `indexStatus`. When `indexStatus` is FAILED the response also carries `indexFailure` with a machine-readable `code` telling you whether the content is still findable \u2014 e.g. TEXT_INDEX_FAILED / VECTOR_LIMIT_EXCEEDED (one leg still serves it) vs INDEXING_FAILED (not findable by search at all). Branch on `code`, not on the message.",
   inputSchema: inputSchema10,
   handler: async (args) => {
     const documentId = args.documentId;
@@ -9920,7 +9946,7 @@ var inputSchema15 = {
 var folderCreate = ({ client, log }) => ({
   name: "folder_create",
   title: "Create a folder",
-  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent. Requires the key to allow folders:c.",
+  description: "Create a folder to organize documents and records. Pass `parentId` to nest it (create-only \u2014 folders cannot be moved later). Idempotent by `slug` within the parent. Requires the key to allow folders:c (and folders:r to receive the existing folder on a collision).",
   inputSchema: inputSchema15,
   handler: async (args) => {
     try {
@@ -10019,7 +10045,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, and (for scoped keys) allowedActions + dataScope. Use this when the user asks 'what can you do here?' or 'what tenant am I in?'. Calls GET /v1/ping under the hood. Backend may still be rolling out the extended /v1/ping response shape \u2014 until then this tool returns a minimal shape; richer fields appear automatically as backend ships.",
+  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.",
   inputSchema: inputSchema18,
   handler: async () => {
     try {
@@ -10117,7 +10143,7 @@ var inputSchema19 = {
     "Index strategy. HYBRID (BM25 + dense, default; best for general retrieval), SEMANTIC (dense only; concept-driven queries), TEXT (BM25 only; exact-match / keyword), NONE (store-only / archival \u2014 retrievable by id and structured-field lookup but never in search results). Omit to inherit the bound schema's default."
   ),
   externalId: import_zod18.z.string().optional().describe(
-    "Stable caller-supplied id. Immutable; unique per type within your context. Re-ingesting with the same externalId returns the existing document (idempotent) instead of creating a duplicate \u2014 use it to make ingests safely retryable and as the key other records reference. Mirrors record_create."
+    'Stable caller-supplied id. Immutable; unique per type within your context. Re-ingesting with the same externalId returns the existing document (idempotent) instead of creating a duplicate \u2014 use it to make ingests safely retryable and as the key other records reference. Mirrors record_create. Receiving the existing document back is a read of it and needs documents:r in addition to documents:c; a create-only key gets an "already exists" error instead of the document.'
   ),
   upsert: import_zod18.z.boolean().optional().describe(
     "When true, re-ingesting an existing externalId OVERWRITES that document and re-indexes the new body (text mode) / re-uploads and re-indexes the new file (file mode), instead of returning the existing one unchanged. This is the curation/re-sync primitive: edit a source, re-ingest with upsert:true, and the search index reflects the new content. Requires the documents:u scope. IMPORTANT: pass the SAME schemaId (and type) you used originally \u2014 externalId is unique WITHIN a type, so omitting schemaId resolves in the untyped namespace and mints a duplicate instead of updating. The response `created` flag confirms which happened (created:true = a new document was minted)."
@@ -10126,12 +10152,12 @@ var inputSchema19 = {
     "Bind this document to a record schema. When set, `payload` is validated against the schema and its lookup fields become directly queryable via document_query (records parity). Resolve a schema id from its type via list_schemas. Omit for an untyped document."
   ),
   payload: import_zod18.z.record(import_zod18.z.string(), import_zod18.z.unknown()).optional().describe(
-    "The document's structured data \u2014 a flat key/value object. With `schemaId`, declared fields are validated and lookup fields indexed; undeclared keys pass through as free-form and are searchable via the hybrid_search `filters` param. Without a schema it is stored as free-form metadata."
+    "The document's structured data \u2014 a flat key/value object. With `schemaId`, declared fields are validated and lookup fields indexed; undeclared keys pass through as free-form and are searchable via the hybrid_search `filters` param. Without a schema it is stored as free-form metadata. Every number must fall within the signed 64-bit range \u2014 send a larger whole number as a STRING (stored exactly, exact-match lookup), else the ingest is refused with a 400 naming the field."
   ),
   // Inline text mode (mutually exclusive with filePath):
   text: import_zod18.z.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
   storeText: import_zod18.z.boolean().optional().describe(
-    "Whether the document's text is retained after indexing (default true). Applies to BOTH modes and is fixed at ingest time. Text mode: the ingested body is always retained (this flag is effectively always true \u2014 the body is the document). File mode: true keeps the extracted text retrievable via document_get(includeText:true) and usable by document_ask; false discards the extracted text once indexing completes \u2014 search still works and the original file remains downloadable, but includeText returns textAvailable:false and document_ask is unavailable."
+    "FILE MODE ONLY. Whether the uploaded file's EXTRACTED text is retained after indexing (default true), fixed at ingest. true keeps the extracted text retrievable via document_get(includeText:true) and usable by document_ask; false discards it once indexing completes \u2014 search still works and the original file remains downloadable, but includeText returns textAvailable:false and document_ask is unavailable. NOT accepted with `text`: a text-ingested body is the document itself and is ALWAYS retained, so the backend has no storeText knob on the text path \u2014 passing it with `text` is rejected rather than silently ignored."
   ),
   // File upload mode (mutually exclusive with text; stdio-transport-only):
   filePath: import_zod18.z.string().min(1).optional().describe(
@@ -10148,7 +10174,7 @@ var inputSchema19 = {
 var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   name: "document_ingest",
   title: "Ingest a new document (text body or file upload)",
-  description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText defaults to true and is fixed at ingest: in file mode, false discards the extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained.",
+  description: "Create a new document in your Vectros tenant. Two modes:\n  \u2022 Text mode: pass `text` (string body). Single-call. Use for crawled content, notes, generated text.\n  \u2022 File mode: pass `filePath` (local path on the MCP server's host machine). STDIO-TRANSPORT ONLY \u2014 rejected on HTTP transport. MCP server reads the bytes, requests a presigned upload URL, and PUTs them. Returns when the upload is accepted (indexStatus: PENDING_INDEX); poll with `document_get` until indexStatus is INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate \u2014 requires documents:r in addition to documents:c, since being handed the existing document is a read of it). To UPDATE an existing document instead \u2014 re-index an edited body \u2014 pass `upsert:true` with the same `externalId` (and the same `schemaId`); this is the re-sync primitive for keeping a knowledge base current. Pass `schemaId` + `payload` for a typed, lookup-queryable document (records parity). indexMode defaults to HYBRID for untyped documents (omit to inherit a bound schema's default). storeText is a FILE-MODE knob (default true): false discards the uploaded file's extracted text after indexing (search + file download keep working; text retrieval and document_ask do not). Text-mode bodies are always retained, so storeText is not accepted with `text`.",
   inputSchema: inputSchema19,
   handler: async (args) => {
     const title = args.title;
@@ -10185,6 +10211,14 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
         )
       );
     }
+    if (text && args.storeText !== void 0) {
+      return toolError(
+        "document_ingest",
+        new Error(
+          "`storeText` is not supported with `text` \u2014 a text-ingested body is the document itself and is always retained; the text path has no storeText control. Omit it (text mode), or use `filePath` mode where storeText:false discards the uploaded file's extracted text after indexing."
+        )
+      );
+    }
     const common = {
       folderId: args.folderId,
       payload: args.payload,
@@ -10489,7 +10523,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, environment, principalType, principalKeyId, and (for scoped keys) allowedActions + dataScope. Until backend ships the extended /v1/ping response, returns a minimal derived shape; richer fields appear automatically as backend rolls out.",
+  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.",
   mimeType: "application/json",
   read: async () => {
     const identity = await resolveIdentity({ log, apiKey, environment });