@astral-mcp/projection 0.8.0 → 0.9.0

package/README.md

@@ -13,24 +13,45 @@ Both SDK packages are pinned at `2.0.0` in Projection's own dependencies, so
 install the same version to match the pin.
 
 Projection wraps an existing MCP server and exposes two projections of it —
-five tools in all, never the wrapped server's own:
+five tools in all, never a pass-through to the wrapped server's own:
 
 - **Code mode** — `execute_machine` runs an LLM-authored XState v5 state
-  machine in a QuickJS WebAssembly sandbox (read-only calls run inline; any
-  write suspends the machine into a sealed, encrypted blob and asks the human
-  to approve that exact call via MRTR elicitation); `discover_apis` returns
+  machine in a QuickJS WebAssembly sandbox (read-only calls, or, under
+  `destructive-only`, a non-destructive write, run inline; any other write
+  suspends the machine into a sealed, encrypted blob and asks the human to
+  approve that exact call via MRTR elicitation); `discover_apis` returns
   the generated TypeScript definitions and the authoring contract.
 - **Catalog** — `search_tools` lists the wrapped tools with their approval
-  posture, `describe_tool` returns one tool's schemas (and its generated
+  posture (a query's top three hits with their arguments), `describe_tool` returns one tool's schemas (and its generated
   types on request, `types: true`), and `call_tool` runs one tool by name
   under the same approval gate. The instructions route the model: one step
   → `call_tool`; a workflow → `execute_machine`. Either projection can be
   disabled (`projections: { codeMode: false }` or `{ catalog: false }`; not
   both).
+- **Direct listing** (default `projections.direct: 'auto'`) — when the
+  wrapped tools' estimated definitions fit `directBudgetTokens` (8 000),
+  each is also listed by name (`<box>__<tool>` on a multi-server facade) as
+  a mediated alias of `call_tool` under the same gate, and `search_tools`
+  is dropped. `projections: { direct: false }` keeps the five tools.
 
 Every tool surface uses one posture vocabulary: a tool `runs immediately`
-(read-only, or `auto` by policy), `asks for approval`, or is `blocked by
-policy`.
+(read-only, `auto` by policy, or, under `destructive-only`, a non-destructive
+write), `asks for approval`, or is `blocked by policy`.
+
+`approvals` sets the approvals mode: `'every-write'` (default) asks before
+every tool that is not read-only; `'destructive-only'` also runs, without
+approval, a tool whose annotations declare `destructiveHint: false` exactly
+(a missing or any other hint still asks). A per-tool `policy` override wins
+over the mode. The mode extends the trust Projection places in
+`readOnlyHint` to `destructiveHint: false`, and a hostile server can
+mislabel a damaging tool — enable it only for servers you trust.
+
+`upstreamElicitation: 'forward'` lets a trusted wrapped server ask the user
+questions mid-call (a form, or a link to open): each is relayed over MRTR as
+`Question from <box> (not an approval)` with the server's words quoted and
+its form allowlisted, after the call itself passed the approval gate. The
+default, `'refuse'`, fails such a call with a result telling the model the
+tool needs the user's input. Per box on `wrapMcpServers`.
 
 All suspension state rides the MRTR `requestState` payload, so Projection is
 fully stateless: any server instance can resume any workflow.
@@ -44,6 +65,8 @@ import { wrapMcpServer } from '@astral-mcp/projection';
 const facade = await wrapMcpServer(myMcpServer, {
   blob: { key: myThirtyTwoByteKey }, // shared across instances
   policy: { query: 'ask' }, // override annotations per tool
+  // approvals: 'destructive-only', // skip approval for destructiveHint: false writes (trusted servers only)
+  // upstreamElicitation: 'forward', // pass the server's own questions on to the user (trusted servers only)
   redact: (tool, args) => ({ ...args, token: '[redacted]' }),
 });
 
@@ -56,6 +79,31 @@ still run read-only machines and calls, and get a structured error the
 moment a call needs approval. You can also wrap a connected SDK `Client` to put
 Projection in front of a server you don't own.
 
+### Several servers (preview)
+
+`wrapMcpServers({ fs: filesServer, github: { source: githubClient } }, options)`
+fronts several servers as tool boxes: tools are addressed as
+`<alias>.<name>` (`fs.write_file`), policy keys are qualified names, each
+box has its own `search_<alias>` tool (whose first page shows the server's
+guidance), and `search_tools` searches every box (`catalog.globalSearch:
+false` turns it off). Code mode works across boxes: the generated types have
+one `tools.<alias>` property per box, and machines call
+`toolCall('fs.read_file', args)`. Optional sources are not available yet.
+See `docs/server-authors.md`.
+
+### Remote servers by URL (preview)
+
+Any source can be `{ url, oauth?: { clientId, scopes } }`: Projection builds
+the Streamable HTTP connection itself, uses and refreshes tokens from a
+token store (the OS credential store through the optional
+`@napi-rs/keyring` dependency by default, or `WrapOptions.tokenStore`, a
+plain string key-value store), and `facade.signOut()` clears them. Never put
+a token in an MCP configuration file. Just-in-time sign-in (asking the user
+on first use) is not supported in this version: a public server works, and
+so does one whose token is already in your `tokenStore`; otherwise the wrap
+fails with an `auth` error. See "Upstream authentication" in
+`docs/server-authors.md`.
+
 ## Security model
 
 | Invariant                                               | How it holds                                                                                                                                      |
@@ -71,6 +119,9 @@ Projection in front of a server you don't own.
 Known limitation: unless you supply a shared `replayCache` (R38), an approved
 retry can be replayed until its blob expires (by default 5 min for
 `call_tool`, 15 for machines; `blob.callTtlMs` and `blob.ttlMs` override).
+A forwarded server question's blob keeps the expiry of the approval it
+follows. With `upstreamElicitation: 'forward'` on, a `replayCache` is
+recommended.
 See
 [Lifecycle](https://github.com/astralMCP/projection/blob/main/docs/server-authors.md#lifecycle-and-operations).