@vectros-ai/mcp-server 0.7.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,107 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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
+
+- **Ownership scopes on writes.** `record_create`, `document_ingest`, and `folder_create`
+  accept a `scopes` array of `namespace:value` entries (at most 2 — e.g.
+  `["org:<uuid>", "group:eng-team"]`), declaring the item's complete scope ownership
+  from the credential's own identity. An empty array (`[]`) creates a **private**,
+  user-owned item — the building block for per-user agent memory alongside shared
+  team content. Omit the field to keep today's behavior (the credential's full
+  identity is stamped).
+- **`scope` filter on reads and retrieval.** `record_query` and `document_query`
+  (list mode), `hybrid_search`, and `rag_ask` retrieval accept a `scope` filter in the
+  same `namespace:value` form, confining results — or a grounded answer's corpus — to
+  one scope. `scope=org:<id>` / `scope=client:<id>` are equivalent to the existing
+  `orgId`/`clientId` filters.
+
+## 0.8.1 — 2026-07-10
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.34.0`
+  (additive `scopes` read-back on record/document/folder responses, plus webhooks).
+  The server bundles the SDK into its published output, so this is a rebuild against
+  the current SDK; no tool behavior changes.
+
+## 0.8.0 — 2026-07-10
+
+Larger result limits and real pagination across every enumeration tool — no tool
+forces you to accept a hard ceiling you can't get past.
+
+### Changed
+
+- **Higher `limit` ceilings, up to each API's max.** Every enumeration tool keeps a low
+  default (context protection) but now lets you raise `limit` in a single call when you
+  can accept the larger payload: `record_query` and `document_query` max **10 → 100**;
+  `hybrid_search` max **10 → 50**; `rag_ask`'s grounding-corpus limit max **10 → 50**;
+  `lookup_principal` max **50 → 100**; `folder_query` max **50 → 100**. Heavy
+  passages/payloads already auto-truncate, so a high limit is safe.
+- **Pagination on every enumeration tool, with an explicit "more remains" signal.**
+  - `record_query`, `document_query`, and `lookup_principal` now return a
+    `{ data, nextCursor }` page and accept a `startFrom` cursor. **This is a shape change**
+    — these tools previously returned a bare array. A non-null `nextCursor` means more
+    results remain; pass it back as `startFrom` to page. (This matches `folder_query` and
+    `version_history`, which already worked this way.)
+  - `hybrid_search` keeps `offset` pagination and now adds an explicit `hasMore` flag
+    (derived from `totalResults`) so you know when results remain past the current page.
+- **Tool descriptions refreshed** to state the real max, that raising it is the agent's
+  context-cost call, and how to page.
+
+## 0.7.1 — 2026-07-09
+
+### Changed
+
+- **`rag_ask` model examples updated.** The `model` parameter description now lists
+  `claude-sonnet-5`; the earlier `claude-sonnet-4-6` alias has been retired. Call
+  `GET /v1/models` for the current inference catalog your key can reach.
+
 ## 0.7.0 — 2026-07-05
 
 Text-retention control that works, and tool descriptions that tell the truth

package/README.md

@@ -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.
 
@@ -376,6 +407,13 @@ registry.
 self-contained and works without `.npmrc` config on the consumer's
 machine.
 
+## Security & trust
+
+Vectros enforces per-customer, fail-closed isolation and least-privilege scoped keys, with a
+tamper-evident audit and version history. Customer-facing surfaces are hardened through extensive
+adversarial security review. For the full trust posture, drawn plainly with its boundaries, see the
+[compliance and trust guide](https://docs.vectros.ai/guides/operations-trust/compliance).
+
 ## License
 
 Apache-2.0. See the LICENSE file.