@vectros-ai/mcp-server 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 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.
+
+### Changed
+
+- Updated the bundled `@vectros-ai/sdk` to **0.31.0**, keeping the server aligned
+  with the current Vectros API (create endpoints now report whether a resource was
+  newly created and accept an opt-in `upsert`). The `record_create`, `folder_create`,
+  and `document_ingest` tools were adjusted to the regenerated client's request shape;
+  their MCP-facing inputs and outputs are unchanged.
+
 ## 0.5.2 — 2026-06-26
 
 Distribution fix + 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)