@vectros-ai/mcp-server 0.5.3 → 0.7.0

package/dist/cli.mjs

@@ -481,10 +481,18 @@ var DocumentRequest;
     Text: "TEXT",
     None: "NONE"
   };
+  DocumentRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
 })(DocumentRequest || (DocumentRequest = {}));
 var DocumentResponse;
 ((DocumentResponse2) => {
   DocumentResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
+  DocumentResponse2.IndexStatus = {
     PendingUpload: "PENDING_UPLOAD",
     Uploaded: "UPLOADED",
     Extracting: "EXTRACTING",
@@ -4890,7 +4898,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "DELETE", "/v1/documents/{id}");
   }
   /**
-   * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `storeText`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode` and `externalId` are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
+   * Partially updates a document using an RFC 7386 JSON Merge Patch. The `payload` object is deep-merged: keys you send overwrite existing values (recursing into nested objects), a key set to `null` is deleted, and keys you omit are preserved — unlike PUT, which replaces the whole payload. Top-level fields (`title`, `folderId`, `schemaId`, ownership) are set when present and left unchanged when omitted; sending a top-level field as `null` is rejected. Supplying `text` re-ingests the document body (same as PUT). `indexMode`, `externalId`, and `storeText` (text retention is fixed at ingest) are immutable and rejected if present. The merged result is validated against the bound schema. Pass `expectedVersion` for optimistic concurrency (409 on conflict). Requires the `documents:u` scope.
    *
    * @param {Vectros.PatchDocumentRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5142,7 +5150,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/download");
   }
   /**
-   * Returns the full extracted or ingested text body for documents that were stored with `storeText=true`. Returns 404 when the document does not exist or when no text is available (because `storeText` was false, or extraction has not yet completed). Requires the `documents:r` scope.
+   * Returns the document's full text body when it is retained: always available for text-ingested documents, and for file-uploaded documents unless they were uploaded with `storeText=false` (which discards the extracted text once indexing completes — the original file remains available via `GET /{id}/download`). Returns 404 when the document does not exist, its text was not retained, or extraction has not yet completed. Requires the `documents:r` scope.
    *
    * @param {Vectros.GetDocumentTextRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -5255,7 +5263,7 @@ var DocumentsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/documents/{id}/versions");
   }
   /**
-   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body; `?upsert=true` requires the `documents:u` scope). Requires the `documents:c` scope.
+   * Starts a file-based document by returning a short-lived presigned S3 PUT URL. Upload the file bytes directly to `uploadUrl`; the document is then automatically queued for text extraction and asynchronous indexing. Supplying an `externalId` makes this idempotent — re-initiating an upload with the same `externalId` re-issues a fresh presigned URL to the SAME existing document/object (so a re-upload inherently replaces the file body) rather than creating a duplicate. The response's `created` field (and the HTTP status — 201 when a new document was minted, 200 when an existing one was matched) tells the two apart. With `?upsert=true`, the submitted `payload`/`title` are also applied to the matched document (file-body divergence cannot be diffed at upload-init — the bytes have not arrived yet — so the re-upload itself replaces the body). Creating a NEW document requires the `documents:c` scope. Re-uploading over an EXISTING document overwrites (and re-indexes) its body, so it is an update: it requires the `documents:u` scope (as does `?upsert=true` for the metadata).
    *
    * @param {Vectros.FileUploadRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -8756,8 +8764,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.5.3" : "dev",
-  sdk: true ? "0.31.0" : "dev"
+  mcpServer: true ? "0.7.0" : "dev",
+  sdk: true ? "0.33.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -8997,6 +9005,32 @@ ${detail}${pointer}`
 // src/tools/hybrid_search.ts
 var MCP_DEFAULT_LIMIT = 3;
 var MCP_MAX_LIMIT = 10;
+var MCP_RESPONSE_CHAR_BUDGET = 24e3;
+var SNIPPET_MAX_CHARS = 160;
+var INTERNAL_METADATA_KEYS = /* @__PURE__ */ new Set(["tenantId", "owner_id", "model_type", "rootFolderId", "folderId"]);
+function trimMetadata(md) {
+  if (!md || typeof md !== "object" || Array.isArray(md)) return md;
+  const out = {};
+  for (const [k, v] of Object.entries(md)) {
+    if (!INTERNAL_METADATA_KEYS.has(k)) out[k] = v;
+  }
+  return out;
+}
+function reshapeHit(hit, includeContext) {
+  const out = { ...hit };
+  if ("metadata" in out) out.metadata = trimMetadata(out.metadata);
+  const chunk = typeof hit.chunkText === "string" ? hit.chunkText : void 0;
+  const ctx = typeof hit.contextText === "string" ? hit.contextText : void 0;
+  if (includeContext) {
+    if (chunk && ctx && ctx.includes(chunk)) delete out.chunkText;
+  } else {
+    delete out.contextText;
+  }
+  if ((out.snippet == null || out.snippet === "") && chunk) {
+    out.snippet = chunk.length > SNIPPET_MAX_CHARS ? chunk.slice(0, SNIPPET_MAX_CHARS) + "\u2026" : chunk;
+  }
+  return out;
+}
 var inputSchema = {
   query: z.string().min(1, "query must be non-empty").describe("Natural-language or keyword query."),
   mode: z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("HYBRID (BM25 + dense, default), TEXT (BM25 only), or SEMANTIC (dense only)."),
@@ -9011,7 +9045,9 @@ var inputSchema = {
   rootFolderId: z.string().optional().describe("Scope to content under this folder AND all its descendants (subtree-root folder id)."),
   // Content narrowing.
   contentTypes: z.array(z.enum(["documents", "records"])).optional().describe('Narrow to content types. ["documents"] or ["records"]; omit for unified (both).'),
-  typeName: z.string().optional().describe('Restrict record hits to this schema type (e.g. "patient"). No-op for documents.'),
+  typeName: z.string().optional().describe(
+    'Restrict hits to this schema type (e.g. "patient", "runbook"). Applies to BOTH documents and records \u2014 combine with contentTypes to scope within one content type. Untyped content never matches.'
+  ),
   filters: z.record(z.unknown()).optional().describe(
     'Field-level metadata filters (AND-combined). Value = scalar (equality), array (OR-set), or operator map: $eq/$ne/$gt/$gte/$lt/$lte (scalar) or $in/$nin (array). e.g. {"status":"open"} or {"price":{"$gte":100,"$lte":500}}.'
   ),
@@ -9026,6 +9062,9 @@ var inputSchema = {
   minSimilarity: z.number().min(0).max(1).optional().describe("Minimum semantic similarity (0.0\u20131.0); results below are excluded."),
   minTextRelevance: z.number().min(0).max(1).optional().describe("Minimum relative keyword (BM25) relevance (0.0\u20131.0); the keyword-leg analogue of minSimilarity."),
   uniqueDocuments: z.boolean().optional().describe("When true, return at most one chunk per source document."),
+  includeContext: z.boolean().optional().describe(
+    "Include the broader passage (contextText) around each matched chunk. Off by default to keep the result compact \u2014 each hit returns its matched chunkText plus a short snippet. Turn this on only when you need more surrounding context inline; for a full deep read, fetch the source with document_get."
+  ),
   requireComplete: z.boolean().optional().describe(
     "When true, fail closed (HTTP 503) if a search backend is unavailable rather than silently returning partial/degraded results. Default false (degrade to the surviving engine; the result still flags degraded)."
   )
@@ -9033,7 +9072,7 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: "Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), 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.",
+  description: `Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), 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). textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:"OR".`,
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -9060,13 +9099,30 @@ var hybridSearch = ({ client, log }) => ({
         uniqueDocuments: args.uniqueDocuments,
         requireComplete: args.requireComplete
       });
+      const hits = Array.isArray(
+        result.results
+      ) ? result.results : [];
+      const includeContext = args.includeContext ?? false;
+      let shaped = hits.map((h) => reshapeHit(h, includeContext));
+      const textLegEmpty = mode !== "SEMANTIC" && hits.length > 0 && hits.every((h) => !(Number(h.textScore) > 0));
+      const envelope = {
+        ...result,
+        results: shaped
+      };
+      if (textLegEmpty) envelope.textLegEmpty = true;
+      let text = JSON.stringify(envelope, null, 2);
+      while (shaped.length > 1 && text.length > MCP_RESPONSE_CHAR_BUDGET) {
+        shaped = shaped.slice(0, -1);
+        envelope.results = shaped;
+        envelope.truncated = true;
+        envelope.returnedResults = shaped.length;
+        text = JSON.stringify(envelope, null, 2);
+      }
       log.debug(
-        { tool: "hybrid_search", mode, limit, returned: result.results?.length },
+        { tool: "hybrid_search", mode, limit, returned: shaped.length, textLegEmpty },
         "hybrid_search ok"
       );
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return { content: [{ type: "text", text }] };
     } catch (err) {
       log.warn({ tool: "hybrid_search", err: String(err) }, "hybrid_search failed");
       return toolError("hybrid_search", err);
@@ -9101,7 +9157,9 @@ var MCP_MAX_LIMIT2 = 10;
 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.
-  field: z2.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
+  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.)'
+  ),
   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`."),
@@ -9196,19 +9254,77 @@ var record_query_default = recordQuery;
 
 // src/tools/record_get.ts
 import { z as z3 } from "zod";
+
+// src/tools/resolve-external-id.ts
+function validateSelector(sel, entity) {
+  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}.`;
+  }
+  if (!hasId && !hasExt) {
+    return `Provide id, 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).";
+  }
+  return void 0;
+}
+async function resolveRecordIdByExternalId(client, sel) {
+  const err = validateSelector(sel, "record");
+  if (err) return { error: err };
+  if (sel.id) return { id: sel.id };
+  const page = await client.records.lookupRecordsByBody({
+    type: sel.type,
+    field: "externalId",
+    value: sel.externalId,
+    limit: 1
+  });
+  const items = pageItems(page);
+  if (items.length === 0) {
+    return { error: `No record of type '${sel.type}' with externalId '${sel.externalId}'.` };
+  }
+  return { id: items[0].id };
+}
+async function resolveDocumentIdByExternalId(client, sel) {
+  const err = validateSelector(sel, "document");
+  if (err) return { error: err };
+  if (sel.id) return { id: sel.id };
+  const page = await client.documents.lookupDocumentsByBody({
+    type: sel.type,
+    field: "externalId",
+    value: sel.externalId,
+    limit: 1
+  });
+  const items = pageItems(page);
+  if (items.length === 0) {
+    return { error: `No document of type '${sel.type}' with externalId '${sel.externalId}'.` };
+  }
+  return { id: items[0].id };
+}
+
+// src/tools/record_get.ts
 var MAX_PAYLOAD_CHARS = 32e3;
 var inputSchema3 = {
-  id: z3.string().min(1, "id is required").describe("The Vectros record id (e.g. from record_query or hybrid_search).")
+  id: z3.string().optional().describe("The Vectros record id (e.g. from record_query or hybrid_search). Provide this OR externalId+type."),
+  externalId: z3.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `id`. Requires `type` (externalId is unique within a type). Resolves to the record without a manual record_query lookup first."
+  ),
+  type: z3.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type).")
 };
 var recordGet = ({ client, log }) => ({
   name: "record_get",
-  title: "Get a record by id",
-  description: "Fetch a single structured record by its Vectros id, including the full payload. Use after record_query / hybrid_search surfaces an id and you need the complete record. Very large payloads are truncated to protect the agent context window.",
+  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.",
   inputSchema: inputSchema3,
   handler: async (args) => {
     const id = args.id;
+    const externalId = args.externalId;
+    const type = args.type;
     try {
-      const record = await client.records.getRecord({ id });
+      const resolved = await resolveRecordIdByExternalId(client, { id, externalId, type });
+      if ("error" in resolved) return toolError("record_get", new Error(resolved.error));
+      const record = await client.records.getRecord({ id: resolved.id });
       const out = { ...record };
       if (record.payload !== void 0) {
         const json = JSON.stringify(record.payload);
@@ -9220,12 +9336,12 @@ var recordGet = ({ client, log }) => ({
         }
       }
       log.debug(
-        { tool: "record_get", id, truncated: out.payloadTruncated === true },
+        { tool: "record_get", id: resolved.id, externalId, truncated: out.payloadTruncated === true },
         "record_get ok"
       );
       return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
     } catch (err) {
-      log.warn({ tool: "record_get", id, err: String(err) }, "record_get failed");
+      log.warn({ tool: "record_get", id, externalId, type, err: String(err) }, "record_get failed");
       return toolError("record_get", err);
     }
   }
@@ -9285,7 +9401,11 @@ var record_create_default = recordCreate;
 // src/tools/record_update.ts
 import { z as z5 } from "zod";
 var inputSchema5 = {
-  id: z5.string().min(1, "id is required").describe("The Vectros record id to update."),
+  id: z5.string().optional().describe("The Vectros record id to update. Provide this OR externalId+type."),
+  externalId: z5.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `id` (requires `type`). Updates the record you created under that externalId without a manual record_query lookup first."
+  ),
+  type: z5.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   fields: z5.record(z5.string(), z5.unknown()).describe(
     "Field\u2192value changes DEEP-MERGED into the existing payload: keys you send overwrite (recursing into nested objects), a key set to `null` is deleted, and unspecified fields are preserved."
   ),
@@ -9296,23 +9416,27 @@ var inputSchema5 = {
 };
 var recordUpdate = ({ client, log }) => ({
   name: "record_update",
-  title: "Update a record",
-  description: "Update a record by id. The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
+  title: "Update a record by id or externalId",
+  description: "Update a record \u2014 select it by its Vectros `id` OR by your own `externalId` + `type` (the same key you passed to record_create, resolved for you). The provided `fields` are DEEP-MERGED into the existing payload (unspecified fields are preserved; a field set to `null` is deleted). Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Use `status` to archive without deleting. Requires the key to allow records:u.",
   inputSchema: inputSchema5,
   handler: async (args) => {
     const id = args.id;
+    const externalId = args.externalId;
+    const type = args.type;
     const fields = args.fields;
     const status = args.status;
     const expectedVersion = args.expectedVersion;
     try {
+      const resolved = await resolveRecordIdByExternalId(client, { id, externalId, type });
+      if ("error" in resolved) return toolError("record_update", new Error(resolved.error));
       const body = { payload: fields };
       if (status !== void 0) body.status = status;
       if (expectedVersion !== void 0) body.expectedVersion = expectedVersion;
-      const updated = await client.records.patchRecord({ id, body });
-      log.debug({ tool: "record_update", id }, "record_update ok");
+      const updated = await client.records.patchRecord({ id: resolved.id, body });
+      log.debug({ tool: "record_update", id: resolved.id, externalId }, "record_update ok");
       return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
     } catch (err) {
-      log.warn({ tool: "record_update", id, err: String(err) }, "record_update failed");
+      log.warn({ tool: "record_update", id, externalId, type, err: String(err) }, "record_update failed");
       return toolError("record_update", err);
     }
   }
@@ -9579,7 +9703,11 @@ var list_schemas_default = listSchemas;
 import { z as z10 } from "zod";
 var MAX_TEXT_CHARS = 32e3;
 var inputSchema10 = {
-  documentId: z10.string().min(1, "documentId is required").describe("The document ID returned by document_ingest or hybrid_search."),
+  documentId: z10.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
+  externalId: z10.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Fetches the document you ingested under that externalId without a manual lookup first."
+  ),
+  type: z10.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   includeText: z10.boolean().optional().describe(
     "If true, fetch and include the document text (capped at ~8K tokens, truncated: true flag if cut). Default false \u2014 metadata only. For larger documents, prefer `document_ask` over dumping text into context."
   ),
@@ -9599,13 +9727,18 @@ function isNotAvailable(err) {
 var documentGet = ({ client, log }) => ({
   name: "document_get",
   title: "Get document metadata (and optionally text)",
-  description: "Fetch metadata for a single document by id. Pass `includeText: true` to also fetch the text body (capped at ~8K tokens; `truncated: true` flag if cut). If the document was ingested without `storeText: true`, text is unavailable \u2014 `textAvailable: false` flag is set and the agent should use `document_ask` for question-driven extraction instead. Pass `includeDownloadUrl: true` to also get a short-lived presigned `downloadUrl` for the original file (file-backed documents only). Returns full DocumentResponse from the SDK.",
+  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`.",
   inputSchema: inputSchema10,
   handler: async (args) => {
-    const id = args.documentId;
+    const documentId = args.documentId;
+    const externalId = args.externalId;
+    const type = args.type;
     const includeText = args.includeText ?? false;
     const includeDownloadUrl = args.includeDownloadUrl ?? false;
     try {
+      const resolved = await resolveDocumentIdByExternalId(client, { id: documentId, externalId, type });
+      if ("error" in resolved) return toolError("document_get", new Error(resolved.error));
+      const id = resolved.id;
       const doc = await client.documents.getDocument({ id });
       let extra = {};
       if (includeText) {
@@ -9618,7 +9751,7 @@ var documentGet = ({ client, log }) => ({
           if (isNotAvailable(textErr)) {
             log.debug(
               { tool: "document_get", id },
-              "document_get text unavailable (ingested without storeText)"
+              "document_get text unavailable (not retained \u2014 storeText:false upload)"
             );
             extra = { ...extra, textAvailable: false };
           } else {
@@ -9652,7 +9785,7 @@ var documentGet = ({ client, log }) => ({
         ]
       };
     } catch (err) {
-      log.warn({ tool: "document_get", id, err: String(err) }, "document_get failed");
+      log.warn({ tool: "document_get", documentId, externalId, type, err: String(err) }, "document_get failed");
       return toolError("document_get", err);
     }
   }
@@ -9767,13 +9900,22 @@ var document_query_default = documentQuery;
 // src/tools/document_update.ts
 import { z as z12 } from "zod";
 var inputSchema12 = {
-  documentId: z12.string().min(1, "documentId is required").describe("The Vectros document id to update."),
+  documentId: z12.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
+  externalId: z12.string().optional().describe(
+    "Your caller-owned externalId \u2014 an alternative selector to `documentId` (requires `type`). Updates the document you ingested under that externalId without a manual lookup first."
+  ),
+  type: z12.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   title: z12.string().optional().describe("New title. Omit to keep the current title."),
   fields: z12.record(z12.string(), z12.unknown()).optional().describe(
     "Typed-payload field\u2192value changes DEEP-MERGED into the existing payload (a field set to `null` is deleted; unspecified fields preserved). Omit to leave the payload unchanged."
   ),
+  text: z12.string().optional().describe(
+    "New raw text body. Supplying it re-ingests the document body and re-queues it for indexing, so the search index reflects the edit (text-ingested documents only \u2014 not file-backed ones). Omit to leave the stored text unchanged. This is the in-place alternative to re-ingesting with upsert:true."
+  ),
   folderId: z12.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
-  storeText: z12.boolean().optional().describe("Whether the raw text is stored + retrievable."),
+  status: z12.enum(["ACTIVE", "ARCHIVED"]).optional().describe(
+    "Lifecycle status. `ARCHIVED` soft-retracts the document \u2014 it is pulled from search and recall but kept and recoverable; set it back to `ACTIVE` to re-index and restore it. The way to retire superseded content when the credential has no delete authority. Omit to leave unchanged."
+  ),
   userId: z12.string().optional().describe("Reassign the owning user (Vectros UUID)."),
   orgId: z12.string().optional().describe("Reassign the owning org (Vectros UUID)."),
   clientId: z12.string().optional().describe("Reassign the associated client (Vectros UUID)."),
@@ -9784,33 +9926,39 @@ var inputSchema12 = {
 var documentUpdate = ({ client, log }) => ({
   name: "document_update",
   title: "Update a document",
-  description: "Update a document by id. `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/ownership are updated when provided and preserved otherwise. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.",
+  description: 'Update a document \u2014 select it by its Vectros `documentId` OR by your own `externalId` + `type` (resolved for you). `fields` are DEEP-MERGED into the existing typed payload (unspecified fields preserved; a field set to `null` is deleted); title/folderId/status/ownership are updated when provided and preserved otherwise. Supply `text` to re-ingest and re-index the document body in place (text documents only). Set `status: "ARCHIVED"` to soft-retract a document (pulled from search, kept and recoverable) and `status: "ACTIVE"` to restore it. Pass `expectedVersion` (the version you last read) for safe concurrent edits \u2014 a stale update is refused (409). Requires the key to allow documents:u.',
   inputSchema: inputSchema12,
   handler: async (args) => {
     const documentId = args.documentId;
+    const externalId = args.externalId;
+    const type = args.type;
     const title = args.title;
     const fields = args.fields;
+    const text = args.text;
     const folderId = args.folderId;
-    const storeText = args.storeText;
+    const status = args.status;
     const userId = args.userId;
     const orgId = args.orgId;
     const clientId = args.clientId;
     const expectedVersion = args.expectedVersion;
     try {
+      const resolved = await resolveDocumentIdByExternalId(client, { id: documentId, externalId, type });
+      if ("error" in resolved) return toolError("document_update", new Error(resolved.error));
       const body = {};
       if (title !== void 0) body.title = title;
       if (fields !== void 0) body.payload = fields;
+      if (text !== void 0) body.text = text;
       if (folderId !== void 0) body.folderId = folderId;
-      if (storeText !== void 0) body.storeText = storeText;
+      if (status !== void 0) body.status = status;
       if (userId !== void 0) body.userId = userId;
       if (orgId !== void 0) body.orgId = orgId;
       if (clientId !== void 0) body.clientId = clientId;
       if (expectedVersion !== void 0) body.expectedVersion = expectedVersion;
       const updated = await client.documents.patchDocument({
-        id: documentId,
+        id: resolved.id,
         body
       });
-      log.debug({ tool: "document_update", documentId }, "document_update ok");
+      log.debug({ tool: "document_update", documentId: resolved.id, externalId }, "document_update ok");
       return { content: [{ type: "text", text: JSON.stringify(updated, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "document_update", documentId, err: String(err) }, "document_update failed");
@@ -9828,7 +9976,7 @@ var inputSchema13 = {
 var documentDelete = ({ client, log }) => ({
   name: "document_delete",
   title: "Delete a document",
-  description: "Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error.",
+  description: 'Permanently delete a document by id (removes it and its indexed content). Requires the key to allow documents:d \u2014 a key without it gets a permission error. To archive without deleting, use document_update to set status: "ARCHIVED" instead (recoverable, and needs no delete authority).',
   inputSchema: inputSchema13,
   handler: async (args) => {
     const documentId = args.documentId;
@@ -10108,6 +10256,9 @@ var inputSchema19 = {
   externalId: z18.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."
   ),
+  upsert: z18.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)."
+  ),
   schemaId: z18.string().optional().describe(
     "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."
   ),
@@ -10117,7 +10268,7 @@ var inputSchema19 = {
   // Inline text mode (mutually exclusive with filePath):
   text: z18.string().min(1).optional().describe("Text body to ingest inline. Mutually exclusive with filePath. Either text or filePath is required."),
   storeText: z18.boolean().optional().describe(
-    "If true (default), the text body is stored alongside the index so document_get(includeText:true) can retrieve it later. Set false to index only \u2014 saves storage cost on large corpora but document_get(includeText) will return textAvailable:false."
+    "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 upload mode (mutually exclusive with text; stdio-transport-only):
   filePath: z18.string().min(1).optional().describe(
@@ -10133,13 +10284,14 @@ 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 the partner 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 (status: PENDING_INDEX); poll with `document_get` to confirm INDEXED.\nEither `text` or `filePath` must be present; both is an error. Idempotent by `externalId` (re-ingest returns the existing document, not a duplicate). 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 (set false to skip storing the text body).",
+  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.",
   inputSchema: inputSchema19,
   handler: async (args) => {
     const title = args.title;
     const text = args.text;
     const filePath = args.filePath;
     const schemaId = args.schemaId;
+    const upsert = args.upsert;
     const indexMode = args.indexMode ?? (schemaId ? void 0 : "HYBRID");
     if (!text && !filePath) {
       return toolError(
@@ -10172,13 +10324,12 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
     };
     try {
       if (text) {
-        const storeText = args.storeText ?? true;
         const result = await client.documents.ingestDocument({
+          upsert,
           body: {
             title,
             text,
             indexMode,
-            storeText,
             ...common
           }
         });
@@ -10209,10 +10360,13 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       }
       const fileName = basename(safePath);
       const fileType = args.fileType ?? inferMimeType(safePath);
+      const storeTextFile = args.storeText ?? true;
       const upload = await client.documents.uploadDocument({
+        upsert,
         fileName,
         fileType,
         indexMode,
+        storeText: storeTextFile,
         ...common
       });
       const uploadUrl = upload?.uploadUrl;
@@ -10248,8 +10402,8 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
             text: JSON.stringify(
               {
                 ...upload,
-                status: "PENDING_INDEX",
-                _note: "File uploaded; indexing is asynchronous. Poll document_get(id) until status is INDEXED."
+                indexStatus: "PENDING_INDEX",
+                _note: "File uploaded; indexing is asynchronous. Poll document_get(id) until indexStatus is INDEXED."
               },
               null,
               2
@@ -10546,6 +10700,14 @@ function zodTypeToJsonSchema(schema) {
 
 // src/server.ts
 var DEFAULT_ENVIRONMENT = "https://api.vectros.ai";
+function formatArgError(tool, error) {
+  const unknownKeys = error.issues.filter((i) => i.code === "unrecognized_keys").flatMap((i) => i.keys);
+  if (unknownKeys.length > 0) {
+    const valid = Object.keys(tool.inputSchema).join(", ");
+    return `Unknown argument(s): ${unknownKeys.join(", ")}. Valid arguments for ${tool.name}: ${valid}. Pass only these \u2014 an unrecognized argument is rejected, not ignored.`;
+  }
+  return `Invalid arguments: ${error.message}`;
+}
 var VectrosMCPServer = class {
   server;
   log;
@@ -10635,7 +10797,11 @@ var VectrosMCPServer = class {
           name: t.name,
           title: t.title,
           description: t.description,
-          inputSchema: zodShapeToJsonSchema(t.inputSchema)
+          // additionalProperties:false advertises strict argument validation to the
+          // MCP client (a well-behaved client rejects an unknown key before the call).
+          // The server enforces it too (z.object(...).strict() below) so a raw JSON-RPC
+          // call that skips client validation is still rejected — belt and suspenders.
+          inputSchema: { ...zodShapeToJsonSchema(t.inputSchema), additionalProperties: false }
         }))
       })
     );
@@ -10645,9 +10811,9 @@ var VectrosMCPServer = class {
       if (!tool) {
         result = toolError(req.params.name ?? "unknown", new Error("No such tool."));
       } else {
-        const parsed = z22.object(tool.inputSchema).safeParse(req.params.arguments ?? {});
+        const parsed = z22.object(tool.inputSchema).strict().safeParse(req.params.arguments ?? {});
         if (!parsed.success) {
-          result = toolError(tool.name, new Error(`Invalid arguments: ${parsed.error.message}`));
+          result = toolError(tool.name, new Error(formatArgError(tool, parsed.error)));
         } else {
           try {
             result = await tool.handler(