@vectros-ai/mcp-server 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -3,6 +3,110 @@
 All notable changes to `@vectros-ai/mcp-server` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org).
 
+## 0.17.1 — 2026-09-17
+
+### Security
+
+- **README no longer instructs committing a live API key.** Both "Configure manually" examples
+  (Claude Desktop and Claude Code) led with a JSON snippet embedding a real `ssk_live_...` value,
+  and the Claude Code section explicitly said to commit the resulting `.mcp.json` "to share the
+  server with the repo" — on the page that renders as this package's npm landing page. Both
+  sections now lead with the keyring-based config (no `env` block, no secret in the file — the
+  server resolves the key from the local `vectros` CLI keyring, same as before) and explicitly warn
+  against committing a config that does carry a real key.
+
+### Added
+
+- **All 23 tools now declare MCP annotations** (`readOnlyHint`/`destructiveHint`/`idempotentHint`)
+  in the actual `tools/list` response, not just their own source — a host previously had nothing
+  to gate a confirmation prompt on, so every tool looked alike including the deletes and the
+  batch-write. Annotated per tool against what its handler actually calls, not its name:
+  - Reads with no real-money leg (`hybrid_search`, `record_get`/`_query`/`_batch_get`,
+    `document_get`/`_query`, `folder_query`, `list_schemas`, `current_identity`,
+    `lookup_principal`, `version_history`) are `readOnlyHint: true`.
+  - `rag_ask` and `document_ask` are **not** read-only: both reserve an atomic hold against the
+    caller's prepaid inference balance before generation and debit it on completion, which can
+    trigger a configured auto-recharge against a payment method on file. Also not idempotent —
+    every repeat charges again, and generation is non-deterministic.
+  - `record_create`, `document_ingest`, and `record_batch_write` each dedupe by an OPTIONAL
+    `externalId` — supplying it makes a retry converge, omitting it does not — so all three are
+    annotated for that less-safe default (`idempotentHint: false`), not the safer opt-in;
+    `document_ingest` and `record_batch_write` are additionally flagged destructive because their
+    `upsert:true` paths overwrite existing content.
+  - `folder_create` is idempotent **only when the caller supplies `slug` explicitly** — an omitted
+    slug is derived through a collision-probing suffix loop that returns only a value already
+    proved free, so a retry with no `slug` creates a new sibling folder rather than converging.
+    Annotated `idempotentHint: false` for that default, the same standard as the optional-key
+    create tools above.
+  - The three `*_update` tools (JSON Merge Patch) and the three `*_delete` tools are all flagged
+    destructive.
+
+  Verified against the real, over-the-wire `tools/list` response from the compiled binary, not the
+  source that builds it.
+
+### Fixed
+
+- **`document_ingest` in file mode now works against an API that makes presigned upload URLs
+  single-use.** Such an API bakes a conditional-write header into the upload URL's signature and
+  names it in the upload response (`requiredHeaderName` / `requiredHeaderValue`); the tool's PUT
+  omitted it, so storage rejected the upload with a 403 and the tool reported the document as
+  created but incomplete. The tool now sends whatever header the response names, and no extra
+  header when the response names none, so it works against API versions on either side of the
+  change.
+
+- **A failed startup could abort the whole process with a native Windows crash instead of the
+  server's own exit code.** Both entry points (`vectros-mcp-server`, `vectros-mcp-server-http`)
+  end EVERY startup failure path — a missing/invalid credential, a bad `--` env config, a rejected
+  `GET /v1/ping` check (enabled by default; `VECTROS_MCP_SKIP_PING_VALIDATION` to opt out) — with a
+  raw `process.exit()`. On Windows, an async operation still settling (a `fetch` for the ping check;
+  an `execFile` spawn out to the local CLI keyring helper for credential resolution) when
+  `process.exit()` runs can race libuv and abort the process, printing an `Assertion failed` line
+  and replacing the real exit code with `127` — the same class of defect fixed in `@vectros-ai/cli`
+  around the same time. Every startup-failure exit in both files now sets `process.exitCode` and
+  lets the event loop drain naturally, instead of hard-exiting.
+
+  This needed one adjustment `@vectros-ai/cli`'s equivalent fix didn't: both entry points register
+  `SIGINT`/`SIGTERM` handlers for graceful shutdown, and Node keeps a process alive for as long as
+  either signal has a registered listener. Registering them before the connect attempt would mean a
+  failed connect never actually exits under the new idiom — it hangs forever instead, waiting for a
+  signal that will never come. Both files register those handlers only after a successful connect,
+  so a failed startup still exits promptly; the alternative (register early, make the shutdown
+  handler itself exit-code-safe too) doesn't work here, because the ping check's underlying fetch
+  has no timeout and no cancellation — that path trades the crash for a possible silent hang on a
+  stuck connection instead of fixing it.
+
+- **Two integration tests carried an internal issue number and internal review-process wording**
+  (a bare tracker reference in two test names/comments describing the exit-code fix above, and one
+  comment describing a defect an earlier internal review pass had caught). This package's GitHub
+  source mirror ships `tests/` verbatim, so both leaked into the public repo. Reworded to
+  self-contained descriptive text; no behavioral change.
+
+- **Four more source comments carried an internal workstream/finding code**, on the base-URL
+  SSRF/credential-exfil guard in `cli.ts`, `cli-http.ts`, `server.ts`, and its test — found on a
+  later sweep with a wider scan pattern. The substantive rationale was already self-contained in
+  each comment; only the bare internal code was dropped. No behavioral change.
+
+- **One more source comment on that same base-URL guard named a sibling package's file by
+  monorepo-relative path** (`base-url.ts`'s own doc comment, describing that the same guard is
+  ported into another package's CLI) — found by a post-merge audit. Reworded to describe the
+  sibling generically. No behavioral change.
+
+- **One source comment named an internal backend class by name** (`record_query.ts`, describing
+  how a composite field's identity is joined on the backend). Reworded to describe the mechanism
+  without the class name. No behavioral change.
+
+### Docs
+
+- **`current_identity`'s capability-gap list now includes `trigger-control-plane-grant`**, the
+  sixth named `granted_capabilities` value, alongside the five it already tracked. **`document_get`'s
+  `downloadUrl` description now notes the platform always forces `attachment` disposition** on
+  download, so a caller expecting inline rendering of a safe type knows to expect a save prompt
+  instead. No behavior changed — both were description-only gaps.
+
+### Changed
+
+- **Dependency maintenance** — repinned the bundled `@vectros-ai/sdk` to `0.44.0`.
+
 ## 0.17.0 — 2026-09-07
 
 ### Added

package/README.md

@@ -123,6 +123,29 @@ Precision is the pitch — what this server deliberately does *not* do:
 
 ## Configure manually (Claude Desktop or any MCP client)
 
+If `@vectros-ai/cli` is installed **globally** (`npm install -g @vectros-ai/cli`,
+not a one-off `npx` run — the server needs `vectros` to still be on `PATH`
+later, when IT runs, not just while bootstrap ran) and you've run
+`vectros bootstrap` with it, omit the `env` block entirely — the server
+resolves your key from the local `vectros` CLI keyring automatically (see
+[Credential resolution](#credential-resolution) below). `vectros login` alone
+does **not** do this — it stores a separate sign-in session, not this key —
+so `bootstrap` is the step that actually has to have run:
+
+```json
+{
+  "mcpServers": {
+    "vectros": {
+      "command": "npx",
+      "args": ["-y", "@vectros-ai/mcp-server"]
+    }
+  }
+}
+```
+
+No CLI installed, or a machine you can't log in on? Set the key directly
+instead:
+
 ```json
 {
   "mcpServers": {
@@ -137,34 +160,53 @@ Precision is the pitch — what this server deliberately does *not* do:
 }
 ```
 
+This file lives under Claude Desktop's own per-user app-support directory,
+not a shared repo — but a real key pasted into it is still a live secret at
+rest: don't paste it into a chat, ticket, or screenshot with the value
+intact, and prefer the keyring form above whenever you can.
+
 Restart Claude Desktop. The agent now sees the Vectros tools and
 two resources as callable surfaces.
 
 ## Configure manually (Claude Code)
 
-Claude Code reads a project-scoped `.mcp.json` with the same shape — drop this
-at your project root (commit it to share the server with the repo):
+Claude Code reads a project-scoped `.mcp.json` with the same shape.
+**Never commit a real key into it** — `.mcp.json` is exactly the kind of file
+teams check in to share a project's tooling, and a live `ssk_*`/`sk_*` value
+inside it is a credential leak the moment it lands in git history, not just
+if the repo is public.
+
+The way to share this config safely: commit the entry with **no `env` block
+at all**, and let each developer's own `vectros` CLI keyring supply the key
+(see [Credential resolution](#credential-resolution) below — this is the
+same delegation `git credential` / `docker-credential-*` use). This needs
+each teammate to have `@vectros-ai/cli` installed **globally** and to have
+run `vectros bootstrap` with it — `npx`-ing the CLI once, or running
+`vectros login` alone (a separate sign-in session, not this key), leaves
+nothing on `PATH` or in the keyring for the server to find later:
 
 ```json
 {
   "mcpServers": {
     "vectros": {
       "command": "npx",
-      "args": ["-y", "@vectros-ai/mcp-server"],
-      "env": {
-        "VECTROS_API_KEY": "ssk_live_..."
-      }
+      "args": ["-y", "@vectros-ai/mcp-server"]
     }
   }
 }
 ```
 
-Or let Claude Code's CLI write it for you:
+Or let Claude Code's CLI write that keyring-based entry for you:
 
 ```bash
-claude mcp add vectros -e VECTROS_API_KEY=ssk_live_... -- npx -y @vectros-ai/mcp-server
+claude mcp add vectros -- npx -y @vectros-ai/mcp-server
 ```
 
+If a machine genuinely has no `vectros` CLI installed, you can pass the key
+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.
 
@@ -213,7 +255,7 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 |---|---|
 | `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_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). |
+| `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). |
 
@@ -230,7 +272,7 @@ resolves to its main repo's `.mcp.json` — add and open from the same project.
 
 | 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`, 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`). |
+| `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 and `trigger-control-plane-grant` in 0.44.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. |