@astral-mcp/projection 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +39 -19
  2. package/dist/index.d.mts +288 -267
  3. package/dist/index.d.mts.map +1 -1
  4. package/dist/index.mjs +617 -220
  5. package/dist/index.mjs.map +1 -1
  6. package/package.json +9 -8
package/README.md CHANGED
@@ -1,11 +1,19 @@
1
1
  # @astral-mcp/projection
2
2
 
3
- Turn any MCP server into a **code-mode** server with **human-approved side
4
- effects**, built on MCP MRTR (Multi Round-Trip Requests, revision
5
- 2026-07-28) and XState v5.
3
+ Wrap any MCP server in **code mode** (LLM-authored XState workflows) and a
4
+ **tool catalog** (search, describe, call), with **human-approved side
5
+ effects** over MCP MRTR (Multi Round-Trip Requests).
6
+
7
+ ```bash
8
+ npm install @astral-mcp/projection @modelcontextprotocol/server@2.0.0
9
+ ```
10
+
11
+ Add `@modelcontextprotocol/client@2.0.0` when wrapping a connected `Client`.
12
+ Both SDK packages are pinned at `2.0.0` in Projection's own dependencies, so
13
+ install the same version to match the pin.
6
14
 
7
15
  Projection wraps an existing MCP server and exposes two projections of it —
8
- five tools, never the wrapped server's own:
16
+ five tools in all, never the wrapped server's own:
9
17
 
10
18
  - **Code mode** — `execute_machine` runs an LLM-authored XState v5 state
11
19
  machine in a QuickJS WebAssembly sandbox (read-only calls run inline; any
@@ -13,10 +21,16 @@ five tools, never the wrapped server's own:
13
21
  to approve that exact call via MRTR elicitation); `discover_apis` returns
14
22
  the generated TypeScript definitions and the authoring contract.
15
23
  - **Catalog** — `search_tools` lists the wrapped tools with their approval
16
- posture, `describe_tool` returns one tool's schemas and types, and
17
- `call_tool` runs one tool by name under the same approval gate. The
18
- instructions route the model: one step → `call_tool`; a workflow →
19
- `execute_machine`. Either projection can be disabled.
24
+ posture, `describe_tool` returns one tool's schemas (and its generated
25
+ types on request, `types: true`), and `call_tool` runs one tool by name
26
+ under the same approval gate. The instructions route the model: one step
27
+ → `call_tool`; a workflow → `execute_machine`. Either projection can be
28
+ disabled (`projections: { codeMode: false }` or `{ catalog: false }`; not
29
+ both).
30
+
31
+ Every tool surface uses one posture vocabulary: a tool `runs immediately`
32
+ (read-only, or `auto` by policy), `asks for approval`, or is `blocked by
33
+ policy`.
20
34
 
21
35
  All suspension state rides the MRTR `requestState` payload, so Projection is
22
36
  fully stateless: any server instance can resume any workflow.
@@ -44,15 +58,21 @@ Projection in front of a server you don't own.
44
58
 
45
59
  ## Security model
46
60
 
47
- | Invariant | How it holds |
48
- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
49
- | The tools bridge is the only way out of the sandbox | No `fetch`, no filesystem, no host globals; only `xstate` and `@astral-mcp/tools` resolve as imports |
50
- | No gated call runs without a matching approval | The approved name and arguments are sealed in the blob and executed from there |
51
- | Clients are untrusted couriers | Blobs are AES-256-GCM encrypted under a per-blob HKDF-derived key and authenticated |
52
- | A snapshot cannot resume under different code | The blob binds a SHA-256 hash of the original `code` — for `call_tool`, of the canonical `{ kind, name, args }` request |
53
- | A blob answers only the tool that issued it | Blobs carry their kind; a `call_tool` blob cannot resume `execute_machine` or vice versa |
54
- | A wrapped server's annotations are hints, not authority | Unannotated tools default to asking; developer overrides always win |
55
- | Approval prompts cannot be forged | Prompt text comes from the catalog and redacted arguments, rendered inert |
61
+ | Invariant | How it holds |
62
+ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
63
+ | The tools bridge is the only way out of the sandbox | No `fetch`, no filesystem, no host globals; only `xstate` and `@astral-mcp/tools` are meant for authored code; nothing that performs I/O resolves |
64
+ | No gated call runs without a matching approval | The approved name and arguments are sealed in the blob and executed from there |
65
+ | Clients carry state but can neither read nor alter it | Blobs are AES-256-GCM encrypted under a per-blob HKDF-derived key and authenticated |
66
+ | A snapshot cannot resume under different code | The blob binds a SHA-256 hash of the original `code` — for `call_tool`, of the canonical `{ kind, name, args }` request |
67
+ | A blob answers only the tool that issued it | Blobs carry their kind; a `call_tool` blob cannot resume `execute_machine` or vice versa |
68
+ | A wrapped server's annotations are hints, not authority | Unannotated tools default to asking; developer overrides always win |
69
+ | Approval prompts cannot be forged | Prompt text comes from the catalog and redacted arguments, rendered inert |
70
+
71
+ Known limitation: unless you supply a shared `replayCache` (R38), an approved
72
+ retry can be replayed until its blob expires (by default 5 min for
73
+ `call_tool`, 15 for machines; `blob.callTtlMs` and `blob.ttlMs` override).
74
+ See
75
+ [Lifecycle](https://github.com/astralMCP/projection/blob/main/docs/server-authors.md#lifecycle-and-operations).
56
76
 
57
77
  ## Documentation
58
78
 
@@ -61,7 +81,7 @@ Projection in front of a server you don't own.
61
81
  - [Product requirements](https://github.com/astralMCP/projection/blob/main/docs/PRD.md)
62
82
  and [engineering decisions](https://github.com/astralMCP/projection/blob/main/docs/DECISIONS.md)
63
83
  - [Repository](https://github.com/astralMCP/projection) — scenario test
64
- harness, self-heal benchmark, and an interactive demo TUI live alongside
65
- the library
84
+ harness, self-heal benchmark, an interactive demo TUI, and an MCP Apps
85
+ demo host live alongside the library
66
86
 
67
87
  Requires Node ≥ 22. MIT licensed.