@skaile/forge-app-actions 0.2.1 → 0.4.0

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

@@ -0,0 +1,57 @@
+import type { ActionManifestEntry, ActionsManifest } from "../internal/manifest.js";
+import type { ActionInput, ActionOutput, ServerAction } from "../server/utils/server-actions.js";
+export type { ActionManifestEntry, ActionsManifest };
+/**
+ * The transport. It resolves to the already decoded response body and rejects
+ * on a non-2xx status, exactly as Nuxt's `$fetch` does, so `$fetch` can be
+ * injected as is. Declared through a method type so its parameters are compared
+ * bivariantly: `$fetch` accepts a narrower `body` type than `unknown`.
+ */
+export type ActionsFetch = {
+    bivarianceHack(url: string, init: {
+        method: "GET" | "POST";
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<unknown>;
+}["bivarianceHack"];
+export interface ActionsClientOptions {
+    /** Prefix of `route`, e.g. `https://app.example.com`. Defaults to none (same origin). */
+    baseUrl?: string;
+    /** Where the host mounted the HTTP adapter. Defaults to `/api/actions`. */
+    route?: string;
+    /** Defaults to a `fetch`-based transport; Nuxt callers pass `$fetch`. */
+    fetch?: ActionsFetch;
+    /** Sent with every request (e.g. `Authorization`); a function is read per request. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+/**
+ * What the default transport throws for a non-2xx response. Carries the fields
+ * Nuxt's `$fetch` errors do: `statusCode`, `statusMessage` and `data`, the
+ * decoded response body (for an action failure the H3 error body, whose own
+ * `data.issues` lists schema errors).
+ */
+export declare class ActionsClientError extends Error {
+    readonly statusCode: number;
+    readonly statusMessage: string;
+    readonly data: unknown;
+    constructor(statusCode: number, statusMessage: string, message: string, data: unknown);
+}
+export interface ActionsClient<R extends readonly ServerAction[]> {
+    /**
+     * Calls the action and resolves to its result. A failure rejects with the
+     * transport's error, which carries `statusCode`, `statusMessage` and `data`.
+     */
+    call<K extends R[number]["id"]>(id: K, input: ActionInput<Extract<R[number], {
+        id: K;
+    }>>): Promise<ActionOutput<Extract<R[number], {
+        id: K;
+    }>>>;
+    /** The `user`-audience actions the server offers, with their JSON input schemas. */
+    manifest(): Promise<ActionsManifest<R[number]["id"]>>;
+}
+/**
+ * A typed client of the HTTP adapter. `R` is the app's action catalogue
+ * (`typeof SERVERAKTIONEN`), so `call` checks ids and inputs and returns the
+ * handler's output type; import the catalogue as a type only.
+ */
+export declare function createActionsClient<R extends readonly ServerAction[]>(options?: ActionsClientOptions): ActionsClient<R>;

package/dist/runtime/client/index.js

@@ -0,0 +1,60 @@
+export class ActionsClientError extends Error {
+  statusCode;
+  statusMessage;
+  data;
+  constructor(statusCode, statusMessage, message, data) {
+    super(message);
+    this.name = "ActionsClientError";
+    this.statusCode = statusCode;
+    this.statusMessage = statusMessage;
+    this.data = data;
+  }
+}
+function decode(text) {
+  if (text === "") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+const nativeFetch = async (url, init) => {
+  const hasBody = init.body !== void 0;
+  const response = await globalThis.fetch(url, {
+    method: init.method,
+    headers: {
+      accept: "application/json",
+      ...hasBody ? { "content-type": "application/json" } : {},
+      ...init.headers
+    },
+    body: hasBody ? JSON.stringify(init.body) : void 0
+  });
+  const data = decode(await response.text());
+  if (!response.ok) {
+    const body = typeof data === "object" && data !== null ? data : {};
+    const statusMessage = typeof body.statusMessage === "string" ? body.statusMessage : response.statusText;
+    const message = typeof body.message === "string" ? body.message : statusMessage;
+    throw new ActionsClientError(response.status, statusMessage, message, data);
+  }
+  return data;
+};
+export function createActionsClient(options = {}) {
+  const base = `${(options.baseUrl ?? "").replace(/\/+$/, "")}/${(options.route ?? "/api/actions").replace(/^\/+|\/+$/g, "")}`;
+  const transport = options.fetch ?? nativeFetch;
+  const headersOf = async () => {
+    const headers = options.headers;
+    return typeof headers === "function" ? await headers() : headers;
+  };
+  const send = async (method, url, body) => {
+    const headers = await headersOf();
+    return transport(url, {
+      method,
+      ...body === void 0 ? {} : { body },
+      ...headers ? { headers } : {}
+    });
+  };
+  return {
+    call: (id, input) => send("POST", `${base}/${encodeURIComponent(id)}`, input ?? {}),
+    manifest: () => send("GET", base)
+  };
+}

package/dist/runtime/internal/bearer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The credential of an `Authorization: Bearer …` header value, or `null` when
+ * the header is absent, not a bearer scheme, or empty. Shared by the MCP and
+ * HTTP adapters so both read credentials the same way.
+ */
+export declare function bearerOf(header: string | string[] | null | undefined): string | null;

package/dist/runtime/internal/bearer.js

@@ -0,0 +1,5 @@
+const BEARER = /^Bearer\s+(\S.*)$/i;
+export function bearerOf(header) {
+  const value = Array.isArray(header) ? header[0] : header;
+  return value?.match(BEARER)?.[1]?.trim() || null;
+}

package/dist/runtime/internal/manifest.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wire types of the HTTP action manifest. Types only: the client imports them
+ * without pulling any server code.
+ */
+/** One action as `GET <route>` lists it. */
+export interface ActionManifestEntry<Id extends string = string> {
+    id: Id;
+    /** Canonical name `app.<id>`. */
+    name: string;
+    description: string;
+    kind: "effect" | "query";
+    /** JSON Schema (draft-07, input side) of the action's input. */
+    inputSchema: Record<string, unknown>;
+}
+export interface ActionsManifest<Id extends string = string> {
+    actions: ActionManifestEntry<Id>[];
+}

package/dist/runtime/internal/tool-name.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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;

package/dist/runtime/internal/tool-name.js

@@ -0,0 +1,4 @@
+const TOOL_NAME_MAX = 64;
+export function toolNameOf(capabilityName) {
+  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
+}

package/dist/runtime/server/http/create-handler.d.ts

@@ -0,0 +1,50 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type ServerAction } from "../utils/server-actions.js";
+/** What the `authorize` callback receives and may change. */
+export interface ActionsHttpAuthorizeDecision {
+    /** The host event (under Nitro an `H3Event`), or the Node request when the host passed none. */
+    event: unknown;
+    req: IncomingMessage;
+    /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+    bearer: string | null;
+    /** Defaults to `false`; both the manifest and every call answer 401 unless the callback sets it. */
+    allowed: boolean;
+    /** What the actions see as `ctx.principal`. */
+    principal?: unknown;
+    /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+    deps?: unknown;
+}
+export interface ActionsHttpHandlerOptions {
+    /** Narrowed to the `user` audience by the handler itself; the rest answer 404. */
+    actions: readonly ServerAction[];
+    /** Mount path, e.g. `/api/actions`. The manifest is `GET <route>`, a call `POST <route>/<id>`. */
+    route: string;
+    /**
+     * Asked once per request, before any action id is looked up or any body is
+     * read. Set `decision.allowed = true` to let it in. An error thrown here
+     * denies. A host that authenticates by cookie MUST also check the request's
+     * origin here before allowing a `POST`: this adapter performs no CSRF defence.
+     */
+    authorize: (decision: ActionsHttpAuthorizeDecision) => void | Promise<void>;
+}
+/** Per-request inputs a host may supply instead of the handler deriving them from `req`. */
+export interface ActionsHttpRequestInput {
+    /** Passed to `authorize` and to the actions as `ctx.event`. Defaults to `req`. */
+    event?: unknown;
+    /** The raw request body, for hosts whose framework already consumed the stream. Called only after authorization. */
+    readBody?: () => Promise<string | undefined>;
+}
+/**
+ * A Node `(req, res, input?)` handler for the HTTP projection of server actions.
+ *
+ * - `GET <route>`: `{ actions: [{ id, name, description, kind, inputSchema }] }` of the
+ *   `user`-audience actions, `cache-control: no-store`.
+ * - `POST <route>/<id>`: the JSON body is the action's input; the response is its raw
+ *   result. A failure is an H3-shaped error body (`statusCode`, `statusMessage`, `message`,
+ *   `data.issues` for schema errors) with the outcome's status.
+ *
+ * Both routes deny by default (401) until `authorize` sets `decision.allowed`.
+ * Unknown and non-`user` actions answer 404, malformed JSON 400. Input parsing and
+ * the action's own `authorize` happen inside `action.run`, once, via `invokeAction`.
+ */
+export declare function createActionsHttpHandler(options: ActionsHttpHandlerOptions): (req: IncomingMessage, res: ServerResponse, input?: ActionsHttpRequestInput) => Promise<void>;

package/dist/runtime/server/http/create-handler.js

@@ -0,0 +1,135 @@
+import { bearerOf } from "../../internal/bearer.js";
+import { invokeAction } from "../utils/invoke-action.js";
+import { forAudience } from "../utils/server-actions.js";
+const MAX_BODY_BYTES = 1024 * 1024;
+function errorBody(statusCode, message, data) {
+  return {
+    statusCode,
+    statusMessage: message,
+    message,
+    ...data === void 0 ? {} : { data }
+  };
+}
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    ...headers
+  });
+  res.end(JSON.stringify(body) ?? "null");
+}
+async function readStream(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw Object.assign(new Error("body too large"), { tooLarge: true });
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function actionIdOf(url, route) {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  if (pathname !== route && !pathname.startsWith(`${route}/`)) return void 0;
+  const rest = pathname.slice(route.length).replace(/^\/+/, "");
+  if (rest === "") return null;
+  if (rest.includes("/")) return void 0;
+  try {
+    return decodeURIComponent(rest);
+  } catch {
+    return void 0;
+  }
+}
+function manifestOf(actions) {
+  return {
+    actions: actions.map(
+      (action) => ({
+        id: action.id,
+        name: action.name,
+        description: action.description,
+        kind: action.kind,
+        inputSchema: action.inputSchema
+      })
+    )
+  };
+}
+export function createActionsHttpHandler(options) {
+  const route = `/${options.route.replace(/^\/+|\/+$/g, "")}`;
+  const actions = forAudience(options.actions, "user");
+  const byId = /* @__PURE__ */ new Map();
+  for (const action of actions) {
+    const other = byId.get(action.id);
+    if (other) throw new Error(`Duplicate action id: ${action.id} (${other.name}, ${action.name})`);
+    byId.set(action.id, action);
+  }
+  return async (req, res, input = {}) => {
+    const id = actionIdOf(req.url, route);
+    if (id === void 0) {
+      return send(res, 404, errorBody(404, "Not found"));
+    }
+    const method = req.method ?? "GET";
+    const allowedMethod = id === null ? "GET" : "POST";
+    if (method !== allowedMethod && !(id === null && method === "HEAD")) {
+      return send(
+        res,
+        405,
+        errorBody(405, `Use ${allowedMethod} here`),
+        { allow: allowedMethod }
+      );
+    }
+    const event = input.event ?? req;
+    const decision = {
+      event,
+      req,
+      bearer: bearerOf(req.headers.authorization),
+      allowed: false,
+      principal: void 0,
+      deps: void 0
+    };
+    try {
+      await options.authorize(decision);
+    } catch {
+      decision.allowed = false;
+    }
+    if (decision.allowed !== true) {
+      return send(res, 401, errorBody(401, "Invalid or missing credential"), {
+        "www-authenticate": "Bearer"
+      });
+    }
+    if (id === null) return send(res, 200, manifestOf(actions));
+    const action = byId.get(id);
+    if (!action) return send(res, 404, errorBody(404, `Unknown action: ${id}`));
+    let raw;
+    try {
+      raw = await (input.readBody ? input.readBody() : readStream(req));
+    } catch (error) {
+      const tooLarge = error?.tooLarge === true;
+      return send(res, tooLarge ? 413 : 400, errorBody(tooLarge ? 413 : 400, "Unreadable body"));
+    }
+    let body = {};
+    if (raw !== void 0 && raw.trim() !== "") {
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        return send(res, 400, errorBody(400, "Malformed JSON body"));
+      }
+    }
+    const outcome = await invokeAction(action, body, {
+      principal: decision.principal,
+      event,
+      deps: decision.deps
+    });
+    if (outcome.ok) return send(res, 200, outcome.result);
+    return send(
+      res,
+      outcome.status,
+      errorBody(
+        outcome.status,
+        outcome.message,
+        outcome.issues === void 0 ? void 0 : { issues: outcome.issues }
+      )
+    );
+  };
+}

package/dist/runtime/server/http/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Explicit entry point for the HTTP projection of server actions, via the
+ * `./http` subpath. The Nuxt module mounts the routes itself when
+ * `forgeAppActions.http` is set; use these to serve actions from elsewhere.
+ */
+export type { ActionManifestEntry, ActionsManifest } from "../../internal/manifest.js";
+export * from "./create-handler.js";
+export type { HttpAuthorizeDecision } from "./route.js";

package/dist/runtime/server/http/index.js

@@ -0,0 +1 @@
+export * from "./create-handler.js";

package/dist/runtime/server/http/route.d.ts

@@ -0,0 +1,16 @@
+import type { H3Event } from "h3";
+/** What the `forge-app-actions:http:authorize` hook receives and may change. */
+export interface HttpAuthorizeDecision {
+    event: H3Event;
+    /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+    bearer: string | null;
+    /** Defaults to `false`; manifest and calls answer 401 unless the hook sets it. */
+    allowed: boolean;
+    /** What the actions see as `ctx.principal`. */
+    principal?: unknown;
+    /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+    deps?: unknown;
+}
+/** `GET <route>` (manifest) and `POST <route>/:id` over the registered server actions. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/http/route.js

@@ -0,0 +1,28 @@
+import { defineEventHandler, readRawBody } from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions.js";
+import { createActionsHttpHandler } from "./create-handler.js";
+export default defineEventHandler(async (event) => {
+  const { http } = useRuntimeConfig(event).forgeAppActions;
+  await createActionsHttpHandler({
+    actions: serverActionRegistry.list(),
+    route: http.route,
+    authorize: async (inner) => {
+      const decision = {
+        event,
+        bearer: inner.bearer,
+        allowed: false,
+        principal: void 0,
+        deps: void 0
+      };
+      const { hooks } = useNitroApp();
+      await hooks.callHook("forge-app-actions:http:authorize", decision);
+      inner.allowed = decision.allowed === true;
+      inner.principal = decision.principal;
+      inner.deps = decision.deps;
+    }
+  })(event.node.req, event.node.res, {
+    event,
+    readBody: () => readRawBody(event, "utf8")
+  });
+});

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

@@ -5,3 +5,5 @@
  */
 export * from "./utils/capability-registry.js";
 export * from "./utils/client-capability-bridge.js";
+export * from "./utils/server-actions.js";
+export * from "./utils/invoke-action.js";

package/dist/runtime/server/index.js

@@ -1,2 +1,4 @@
 export * from "./utils/capability-registry.js";
 export * from "./utils/client-capability-bridge.js";
+export * from "./utils/server-actions.js";
+export * from "./utils/invoke-action.js";

package/dist/runtime/server/mcp/create-handler.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { toolNameOf } from "../../internal/tool-name.js";
+import type { ServerAction, ServerActionScope } from "../utils/server-actions.js";
+export { toolNameOf };
+export interface ActionsMcpServerOptions {
+    /** Served as given; narrow them with `forAudience(actions, "llm")` first to honor audiences. */
+    actions: readonly ServerAction[];
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /** `principal`, `event` and `deps` handed to every action as `ctx`; its `name` is derived per action. */
+    context: ServerActionScope;
+}
+/**
+ * An MCP server whose tools are the given server actions, named
+ * `toolNameOf(action.name)`. Every call goes through `invokeAction` with `context`;
+ * a failed call (invalid input, denied by the action's `authorize`, handler error)
+ * is an `isError` result carrying the outcome's message, never an HTTP error.
+ */
+export declare function createActionsMcpServer(options: ActionsMcpServerOptions): Server;
+export type ActionsMcpHttpHandlerOptions = ActionsMcpServerOptions;
+/**
+ * A Node `(req, res, parsedBody?)` handler for the Streamable HTTP MCP endpoint.
+ * Stateless: every POST serves one JSON-RPC exchange with a fresh server and
+ * ends, so no session outlives a request. Authorization is the caller's job
+ * (the Nitro route runs the `forge-app-actions:mcp:authorize` hook first);
+ * `GET`/`DELETE` answer 405.
+ */
+export declare function createActionsMcpHttpHandler(options: ActionsMcpHttpHandlerOptions): (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;

package/dist/runtime/server/mcp/create-handler.js

@@ -0,0 +1,80 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toolNameOf } from "../../internal/tool-name.js";
+import { invokeAction } from "../utils/invoke-action.js";
+export { toolNameOf };
+const text = (value) => [{ type: "text", text: value }];
+const failure = (message) => ({ isError: true, content: text(message) });
+export function createActionsMcpServer(options) {
+  const byTool = /* @__PURE__ */ new Map();
+  for (const action of options.actions) {
+    const toolName = toolNameOf(action.name);
+    const other = byTool.get(toolName);
+    if (other) {
+      throw new Error(
+        `Tool name collision: ${other.name} and ${action.name} both map to ${toolName}`
+      );
+    }
+    byTool.set(toolName, action);
+  }
+  const server = new Server(options.serverInfo, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [...byTool].map(([name, action]) => ({
+      name,
+      description: action.description,
+      inputSchema: action.inputSchema
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    const action = byTool.get(params.name);
+    if (!action) return failure(`unknown tool: ${params.name}`);
+    const outcome = await invokeAction(action, params.arguments ?? {}, options.context);
+    if (!outcome.ok) return failure(outcome.message);
+    const { result } = outcome;
+    const content = text(JSON.stringify(result) ?? "null");
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+      return { content, structuredContent: result };
+    }
+    return { content };
+  });
+  return server;
+}
+const reply = (res, status, body, headers = {}) => {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    ...headers
+  });
+  res.end(JSON.stringify(body));
+};
+const ACCEPT = "application/json, text/event-stream";
+export function createActionsMcpHttpHandler(options) {
+  return async (req, res, parsedBody) => {
+    if (req.method !== "POST") {
+      return reply(res, 405, { error: "Use POST for Streamable HTTP MCP" }, { allow: "POST" });
+    }
+    const accept = String(req.headers.accept ?? "");
+    if (!accept.includes("application/json") || !accept.includes("text/event-stream")) {
+      req.headers.accept = ACCEPT;
+      req.rawHeaders.push("Accept", ACCEPT);
+    }
+    const server = createActionsMcpServer(options);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, parsedBody);
+    } catch {
+      if (!res.headersSent) reply(res, 500, { error: "Internal server error" });
+      else res.end();
+    }
+  };
+}

package/dist/runtime/server/mcp/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Explicit entry point for the MCP projection of server actions, via the
+ * `./mcp` subpath. The Nuxt module mounts the route itself when
+ * `forgeAppActions.mcp` is set; use these to serve actions from elsewhere.
+ */
+export * from "./create-handler.js";
+export type { McpAuthorizeDecision } from "./route.js";

package/dist/runtime/server/mcp/index.js

@@ -0,0 +1 @@
+export * from "./create-handler.js";

package/dist/runtime/server/mcp/route.d.ts

@@ -0,0 +1,16 @@
+import type { H3Event } from "h3";
+/** What the `forge-app-actions:mcp:authorize` hook receives and may change. */
+export interface McpAuthorizeDecision {
+    event: H3Event;
+    /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+    bearer: string | null;
+    /** Defaults to `false`; the request is rejected with 401 unless the hook sets it. */
+    allowed: boolean;
+    /** What the actions see as `ctx.principal`. */
+    principal?: unknown;
+    /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+    deps?: unknown;
+}
+/** The Streamable HTTP MCP endpoint over the registered server actions. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<unknown>>;
+export default _default;

package/dist/runtime/server/mcp/route.js

@@ -0,0 +1,57 @@
+import {
+  defineEventHandler,
+  getRequestHeader,
+  readRawBody,
+  setResponseHeaders,
+  setResponseStatus
+} from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { bearerOf } from "../../internal/bearer.js";
+import { forAudience, serverActionRegistry } from "../utils/server-actions.js";
+import { createActionsMcpHttpHandler } from "./create-handler.js";
+export default defineEventHandler(async (event) => {
+  const reply = (status, body, headers = {}) => {
+    setResponseStatus(event, status);
+    setResponseHeaders(event, { "cache-control": "no-store", ...headers });
+    return body;
+  };
+  if (event.method !== "POST") {
+    return reply(405, { error: "Use POST for Streamable HTTP MCP" }, { allow: "POST" });
+  }
+  const decision = {
+    event,
+    bearer: bearerOf(getRequestHeader(event, "authorization")),
+    allowed: false,
+    principal: void 0,
+    deps: void 0
+  };
+  try {
+    const { hooks } = useNitroApp();
+    await hooks.callHook("forge-app-actions:mcp:authorize", decision);
+  } catch {
+    decision.allowed = false;
+  }
+  if (decision.allowed !== true) {
+    return reply(
+      401,
+      { error: "Invalid or missing agent credential" },
+      { "www-authenticate": "Bearer" }
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readRawBody(event, "utf8") ?? "");
+  } catch {
+    return reply(400, {
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32700, message: "Parse error" }
+    });
+  }
+  const { mcp } = useRuntimeConfig(event).forgeAppActions;
+  await createActionsMcpHttpHandler({
+    actions: forAudience(serverActionRegistry.list(), "llm"),
+    serverInfo: { name: mcp.name, version: mcp.version },
+    context: { principal: decision.principal, event, deps: decision.deps }
+  })(event.node.req, event.node.res, parsed);
+});

package/dist/runtime/server/utils/invoke-action.d.ts

@@ -0,0 +1,19 @@
+import type { ServerAction, ServerActionScope } from "./server-actions.js";
+/** What a projection maps to its own error shape: `status` is HTTP-style, whatever the transport. */
+export type ActionOutcome = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+    issues?: unknown[];
+};
+/**
+ * Runs `action` and classifies the result: schema error → 400 with
+ * `invalid input: …` and its `issues`; an error with a numeric `statusCode` →
+ * that status; anything else → 500. Calls `action.run` only: parsing and the
+ * action's `authorize` happen there, exactly once, so this never reparses or
+ * authorizes a second time.
+ */
+export declare function invokeAction(action: ServerAction, input: unknown, ctx: ServerActionScope): Promise<ActionOutcome>;