@vectros-ai/mcp-server 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -3,6 +3,105 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.11.0
+
+Refreshed to the 0.36.0 Vectros API, with clearer, more actionable errors and a
+few tool-surface corrections.
+
+### Changed
+
+- **Tool errors now carry the server's real reason, a typed code, and a request
+  id.** When a tool call fails, the result surfaces the API's own message, the
+  machine-readable `errorCode` (so an agent can branch on the cause — e.g.
+  `INSUFFICIENT_BALANCE` "top up your balance" versus `SUBSCRIPTION_LIMIT_EXCEEDED`
+  "upgrade your plan" on a payment-required failure, or a placement/authorization
+  denial), and the `requestId` to quote to support — instead of a bare HTTP status
+  and a generic class name.
+- **`document_ingest` rejects `storeText` in text mode instead of ignoring it.**
+  `storeText` only applies to file uploads (it controls whether a file's extracted
+  text is retained). A text-ingested body is the document itself and is always
+  retained, so passing `storeText` alongside `text` is now refused with a clear
+  message rather than silently having no effect.
+
+### Added
+
+- **Errors surface the 0.36.0 typed error codes.** Payment-required failures on
+  `rag_ask` / `document_ask` now distinguish an exhausted pre-paid balance from a
+  reached plan limit; a number outside the signed 64-bit range is reported as a
+  `400` naming the field.
+- **Guidance for search-indexing failures.** `document_get` and `record_get`
+  descriptions explain the `indexFailure.code` that accompanies a `FAILED`
+  `indexStatus`, so an agent can tell content that is still partly findable
+  (e.g. `VECTOR_LIMIT_EXCEEDED`, keyword search still serves it) from content that
+  is not findable at all (`INDEXING_FAILED`).
+- **Large-number guidance.** `record_create` and `document_ingest` note that every
+  number must fall within the signed 64-bit range and that larger whole numbers
+  (e.g. big external ids) should be sent as strings, which store exactly and support
+  exact-match lookup.
+
+### Fixed
+
+- **`current_identity` / the `identity` resource describe the identity shape they
+  actually return.** The obsolete "the backend is still rolling this out" caveat is
+  gone; the extended shape (`principalType`, `principalKeyId`, `allowedActions`, and
+  a `dataScope` of `{ userId, scopes[] }`) is returned today.
+- **`hybrid_search` gives accurate keyword-leg guidance.** When the keyword leg
+  matches nothing (`textLegEmpty`), the description now explains that the default
+  phrase match found no contiguous hit for a long query and points to shortening the
+  query or setting `textMode` to `AND` (precision) or `OR` (recall), rather than
+  prescribing a single fix.
+- **`record_create` and `folder_create` describe the scope needed to receive an
+  existing item on a collision, not just to create one.** Both tools are
+  idempotent by key (`externalId` for records, `slug` for folders); the
+  description previously said only `records:c`/`folders:c` was required, but
+  being handed back the existing item on a collision is a read of that item
+  and separately requires `records:r`/`folders:r`. A key holding only the
+  create scope now gets an accurate description of the "already exists"
+  error it will see instead of the record.
+
+## 0.10.0
+
+### Changed (breaking)
+
+- **Organization and client identities are now namespaces.** The tools that took
+  `orgId` / `clientId` now use namespaced scopes:
+  - `lookup_principal`: `kind` is `"user"` or a namespace (`org`, `client`, or
+    one you define).
+  - Write tools (`record_create`, `folder_create`, `folder_update`,
+    `document_ingest`, `document_update`): the `orgId` / `clientId` inputs are
+    replaced by `scopes` — an array of `namespace:value` entries, e.g.
+    `["org:<id>"]`.
+  - Read and query tools (`record_query`, `document_query`, `folder_query`,
+    `hybrid_search`, `rag_ask`, `list_schemas`): the `orgId` / `clientId` filters
+    are replaced by a single `scope` filter (`namespace:value`). `list_schemas`'s
+    `surface` now accepts `record`, `document`, `user`, `entity`.
+
+### Added
+
+- **Automatic API-key resolution from the Vectros CLI keyring.** When
+  `VECTROS_API_KEY` is not set, the server now resolves its key by invoking the
+  `vectros` CLI credential helper (`vectros keyring show --format raw`) as a
+  subprocess — so a key stored once in the CLI keyring is shared by the server, agent
+  hooks, and scripts, instead of a plaintext copy pasted into the server's config
+  that silently drifts. `VECTROS_API_KEY` still takes precedence when set (behavior
+  unchanged), and an unset key now falls back to the keyring rather than failing
+  immediately. Set `VECTROS_KEYRING_ALIAS` to resolve a specific keyring entry
+  instead of the active one. Requires **`@vectros-ai/cli` 0.9.0+** on `PATH` (the
+  version the keyring itself shipped in — the helper deliberately calls no command
+  newer than that, so it works with an existing install); if neither an env key nor
+  the CLI is available, startup fails with actionable guidance naming both options.
+  The resolved key is held in memory only and never logged.
+- **Startup says which identity it resolved, and warns when you didn't name one.**
+  The startup log names the keyring entry the key came from (never the key itself).
+  When `VECTROS_API_KEY` is unset and no `VECTROS_KEYRING_ALIAS` is given, the key
+  comes from whichever entry was last made active — and that log is a **warning**,
+  whatever key turns up: silently getting a live key (acting on real data) and
+  silently getting a test key (not acting on it, when you believed you were) are both
+  unwelcome. It is easy to reach by accident, because a blank placeholder
+  (`"VECTROS_API_KEY": ""` in a client config, or a Docker `-e` pass-through of an
+  unset var) reads as "not configured yet" but resolves like an unset key. Nothing is
+  blocked, and naming an entry never warns.
+
 ## 0.9.0
 
 ### Added

package/README.md

@@ -213,7 +213,7 @@ available.
 
 | Tool | What it does |
 |---|---|
-| `current_identity` | Describe the credential: tenantId, environment, principalType, and (where surfaced) allowedActions + dataScope. |
+| `current_identity` | Describe the credential: tenantId, environment, principalType, principalKeyId, and (for scoped credentials) allowedActions + dataScope. |
 | `lookup_principal` | Resolve a user / org / client by your own `externalId` (→ its Vectros UUID, for the ownership filters) or by a schema lookup field. Read-only. |
 | `version_history` | Read the audit/version trail (CREATE/UPDATE/DELETE, with actor + diff) for one record or document. Read-only. |
 
@@ -242,7 +242,7 @@ Two read-only resources for ambient context (no tool call required):
 Use a **scoped permanent API key** (`ssk_*`), not a root key (`sk_*`).
 
 A scoped key is bound to a narrowed `AccessProfile` — e.g. read-only
-across one `orgId`. If your MCP install is compromised, the blast
+across one org scope (`scope:org`). If your MCP install is compromised, the blast
 radius is whatever the profile allows, not the whole tenant. The
 server emits a `warn` log line on startup when you pass a wildcard
 `sk_*` for exactly this reason.
@@ -259,11 +259,42 @@ AccessProfile for MCP") for least-privilege credential setup — the
 `vectros bootstrap` flow provisions a scoped `ssk_*` key and its AccessProfile
 in one command.
 
+## Credential resolution
+
+The server resolves its API key from the first source that yields one:
+
+1. **`VECTROS_API_KEY`** — always wins when set.
+2. **The `vectros` CLI keyring** — if the key is unset and
+   [`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli) **0.9.0+** is on
+   your `PATH`, the server runs `vectros keyring show --format raw` as a subprocess
+   and uses the key it prints. By default that is your **active** identity; set
+   `VECTROS_KEYRING_ALIAS` to pick a specific entry. This is the same pattern as
+   `git credential` / `docker-credential-*` / `aws credential_process`: the key
+   lives in one place, and the server, your scripts, and your agent hooks all read
+   it from there instead of each keeping a plaintext copy that drifts.
+3. **Neither** — startup fails with a message naming both options.
+
+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.
+
+> **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
+> **active** keyring entry and logs a warning — it is running as whatever identity
+> `vectros switch` last selected, which may be a `ssk_live_*` key acting on real data
+> or a `ssk_test_*` one that isn't. Either can be an unwelcome surprise, because a
+> 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
+> which entry is active and which of your keys are live.
+
 ## Environment variables
 
 | Var | Required | Default | Purpose |
 |---|---|---|---|
-| `VECTROS_API_KEY` | **yes** | — | Vectros API key. Accepts `sk_*` / `ssk_*` / `st_*`; `ssk_*` recommended. |
+| `VECTROS_API_KEY` | no\* | — | Vectros API key. Accepts `sk_*` / `ssk_*` / `st_*`; `ssk_*` recommended. \*Required **unless** the `vectros` CLI is installed with a usable keyring entry — see [Credential resolution](#credential-resolution). Takes precedence when set. |
+| `VECTROS_KEYRING_ALIAS` | no | (the active entry) | Resolve this `vectros` keyring entry instead of the active one. Ignored when `VECTROS_API_KEY` is set. |
 | `VECTROS_API_BASE_URL` | no | `https://api.vectros.ai` | Override for staging or other envs. Validated: must be `https://` (or `http://` to localhost) and an official `*.vectros.ai` host. |
 | `VECTROS_ALLOW_INSECURE_BASE_URL` | no | — | Set `1` to bypass the base-URL allow-list (e.g. a trusted local proxy). **Not recommended** — sends your key to an unvalidated host; logs a warning. |
 | `VECTROS_MCP_INGEST_ROOT` | no | process cwd | Directory `document_ingest`'s `filePath` mode is jailed to. Paths escaping it (traversal/absolute/symlink) or matching a sensitive pattern are rejected. |
@@ -310,7 +341,7 @@ Health probe lives at `GET /healthz` (always unauthenticated, k8s
 readiness-friendly).
 
 Current limitation: the server uses one upstream credential per process
-(the env `VECTROS_API_KEY`). Per-request credential override via the
+(the key resolved at startup). Per-request credential override via the
 incoming Authorization header is a planned enhancement. For now, deploy one
 server per credential boundary you want.