Documents saga a2ui 0.11.0-rc.1 (prerelease). This is the SDK guideThis document is generated. Each snippet is the maintained starter template’s own text, cut from the files CI builds and qualifies, so it cannot drift from a tested file. The setup guide explains the concepts and the order to read them in. Attaching SAGA to a backend you already run is an integration you make in your own source. No command edits an existing application:docs/attach-to-existing-backend.mdat source revisionfb4126c. It is published as a snapshot: later source changes do not alter it. Licensed under Apache-2.0.
saga init creates one new directory and nothing else. The Lit and React stacks belong to the public npm release set. These source-based snippets use matched local candidate packages so they can qualify unpublished changes (see Install the packages from a candidate).
Which pairs have a recipe
A pair is listed only while CI qualifies it, and a qualified pair is not automatically offered by
saga init: that command offers the pairs in its own list. A recipe is not a claim about any other pair, and no full matrix is claimed.
Required servers without a recipe yet
Every required server target has a qualified template above.The steps, whichever server you use
- Install the SDK packages the recipe lists from one candidate, together, and keep the
@a2ui/markdown-itoverride in your rootpackage.json. - Decide who is asking. Your application authenticates the request (
server/verifier.tsis the seam for your identity provider) and gives SAGA the result only through the transport’s per-request auth, as in the identity handoff below. A protected operation that receives no verified identity does not run; a declared public operation needs none and is given none. - Read the built HTML before listening. The preparation snippet defines
viewfromoptions.htmland its actual filename (index.htmlin the starter);server/main.tsreads that file. Prepare it once and reuse it in each request factory. - Register the operations your backend exposes. The handler makes your own authorization decision for that request’s identity, and the projection copies the public fields out of the record by name.
- Build the view with your own catalog and serve it as the operation’s view resource, as the starter does. The view’s address preserves its filename and fingerprints its final bytes, so rebuild the view and restart the server together.
- Attach each action to the rendered control it belongs to. The layout names no action; the attachment is application code.
node with lit-mcp
Template: templates/lit-node. Server adapter: @modelcontextprotocol/node 2.1.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/lit-node/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/lit-node/server/listener.ts:
Register a protected operation
Fromtemplates/lit-node/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/lit-node/src/view.ts:
express with lit-mcp
Template: templates/lit-express. Server adapter: @modelcontextprotocol/express 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/lit-express/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/lit-express/server/listener.ts:
Register a protected operation
Fromtemplates/lit-express/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/lit-express/src/view.ts:
fastify with lit-mcp
Template: templates/lit-fastify. Server adapter: @modelcontextprotocol/fastify 2.0.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/lit-fastify/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/lit-fastify/server/listener.ts:
Register a protected operation
Fromtemplates/lit-fastify/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/lit-fastify/src/view.ts:
hono with lit-mcp
Template: templates/lit-hono. Server adapter: @modelcontextprotocol/hono 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/lit-hono/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/lit-hono/server/listener.ts:
Register a protected operation
Fromtemplates/lit-hono/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/lit-hono/src/view.ts:
hapi with lit-mcp
Template: templates/lit-hapi. Server adapter: @modelcontextprotocol/node 2.1.1. SDK packages: @saga-a2ui/core, @saga-a2ui/lit, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/lit-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/bridge.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/lit-hapi/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/lit-hapi/server/listener.ts:
Register a protected operation
Fromtemplates/lit-hapi/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/lit-hapi/src/view.ts:
hono with react-mcp
Template: templates/react-hono. Server adapter: @modelcontextprotocol/hono 2.0.2. SDK packages: @saga-a2ui/core, @saga-a2ui/react, @saga-a2ui/components, @saga-a2ui/mcp, @saga-a2ui/react-mcp-stack.
The snippets below call the starter’s own application files, which you read in the template (or in a project saga init created) and adapt: server/authenticate.ts, server/authorization.ts, server/endpoint.ts, server/identity.ts, server/verifier.ts. server/verifier.ts and server/authorization.ts are where your identity provider and your policy go; the starter ships neither.
Prepare the view and endpoint handlers once
Fromtemplates/react-hono/server/listener.ts:
Hand the verified identity to the transport
Fromtemplates/react-hono/server/listener.ts:
Register a protected operation
Fromtemplates/react-hono/server/operations.ts:
Attach an action to a rendered control
Fromtemplates/react-hono/src/view.tsx: