@vectros-ai/mcp-server 0.17.2 → 0.18.1

package/CHANGELOG.md

@@ -3,6 +3,61 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 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
+
+- **`document_ingest` takes an optional `confirmUntyped`.** The platform refuses a document create that supplies an
+  `externalId` without a `schemaId` (`400`), because `externalId` is unique per schema. Pass `confirmUntyped: true`
+  to say an untyped document is intended; it works in both text and file mode and is never set for you. An agent
+  that calls `document_ingest` with an `externalId` and no `schemaId` gets that `400` unless it passes
+  `confirmUntyped: true` or a `schemaId`.
+- **`rag_ask` and `document_ask` take an optional `providerAlias`.** It routes that one call through the model
+  provider your account has activated under that alias instead of platform-hosted Bedrock, and `model` then names a
+  model on that provider's own id space. It works only after your account has configured the provider and signed the
+  platform's risk-acceptance waiver; otherwise the platform refuses the call with a `403`, which the tool returns as
+  written. The README section on routing a call through your own provider has the details.
+
+### Changed
+
+- **`rag_ask` and `document_ask` descriptions say where a call is served:** platform-hosted AWS Bedrock by default,
+  your own model provider when `providerAlias` is set.
+- **`document_ingest` in file mode reports how to confirm a replacement.** When the call replaces an existing
+  document's file (`created: false`), the tool description and the response note say to watch the document's
+  `fileItemId` for the new file instead of `indexStatus`, and `document_get`'s `includeDownloadUrl` description says a
+  download URL can stop working before its stated `downloadExpires` once the file is replaced. The description also
+  states that re-ingesting a file against an existing `externalId` needs `documents:u`.
+- **`rag_ask`'s model example is `claude-opus-5-5`,** since `claude-opus-4-8` is retired.
+- **The README states that tool output is untrusted, API-supplied content.** No tool sanitizes, escapes or
+  pre-renders the text it returns; render it safely in your own client.
+
 ## 0.17.2 — 2026-09-22
 
 ### Changed

package/README.md

@@ -86,7 +86,7 @@ Prefer to wire it up by hand? See **Configure manually** below.
 |---|---|---|
 | **Claude Desktop** | [Desktop Extension (`.mcpb`)](https://github.com/vectros-ai/vectros-mcp-server/releases/latest/download/vectros.mcpb) — double-click, paste your key | [JSON snippet](#configure-manually-claude-desktop-or-any-mcp-client) |
 | **Cursor** | [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D) | `.cursor/mcp.json`, same shape as below |
-| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D) | `.vscode/mcp.json`, same shape |
+| **VS Code** | [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D) | `.vscode/mcp.json`, the same entry under a top-level `servers` key |
 | **Claude Code** | `claude mcp add` (below) | [project `.mcp.json`](#configure-manually-claude-code) |
 | **Cline / Continue** | — | same JSON snippet as Claude Desktop |
 | **Smithery** | `npx -y @smithery/cli install @vectros-ai/mcp-server` | — |
@@ -207,8 +207,8 @@ directly with `-e VECTROS_API_KEY=ssk_live_...` — but then keep that config
 **local**: add `.mcp.json` to `.gitignore` first, rather than committing it
 with the key inside.
 
-Add `-e VECTROS_API_BASE_URL=https://api.staging.vectros.ai` for a non-production
-environment.
+Add `-e VECTROS_API_BASE_URL=<your environment's API base URL>` to point the server at a
+different 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
@@ -219,12 +219,11 @@ 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.
+> `@vectros-ai` scope at another registry, a bare `npx -y @vectros-ai/mcp-server`
+> can resolve a build other than the public release. 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)
 
@@ -233,8 +232,8 @@ 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. |
-| `document_ask` | Ask a question grounded against a single document. Same aggregation + progress-notification shape as `rag_ask`. |
+| `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)
 
@@ -253,8 +252,8 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 
 | Tool | What it does |
 |---|---|
-| `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_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. An `externalId` with no `schemaId` is refused by platform 0.46.0 and later unless you also pass `confirmUntyped: true`. |
+| `document_query` | Query documents by lookup field (equality / range / prefix, with `asc`/`desc` ordering) or list mode (filter by folder and ownership). |
 | `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 — always forces a download, never inline rendering, regardless of file type). |
 | `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). |
@@ -280,11 +279,31 @@ 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.
 
+### 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
+account has activated. When you pass it, that one call is served by your own provider instead of the
+platform-hosted default, and `model` then names a model on your provider's own id space (it falls back to that
+provider config's default model when omitted). The server forwards `providerAlias` only when you supply it and
+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.
+
+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
@@ -309,12 +328,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.
 
@@ -349,7 +367,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
@@ -359,7 +377,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
@@ -368,7 +386,7 @@ running as — `vectros keyring doctor` shows the same view.
 |---|---|---|---|
 | `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_API_BASE_URL` | no | `https://api.vectros.ai` | Override for another environment. 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. |
 | `VECTROS_MCP_TOOLS` | no | (all tools) | Comma-separated tool names (e.g. `hybrid_search,rag_ask`). |
@@ -498,17 +516,16 @@ The server is on a pre-1.0 track toward a stable 1.0 release.
 
 ## Rate limits
 
-Tool calls hit the same per-account per-minute rate limit as any API client (writes, searches,
-and inference count against it; reads do not). On a `429` the server surfaces the error with its
-`Retry-After` hint so the agent can pace and retry rather than blind-retrying. See the
-[rate limits guide](https://docs.vectros.ai/guides/operations-trust/rate-limits) for the per-plan
-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 tool returns the error with `HTTP 429` and `errorCode: RATE_LIMITED`, so the agent can pace and retry
+rather than blind-retrying. The guide also lists
+the per-plan limits.
 
 ## Building from source
 
 ```sh
 git clone https://github.com/vectros-ai/vectros-mcp-server
-cd mcp-server
+cd vectros-mcp-server
 npm install
 npm run build
 npm test
@@ -530,6 +547,12 @@ tamper-evident audit and version history. Customer-facing surfaces are hardened
 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).
 
+**Tool output is untrusted, API-supplied content.** Every tool here returns your own tenant's data —
+document text, search results, error messages — as plain text inside the MCP response. This server
+does not sanitize, escape, or pre-render that text, and none of these tools evaluate or execute it.
+Render tool output the same way you'd render any other data an agent pulled from an external source
+— safely, in your client — rather than `eval`-ing it or trusting it as pre-sanitized.
+
 ## License
 
 Apache-2.0. See the LICENSE file.