@astral-mcp/projection 0.6.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.
- package/README.md +48 -22
- package/dist/index.d.mts +696 -269
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +3260 -1831
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -8
package/README.md
CHANGED
|
@@ -1,17 +1,36 @@
|
|
|
1
1
|
# @astral-mcp/projection
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
6
|
|
|
7
|
-
|
|
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.
|
|
14
|
+
|
|
15
|
+
Projection wraps an existing MCP server and exposes two projections of it —
|
|
16
|
+
five tools in all, never the wrapped server's own:
|
|
8
17
|
|
|
9
|
-
-
|
|
10
|
-
QuickJS WebAssembly sandbox
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
18
|
+
- **Code mode** — `execute_machine` runs an LLM-authored XState v5 state
|
|
19
|
+
machine in a QuickJS WebAssembly sandbox (read-only calls run inline; any
|
|
20
|
+
write suspends the machine into a sealed, encrypted blob and asks the human
|
|
21
|
+
to approve that exact call via MRTR elicitation); `discover_apis` returns
|
|
22
|
+
the generated TypeScript definitions and the authoring contract.
|
|
23
|
+
- **Catalog** — `search_tools` lists the wrapped tools with their approval
|
|
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`.
|
|
15
34
|
|
|
16
35
|
All suspension state rides the MRTR `requestState` payload, so Projection is
|
|
17
36
|
fully stateless: any server instance can resume any workflow.
|
|
@@ -33,20 +52,27 @@ export default createMcpHandler(facade.serverFactory);
|
|
|
33
52
|
|
|
34
53
|
`serverFactory` carries the negotiated protocol era into each serving unit:
|
|
35
54
|
modern (2026-07-28) clients get MRTR approval round trips; legacy clients
|
|
36
|
-
still run read-only machines and get a structured error the
|
|
37
|
-
|
|
55
|
+
still run read-only machines and calls, and get a structured error the
|
|
56
|
+
moment a call needs approval. You can also wrap a connected SDK `Client` to put
|
|
38
57
|
Projection in front of a server you don't own.
|
|
39
58
|
|
|
40
59
|
## Security model
|
|
41
60
|
|
|
42
|
-
| Invariant | How it holds
|
|
43
|
-
| ------------------------------------------------------- |
|
|
44
|
-
| The tools bridge is the only way out of the sandbox | No `fetch`, no filesystem, no host globals; only `xstate` and `@astral-mcp/tools`
|
|
45
|
-
| No gated call runs without a matching approval | The approved name and arguments are sealed in the blob and executed from there
|
|
46
|
-
| Clients
|
|
47
|
-
| A snapshot cannot resume under different code | The blob binds a SHA-256 hash of the original `code`
|
|
48
|
-
| A
|
|
49
|
-
|
|
|
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).
|
|
50
76
|
|
|
51
77
|
## Documentation
|
|
52
78
|
|
|
@@ -55,7 +81,7 @@ Projection in front of a server you don't own.
|
|
|
55
81
|
- [Product requirements](https://github.com/astralMCP/projection/blob/main/docs/PRD.md)
|
|
56
82
|
and [engineering decisions](https://github.com/astralMCP/projection/blob/main/docs/DECISIONS.md)
|
|
57
83
|
- [Repository](https://github.com/astralMCP/projection) — scenario test
|
|
58
|
-
harness, self-heal benchmark,
|
|
59
|
-
the library
|
|
84
|
+
harness, self-heal benchmark, an interactive demo TUI, and an MCP Apps
|
|
85
|
+
demo host live alongside the library
|
|
60
86
|
|
|
61
87
|
Requires Node ≥ 22. MIT licensed.
|