@skaile/forge-app-actions 0.2.1 → 0.4.0

package/README.md

@@ -19,7 +19,7 @@ export default defineNuxtConfig({
 })
 ```
 
-Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional peer (type-only imports from `@skaile/workspaces/sdk/types`).
+Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional peer (type-only imports from `@skaile/workspaces/sdk/types`); `ai ^7.0.124` is an optional peer, imported only by `./chat/ai-sdk`.
 
 `@skaile/forge-common` installs this module for you.
 
@@ -31,7 +31,11 @@ Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional p
 | `./client-capabilities` | browser-side API, explicit-import entry for tests and non-auto-import contexts |
 | `./chat` | `useChatActions`, `toolNameOf` — forge actions as forge-chat client tools (browser) |
 | `./chat/server` | `clientToolsFromBody` — validates the `clientTools` request field (no Vue) |
-| `./server` | `clientCapabilityBridge`, `capabilityRegistry`, `routeCapabilityInvocation`, … |
+| `./server` | `clientCapabilityBridge`, `capabilityRegistry`, `routeCapabilityInvocation`, `defineServerAction`, `createServerActionDefiner`, `forAudience`, `invokeAction`, … |
+| `./mcp` | `createActionsMcpServer`, `createActionsMcpHttpHandler`, `toolNameOf` — the MCP projection of server actions |
+| `./http` | `createActionsHttpHandler` — the HTTP projection (manifest + calls) of `user`-audience server actions |
+| `./client` | `createActionsClient`, `ActionsClientError` — typed client of the HTTP projection (no Vue/H3/AI SDK) |
+| `./chat/ai-sdk` | `serverActionToolSet` — server actions as AI SDK tools (the only entry that imports `ai`) |
 | `./types` | `ClientCapability*`, `ForgeAction*`, `Palette*` types |
 
 Moved here from `@skaile-ai/forge-common` 9.x (`./client-capabilities` and the capability parts of `./server` and `./types`).
@@ -60,3 +64,152 @@ Round trip: the model emits a tool call → the handler ends the turn with `turn
 `clientToolsFromBody` returns `undefined` when the body has no `clientTools`, and throws an error with `statusCode: 400` (`clientTools: <issues>`) for a bad tool name, an over-long description or a non-object schema — `createAiSdkChatHandler` answers such an error with that status.
 
 Peer: `@skaile/forge-chat ^0.2.0` (optional; type-only imports).
+
+## Server actions: audience and authorization
+
+`defineServerAction` keeps the literal `id` and infers input (`z.input`) and output types, exposed as `ActionInput<A>` / `ActionOutput<A>`; a `const` tuple of actions keeps every element type through `forAudience` and the registry.
+
+```ts
+const defineAppAction = createServerActionDefiner<AppPrincipal, AppDeps>()   // binds only the app's types
+
+export const trainings = [
+  defineAppAction({
+    id: 'trainings.delete',                    // canonical name `app.trainings.delete`
+    description: 'Delete a training.',
+    input: z.object({ id: z.string() }).strict(),
+    audience: ['user'],                        // not offered to models; default is both, [] throws
+    authorize: async (input, ctx) => {         // after the one input parse, before the handler
+      await assertMayDelete(ctx.principal, ctx.name, input.id)   // read current authority here
+    },
+    run: ({ id }, ctx) => ctx.deps.trainings.delete(id),
+  }),
+] as const
+
+serverActionRegistry.registerAll(trainings)
+const forModels = forAudience(trainings, 'llm')
+```
+
+- `run` parses the input exactly once, derives `name = app.<id>` (a `name` in the caller's context is ignored), awaits `authorize(parsed, context)` and only then calls the handler. A throwing `authorize` denies the call on every path, direct `.run` included; a malformed input never reaches `authorize` or the handler. Without `authorize` nothing changes.
+- The core has no principal, role or grant vocabulary: `ctx.principal` and `ctx.deps` are whatever the transport's authorize hook set (`P`/`D` default to `unknown`). Authorization is the app's; read the current identity and grants inside `authorize`, not from a value captured when the tool set was built.
+- `audience` (`'user'`, `'llm'`) only controls where an action is offered; it is not authorization.
+- `invokeAction(action, input, ctx)` returns an `ActionOutcome`, `{ ok: true, result }` or `{ ok: false, status, message, issues? }`: a schema error is 400 (`invalid input: …`, with `issues`), an error with a numeric `statusCode` keeps it, anything else is 500. It calls `action.run` only and never parses or authorizes itself.
+
+## Exposing server actions over MCP
+
+Server actions are headless: they run in Nitro, have no palette row and no browser round trip. `defineServerAction` declares one, `serverActionRegistry` (from `@skaile/forge-app-actions/server`, auto-imported in a Nuxt app) collects them, and `forgeAppActions.mcp` serves the registry as a stateless Streamable HTTP MCP endpoint (POST only). Without `mcp` no route exists.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@skaile/forge-app-actions'],
+  forgeAppActions: { mcp: { route: '/mcp', name: 'my-app', version: '1.0.0' } },   // route defaults to '/mcp'
+})
+
+// server/plugins/mcp.ts
+import * as z from 'zod'
+
+export default defineNitroPlugin((nitroApp) => {
+  serverActionRegistry.register(defineServerAction({
+    id: 'notes.create',                       // capability `app.notes.create`, tool `app_notes_create`
+    description: 'Create a note.',
+    input: z.object({ text: z.string().min(1) }).strict(),
+    run: (input, ctx) => createNote(ctx.event as H3Event, input.text),
+  }))
+
+  // Authorization is the app's job. Without a hook that sets `allowed`, the route answers 401.
+  nitroApp.hooks.hook('forge-app-actions:mcp:authorize', async (decision) => {
+    if (!decision.bearer) return
+    const user = await userForToken(decision.bearer)
+    if (!user) return
+    decision.allowed = true
+    decision.principal = user                 // reaches the actions as `ctx.principal`
+  })
+})
+```
+
+```sh
+curl -s -X POST http://localhost:3000/mcp \
+  -H 'authorization: Bearer <token>' -H 'content-type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"app_notes_create","arguments":{"text":"hi"}}}'
+```
+
+**Tools.** Every registered action whose `audience` includes `llm` is a tool named `toolNameOf(action.name)`; two actions that map to the same name make the server fail with `Tool name collision`. The description and the zod-derived input schema come from the action. A call validates the input first (invalid → `isError` with `invalid input: <issues>`); a denial by the action's `authorize` or an exception becomes `isError` with its message (an H3 error: its `statusMessage`); an unknown name gives `unknown tool: <name>`. A result is returned as JSON text, and for a non-array object also as `structuredContent`.
+
+**Authorization.** The route reads `Authorization: Bearer …` and calls the Nitro hook `forge-app-actions:mcp:authorize` with `{ event, bearer, allowed: false, principal, deps }` (`bearer` is `null` without such a header). The hook sets `allowed` and, optionally, `principal` (`ctx.principal`) and `deps` (`ctx.deps`). A hook that throws or leaves `allowed` false gives 401 (`www-authenticate: Bearer`, `cache-control: no-store`). Non-POST requests give 405 (`allow: POST`); an unreadable body gives JSON-RPC `-32700`. The package ships no shared token on purpose: a token with a default is a token somebody forgets.
+
+To serve actions from another HTTP stack, `@skaile/forge-app-actions/mcp` exports `createActionsMcpServer` and `createActionsMcpHttpHandler`.
+
+## Exposing server actions over HTTP
+
+`forgeAppActions.http` mounts the actions that include the `user` audience as a small JSON API; without it no route exists. It is how browsers, scripts and the CLI reach the same operations MCP gives models, through the same `authorize` of each action.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@skaile/forge-app-actions'],
+  forgeAppActions: { http: { route: '/api/actions' } },   // route defaults to '/api/actions'
+})
+
+// server/plugins/actions-http.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('forge-app-actions:http:authorize', async (decision) => {
+    // Bearer clients (CLI, scripts): a credential the app issued.
+    if (decision.bearer) {
+      const user = await userForToken(decision.bearer)
+      if (!user) return
+      decision.allowed = true
+      decision.principal = user               // reaches the actions as `ctx.principal`
+      return
+    }
+    // Cookie sessions: the browser sends the cookie on cross-site requests too, so a POST
+    // needs a same-origin check HERE. The adapter does no CSRF defence of its own.
+    const session = await sessionOf(decision.event)
+    if (!session || (isMutation(decision.event) && !isSameOrigin(decision.event))) return
+    decision.allowed = true
+    decision.principal = session.user
+  })
+})
+```
+
+- `GET <route>` answers `{ actions: [{ id, name, description, kind, inputSchema }] }` for the `user`-audience actions, with `cache-control: no-store`. `POST <route>/<id>` takes the JSON body as the action's input and answers its raw result.
+- **Both routes deny by default.** The hook `forge-app-actions:http:authorize` receives `{ event, bearer, allowed: false, principal?, deps? }` once per request, before an id is looked up or a body is read, and answers 401 (`www-authenticate: Bearer`) unless it sets `allowed`. `principal` and `deps` become `ctx.principal` / `ctx.deps`. A bearer credential and a cookie session are different authentications: never infer one from the other's role.
+- Failures use the H3 error body (`{ statusCode, statusMessage, message, data? }`): malformed JSON 400, a schema error 400 with `data.issues`, an unknown action or one without the `user` audience 404, a wrong method 405, a denial by the action's `authorize` its own `statusCode` (403 for a grant check), an unexpected error 500.
+- To serve the same API from another stack (Express, plain `node:http`), `@skaile/forge-app-actions/http` exports `createActionsHttpHandler({ actions, route, authorize })`, a `(req, res, input?)` handler. `authorize` receives the same decision plus `req`; pass `input.readBody` when your framework already consumed the request stream.
+
+## Typed client
+
+```ts
+import type { SERVERAKTIONEN } from '~~/server/utils/serveraktionen'
+import { createActionsClient } from '@skaile/forge-app-actions/client'
+
+const actions = createActionsClient<typeof SERVERAKTIONEN>({ fetch: $fetch })   // Nuxt: inject $fetch
+const created = await actions.call('trainings.create', { title: 'Abend' })      // ids, inputs, outputs are typed
+const { actions: offered } = await actions.manifest()
+```
+
+Import the catalogue as a **type** only: the client entry imports no server code, Vue, H3 or AI SDK. Options: `baseUrl`, `route` (default `/api/actions`), `headers` (an object or a function read per request) and `fetch`. An injected `fetch` is `(url, init: { method: 'GET' | 'POST'; body?; headers? }) => Promise<decoded body>` that rejects on non-2xx, exactly like `$fetch`, so its errors reach you untouched. The default uses the global `fetch`, sends JSON, decodes the response and throws an `ActionsClientError` for non-2xx with `statusCode`, `statusMessage` and `data` (the decoded H3 error body, so schema issues are `error.data.data.issues`, as with `$fetch`). The action id is encoded as one path segment.
+
+## CLI
+
+`forge-actions` (Node >= 20, no dependencies) calls a deployed app's `user` actions:
+
+```sh
+export FORGE_ACTIONS_URL=https://app.example.com FORGE_ACTIONS_TOKEN=…      # or --url / --token
+npx forge-actions list                                       # [{ id, kind, description }]
+npx forge-actions trainings.create --help                    # the action's fields from its manifest
+npx forge-actions trainings.create --title Abend --seats 12  # primitive flags, coerced by the schema type
+npx forge-actions trainings.create --json '{"title":"Abend","tags":["a"]}'
+```
+
+`--route` defaults to `/api/actions`; the token is sent as `Authorization: Bearer` and never printed (output is masked). Flags work for `string`, `number`, `integer` and `boolean` fields (a bare `--online` is `true`); object and array fields, and fields named `url`, `token`, `route`, `json` or `help`, go through `--json`, and a flag overrides the same field in `--json`. Exit codes: **0** success (JSON on stdout); **1** transport failure or a failed action (denied, not found, handler error), message on stderr; **2** invalid usage: unknown flag or action id, missing or uncoercible arguments, or input the server's schema rejected.
+
+## Using server actions as AI SDK tools
+
+```ts
+import { serverActionToolSet } from '@skaile/forge-app-actions/chat/ai-sdk'
+
+const tools = serverActionToolSet(forAudience(SERVERAKTIONEN, 'llm'), { principal, event, deps })
+await streamText({ model, tools, … })     // or hand them to createAiSdkChatHandler
+```
+
+Each action becomes a tool named `toolNameOf(action.name)` (as in MCP) with its description and JSON input schema, in a null-prototype map. Calls go through `invokeAction` with the scope you gave: input is parsed and the action's `authorize` runs inside `run` for every call, so a grant removed from your store between two calls of the same tool set denies the second. Do not rely on `scope` for fresh authority; it is captured. A failed call throws an `Error` with the outcome's message, which the AI SDK reports to the model as a tool error. Two different action names that map to one tool name throw at construction, naming both. Narrow with `forAudience(…, 'llm')` yourself. Peer: `ai ^7.0.124` (optional).

package/bin/forge-actions.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// forge-actions: calls the `user`-audience server actions of an app that serves
+// them over HTTP (`forgeAppActions.http`). Dependency-free, Node >= 20.
+//
+//   forge-actions [--url U] [--token T] [--route R] list
+//   forge-actions [--url U] [--token T] [--route R] <id> --help
+//   forge-actions [--url U] [--token T] [--route R] <id> [--json '<object>'] [--field value ...]
+//
+// Exit codes: 0 success; 1 transport or action failure; 2 invalid usage
+// (unknown flag or action, bad or missing arguments, input the server's schema rejected).
+
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
+
+const USAGE = `Usage:
+  forge-actions [options] list
+  forge-actions [options] <id> --help
+  forge-actions [options] <id> [--json '<object>'] [--<field> <value> ...]
+
+Options:
+  --url <url>      Base URL of the app (or FORGE_ACTIONS_URL)
+  --token <token>  Bearer token (or FORGE_ACTIONS_TOKEN)
+  --route <path>   Where the app mounts the actions API (default /api/actions)
+  --json <object>  The action input as a JSON object
+  --help           Show this text, or an action's fields with <id>
+
+Fields of type string, number, integer and boolean can be given as flags;
+object and array fields need --json.`;
+
+class UsageError extends Error {}
+class FailureError extends Error {}
+
+/** `--name value`, `--name=value` and bare `--name` flags, plus positionals; `-h` is `--help`. */
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = new Map();
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h") {
+      flags.set("help", true);
+    } else if (arg.startsWith("--") && arg.length > 2) {
+      const eq = arg.indexOf("=");
+      if (eq > 0) {
+        flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+        continue;
+      }
+      const name = arg.slice(2);
+      const next = argv[i + 1];
+      // A following token that is not itself a flag is this flag's value (`--help` takes none).
+      if (name !== "help" && next !== undefined && !next.startsWith("--")) {
+        flags.set(name, next);
+        i++;
+      } else {
+        flags.set(name, true);
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+/** The one primitive type a property schema admits (nulls ignored), or null when it needs --json. */
+function primitiveTypeOf(schema) {
+  const types = new Set();
+  const collect = (node) => {
+    if (!node || typeof node !== "object") return;
+    for (const type of Array.isArray(node.type) ? node.type : node.type ? [node.type] : []) {
+      types.add(type);
+    }
+    if (Array.isArray(node.enum)) {
+      for (const value of node.enum) types.add(value === null ? "null" : typeof value);
+    }
+    if ("const" in node) types.add(node.const === null ? "null" : typeof node.const);
+    for (const branch of [...(node.anyOf ?? []), ...(node.oneOf ?? [])]) collect(branch);
+  };
+  collect(schema);
+  types.delete("null");
+  if (types.size === 2 && types.has("number") && types.has("integer")) types.delete("integer");
+  if (types.size !== 1) return null;
+  const [type] = types;
+  return ["string", "number", "integer", "boolean"].includes(type) ? type : null;
+}
+
+function coerce(field, type, raw) {
+  if (type === "string") {
+    if (raw === true) throw new UsageError(`--${field} needs a value`);
+    return raw;
+  }
+  if (type === "boolean") {
+    if (raw === true || raw === "true") return true;
+    if (raw === "false") return false;
+    throw new UsageError(`--${field} must be true or false, got "${raw}"`);
+  }
+  if (raw === true || String(raw).trim() === "" || Number.isNaN(Number(raw))) {
+    throw new UsageError(`--${field} must be a number, got "${raw === true ? "" : raw}"`);
+  }
+  const value = Number(raw);
+  if (type === "integer" && !Number.isInteger(value)) {
+    throw new UsageError(`--${field} must be an integer, got "${raw}"`);
+  }
+  return value;
+}
+
+function describeField(name, schema, required) {
+  const type = primitiveTypeOf(schema) ?? (schema?.type ? [].concat(schema.type).join("|") : "json");
+  const flag = primitiveTypeOf(schema) ? `--${name} <${type}>` : `--json (${name}: ${type})`;
+  const notes = [required ? "required" : "optional"];
+  if (Array.isArray(schema?.enum)) notes.push(`one of ${schema.enum.map(String).join(", ")}`);
+  if (schema?.description) notes.push(schema.description);
+  return `  ${flag}  ${notes.join("; ")}`;
+}
+
+async function main(argv, env, out) {
+  const { positionals, flags } = parseArgs(argv);
+  const want = (name) => (typeof flags.get(name) === "string" ? flags.get(name) : undefined);
+
+  const baseUrl = want("url") ?? env.FORGE_ACTIONS_URL;
+  const token = want("token") ?? env.FORGE_ACTIONS_TOKEN;
+  const route = `/${(want("route") ?? "/api/actions").replace(/^\/+|\/+$/g, "")}`;
+  out.secret = token;
+
+  const [command, ...extra] = positionals;
+  if (!command) {
+    if (flags.has("help")) return out.stdout(USAGE);
+    throw new UsageError("missing command");
+  }
+  if (extra.length > 0) throw new UsageError(`unexpected argument: ${extra[0]}`);
+  if (command === "list" && flags.has("help")) return out.stdout(USAGE);
+  if (!baseUrl) throw new UsageError("missing --url (or FORGE_ACTIONS_URL)");
+
+  let base;
+  try {
+    base = `${new URL(baseUrl).href.replace(/\/+$/, "")}${route}`;
+  } catch {
+    throw new UsageError("--url is not a valid URL");
+  }
+
+  const request = async (method, url, body) => {
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: {
+          accept: "application/json",
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+          ...(token ? { authorization: `Bearer ${token}` } : {}),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (error) {
+      const cause = error?.cause?.code ?? error?.cause?.message ?? error?.message ?? "request failed";
+      throw new FailureError(`cannot reach ${new URL(url).origin}: ${cause}`);
+    }
+    const text = await response.text();
+    let data;
+    try {
+      data = text === "" ? undefined : JSON.parse(text);
+    } catch {
+      data = text;
+    }
+    if (!response.ok) {
+      const message =
+        (typeof data === "object" && data !== null && (data.statusMessage || data.message)) ||
+        response.statusText ||
+        "request failed";
+      const issues = data?.data?.issues;
+      const error = new FailureError(`${response.status} ${message}`);
+      // The server's schema rejected the input: that is invalid arguments, not a failed action.
+      error.usage = response.status === 400 && Array.isArray(issues);
+      throw error;
+    }
+    return data;
+  };
+
+  const manifest = await request("GET", base);
+  const actions = Array.isArray(manifest?.actions) ? manifest.actions : [];
+
+  if (command === "list") {
+    return out.stdout(
+      JSON.stringify(
+        actions.map(({ id, kind, description }) => ({ id, kind, description })),
+        null,
+        2,
+      ),
+    );
+  }
+
+  const action = actions.find((entry) => entry.id === command);
+  if (!action) throw new UsageError(`unknown action: ${command} (try: forge-actions list)`);
+  const schema = action.inputSchema ?? {};
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+
+  if (flags.has("help")) {
+    const fields = Object.entries(properties).map(([name, property]) =>
+      describeField(name, property, required.has(name)),
+    );
+    return out.stdout(
+      [
+        `${action.id} (${action.kind}): ${action.description}`,
+        "",
+        fields.length ? "Fields:" : "No input fields.",
+        ...fields,
+      ].join("\n"),
+    );
+  }
+
+  let input = {};
+  const json = flags.get("json");
+  if (json !== undefined) {
+    if (typeof json !== "string") throw new UsageError("--json needs a value");
+    let parsed;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      throw new UsageError("--json is not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new UsageError("--json must be a JSON object");
+    }
+    input = parsed;
+  }
+
+  for (const [name, raw] of flags) {
+    if (["url", "token", "route", "json", "help"].includes(name)) continue;
+    if (!Object.hasOwn(properties, name)) {
+      throw new UsageError(`unknown flag --${name} for ${action.id} (see: forge-actions ${action.id} --help)`);
+    }
+    const type = primitiveTypeOf(properties[name]);
+    if (!type) throw new UsageError(`--${name} is not a primitive field: pass it through --json`);
+    input[name] = coerce(name, type, raw);
+  }
+
+  for (const name of required) {
+    if (!(name in input)) throw new UsageError(`missing required field: ${name}`);
+  }
+
+  const result = await request("POST", `${base}/${encodeURIComponent(action.id)}`, input);
+  return out.stdout(JSON.stringify(result ?? null, null, 2));
+}
+
+/** Writes with every occurrence of the bearer token masked: it must never reach the terminal. */
+function createOutput() {
+  const out = {
+    secret: undefined,
+    mask(text) {
+      return out.secret ? text.split(out.secret).join("***") : text;
+    },
+    stdout(text) {
+      process.stdout.write(`${out.mask(text)}\n`);
+    },
+    stderr(text) {
+      process.stderr.write(`${out.mask(text)}\n`);
+    },
+  };
+  return out;
+}
+
+const out = createOutput();
+try {
+  await main(process.argv.slice(2), process.env, out);
+} catch (error) {
+  if (error instanceof UsageError) {
+    out.stderr(`forge-actions: ${error.message}`);
+    process.exitCode = EXIT_USAGE;
+  } else if (error instanceof FailureError) {
+    out.stderr(`forge-actions: ${error.message}`);
+    process.exitCode = error.usage ? EXIT_USAGE : EXIT_FAILURE;
+  } else {
+    out.stderr(`forge-actions: ${error?.message ?? "unexpected error"}`);
+    process.exitCode = EXIT_FAILURE;
+  }
+}

package/dist/module.d.mts

@@ -7,6 +7,30 @@ interface ForgeAppActionsOptions {
     componentAutoRegister?: boolean;
     /** Disable composable auto-imports. */
     composableAutoImport?: boolean;
+    /**
+     * Serve the registered server actions (`defineServerAction`) as an MCP
+     * endpoint (Streamable HTTP, stateless, POST only). Absent: no route.
+     * Requests are rejected with 401 unless a Nitro hook on
+     * `forge-app-actions:mcp:authorize` sets `decision.allowed`.
+     */
+    mcp?: {
+        /** Route to mount. Defaults to `/mcp`. */
+        route?: string;
+        /** MCP `serverInfo.name`. Defaults to `forge-app`. */
+        name?: string;
+        /** MCP `serverInfo.version`. Defaults to `0.0.0`. */
+        version?: string;
+    };
+    /**
+     * Serve the `user`-audience server actions as JSON over HTTP: `GET <route>` is
+     * the manifest, `POST <route>/<id>` calls an action. Absent: no route.
+     * Both answer 401 unless a Nitro hook on `forge-app-actions:http:authorize`
+     * sets `decision.allowed`. The hook also owns CSRF defence for cookie sessions.
+     */
+    http?: {
+        /** Route to mount. Defaults to `/api/actions`. */
+        route?: string;
+    };
 }
 /**
  * Nuxt module for browser-declared app actions: `defineForgeAction` /

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@skaile/forge-app-actions",
   "configKey": "forgeAppActions",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,4 +1,4 @@
-import { defineNuxtModule, createResolver, hasNuxtModule, addServerImportsDir, addComponentsDir, addImportsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerImportsDir, addComponentsDir, addImportsDir, addServerHandler, addTypeTemplate } from '@nuxt/kit';
 
 const forgeAppActionsModule = defineNuxtModule({
   meta: {
@@ -31,6 +31,83 @@ const forgeAppActionsModule = defineNuxtModule({
     if (options.composableAutoImport) {
       addImportsDir(resolve("./runtime/composables"));
     }
+    if (options.mcp || options.http) {
+      const mcp = options.mcp ? {
+        route: options.mcp.route ?? "/mcp",
+        name: options.mcp.name ?? "forge-app",
+        version: options.mcp.version ?? "0.0.0"
+      } : void 0;
+      const http = options.http ? { route: `/${(options.http.route ?? "/api/actions").replace(/^\/+|\/+$/g, "")}` } : void 0;
+      nuxt.options.runtimeConfig.forgeAppActions = {
+        ...mcp ? { mcp: { name: mcp.name, version: mcp.version } } : {},
+        ...http ? { http: { route: http.route } } : {}
+      };
+      if (mcp) {
+        addServerHandler({ route: mcp.route, handler: resolve("./runtime/server/mcp/route") });
+      }
+      if (http) {
+        const handler = resolve("./runtime/server/http/route");
+        addServerHandler({ route: http.route, handler });
+        addServerHandler({ route: `${http.route}/**`, handler });
+      }
+      const hooks = [
+        mcp ? `    /**
+     * Asked once per MCP request. Set \`decision.allowed = true\` to let the
+     * request in (the route answers 401 otherwise) and \`decision.principal\`
+     * to what the server actions see as \`ctx.principal\` (and \`decision.deps\`
+     * as \`ctx.deps\`). \`decision.bearer\` is the \`Authorization: Bearer\`
+     * credential, or \`null\`.
+     */
+    'forge-app-actions:mcp:authorize': (decision: {
+      event: H3Event
+      bearer: string | null
+      allowed: boolean
+      principal?: unknown
+      deps?: unknown
+    }) => void | Promise<void>` : "",
+        http ? `    /**
+     * Asked once per HTTP action request (manifest and calls alike). Set
+     * \`decision.allowed = true\` to let the request in (401 otherwise),
+     * \`decision.principal\` / \`decision.deps\` to what the actions see as
+     * \`ctx.principal\` / \`ctx.deps\`. \`decision.bearer\` is the
+     * \`Authorization: Bearer\` credential, or \`null\`. A host that authenticates
+     * by cookie MUST check the request origin here before allowing a POST.
+     */
+    'forge-app-actions:http:authorize': (decision: {
+      event: H3Event
+      bearer: string | null
+      allowed: boolean
+      principal?: unknown
+      deps?: unknown
+    }) => void | Promise<void>` : ""
+      ].filter(Boolean);
+      const runtimeConfig = [
+        mcp ? "mcp: { name: string, version: string }" : "",
+        http ? "http: { route: string }" : ""
+      ].filter(Boolean).join("; ");
+      addTypeTemplate(
+        {
+          filename: "types/forge-app-actions.d.ts",
+          getContents: () => `import type { H3Event } from 'h3'
+
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+${hooks.join("\n")}
+  }
+}
+
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    forgeAppActions: { ${runtimeConfig} }
+  }
+}
+
+export {}
+`
+        },
+        { nuxt: true, nitro: true }
+      );
+    }
   }
 });
 

package/dist/runtime/chat/ai-sdk.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AI SDK projection of server actions (`@skaile/forge-app-actions/chat/ai-sdk`).
+ *
+ * The only module of this package that imports `ai`, which is an optional peer:
+ * hosts that never serve actions to an AI SDK chat never load it.
+ */
+import { type ToolSet } from "ai";
+import type { ServerAction, ServerActionScope } from "../server/utils/server-actions.js";
+/**
+ * The given server actions as AI SDK tools, named `toolNameOf(action.name)` like
+ * their MCP counterparts, with the action's description and JSON input schema.
+ * Narrow with `forAudience(actions, "llm")` first to honor audiences.
+ *
+ * Every execution goes through `invokeAction` with `scope`: input is parsed and the
+ * action's own `authorize` runs inside `action.run`, once, at call time. Fresh
+ * authority therefore comes from that callback reading the app's current store,
+ * never from `scope`, which is captured when the tool set is built. A failed call
+ * (invalid input, denied, handler error) throws an `Error` carrying the outcome's
+ * message, which the AI SDK reports to the model as a tool error.
+ *
+ * @throws when two different action names map to one tool name.
+ */
+export declare function serverActionToolSet(actions: readonly ServerAction[], scope: ServerActionScope): ToolSet;

package/dist/runtime/chat/ai-sdk.js

@@ -0,0 +1,25 @@
+import { jsonSchema, tool } from "ai";
+import { toolNameOf } from "../internal/tool-name.js";
+import { invokeAction } from "../server/utils/invoke-action.js";
+export function serverActionToolSet(actions, scope) {
+  const tools = /* @__PURE__ */ Object.create(null);
+  const owners = /* @__PURE__ */ new Map();
+  for (const action of actions) {
+    const toolName = toolNameOf(action.name);
+    const other = owners.get(toolName);
+    if (other !== void 0) {
+      throw new Error(`Tool name collision: ${other} and ${action.name} both map to ${toolName}`);
+    }
+    owners.set(toolName, action.name);
+    tools[toolName] = tool({
+      description: action.description,
+      inputSchema: jsonSchema(action.inputSchema),
+      execute: async (input) => {
+        const outcome = await invokeAction(action, input, scope);
+        if (!outcome.ok) throw new Error(outcome.message);
+        return outcome.result ?? null;
+      }
+    });
+  }
+  return tools;
+}

package/dist/runtime/chat/index.d.ts

@@ -16,6 +16,7 @@
  * {@link toolNameOf}(capability name) — `app.<id>` becomes `app_<id>` — because
  * model providers reject dots in tool names.
  */
+import { toolNameOf } from "../internal/tool-name.js";
 import type { ClientCapabilityLogger } from "../types/client-capability.js";
 import type { ForgeAction } from "../types/forge-action.js";
 import type { ClientToolDecls, ClientToolHandlers } from "./types.js";
@@ -43,10 +44,5 @@ export interface UseChatActionsReturn {
     /** Tool handlers for `createChatSession({ tools })`, resolved against `actions()` at call time. */
     handlers: ClientToolHandlers;
 }
-/**
- * The provider-safe tool name of a capability name: every character outside
- * `[A-Za-z0-9_-]` becomes `_` (Anthropic and OpenAI reject others), truncated
- * to 64. `app.doc.read` → `app_doc_read`. Hosts use it to name tools in prompts.
- */
-export declare function toolNameOf(capabilityName: string): string;
+export { toolNameOf };
 export declare function useChatActions(options: UseChatActionsOptions): UseChatActionsReturn;

package/dist/runtime/chat/index.js

@@ -3,15 +3,13 @@ import {
   useCapabilityApproval
 } from "../composables/useCapabilityApproval.js";
 import { describeError } from "../internal/describe-error.js";
+import { toolNameOf } from "../internal/tool-name.js";
 const defaultLog = {
   info: (message, ...args) => console.log(message, ...args),
   warn: (message, ...args) => console.warn(message, ...args),
   error: (message, ...args) => console.error(message, ...args)
 };
-const TOOL_NAME_MAX = 64;
-export function toolNameOf(capabilityName) {
-  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
-}
+export { toolNameOf };
 function withoutSchemaKey(schema) {
   const { $schema: _draft, ...rest } = schema;
   return rest;