@skaile/forge-app-actions 0.2.0 → 0.3.0

package/README.md

@@ -32,6 +32,7 @@ Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional p
 | `./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`, … |
+| `./mcp` | `createActionsMcpServer`, `createActionsMcpHttpHandler`, `toolNameOf` — the MCP projection of server actions |
 | `./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 +61,48 @@ 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).
+
+## 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 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>`); 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 }` (`bearer` is `null` without such a header). The hook sets `allowed` and, optionally, `principal`. 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`.

package/dist/module.d.mts

@@ -7,6 +7,20 @@ 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;
+    };
 }
 /**
  * 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.0",
+  "version": "0.3.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,44 @@ const forgeAppActionsModule = defineNuxtModule({
     if (options.composableAutoImport) {
       addImportsDir(resolve("./runtime/composables"));
     }
+    if (options.mcp) {
+      const { route = "/mcp", name = "forge-app", version = "0.0.0" } = options.mcp;
+      nuxt.options.runtimeConfig.forgeAppActions = { mcp: { name, version } };
+      addServerHandler({ route, handler: resolve("./runtime/server/mcp/route") });
+      addTypeTemplate(
+        {
+          filename: "types/forge-app-actions-mcp.d.ts",
+          getContents: () => `import type { H3Event } from 'h3'
+
+declare module 'nitropack/types' {
+  interface NitroRuntimeHooks {
+    /**
+     * 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\`. \`decision.bearer\`
+     * is the \`Authorization: Bearer\` credential, or \`null\`.
+     */
+    'forge-app-actions:mcp:authorize': (decision: {
+      event: H3Event
+      bearer: string | null
+      allowed: boolean
+      principal?: unknown
+    }) => void | Promise<void>
+  }
+}
+
+declare module 'nuxt/schema' {
+  interface RuntimeConfig {
+    forgeAppActions: { mcp: { name: string, version: string } }
+  }
+}
+
+export {}
+`
+        },
+        { nuxt: true, nitro: true }
+      );
+    }
   }
 });
 

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;

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/index.d.ts

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

package/dist/runtime/server/index.js

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

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

@@ -0,0 +1,29 @@
+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, ServerActionContext } from "../utils/server-actions.js";
+export { toolNameOf };
+export interface ActionsMcpServerOptions {
+    actions: ServerAction[];
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /** `principal` and `event` handed to every action as `ctx`; `name` is set per call. */
+    context: Omit<ServerActionContext, "name">;
+}
+/**
+ * An MCP server whose tools are the given server actions, named
+ * `toolNameOf(action.name)`. Every call runs the action with
+ * `{ ...context, name: action.name }`.
+ */
+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,98 @@
+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 * as z from "zod";
+import { toolNameOf } from "../../internal/tool-name.js";
+export { toolNameOf };
+const text = (value) => [{ type: "text", text: value }];
+const failure = (message) => ({ isError: true, content: text(message) });
+function isZodError(error) {
+  const candidate = error;
+  return typeof candidate?.name === "string" && /^\$?ZodError$/.test(candidate.name) && Array.isArray(candidate.issues);
+}
+function messageOf(error) {
+  if (error && typeof error === "object") {
+    const { statusMessage, message } = error;
+    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
+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}`);
+    try {
+      const result = await action.run(params.arguments ?? {}, {
+        ...options.context,
+        name: action.name
+      });
+      const content = text(JSON.stringify(result) ?? "null");
+      if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+        return { content, structuredContent: result };
+      }
+      return { content };
+    } catch (error) {
+      if (isZodError(error)) return failure(`invalid input: ${z.prettifyError(error)}`);
+      return failure(messageOf(error));
+    }
+  });
+  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,14 @@
+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;
+}
+/** 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,60 @@
+import {
+  defineEventHandler,
+  getRequestHeader,
+  readRawBody,
+  setResponseHeaders,
+  setResponseStatus
+} from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions.js";
+import { createActionsMcpHttpHandler } from "./create-handler.js";
+const BEARER = /^Bearer\s+(\S.*)$/i;
+function bearerOf(event) {
+  const header = getRequestHeader(event, "authorization");
+  return header?.match(BEARER)?.[1]?.trim() || null;
+}
+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(event),
+    allowed: false,
+    principal: 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: serverActionRegistry.list(),
+    serverInfo: { name: mcp.name, version: mcp.version },
+    context: { principal: decision.principal, event }
+  })(event.node.req, event.node.res, parsed);
+});

package/dist/runtime/server/utils/server-actions.d.ts

@@ -0,0 +1,42 @@
+import * as z from "zod";
+export interface ServerActionContext<P = unknown> {
+    /** Capability name as invoked, e.g. `app.trainings.create`. */
+    name: string;
+    /** What the `forge-app-actions:mcp:authorize` hook set as `principal`. */
+    principal: P;
+    /** Host event (under Nitro an `H3Event`); apps pass it on to their server utils. */
+    event: unknown;
+}
+export interface DefineServerActionArgs<T extends z.ZodType, P = unknown> {
+    /** Without the `app.` prefix, e.g. `trainings.create`; the name becomes `app.<id>`. An id starting with `app.` throws. */
+    id: string;
+    /** Description the model reads. Required; empty throws. */
+    description: string;
+    /** Zod schema of the input. Defaults to `z.object({})`. */
+    input?: T;
+    /** Documentation only, as with `defineForgeAction`. Defaults to `"effect"`. */
+    kind?: "effect" | "query";
+    run: (input: z.infer<T>, ctx: ServerActionContext<P>) => unknown | Promise<unknown>;
+}
+export interface ServerAction {
+    id: string;
+    name: string;
+    description: string;
+    kind: "effect" | "query";
+    readonly inputZod: z.ZodType;
+    /** `z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })` without `$schema`. */
+    inputSchema: Record<string, unknown>;
+    /** Parses `input` through `inputZod` (a `ZodError` propagates), then calls the handler. */
+    run(input: unknown, ctx: ServerActionContext): Promise<unknown>;
+}
+export declare function defineServerAction<T extends z.ZodType = z.ZodObject<Record<string, never>>, P = unknown>(args: DefineServerActionArgs<T, P>): ServerAction;
+export declare class ServerActionRegistry {
+    private readonly actions;
+    register(action: ServerAction): void;
+    registerAll(actions: ServerAction[]): void;
+    /** In registration order. */
+    list(): ServerAction[];
+    get(name: string): ServerAction | undefined;
+}
+/** Process-wide singleton, like `capabilityRegistry`. */
+export declare const serverActionRegistry: ServerActionRegistry;

package/dist/runtime/server/utils/server-actions.js

@@ -0,0 +1,57 @@
+import * as z from "zod";
+function withoutSchemaKey(schema) {
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+}
+export function defineServerAction(args) {
+  const { id } = args;
+  if (!id || id.trim().length === 0) {
+    throw new Error("defineServerAction: an action needs a non-empty id.");
+  }
+  if (id.startsWith("app.")) {
+    throw new Error(
+      `defineServerAction("${id}"): the id must not carry the \`app.\` prefix \u2014 it is added automatically to derive the action name. Use "${id.slice(4)}".`
+    );
+  }
+  if (!args.description || args.description.trim().length === 0) {
+    throw new Error(
+      `defineServerAction("${id}"): a server action must declare a description \u2014 the model reads it.`
+    );
+  }
+  const inputZod = args.input ?? z.object({});
+  const inputSchema = withoutSchemaKey(
+    z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })
+  );
+  return {
+    id,
+    name: `app.${id}`,
+    description: args.description,
+    kind: args.kind ?? "effect",
+    inputZod,
+    inputSchema,
+    async run(input, ctx) {
+      const parsed = inputZod.parse(input);
+      return await args.run(parsed, ctx);
+    }
+  };
+}
+export class ServerActionRegistry {
+  actions = /* @__PURE__ */ new Map();
+  register(action) {
+    if (this.actions.has(action.name)) {
+      throw new Error(`Server action already registered: ${action.name}`);
+    }
+    this.actions.set(action.name, action);
+  }
+  registerAll(actions) {
+    for (const action of actions) this.register(action);
+  }
+  /** In registration order. */
+  list() {
+    return [...this.actions.values()];
+  }
+  get(name) {
+    return this.actions.get(name);
+  }
+}
+export const serverActionRegistry = new ServerActionRegistry();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-app-actions",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Browser-declared app actions for Skaile forge apps: defineForgeAction / defineClientCapability, the agent capability bridge, command palette and approval dialog, as a Nuxt module.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -27,6 +27,10 @@
       "types": "./dist/runtime/server/index.d.ts",
       "import": "./dist/runtime/server/index.js"
     },
+    "./mcp": {
+      "types": "./dist/runtime/server/mcp/index.d.ts",
+      "import": "./dist/runtime/server/mcp/index.js"
+    },
     "./types": {
       "types": "./dist/runtime/types/index.d.ts",
       "import": "./dist/runtime/types/index.js"
@@ -71,6 +75,7 @@
     }
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@nuxt/kit": "^4.0.0",
     "zod": "^4.4.3"
   },
@@ -85,7 +90,9 @@
     "@types/node": "^22.0.0",
     "@vitejs/plugin-vue": "^6.0.5",
     "bun-types": "^1.3.11",
+    "h3": "^1.15.11",
     "happy-dom": "^20.9.0",
+    "nitropack": "^2.13.4",
     "nuxt": "^4.0.0",
     "typescript": "^5.0.0",
     "unbuild": "^3.6.0",

package/src/runtime/chat/index.ts

@@ -22,6 +22,7 @@ import {
   useCapabilityApproval,
 } from "../composables/useCapabilityApproval";
 import { describeError } from "../internal/describe-error";
+import { toolNameOf } from "../internal/tool-name";
 import type {
   ClientCapabilityContext,
   ClientCapabilityLogger,
@@ -65,16 +66,7 @@ const defaultLog: ClientCapabilityLogger = {
 
 type ToolHandler = ClientToolHandlers[string];
 
-const TOOL_NAME_MAX = 64;
-
-/**
- * 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 function toolNameOf(capabilityName: string): string {
-  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
-}
+export { toolNameOf };
 
 /** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
 function withoutSchemaKey(schema: Record<string, unknown>): ClientToolDecls[string]["inputSchema"] {

package/src/runtime/internal/tool-name.ts

@@ -0,0 +1,10 @@
+const TOOL_NAME_MAX = 64;
+
+/**
+ * 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 function toolNameOf(capabilityName: string): string {
+  return capabilityName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, TOOL_NAME_MAX);
+}

package/src/runtime/server/index.ts

@@ -6,3 +6,4 @@
 
 export * from "./utils/capability-registry";
 export * from "./utils/client-capability-bridge";
+export * from "./utils/server-actions";

package/src/runtime/server/mcp/create-handler.ts

@@ -0,0 +1,161 @@
+// server/mcp/create-handler.ts
+//
+// Projects server actions as MCP tools. Deliberately outside `runtime/server/utils/`
+// so the Nuxt module's auto-import of that directory never pulls the MCP SDK
+// into apps that do not enable `forgeAppActions.mcp`.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+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 * as z from "zod";
+import { toolNameOf } from "../../internal/tool-name";
+import type { ServerAction, ServerActionContext } from "../utils/server-actions";
+
+export { toolNameOf };
+
+export interface ActionsMcpServerOptions {
+  actions: ServerAction[];
+  serverInfo: { name: string; version: string };
+  /** `principal` and `event` handed to every action as `ctx`; `name` is set per call. */
+  context: Omit<ServerActionContext, "name">;
+}
+
+type ToolInputSchema = { type: "object"; [key: string]: unknown };
+
+const text = (value: string) => [{ type: "text" as const, text: value }];
+
+const failure = (message: string) => ({ isError: true as const, content: text(message) });
+
+/**
+ * A ZodError by shape, not `instanceof`: the schema belongs to the app, whose
+ * zod instance may differ from the one bundled with this package.
+ */
+function isZodError(error: unknown): error is z.core.$ZodError {
+  const candidate = error as { name?: unknown; issues?: unknown } | null;
+  return (
+    typeof candidate?.name === "string" &&
+    /^\$?ZodError$/.test(candidate.name) &&
+    Array.isArray(candidate.issues)
+  );
+}
+
+/** The message to show the model: an H3 error carries it in `statusMessage`. */
+function messageOf(error: unknown): string {
+  if (error && typeof error === "object") {
+    const { statusMessage, message } = error as { statusMessage?: unknown; message?: unknown };
+    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
+
+/**
+ * An MCP server whose tools are the given server actions, named
+ * `toolNameOf(action.name)`. Every call runs the action with
+ * `{ ...context, name: action.name }`.
+ */
+export function createActionsMcpServer(options: ActionsMcpServerOptions): Server {
+  const byTool = new Map<string, ServerAction>();
+  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 as ToolInputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    const action = byTool.get(params.name);
+    if (!action) return failure(`unknown tool: ${params.name}`);
+    try {
+      const result = await action.run(params.arguments ?? {}, {
+        ...options.context,
+        name: action.name,
+      });
+      const content = text(JSON.stringify(result) ?? "null");
+      if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+        return { content, structuredContent: result as Record<string, unknown> };
+      }
+      return { content };
+    } catch (error) {
+      if (isZodError(error)) return failure(`invalid input: ${z.prettifyError(error)}`);
+      return failure(messageOf(error));
+    }
+  });
+
+  return server;
+}
+
+export type ActionsMcpHttpHandlerOptions = ActionsMcpServerOptions;
+
+const reply = (
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = {},
+) => {
+  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";
+
+/**
+ * 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 function createActionsMcpHttpHandler(
+  options: ActionsMcpHttpHandlerOptions,
+): (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void> {
+  return async (req, res, parsedBody) => {
+    if (req.method !== "POST") {
+      return reply(res, 405, { error: "Use POST for Streamable HTTP MCP" }, { allow: "POST" });
+    }
+    // The transport insists on both media types; plain `curl` clients that omit
+    // them are served anyway. The transport reads `rawHeaders`, so the header
+    // goes into both views of the request.
+    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: undefined,
+      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/src/runtime/server/mcp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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";
+export type { McpAuthorizeDecision } from "./route";

package/src/runtime/server/mcp/route.ts

@@ -0,0 +1,93 @@
+// server/mcp/route.ts
+//
+// The Nitro handler `forgeAppActions.mcp` mounts. Not importable from app code;
+// apps reach the same projection through `@skaile/forge-app-actions/mcp`.
+
+import type { H3Event } from "h3";
+import {
+  defineEventHandler,
+  getRequestHeader,
+  readRawBody,
+  setResponseHeaders,
+  setResponseStatus,
+} from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions";
+import { createActionsMcpHttpHandler } from "./create-handler";
+
+/** 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;
+}
+
+const BEARER = /^Bearer\s+(\S.*)$/i;
+
+function bearerOf(event: H3Event): string | null {
+  const header = getRequestHeader(event, "authorization");
+  return header?.match(BEARER)?.[1]?.trim() || null;
+}
+
+/** The Streamable HTTP MCP endpoint over the registered server actions. */
+export default defineEventHandler(async (event) => {
+  const reply = (status: number, body: unknown, headers: Record<string, string> = {}) => {
+    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: McpAuthorizeDecision = {
+    event,
+    bearer: bearerOf(event),
+    allowed: false,
+    principal: undefined,
+  };
+  try {
+    // The hook's typing comes from the module's type template, which is absent
+    // when this package is type-checked on its own.
+    const { hooks } = useNitroApp() as unknown as {
+      hooks: { callHook(name: string, decision: McpAuthorizeDecision): Promise<void> };
+    };
+    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: unknown;
+  // Read here so the transport does not wait on a stream Nitro may already have consumed.
+  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 as {
+    mcp: { name: string; version: string };
+  };
+  // The handler writes the response itself; h3 sees `res.writableEnded` and sends nothing more.
+  await createActionsMcpHttpHandler({
+    actions: serverActionRegistry.list(),
+    serverInfo: { name: mcp.name, version: mcp.version },
+    context: { principal: decision.principal, event },
+  })(event.node.req, event.node.res, parsed);
+});

package/src/runtime/server/utils/server-actions.ts

@@ -0,0 +1,117 @@
+// server/utils/server-actions.ts
+//
+// NOTE: this file must live *directly* in `runtime/server/utils/`. The Nuxt
+// module auto-imports that directory NON-recursively (see
+// `client-capability-bridge.ts`), so a subdirectory would silently never reach
+// consumers.
+//
+// Server actions are headless: they run in Nitro, have no palette row and no
+// browser round-trip. They are the unit the `./mcp` projection exposes as MCP
+// tools. Browser actions (`defineForgeAction`) are unaffected.
+
+import * as z from "zod";
+
+export interface ServerActionContext<P = unknown> {
+  /** Capability name as invoked, e.g. `app.trainings.create`. */
+  name: string;
+  /** What the `forge-app-actions:mcp:authorize` hook set as `principal`. */
+  principal: P;
+  /** Host event (under Nitro an `H3Event`); apps pass it on to their server utils. */
+  event: unknown;
+}
+
+export interface DefineServerActionArgs<T extends z.ZodType, P = unknown> {
+  /** Without the `app.` prefix, e.g. `trainings.create`; the name becomes `app.<id>`. An id starting with `app.` throws. */
+  id: string;
+  /** Description the model reads. Required; empty throws. */
+  description: string;
+  /** Zod schema of the input. Defaults to `z.object({})`. */
+  input?: T;
+  /** Documentation only, as with `defineForgeAction`. Defaults to `"effect"`. */
+  kind?: "effect" | "query";
+  run: (input: z.infer<T>, ctx: ServerActionContext<P>) => unknown | Promise<unknown>;
+}
+
+export interface ServerAction {
+  id: string;
+  name: string;
+  description: string;
+  kind: "effect" | "query";
+  readonly inputZod: z.ZodType;
+  /** `z.toJSONSchema(inputZod, { target: "draft-07", io: "input" })` without `$schema`. */
+  inputSchema: Record<string, unknown>;
+  /** Parses `input` through `inputZod` (a `ZodError` propagates), then calls the handler. */
+  run(input: unknown, ctx: ServerActionContext): Promise<unknown>;
+}
+
+/** The derived JSON Schema without its top-level `$schema` draft marker; everything else stays. */
+function withoutSchemaKey(schema: Record<string, unknown>): Record<string, unknown> {
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+}
+
+export function defineServerAction<
+  T extends z.ZodType = z.ZodObject<Record<string, never>>,
+  P = unknown,
+>(args: DefineServerActionArgs<T, P>): ServerAction {
+  const { id } = args;
+  if (!id || id.trim().length === 0) {
+    throw new Error("defineServerAction: an action needs a non-empty id.");
+  }
+  if (id.startsWith("app.")) {
+    throw new Error(
+      `defineServerAction("${id}"): the id must not carry the \`app.\` prefix — it is added ` +
+        `automatically to derive the action name. Use "${id.slice(4)}".`,
+    );
+  }
+  if (!args.description || args.description.trim().length === 0) {
+    throw new Error(
+      `defineServerAction("${id}"): a server action must declare a description — the model reads it.`,
+    );
+  }
+
+  const inputZod: z.ZodType = args.input ?? z.object({});
+  const inputSchema = withoutSchemaKey(
+    z.toJSONSchema(inputZod, { target: "draft-07", io: "input" }) as Record<string, unknown>,
+  );
+
+  return {
+    id,
+    name: `app.${id}`,
+    description: args.description,
+    kind: args.kind ?? "effect",
+    inputZod,
+    inputSchema,
+    async run(input, ctx) {
+      const parsed = inputZod.parse(input) as z.infer<T>;
+      return await args.run(parsed, ctx as ServerActionContext<P>);
+    },
+  };
+}
+
+export class ServerActionRegistry {
+  private readonly actions = new Map<string, ServerAction>();
+
+  register(action: ServerAction): void {
+    if (this.actions.has(action.name)) {
+      throw new Error(`Server action already registered: ${action.name}`);
+    }
+    this.actions.set(action.name, action);
+  }
+
+  registerAll(actions: ServerAction[]): void {
+    for (const action of actions) this.register(action);
+  }
+
+  /** In registration order. */
+  list(): ServerAction[] {
+    return [...this.actions.values()];
+  }
+
+  get(name: string): ServerAction | undefined {
+    return this.actions.get(name);
+  }
+}
+
+/** Process-wide singleton, like `capabilityRegistry`. */
+export const serverActionRegistry = new ServerActionRegistry();