@vectros-ai/mcp-server 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.0 — 2026-07-03
+
+Curation-focused tool improvements: look records and documents up by your own
+identifier, re-sync a changed body, archive and restore documents without delete
+authority, and get a clear error when an argument is wrong.
+
+### Added
+
+- **`externalId` selector on `record_get`, `record_update`, `document_get`, and
+  `document_update`.** Pass `externalId` together with `type` as an alternative to the
+  Vectros `id` — the tool resolves it for you, so an agent that only knows its own
+  identifier no longer has to make a separate lookup call first. `id` still works and
+  takes precedence when both are supplied.
+- **`upsert` on `document_ingest`.** With `upsert: true`, ingesting a document whose
+  `externalId` already exists overwrites its stored content and re-indexes it, instead
+  of returning the existing document unchanged. Re-supply the same `schemaId` so the
+  `externalId` resolves within the same type.
+- **`text` on `document_update`.** Replace a text document's body in place; the document
+  is re-queued for indexing so search reflects the new content.
+- **`status` on `document_update` — archive and restore a document.** Set
+  `status: "ARCHIVED"` to soft-retract a document: it is pulled from search and recall
+  but kept and recoverable. Set `status: "ACTIVE"` to re-index and restore it. This is
+  the way to retire superseded content with a credential that has no delete authority.
+  Document reads (`document_get`, `document_query`) surface the caller-controlled
+  lifecycle `status` alongside the read-only processing `indexStatus`.
+- **`hybrid_search` results are now sized for an agent's context window.** Each hit returns
+  its matched `chunkText` plus a short `snippet` by default; the broader surrounding passage
+  (`contextText`) is opt-in via **`includeContext: true`** (and is de-duplicated against
+  `chunkText` when included, so the same text is never sent twice). Internal search-index
+  bookkeeping fields (`tenantId`, `owner_id`, `model_type`, `rootFolderId`, `folderId`) are
+  stripped from each hit's `metadata`, keeping the fields you ingested. An oversized response
+  is trimmed to the top hits with **`truncated: true`** so one search can't overflow the
+  context window. A **`textLegEmpty: true`** flag signals that the keyword (BM25) leg matched
+  nothing across every hit — usually a long natural-language query under the default
+  `PHRASE` matching; retry with a short keyword phrase or `textMode: "OR"`.
+
+### Changed
+
+- Updated the bundled `@vectros-ai/sdk` to **0.32.0**, keeping the server aligned
+  with the current Vectros API (adds the document lifecycle `status` field, kept
+  distinct from the processing `indexStatus`).
+- **Document responses keep the two status axes separate.** `status` is the
+  caller-controlled lifecycle (`ACTIVE`/`ARCHIVED`); `indexStatus` is the read-only
+  processing state (`PENDING_INDEX`, `INDEXED`, …), matching the current API.
+  `document_ingest`'s file mode accordingly reports its "uploaded, indexing queued"
+  marker as `indexStatus: "PENDING_INDEX"` — previously it overwrote `status` with
+  that value. Poll `document_get` until `indexStatus` is `INDEXED`.
+- **Unknown arguments are now rejected, not ignored.** Calling a tool with an argument
+  it does not accept returns an error that names the unrecognized key and lists the
+  valid arguments for that tool, instead of silently dropping it. This surfaces typos
+  and stale parameter names immediately rather than letting a call quietly do the wrong
+  thing. `record_query`'s `field` documentation now also calls out that `externalId` is
+  always queryable.
+
 ## 0.5.3 — 2026-06-29
 
 SDK refresh. No tool, parameter, or result shapes changed.

package/README.md

@@ -55,6 +55,21 @@ developer portal. The command then:
 Restart your MCP client and you're done. It's idempotent (re-run any time);
 `--rotate` replaces this machine's key.
 
+**Want to browse the data yourself?** `bootstrap` sets up the key for your
+*agent*, not a login for *you* — so a blueprint's context won't appear in the
+data-plane app's switcher until you join your own user to it (the app lists only
+contexts your user has access in). Grant yourself a role once, either in the admin
+app (**Access → Contexts → _your context_ → Profiles → Create profile**, pick
+yourself from the by-email picker, choose a role — no raw id needed) or from the
+CLI with `--principal me` (resolves to your own user):
+
+```bash
+vectros access grant --principal me --context <context-id> --role <role>
+```
+
+Blueprints that ship a human role (e.g. `agentic-sdlc`'s `editor`) let you use
+`--role`; otherwise grant inline scopes with `--actions records:r,search:r,…`.
+
 For scripted / agent use, set the sign-in token in the environment and skip
 the prompts:
 
@@ -181,8 +196,8 @@ available.
 |---|---|
 | `document_ingest` | Create a document — inline text body OR local file upload (file mode is stdio-transport only). Idempotent by `externalId`; optional `schemaId` + `payload` for a typed, lookup-queryable document. |
 | `document_query` | Query documents by lookup field (equality / range / prefix, with `asc`/`desc` ordering) or list mode (filter by ownership + type). |
-| `document_get` | Fetch a document by id (metadata; optional text truncated at ~8K tokens; optional presigned `downloadUrl` for file-backed documents). |
-| `document_update` | Patch a document's metadata / typed payload (deep-merged); optimistic concurrency via `expectedVersion`. |
+| `document_get` | Fetch a document by id (metadata incl. lifecycle `status` + processing `indexStatus`; optional text truncated at ~8K tokens; optional presigned `downloadUrl` for file-backed documents). |
+| `document_update` | Patch a document's metadata / typed payload (deep-merged); archive/restore via `status` (`ARCHIVED` soft-retracts from search, `ACTIVE` restores); optimistic concurrency via `expectedVersion`. |
 | `document_delete` | Permanently delete a document by id (removes it and its indexed content). |
 
 **Folders** (group records + documents)

package/dist/cli-http.js

@@ -504,10 +504,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",
@@ -5278,7 +5286,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.
@@ -8774,8 +8782,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.6.0" : "dev",
+  sdk: true ? "0.32.0" : "dev"
 };
 
 // src/log.ts
@@ -9012,6 +9020,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: import_zod.z.string().min(1, "query must be non-empty").describe("Natural-language or keyword query."),
   mode: import_zod.z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("HYBRID (BM25 + dense, default), TEXT (BM25 only), or SEMANTIC (dense only)."),
@@ -9026,7 +9060,9 @@ var inputSchema = {
   rootFolderId: import_zod.z.string().optional().describe("Scope to content under this folder AND all its descendants (subtree-root folder id)."),
   // Content narrowing.
   contentTypes: import_zod.z.array(import_zod.z.enum(["documents", "records"])).optional().describe('Narrow to content types. ["documents"] or ["records"]; omit for unified (both).'),
-  typeName: import_zod.z.string().optional().describe('Restrict record hits to this schema type (e.g. "patient"). No-op for documents.'),
+  typeName: import_zod.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: import_zod.z.record(import_zod.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}}.'
   ),
@@ -9041,6 +9077,9 @@ var inputSchema = {
   minSimilarity: import_zod.z.number().min(0).max(1).optional().describe("Minimum semantic similarity (0.0\u20131.0); results below are excluded."),
   minTextRelevance: import_zod.z.number().min(0).max(1).optional().describe("Minimum relative keyword (BM25) relevance (0.0\u20131.0); the keyword-leg analogue of minSimilarity."),
   uniqueDocuments: import_zod.z.boolean().optional().describe("When true, return at most one chunk per source document."),
+  includeContext: import_zod.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: import_zod.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)."
   )
@@ -9048,7 +9087,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;
@@ -9075,13 +9114,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);
@@ -9116,7 +9172,9 @@ var MCP_MAX_LIMIT2 = 10;
 var inputSchema2 = {
   type: import_zod2.z.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: import_zod2.z.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
+  field: import_zod2.z.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: import_zod2.z.string().optional().describe("Lookup mode (equality): exact-match value for `field`."),
   from: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive lower bound; requires `to`. Non-sensitive fields only."),
   to: import_zod2.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
@@ -9211,19 +9269,77 @@ var record_query_default = recordQuery;
 
 // src/tools/record_get.ts
 var import_zod3 = require("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: import_zod3.z.string().min(1, "id is required").describe("The Vectros record id (e.g. from record_query or hybrid_search).")
+  id: import_zod3.z.string().optional().describe("The Vectros record id (e.g. from record_query or hybrid_search). Provide this OR externalId+type."),
+  externalId: import_zod3.z.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: import_zod3.z.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);
@@ -9235,12 +9351,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);
     }
   }
@@ -9300,7 +9416,11 @@ var record_create_default = recordCreate;
 // src/tools/record_update.ts
 var import_zod5 = require("zod");
 var inputSchema5 = {
-  id: import_zod5.z.string().min(1, "id is required").describe("The Vectros record id to update."),
+  id: import_zod5.z.string().optional().describe("The Vectros record id to update. Provide this OR externalId+type."),
+  externalId: import_zod5.z.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: import_zod5.z.string().optional().describe("Record type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   fields: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.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."
   ),
@@ -9311,23 +9431,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);
     }
   }
@@ -9594,7 +9718,11 @@ var list_schemas_default = listSchemas;
 var import_zod10 = require("zod");
 var MAX_TEXT_CHARS = 32e3;
 var inputSchema10 = {
-  documentId: import_zod10.z.string().min(1, "documentId is required").describe("The document ID returned by document_ingest or hybrid_search."),
+  documentId: import_zod10.z.string().optional().describe("The document ID returned by document_ingest or hybrid_search. Provide this OR externalId+type."),
+  externalId: import_zod10.z.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: import_zod10.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   includeText: import_zod10.z.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."
   ),
@@ -9614,13 +9742,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). 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 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) {
@@ -9667,7 +9800,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);
     }
   }
@@ -9782,13 +9915,23 @@ var document_query_default = documentQuery;
 // src/tools/document_update.ts
 var import_zod12 = require("zod");
 var inputSchema12 = {
-  documentId: import_zod12.z.string().min(1, "documentId is required").describe("The Vectros document id to update."),
+  documentId: import_zod12.z.string().optional().describe("The Vectros document id to update. Provide this OR externalId+type."),
+  externalId: import_zod12.z.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: import_zod12.z.string().optional().describe("Document type \u2014 REQUIRED when selecting by `externalId` (externalId is unique within a type)."),
   title: import_zod12.z.string().optional().describe("New title. Omit to keep the current title."),
   fields: import_zod12.z.record(import_zod12.z.string(), import_zod12.z.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: import_zod12.z.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: import_zod12.z.string().optional().describe("Move the document into this folder (cannot be cleared once set)."),
   storeText: import_zod12.z.boolean().optional().describe("Whether the raw text is stored + retrievable."),
+  status: import_zod12.z.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: import_zod12.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
   orgId: import_zod12.z.string().optional().describe("Reassign the owning org (Vectros UUID)."),
   clientId: import_zod12.z.string().optional().describe("Reassign the associated client (Vectros UUID)."),
@@ -9799,33 +9942,41 @@ 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");
@@ -9843,7 +9994,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;
@@ -10123,6 +10274,9 @@ var inputSchema19 = {
   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."
   ),
+  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)."
+  ),
   schemaId: import_zod18.z.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."
   ),
@@ -10148,13 +10302,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 (set false to skip storing the text body).",
   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(
@@ -10189,6 +10344,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       if (text) {
         const storeText = args.storeText ?? true;
         const result = await client.documents.ingestDocument({
+          upsert,
           body: {
             title,
             text,
@@ -10225,6 +10381,7 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
       const fileName = (0, import_node_path.basename)(safePath);
       const fileType = args.fileType ?? inferMimeType(safePath);
       const upload = await client.documents.uploadDocument({
+        upsert,
         fileName,
         fileType,
         indexMode,
@@ -10263,8 +10420,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
@@ -10561,6 +10718,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;
@@ -10650,7 +10815,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 }
         }))
       })
     );
@@ -10660,9 +10829,9 @@ var VectrosMCPServer = class {
       if (!tool) {
         result = toolError(req.params.name ?? "unknown", new Error("No such tool."));
       } else {
-        const parsed = import_zod22.z.object(tool.inputSchema).safeParse(req.params.arguments ?? {});
+        const parsed = import_zod22.z.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(