@vectros-ai/mcp-server 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -3,6 +3,167 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.17.0 — 2026-09-07
+
+### Added
+
+- **`record_batch_write`** — create or upsert up to 50 structured records in one call,
+  wrapping `POST /v1/records/batch` (API 0.43.0: previously a `501` stub, now live).
+  Use it instead of N `record_create` round-trips when you hold several records.
+  Items may mix types, and each one goes through the same schema validation,
+  `externalId` idempotency, unique-field enforcement and `records:c:<type>` scope
+  check as a single create, applied per item against that item's own type — a batch
+  is not a way to write a type your credential could not write one at a time.
+  `atomicity: "all_or_nothing"` commits every item in one transaction and writes
+  nothing at all if any item fails, which is a better failure shape for an agent than
+  a loop of creates that half-succeeds; the default `best_effort` writes each item
+  independently. The item vocabulary deliberately mirrors `record_create` (`type` +
+  `fields`), so nothing new has to be learned to use it.
+
+  **The call reports success whenever the batch was *processed* — including when
+  every item failed.** That is the endpoint's own contract, so the tool does not
+  fake an error result; read the per-item `results` (matched to what you sent by
+  `index`) and the `succeeded`/`failed` counts. Per-item `status` carries two values
+  beyond the ordinary outcomes, and they call for different remedies:
+  `forbidden` (your credential lacked the scope or ownership that item needed — fix
+  the credential, not the item) and `not_committed` (this item was fine, but an
+  `all_or_nothing` batch was aborted by a different one).
+
+- **`record_query` can list by `folderId`, and serve the account-wide `recent` feed.**
+  Two list-mode selectors the API has carried on `GET /v1/records` for many releases
+  but this tool never exposed: `folderId` lists every record filed in a folder
+  regardless of type (combine with `type` for one type within one folder), and
+  `recent: true` returns the recently-updated feed across all types — the only way to
+  read records without naming a type. `record_create` has always accepted `folderId`,
+  so until now a record could be filed into a folder and never listed back out of it.
+
+  This matters more from 0.43.0 on, because `folder_delete` now refuses a folder that
+  still holds records and the supported way to find them is exactly this call.
+  `type` is consequently optional now: a lookup (`field`) still requires it, a list
+  with no selector at all is refused, and `recent` is refused alongside
+  `type`/`folderId`/`userId`/`scope` rather than silently ignoring them the way the
+  API does.
+
+- **`scopeFilters` on `hybrid_search` and `rag_ask`** — narrow a search or a RAG
+  retrieval by more than one ownership dimension at once, e.g.
+  `["org:<id>", "client:<id>"]` for one specific client within one specific org.
+  Something `scope` alone could not express, for a credential whose access spans
+  several dimensions. Mutually exclusive with `scope`; passing both is refused
+  locally with a message naming both fields, rather than spending a round trip on
+  the API's own rejection.
+
+### Changed
+
+- **`folder_delete` now states its emptiness precondition** — the folder must contain
+  no documents, **no records**, and no sub-folders, and the description says how to clear
+  each: a document can be moved out or deleted, a record can only be deleted (nothing on
+  this surface moves one), and a sub-folder cannot be re-parented, so nesting must be
+  cleared innermost-first. The description previously named only protected folders, so
+  the most common way this call fails read as impossible.
+
+  **API 0.43.0 widened the refusal, and it lands harder on this server than on most
+  callers.** The old guard saw sub-folders and *file-backed* documents only — it was blind
+  to *text-ingested* documents and to records, and a delete that hit one of those returned
+  success while orphaning the contents behind a folder id that no longer resolved.
+  Text-inline ingest is `document_ingest`'s default path, so folders this server filled are
+  precisely the ones whose deletes used to succeed and now do not.
+
+  One consequence worth planning for: the emptiness check counts **everything** in the
+  folder, including items the calling credential cannot read. A scoped credential can be
+  refused by content it has no way to enumerate, so a refusal that contradicts your own
+  listing is expected rather than a bug.
+- **`rag_ask`'s `truncationWarning` now carries `truncatedCount` and `noContentCount`**,
+  and its `reason` can be `no_groundable_content` or `context_window_budget_and_no_content`
+  as well as `context_window_budget`. Results can be dropped before the prompt is built
+  for two independent reasons — not fitting the context window, or having no groundable
+  text at all — and these separate them. Inherited from the API with no code change here;
+  noted because it is new data an agent sees.
+- **`hybrid_search`'s ARCHIVED note now covers records, and stops claiming an absolute.**
+  It said ARCHIVED *documents* never appear in results, which read as an asymmetry implying
+  archived records still match — they do not, and have refused to index since API 0.35.
+  API 0.43.0 additionally fixed two document write paths that could silently re-index an
+  already-archived document. But it deliberately does **not** sweep items already stranded
+  in that state: they stay searchable until written to again. So "never appear" was a false
+  absolute, and the description now names the repair — re-send `status: "ARCHIVED"` on the
+  item — instead of implying the case cannot arise.
+- **A search hit's returned `createdAt` is documented as the INDEX timestamp.** It is the moment
+  the item entered the search index — the same moment it was created in the common case, but later
+  for anything re-indexed since — so it should not be reported to a user as the creation time; fetch
+  the item with `document_get`/`record_get` for that. The `createdAfter`/`createdBefore` FILTERS are a
+  separate thing and are unchanged: they filter on the item's true creation time, which does not move
+  when it is re-indexed, with a bounded allowance that lets an item matched on its FIRST index be
+  checked against its index time instead (clock skew between creating and indexing).
+- **`folder_delete` no longer implies a record cannot be moved.** It said a record must be deleted
+  because it cannot be re-filed. The API supports re-filing one (`folderId` is patchable); it is
+  *this server* that does not expose it — `record_update` has no `folderId` argument. As written, an
+  agent clearing a folder could have deleted partner data where a move was available, then reported
+  that a move was impossible. It now names the gap as this server's and says to move the record
+  through the API/SDK rather than deleting it here.
+- **`record_batch_write` no longer claims duplicate `externalId`s within one batch are refused.**
+  That holds under `atomicity: "all_or_nothing"` only. Under the default `best_effort` each item is
+  written independently, so a second item carrying the same `externalId` matches what the first just
+  wrote and reports `updated` — a duplicated key silently collapses two rows into one, counted as a
+  success. Both modes are now described.
+- **`record_create` / `record_batch_write`: `scopes` is bounded by `data_scope`, not by identity.**
+  Both said the values "must come from the credential's own identity". The platform states the
+  opposite: identity supplies the DEFAULT when you state none and does not limit which value you may
+  state; each entry must fall inside the `data_scope` of a granting clause. The old wording would
+  stop an agent setting a scope it was entitled to set.
+- **`record_query` rejects `folderId`/`recent` on a lookup** instead of ignoring them, matching the
+  existing guard for lookup arguments passed without `field`.
+- **Bundled `@vectros-ai/sdk` repinned to the 0.43.0 line.**
+
+### Notes
+
+- **A root `sk_*` key can no longer file into a non-`default` app context.** As of API
+  0.43.0, a `folderId` / `parentFolderId` — or a document's `schemaId` — belonging to
+  another context is refused with a uniform `400`, on `document_ingest`,
+  `document_update`, `record_create`, `record_update` and `folder_create`. Those calls
+  previously succeeded, but never coherently: a root key's writes are stamped
+  `default`, so the row landed in `default` while its folder or schema lived elsewhere.
+  Existing rows are unaffected. Use a scoped key bound to the target context — the
+  credential this server recommends anyway. See README § Recommended credential.
+- **A `filters` clause on `status` means something different for records now.** Records
+  no longer publish their lifecycle `status` into the search index (API 0.43.0), so on
+  `hybrid_search` / `rag_ask` a `status` filter matches a schema's own `status` field
+  where one is declared, and nothing where none is — it no longer collides with the
+  platform's lifecycle value. Record schemas can now use `status` as a filterable field
+  of their own.
+- **0.43.0 capabilities this server deliberately does not expose:** stored scripts and
+  synchronous script execution, trigger rules, trigger-failure history, and usage
+  reporting. The reasoning is in README § What this server deliberately doesn't expose
+  — briefly: authoring stored code is a design-time act rather than a data-plane one;
+  declaring a trigger rule grants live authority; trigger-failure and usage reporting
+  are operational questions for a person, not mid-task tool calls; and synchronous
+  script execution has a failure surface (an undetermined-outcome run, and an
+  idempotency key a tool call has no natural identity for) that needs a deliberate
+  design rather than a thin wrapper.
+
+## 0.16.1 — 2026-08-27
+
+### Fixed
+
+- **Claude Code setup docs: restart-to-load + Windows npx-resolution caveats.**
+  The "Configure manually (Claude Code)" section now covers three real
+  friction points found in dogfooding: a session already open when the
+  server is added needs a full quit + reopen (not just re-selecting the
+  tab); the `/mcp` panel shows the connector marketplace, not local stdio
+  servers, so it can't confirm the server loaded; and config resolves off
+  the git common root, so a linked worktree needs adding/opening from the
+  same project as its main repo. Also documents a Windows-specific trap: a
+  scoped-registry override for `@vectros-ai` in `.npmrc` can silently
+  resolve `npx -y @vectros-ai/mcp-server` to an unexpected internal build
+  that isn't guaranteed to run there — pin an explicit version if the
+  plain command fails to start.
+- **`current_identity`'s `granted_capabilities` note now lists all five named capabilities.**
+  The tool description and the `identity` resource both listed only four
+  (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`); the
+  platform's fifth, `delegate-principal-stamp`, is now named alongside them.
+
+### Changed
+
+- Bundled `@vectros-ai/sdk` refreshed to the current release's staging build.
+
 ## 0.16.0 — 2026-08-27
 
 ### Added

package/README.md

@@ -166,17 +166,32 @@ claude mcp add vectros -e VECTROS_API_KEY=ssk_live_... -- npx -y @vectros-ai/mcp
 ```
 
 Add `-e VECTROS_API_BASE_URL=https://api.staging.vectros.ai` for a non-production
-environment. Reopen the project in Claude Code and the Vectros tools are
-available.
-
-## Tools (22 tools)
+environment.
+
+**Load it into a session by restarting.** A Claude Code session that was
+already open when you added the server won't pick it up mid-session — fully
+quit and reopen the project (not just re-select the tab). The `/mcp` panel
+shows the connector marketplace, not locally-configured stdio servers, so it
+won't confirm the server is loaded — ask the agent to call a Vectros tool
+instead. Config is keyed by the **git common root**, so a linked worktree
+resolves to its main repo's `.mcp.json` — add and open from the same project.
+
+> **Windows note:** if your `.npmrc` (or a global npm config) points the
+> `@vectros-ai` scope at a private registry, a bare `npx -y @vectros-ai/mcp-server`
+> can resolve an unexpected internal build there instead of the public
+> release — and an internal build is not guaranteed to run on Windows. If the
+> command above fails to start, either remove the scoped-registry override
+> for a plain `npx` run, or pin an explicit version (`npx -y
+> @vectros-ai/mcp-server@<version>`) known to work.
+
+## Tools (23 tools)
 
 **Search & RAG**
 
 | Tool | What it does |
 |---|---|
-| `hybrid_search` | Hybrid BM25 + dense search across the tenant's indexed content (records + documents). Narrow by ownership, folder, type, metadata filters, a created date window, and keyword-precision (`textMode`) / relevance floors. Returns the indexed projection of each hit. |
-| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval (ownership / folder / type / metadata filters / date window) and steer generation (`instructions` / `temperature`). Streaming generation aggregated; progress notifications keep the call alive for the generation window. |
+| `hybrid_search` | Hybrid BM25 + dense search across the tenant's indexed content (records + documents). Narrow by ownership (`scope` for one dimension, `scopeFilters` for several at once — e.g. one client within one org), folder, type, metadata filters, a created date window, and keyword-precision (`textMode`) / relevance floors. Returns the indexed projection of each hit. |
+| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval (ownership — `scope` or multi-dimension `scopeFilters` — / folder / type / metadata filters / date window) and steer generation (`instructions` / `temperature`). Streaming generation aggregated; progress notifications keep the call alive for the generation window. |
 | `document_ask` | Ask a question grounded against a single document. Same aggregation + progress-notification shape as `rag_ask`. |
 
 **Records** (structured, schema-validated data)
@@ -184,10 +199,11 @@ available.
 | Tool | What it does |
 |---|---|
 | `list_schemas` | List the record-schema catalog the credential can see (filter by `surface` or resolve one by `recordType`). Makes `record_query` / `record_create` discoverable. |
-| `record_query` | Query records by lookup field — equality (`value`), range, or prefix, with `asc`/`desc` ordering and an optional `sortFrom`/`sortTo` window — or list mode (filter by ownership + type). Also supports composite equality across 2-3 fields (`values`), but only against a lookup the *schema* declares over those fields together (see `list_schemas`) — not any two fields you pick. |
+| `record_query` | Query records by lookup field — equality (`value`), range, or prefix, with `asc`/`desc` ordering and an optional `sortFrom`/`sortTo` window — or list mode, choosing one of `type`, `folderId` (every record in a folder, any type — combine with `type` to narrow), or `recent` (the account-wide recently-updated feed across all types), then optionally filtering the first two by ownership. Also supports composite equality across 2-3 fields (`values`), but only against a lookup the *schema* declares over those fields together (see `list_schemas`) — not any two fields you pick. |
 | `record_get` | Fetch one record by id, including its full payload (large payloads truncated to protect the agent context window). |
 | `record_batch_get` | Fetch several records by id (1-100) in one call, each with its full payload. Returns `missingIds` for any requested id you can't access, since the API silently omits them. |
 | `record_create` | Create a record of a given type; idempotent by `externalId`; optional per-record `indexMode`. |
+| `record_batch_write` | Create or upsert up to 50 records in one call, instead of N `record_create` round-trips. Items may mix types and are validated and scope-checked individually. `atomicity: all_or_nothing` commits them as one transaction (nothing is written if any item fails); the default `best_effort` writes each independently. Reports success whenever the batch was *processed* — read the per-item `results`, not just the absence of an error. |
 | `record_update` | Patch a record's payload (deep-merged; `null` deletes a key); optimistic concurrency via `expectedVersion`. |
 | `record_delete` | Permanently delete a record by id (leaves a tombstone). |
 
@@ -208,17 +224,17 @@ available.
 | `folder_query` | Get a folder by id, or list folders (a parent's children for tree navigation, or a flat tenant list; paginated via `nextCursor`). |
 | `folder_create` | Create a folder. |
 | `folder_update` | Update a folder's name / description / ownership (merge-patch; optimistic concurrency via `expectedVersion`; folders cannot be re-parented). |
-| `folder_delete` | Delete a folder. |
+| `folder_delete` | Delete a folder. It must be empty first — no documents, no records, and no sub-folders — and a context root is protected outright. |
 
 **Identity & history**
 
 | Tool | What it does |
 |---|---|
-| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope. Does **not** yet include `granted_capabilities` (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`) — a separate reach dimension a scope clause can carry as of API 0.40.0 that `/v1/ping` doesn't report yet, so allowedActions + dataScope may understate a credential's true reach. Also reports this server's own version and the bundled SDK version (`mcpServerVersion`, `sdkVersion`). |
+| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, principalLabel, and (for scoped credentials) allowedActions + dataScope. Does **not** yet include `granted_capabilities` (`member-lifecycle` / `forensic-read` / `context-directory-read` / `delegate-mint`, as of API 0.40.0, joined by `delegate-principal-stamp` in 0.42.0) — a separate reach dimension a scope clause can carry that `/v1/ping` doesn't report yet, so allowedActions + dataScope may understate a credential's true reach. Also reports this server's own version and the bundled SDK version (`mcpServerVersion`, `sdkVersion`). |
 | `lookup_principal` | Resolve a user, or an identity entity in a namespace (`org`/`client`/any namespace you registered), by your own `externalId` (→ its Vectros UUID, for the ownership filters) or by a schema lookup field. Pass `contextId` to target a specific app context for a context-owned namespace. Read-only. |
 | `version_history` | Read the audit/version trail (CREATE/UPDATE/DELETE, with actor + diff) for one record or document. Read-only. |
 
-All 22 tools wrap published Vectros HTTP API endpoints. JSON
+All 23 tools wrap published Vectros HTTP API endpoints. JSON
 responses are what the agent sees as tool output. Per-call cost
 surfaces via the `usage` field on inference responses.
 
@@ -260,6 +276,20 @@ AccessProfile for MCP") for least-privilege credential setup — the
 `vectros bootstrap` flow provisions a scoped `ssk_*` key and its AccessProfile
 in one command.
 
+> **A root `sk_*` can no longer file into another app context, as of API 0.43.0.**
+> If you run this server on a root key and a tool call names a `folderId` /
+> `parentFolderId` — or a `schemaId` on a document — belonging to a context other
+> than `default`, it is now refused with a uniform `400 "Folder not found"` /
+> `"Schema not found"`. This affects `document_ingest`, `document_update`,
+> `record_create`, `record_update` and `folder_create`, and it is a change in
+> outcome: those calls used to succeed. They never did what they appeared to,
+> though — a root key's writes are always stamped `default`, so the row landed in
+> `default` while its folder or schema lived elsewhere, permanently invisible to
+> the context that owned them. Existing rows written the old way are untouched and
+> still readable, updatable and deletable. The fix is the same scoped key
+> recommended above: one bound to the target context can file into it and always
+> could.
+
 ## Credential resolution
 
 The server resolves its API key from the first source that yields one:
@@ -363,6 +393,49 @@ const server = new VectrosMCPServer({
 await server.connect(createStdioTransport());
 ```
 
+## What this server deliberately doesn't expose
+
+This is a decision, not a backlog. An MCP server is a tool surface handed to an
+autonomous caller, so a capability the API offers is not automatically a tool —
+each one has to earn its place on an agent's surface.
+
+The line is the **data plane**: records, documents, folders and search are here in
+full. Anything that grants or administers authority is not, and neither is the
+design-time layer that defines the data model.
+
+- **Stored scripts** (`/v1/scripts` — push, list, fetch, delete). A stored script is
+  code, not data. Authoring it is a design-time act, the same reason schema mutation
+  lives in the CLI rather than here: an agent that can write the code that later runs
+  under your credential is a different proposition from one that can write records.
+- **Synchronous script execution** (`POST /v1/scripts/execute`, the `scripts:x` scope).
+  The closer call of the two, and excluded on operational grounds rather than reach —
+  a `scripts:x:<name>` grant is a deliberately narrow, per-script permission, and an
+  ordinary scoped key can hold it. What an agent handles badly is the failure surface:
+  a run whose outcome cannot be determined returns `500 EXECUTION_OUTCOME_UNKNOWN` with
+  writes that may or may not have committed, which is not something a caller resolves
+  by retrying — it has to go and look. Getting a retry right also means reusing an
+  `Idempotency-Key` across attempts, and a tool call has no natural retry identity, so
+  an agent re-invoking after a timeout would silently run the script a second time.
+  Exposing this well needs a deliberate design for those two things, not a thin wrapper.
+  Until then, run scripts from a caller that can handle them — the API, the SDK, or the
+  CLI.
+- **Trigger rules** (`/v1/triggers`). Declaring a rule grants authority — a rule's
+  `scopes`/`roleIds` are live, and declaring one is scope-monotonicity-checked like
+  any other authority-granting surface. Minting authority is not an agent action.
+- **Trigger failure history** (`GET /v1/trigger-failures`) and **usage/billing**
+  (`GET /v1/usage`). Both are read-only, and both are operational rather than
+  data-plane — they describe how your automation and your account are behaving, not
+  what your content says. That is a question for the developer portal or the CLI,
+  where a person is looking at it, rather than a tool an agent reaches for mid-task.
+- **Identity, access and credential administration** — users, access profiles,
+  roles, app contexts, issuer registrations, and scoped-key minting. Unchanged
+  since launch: identity CRUD stays off the agent tool surface by design.
+  `lookup_principal` resolves an identifier to an id and does nothing else.
+- **Compliance operations** (erasure, export). Same reason.
+
+If one of these belongs on your agent's surface, that's worth telling us — the
+line is drawn on purpose and can be redrawn with a reason.
+
 ## What this server doesn't do (yet)
 
 - **No prompts capability** — `/rag` and `/ingest_pdf` slash-command