@vectros-ai/mcp-server 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.18.2 — 2026-10-25
+
+### Changed
+
+- **The `providerAlias` description of `rag_ask` and `document_ask` names the three waiver refusals.** When a call routed
+  through your own provider is refused because the account's provider waiver is not in force, the `403` carries an
+  `errorCode`: `WAIVER_NOT_SIGNED`, `WAIVER_TEXT_CHANGED` or `WAIVER_REVOKED`. The two descriptions and the README say what
+  each means and that an account owner resolves each in the developer portal.
+- **The `expectedVersion` descriptions of `record_update`, `document_update` and `folder_update` say what happens without it.**
+  An update that meets another change to the same item at the same moment is refused as a conflict (`409`,
+  `VERSION_CONFLICT`) whether or not `expectedVersion` is sent.
+- **The README lists the refusals added in API 0.48.0 and what the tools return for them:** `429` `BALANCE_BUSY`, `503`
+  `BALANCE_UNAVAILABLE`, and a `503` with no `errorCode` for a `providerAlias` whose stored provider key cannot be opened. It
+  also describes the `409` of a concurrent update and the items of a deleted schema.
+- **The `current_identity` tool and the `vectros://identity` resource list `trigger-control-plane-grant` among the capabilities
+  that the credential description omits.**
+- **The comments in the shipped code describe the code as it is today.** Behaviour is unchanged.
+
+## 0.18.1 — 2026-10-12
+
+### Changed
+
+- **`folder_delete` tells the agent to keep a record it cannot re-file, and the `sk_*` startup warning points at
+  things you can find.** The `folder_delete` description says not to delete a record just because this server cannot
+  move it, and to tell the user to move it with the Vectros API or SDK instead. The warning logged for a wildcard `sk_*` key names the
+  command that mints a scoped key (`npx -y @vectros-ai/cli bootstrap`) and the README's "Recommended credential"
+  section.
+- **`rag_ask` and `document_ask` name another reason a routed call (`providerAlias`) is refused with a `403`.**
+  Besides an unknown or inactive alias and a risk waiver your account has not signed, an account that has accepted the
+  Business Associate Agreement with Vectros in the developer portal also needs an account owner to attest each provider
+  config in the portal (Model Providers). Until then the platform refuses the call with a `403` that says it needs a
+  BAA-holder attestation. The `providerAlias` description and the README section on routing a call through your own
+  provider say so; nothing in this server records the attestation.
+- **`rag_ask` and `document_ask` describe the generation limits as the platform applies them.** The platform's default
+  model is `claude-haiku-5-5`. It, `claude-sonnet-5`, `claude-sonnet-5-5` and `claude-opus-5-5` can reason before they
+  answer, and when they do the reasoning counts against `maxTokens`, so a small `maxTokens` can return little or no
+  text; the `maxTokens` description says so and suggests 1024 or more for a short answer. The same four models ignore a
+  `temperature`, so the `rag_ask` `temperature` description says it applies only to models that accept one, such as
+  `claude-haiku-4-5`. The `model` descriptions point to `defaultModel` in `GET /v1/models` instead of naming a default.
+  Only the descriptions change; what the tools send is the same.
+- **The server is built against SDK 0.47.0.** During a long streamed answer the platform now sends a `: keepalive`
+  comment line about every 15 seconds; the server ignores it and the tools return the same answers.
+- **Source comments state their rules themselves.** Comments that pointed at an internal design document
+  now say what the rule is, so the source maps that ship with the package read on their own. No behavior changes.
+
 ## 0.18.0 — 2026-10-01
 
 ### Added
@@ -237,7 +282,7 @@ This project adheres to [Semantic Versioning](https://semver.org).
 - **`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
+  agent clearing a folder could have deleted a record 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.**

package/README.md

@@ -232,7 +232,7 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 | Tool | What it does |
 |---|---|
 | `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. Optional `providerAlias` routes one call through your own model provider (see below). |
+| `rag_ask` | Ask a question grounded against the indexed corpus. Scope retrieval through `search` (ownership — `search.scope` or multi-dimension `search.scopeFilters` — / folder / type / metadata filters / date window) and steer generation (`instructions`, and `temperature` for the models that accept one). Streaming generation aggregated; progress notifications keep the call alive for the generation window. Optional `providerAlias` routes one call through your own model provider (see below). |
 | `document_ask` | Ask a question grounded against a single document. Same aggregation + progress-notification shape as `rag_ask`, including the optional `providerAlias`. |
 
 **Records** (structured, schema-validated data)
@@ -279,6 +279,19 @@ 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.
 
+**Concurrent updates.** `record_update`, `document_update`, `folder_update` and `document_ingest` with `upsert: true`
+return `409` (`errorCode: VERSION_CONFLICT`) when another request changed the same item at the same moment, whether or not
+you pass `expectedVersion`. Nothing is written and the other change is kept: re-read the item and retry.
+`expectedVersion` still refuses an update made against a version you read earlier, even if the other change finished long
+ago. An update to an item that was deleted a moment earlier returns `404`. In `record_batch_write` with `upsert`, an item
+that meets another change at the same moment is reported in the results with `status: conflict` and
+`errorCode: VERSION_CONFLICT`; send that item again. Items written with `atomicity: all_or_nothing` are not covered.
+
+**Items of a deleted schema.** An item whose schema no longer exists is not served: reading it (`record_get`,
+`document_get`) returns an error, updating it, reading its `version_history`, and reading a document's text, download or
+answers (`document_ask`) are refused, and `record_query`, `document_query` and `record_batch_get` leave it out. Delete the
+item.
+
 ### Routing a call through your own model provider
 
 `rag_ask` and `document_ask` take an optional `providerAlias`: the alias of a model provider config your Vectros
@@ -288,15 +301,26 @@ provider config's default model when omitted). The server forwards `providerAlia
 never fills it in.
 
 It works only after your account has set up the provider and signed the platform's risk-acceptance waiver. Without
-both, the platform refuses the call with a `403`, which the tool returns to you as written. A call served by your
-own provider leaves the platform-hosted Bedrock path, and Vectros's AWS BAA boundary, so decide deliberately whether a given call should use it.
-Nothing here is a statement about how a provider you chose handles your data.
+both, the platform refuses the call with a `403`, which the tool returns to you as written. When the waiver is the
+cause, the `403` carries an `errorCode` that says which case it is: `WAIVER_NOT_SIGNED` (the waiver has not been
+signed), `WAIVER_TEXT_CHANGED` (it was signed, but its text changed afterwards, so the earlier signature no longer
+counts) or `WAIVER_REVOKED` (an account owner revoked it). An account owner resolves each in the developer portal
+(**Model Providers**); retrying the call does not help.
+
+If your account has accepted the Business Associate Agreement with Vectros in the developer portal, an account owner must also attest each provider
+config in the developer portal (**Model Providers**) before a call can use it. Until then the platform refuses the
+call with a `403` that says it needs a BAA-holder attestation. The owner does this in the portal; nothing in this
+server does it.
+
+A call served by your own provider leaves the platform-hosted Bedrock path, and Vectros's AWS BAA boundary, so
+decide deliberately whether a given call should use it. Nothing here is a statement about how a provider you chose handles your data.
 
 ### Opting into a subset
 
-Pass `VECTROS_MCP_TOOLS=hybrid_search,rag_ask` to register only those
-two — useful for giving an agent read-only search access without
-exposing ingestion or inference costs to the credential. Unknown tool
+Pass `VECTROS_MCP_TOOLS=hybrid_search,record_query,record_get` to register only those
+three — useful for giving an agent read-only access without
+exposing ingestion or inference costs to the credential. Add `rag_ask` or `document_ask`
+only if the credential should be able to spend inference balance. Unknown tool
 names fail fast at startup.
 
 ## Resources
@@ -321,12 +345,11 @@ server emits a `warn` log line on startup when you pass a wildcard
 **The easiest way to get one is `npx -y @vectros-ai/cli bootstrap` (above)**
 — it mints a least-privilege `ssk_*` and an AccessProfile for you, no root
 key required. To do it by hand instead: mint a scoped key from the developer
-portal under **Keys → Create scoped key**, bind it to an AccessProfile
-titled `mcp-read-all` or `mcp-read-scoped`, and drop the resulting
+portal under **Keys → Create scoped key**, bind it to a read-only AccessProfile
+(any name, for example `mcp-read`), and drop the resulting
 `ssk_live_...` into the config above.
 
-See the Vectros developer documentation on scoped tokens ("Recommended
-AccessProfile for MCP") for least-privilege credential setup — the
+See the Vectros developer documentation on scoped tokens for least-privilege credential setup — the
 `vectros bootstrap` flow provisions a scoped `ssk_*` key and its AccessProfile
 in one command.
 
@@ -361,7 +384,7 @@ The server resolves its API key from the first source that yields one:
 
 The resolved key is held in memory and never logged. Startup logs which alias it
 resolved (not the key), so you can tell at a glance which identity the server is
-running as — `vectros keyring doctor` shows the same view.
+running as — `vectros keyring doctor` (CLI 0.10.0+) shows the same view.
 
 > **Startup warns when it picks an identity you didn't name.** If `VECTROS_API_KEY`
 > is unset and no `VECTROS_KEYRING_ALIAS` is set, the server falls back to your
@@ -371,7 +394,7 @@ running as — `vectros keyring doctor` shows the same view.
 > blank placeholder (`"VECTROS_API_KEY": ""` in a client config, or `-e VECTROS_API_KEY`
 > passing through an unset var in Docker) reads as "not configured yet" but resolves
 > like an unset key. Nothing is blocked — name an entry with `VECTROS_KEYRING_ALIAS`,
-> or set `VECTROS_API_KEY`, and the warning goes away. `vectros keyring doctor` shows
+> or set `VECTROS_API_KEY`, and the warning goes away. `vectros keyring doctor` (CLI 0.10.0+) shows
 > which entry is active and which of your keys are live.
 
 ## Environment variables
@@ -511,8 +534,12 @@ The server is on a pre-1.0 track toward a stable 1.0 release.
 ## Rate limits
 
 Tool calls hit the same per-minute rate limits as any API client; the
-[rate limits guide](https://docs.vectros.ai/guides/operations-trust/rate-limits) says which requests count. On a `429` the server surfaces the error with its
-`Retry-After` hint so the agent can pace and retry rather than blind-retrying. The guide also lists
+[rate limits guide](https://docs.vectros.ai/guides/operations-trust/rate-limits) says which requests count. On a rate-limit `429` the tool returns the error with `HTTP 429` and `errorCode: RATE_LIMITED`, so the agent can pace and retry
+rather than blind-retrying. `rag_ask` and `document_ask` can also return `429` with `errorCode: BALANCE_BUSY` (your pre-paid
+balance is momentarily busy with your other concurrent requests: not a rate limit and not a shortage, so do not top up;
+retry shortly) or `503` with `errorCode: BALANCE_UNAVAILABLE` (a temporary fault interrupted the balance step; also not a
+shortage; retry shortly). A `402` means the balance is short (`INSUFFICIENT_BALANCE`) or the plan's usage limit is reached (`SUBSCRIPTION_LIMIT_EXCEEDED`). A `503` with no `errorCode` on a call that names a `providerAlias` means the platform cannot open the stored provider key: retry shortly, and enter the key again in the developer portal if it persists. The tool returns the message, `errorCode` and
+`requestId`, not the `Retry-After` header. The guide also lists
 the per-plan limits.
 
 ## Building from source