@ggui-ai/mcp-server 0.2.0-alpha.4 → 0.4.0-rc.0

package/dist/mcp-endpoint-routes.d.ts

@@ -0,0 +1,88 @@
+/**
+ * MCP wire endpoints — the audience-routed JSON-RPC surfaces.
+ *
+ *   POST <universalMcpPath>            — agent+runtime tools (default `/mcp`)
+ *   POST <pathPrefix>/:appId           — per-tenant variant (opt-in via
+ *                                        `perAppRouting`)
+ *   POST /protocol                     — design-time spec/discovery tools
+ *   POST /ops                          — operator-class management tools
+ *   POST <service.path>                — isolated MCP services (path IS
+ *                                        the audience)
+ *   GET/DELETE on each                 — 405 (stateless server; no
+ *                                        streaming continuation /
+ *                                        session-terminate verbs)
+ *
+ * Every route shares ONE request pipeline (`makeMcpHandler`): resolve
+ * identity via the AuthAdapter (anonymous services synthesize a
+ * builder identity on missing/invalid bearers), apply the per-app
+ * authorize hook, build a fresh `McpServer` + Streamable HTTP
+ * transport per request (stateless), and dispatch under the
+ * AsyncLocalStorage-scoped `HandlerContext`. The difference between
+ * routes is ONLY the handler set each exposes.
+ *
+ * See `docs/development/audience-routes.md` for the audience taxonomy
+ * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
+ * rules.
+ */
+import type { AuthAdapter, AuthResult } from "@ggui-ai/mcp-server-core";
+import type { HandlerContext, SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import type { Express } from "express";
+import type { AsyncLocalStorage } from "node:async_hooks";
+import type { ZodRawShape } from "zod";
+import { type BuildMcpServerOptions, type ServerInfo } from "./build-mcp.js";
+import type { Logger } from "./logger.js";
+import type { McpService } from "./mcp-mounts.js";
+/** Per-tenant URL routing shape — mirrors `CreateGguiServerOptions.perAppRouting`. */
+interface PerAppRouting {
+    readonly paramName: string;
+    readonly paramPattern: string;
+    readonly pathPrefix?: string;
+    readonly authorize?: (urlAppId: string, identity: AuthResult) => Promise<void>;
+}
+interface MountOptions {
+    /** Express app to mount onto. */
+    readonly app: Express;
+    /** Structured logger; per-request children carry `requestId`. */
+    readonly logger: Logger;
+    /** Auth adapter every route resolves bearers against. */
+    readonly auth: AuthAdapter;
+    /** Server identity forwarded to every per-request `buildMcpServer`. */
+    readonly info: ServerInfo;
+    /** Full composed handler list (audience filtering happens here). */
+    readonly handlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
+    /** Validated isolated-service list (`validateMcpServices` output). */
+    readonly mcpServices: ReadonlyArray<McpService>;
+    /** Request-scoped HandlerContext storage shared with the handlers. */
+    readonly als: AsyncLocalStorage<HandlerContext>;
+    /** Identity → appId resolution rule (SPEC §12.2). */
+    readonly appIdFromIdentity: (result: AuthResult) => string;
+    /** Universal endpoint path (default `/mcp`; cloud overrides to `/`). */
+    readonly universalMcpPath: string;
+    /** Per-tenant endpoint shape — absent = universal-only deployment. */
+    readonly perAppRouting?: PerAppRouting;
+    /** Whether OAuth is enabled (adds `WWW-Authenticate` on 401). */
+    readonly oauthEnabled: boolean;
+    /** Operator-configured issuer URL override (OAuth). */
+    readonly oauthIssuerUrl?: string;
+    /** Operator-supplied error → HTTP/JSON-RPC mapping hook. */
+    readonly errorMapper?: (err: unknown) => {
+        readonly status: number;
+        readonly code: number;
+        readonly message: string;
+    } | undefined;
+    /**
+     * Per-boot `buildMcpServer` options. Assembled once by the composer
+     * (every input is fixed at composition time); the handler spreads a
+     * fresh object per request so the builder never sees a shared
+     * mutable reference.
+     */
+    readonly buildMcpOptions: BuildMcpServerOptions;
+}
+/**
+ * Mount the universal / per-app / protocol / ops / service MCP
+ * endpoints onto the express app. Returns nothing — the routes
+ * self-register.
+ */
+export declare function mountMcpEndpoints(opts: MountOptions): void;
+export {};
+//# sourceMappingURL=mcp-endpoint-routes.d.ts.map

package/dist/mcp-endpoint-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-endpoint-routes.d.ts","sourceRoot":"","sources":["../src/mcp-endpoint-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElF,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,sFAAsF;AACtF,UAAU,aAAa;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,UAAU,YAAY;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAChD,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAChD,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC3D,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,CACrB,GAAG,EAAE,OAAO,KACT;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC9F;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CA4V1D"}

package/dist/mcp-endpoint-routes.js

@@ -0,0 +1,359 @@
+/**
+ * MCP wire endpoints — the audience-routed JSON-RPC surfaces.
+ *
+ *   POST <universalMcpPath>            — agent+runtime tools (default `/mcp`)
+ *   POST <pathPrefix>/:appId           — per-tenant variant (opt-in via
+ *                                        `perAppRouting`)
+ *   POST /protocol                     — design-time spec/discovery tools
+ *   POST /ops                          — operator-class management tools
+ *   POST <service.path>                — isolated MCP services (path IS
+ *                                        the audience)
+ *   GET/DELETE on each                 — 405 (stateless server; no
+ *                                        streaming continuation /
+ *                                        session-terminate verbs)
+ *
+ * Every route shares ONE request pipeline (`makeMcpHandler`): resolve
+ * identity via the AuthAdapter (anonymous services synthesize a
+ * builder identity on missing/invalid bearers), apply the per-app
+ * authorize hook, build a fresh `McpServer` + Streamable HTTP
+ * transport per request (stateless), and dispatch under the
+ * AsyncLocalStorage-scoped `HandlerContext`. The difference between
+ * routes is ONLY the handler set each exposes.
+ *
+ * See `docs/development/audience-routes.md` for the audience taxonomy
+ * (`agent` / `runtime` / `protocol` / `ops`) and the wire-name prefix
+ * rules.
+ */
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID } from "node:crypto";
+import { resolveIdentity, UnauthenticatedError } from "./auth.js";
+import { buildMcpServer } from "./build-mcp.js";
+import { buildWwwAuthenticate, resolveIssuerUrl } from "./oauth.js";
+/**
+ * Resolve the resource path that `WWW-Authenticate` should point at
+ * for the current request. Per-app `/mcp` requests
+ * get `${pathPrefix}/${appId}` so RFC 9728 discovery resolves to the
+ * per-app metadata; universal-route requests get `''` which collapses
+ * back to the universal `${issuer}/.well-known/oauth-protected-resource`.
+ *
+ * Defense in depth: even when `perAppRouting` is configured, we
+ * reject empty or whitespace-only `appId` values rather than emitting
+ * an obviously-wrong `${pathPrefix}//.well-known/...` URL — falling
+ * back to universal is the safer behavior.
+ */
+function resolveWwwAuthResourcePath(req, perAppRouting) {
+    if (perAppRouting === undefined)
+        return "";
+    const { paramName, pathPrefix = "" } = perAppRouting;
+    const appId = req.params[paramName];
+    if (typeof appId !== "string" || appId.length === 0)
+        return "";
+    return `${pathPrefix}/${appId}`;
+}
+/**
+ * Mount the universal / per-app / protocol / ops / service MCP
+ * endpoints onto the express app. Returns nothing — the routes
+ * self-register.
+ */
+export function mountMcpEndpoints(opts) {
+    const { app, logger, auth, info, handlers, mcpServices, als, appIdFromIdentity, universalMcpPath, perAppRouting, oauthEnabled, oauthIssuerUrl, errorMapper, buildMcpOptions, } = opts;
+    /**
+     * Audience filter — returns the subset of `handlers` whose
+     * `audience` tag intersects `allowed`. Read on route mounting so
+     * each MCP route exposes only its audience's tools.
+     *
+     * Handlers with `audience: undefined` default to ['agent'] — every
+     * such handler is agent-runtime callable.
+     */
+    const filterHandlersByAudience = (set, allowed) => set.filter((h) => {
+        const tags = h.audience ?? ["agent"];
+        return tags.some((t) => allowed.includes(t));
+    });
+    const makeMcpHandler = (routeHandlers, handlerOpts) => async (req, res) => {
+        const requestId = typeof req.headers["x-request-id"] === "string"
+            ? req.headers["x-request-id"]
+            : randomUUID();
+        const reqLogger = logger.child({ requestId });
+        // Auth is OPTIONAL on anonymous services and REQUIRED otherwise.
+        // Always attempt to resolve a presented credential: an anonymous
+        // service with a valid bearer still resolves to the real identity
+        // (so it can offer authenticated capabilities — e.g. `/dev`'s ops
+        // tools read `ctx.userId`), while a missing/unauthenticated
+        // credential falls back to the synthesized anonymous builder so
+        // public reads (docs, protocol) work bearer-less. This is what makes
+        // `source: 'anonymous'` distinguishable from an authenticated caller,
+        // per the `McpService.anonymous` contract — resolving a present
+        // bearer is the only way a handler can tell the two apart.
+        let identity;
+        try {
+            identity = await resolveIdentity(auth, req);
+        }
+        catch (err) {
+            if (err instanceof UnauthenticatedError) {
+                if (handlerOpts?.anonymous) {
+                    identity = { identity: { kind: "builder" }, source: "anonymous" };
+                }
+                else {
+                    // Diagnostic: did a Bearer credential actually reach the pod on
+                    // this request? This splits "the client/transport never sent one"
+                    // from "we received it but the adapter rejected it" — otherwise
+                    // indistinguishable in `auth_failed`. Only a short, non-secret
+                    // prefix is logged (a JWT header is public), never the credential.
+                    const rawAuth = req.headers["authorization"];
+                    const authHeaderPresent = typeof rawAuth === "string" && rawAuth.length > 0;
+                    reqLogger.warn("auth_failed", {
+                        reason: err.message,
+                        authHeaderPresent,
+                        authHeaderPrefix: authHeaderPresent ? rawAuth.slice(0, 12) : null,
+                        // Bearer-stripped token length — a transit-truncation check
+                        // (compare against the minted length); never the credential.
+                        tokenLen: authHeaderPresent
+                            ? rawAuth.replace(/^Bearer\s+/i, "").length
+                            : 0,
+                        path: req.path,
+                    });
+                    // OAuth-discovery clients (Claude Desktop, claude.ai, etc.)
+                    // read this header to find the resource-metadata URL and
+                    // begin the OAuth dance. Pure-bearer clients ignore it.
+                    //
+                    // Per-app routes point at the per-app resource-metadata
+                    // document so RFC 9728 discovery resolves
+                    // to a per-app `resource` URL. Universal routes keep the
+                    // bare metadata path.
+                    if (oauthEnabled) {
+                        const wwwAuthResourcePath = resolveWwwAuthResourcePath(req, perAppRouting);
+                        res.setHeader("WWW-Authenticate", buildWwwAuthenticate(resolveIssuerUrl(req, oauthIssuerUrl), wwwAuthResourcePath));
+                    }
+                    res.status(401).json({
+                        jsonrpc: "2.0",
+                        error: { code: -32000, message: err.message },
+                        id: null,
+                    });
+                    return;
+                }
+            }
+            else {
+                reqLogger.error("auth_unexpected_error", { error: String(err) });
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+                return;
+            }
+        }
+        // Operator-surface guard: federated end-user identities (source:'oidc',
+        // minted by the OIDC verify adapter) must never reach operator-class
+        // routes (/ops) or design-time spec routes (/protocol). Audience
+        // filtering only shapes tools/list; it does NOT stop a direct
+        // tools/call, so this is a route-level authorization gate.
+        if (handlerOpts?.rejectFederated && identity.source === "oidc") {
+            reqLogger.warn("federated_identity_rejected", { route: req.path });
+            res.status(403).json({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "federated identities are not permitted on this route" },
+                id: null,
+            });
+            return;
+        }
+        // Per-tenant URL routing. When `perAppRouting`
+        // is configured AND the request matched the per-app path
+        // `/:${paramName}/mcp`, Express populates `req.params[paramName]`
+        // with the validated tenant id. Use it as `ctx.appId` for this
+        // request, overriding `appIdFromIdentity`. The universal `/mcp`
+        // route doesn't have the param so it falls through to the
+        // identity-based resolution.
+        const urlAppId = perAppRouting !== undefined ? req.params[perAppRouting.paramName] : undefined;
+        const hasUrlAppId = typeof urlAppId === "string" && urlAppId.length > 0;
+        // Per-app authorize hook — when the deployment configured
+        // `perAppRouting.authorize` AND the request matched the per-app
+        // path, invoke the callback. Throwing collapses to a 403 before
+        // the MCP handler ever sees the request, which is the boundary
+        // that prevents cross-user blueprint reads when pod tools bypass
+        // AppSync owner-auth via raw DDB. Universal-endpoint requests
+        // skip this entirely (no urlAppId).
+        if (hasUrlAppId && perAppRouting?.authorize) {
+            try {
+                await perAppRouting.authorize(urlAppId, identity);
+            }
+            catch (err) {
+                reqLogger.warn("per_app_authorize_denied", {
+                    urlAppId,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                res.status(403).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32000, message: "Forbidden" },
+                    id: null,
+                });
+                return;
+            }
+        }
+        const ctx = {
+            appId: hasUrlAppId ? urlAppId : appIdFromIdentity(identity),
+            requestId,
+            // Identity is the canonical source of two mutually-exclusive
+            // hosted fields: `apiKeyHash` for kind=app, `userId` for kind=user.
+            // Threading them onto HandlerContext here means hosted handlers
+            // (the K8s ggui-protocol pod's billing gate + per-user blueprint
+            // scoping) can read identity directly without a parallel pod-only
+            // context shape; OSS handlers continue to ignore both fields.
+            ...(identity.identity.kind === "app" ? { apiKeyHash: identity.identity.apiKeyHash } : {}),
+            ...(identity.identity.kind === "user" ? { userId: identity.identity.userId } : {}),
+        };
+        reqLogger.debug?.("mcp_request", { appId: ctx.appId });
+        const mcp = buildMcpServer(info, routeHandlers, () => als.getStore() ?? ctx, reqLogger, {
+            ...buildMcpOptions,
+        });
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on("close", () => {
+            transport.close().catch(() => undefined);
+            mcp.close().catch(() => undefined);
+        });
+        try {
+            await mcp.connect(transport);
+            await als.run(ctx, () => transport.handleRequest(req, res, req.body));
+        }
+        catch (err) {
+            reqLogger.error("mcp_handle_failed", { error: String(err) });
+            if (!res.headersSent) {
+                let mapped;
+                if (errorMapper) {
+                    try {
+                        mapped = errorMapper(err);
+                    }
+                    catch (mapperErr) {
+                        // Defensive: a thrown mapper degrades to the default 500
+                        // rather than letting the inner failure escape the handler.
+                        reqLogger.warn("error_mapper_failed", {
+                            error: String(mapperErr),
+                        });
+                    }
+                }
+                if (mapped) {
+                    res.status(mapped.status).json({
+                        jsonrpc: "2.0",
+                        error: { code: mapped.code, message: mapped.message },
+                        id: null,
+                    });
+                }
+                else {
+                    res.status(500).json({
+                        jsonrpc: "2.0",
+                        error: { code: -32603, message: "Internal server error" },
+                        id: null,
+                    });
+                }
+            }
+        }
+    };
+    const methodNotAllowed = (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed (stateless server).",
+            },
+            id: null,
+        });
+    };
+    // Three audience-filtered handler sets. Each set is the
+    // subset of `handlers` whose `audience` tag intersects the route's
+    // allowed list. Handlers without an explicit tag default to
+    // ['agent'] — every such handler is agent-runtime callable.
+    const agentRouteHandlers = filterHandlersByAudience(handlers, ["agent", "runtime"]);
+    const protocolRouteHandlers = filterHandlersByAudience(handlers, ["protocol"]);
+    const opsRouteHandlers = filterHandlersByAudience(handlers, ["ops"]);
+    const agentMcpHandler = makeMcpHandler(agentRouteHandlers);
+    const protocolMcpHandler = makeMcpHandler(protocolRouteHandlers, { rejectFederated: true });
+    const opsMcpHandler = makeMcpHandler(opsRouteHandlers, { rejectFederated: true });
+    // Universal endpoint — `appId` resolved from the auth identity via
+    // `appIdFromIdentity`. Cloud `mcp.ggui.ai` deployments resolve this
+    // to `User.defaultAppId` via the auth-adapter; OSS deployments fall
+    // through to userId / DEFAULT_BUILDER_APP_ID.
+    //
+    // Path defaults to `/mcp` (Streamable HTTP convention). Cloud
+    // `mcp.ggui.ai` overrides to `/` so the bare-root URL is the
+    // universal endpoint — domain already says "mcp", no path repeat.
+    // Exposes audience tags ['agent', 'runtime'] — runtime tools stay
+    // routable on the same endpoint but invisible to the agent's
+    // `tools/list` via the `_meta.ui.visibility: ['app']` filter.
+    app.post(universalMcpPath, agentMcpHandler);
+    // Per-tenant endpoint — only mounted when the deployment opts in
+    // via `perAppRouting`. The same handler reads `req.params[paramName]`
+    // and uses it as `ctx.appId` for the request.
+    //
+    // When `pathPrefix` is set, the route mounts at
+    // `${pathPrefix}/:${paramName}` — cloud uses `/apps` so URLs are
+    // `mcp.ggui.ai/apps/<appId>`. The prefix segments per-tenant traffic
+    // from system routes (`/health`, `/oauth/*`, `/.well-known/*`,
+    // `/r/*`) so an opaque appId can never shadow a future static path.
+    //
+    // Without `pathPrefix`, the route mounts bare. The `paramPattern`
+    // constraint is the only collision defense — fine when the pattern
+    // guarantees non-collision (e.g. UUIDs).
+    //
+    // `path-to-regexp` v8 (express@5) dropped the `:param(pattern)`
+    // inline-regex syntax, so the pattern is enforced via a single
+    // `app.param` validator (anchored full-match) rather than baked into
+    // the route string. Registered once here; Express resolves it at
+    // dispatch for EVERY route declaring `paramName` — the per-app
+    // well-known route in the OAuth family AND this MCP route —
+    // regardless of registration order. A value failing the pattern
+    // 404s before any handler runs.
+    if (perAppRouting !== undefined) {
+        const { paramName, paramPattern, pathPrefix } = perAppRouting;
+        const appIdPattern = new RegExp(`^(?:${paramPattern})$`);
+        app.param(paramName, (_req, res, next, val) => {
+            if (typeof val !== "string" || !appIdPattern.test(val)) {
+                res.status(404).json({ error: "not_found" });
+                return;
+            }
+            next();
+        });
+        const route = pathPrefix !== undefined ? `${pathPrefix}/:${paramName}` : `/:${paramName}`;
+        app.post(route, agentMcpHandler);
+    }
+    // /protocol — design-time spec/discovery surface.
+    // Hosts the `audience: ['protocol']` tools (`ggui_describe_*`,
+    // `ggui_get_example_blueprints`, `ggui_validate_blueprint`,
+    // `ggui_list_available_primitives`, `ggui_get_blueprint_boilerplate`).
+    // Strips spec-discovery noise off the agent's runtime `tools/list`
+    // — agents that need format docs hit `/protocol` explicitly.
+    // Always mounted; the route has the same auth chain as `/mcp` for
+    // v1 (operators MAY narrow auth in their own middleware later).
+    // Empty when the deployment didn't wire any protocol-tagged handlers.
+    app.post("/protocol", protocolMcpHandler);
+    app.get("/protocol", methodNotAllowed);
+    app.delete("/protocol", methodNotAllowed);
+    // /ops — operator-class management surface. Hosts the
+    // `audience: ['ops']` tools (`ggui_set_provider_key`, `ggui_get_credit_balance`,
+    // etc.). Always mounted; same auth chain as `/mcp`. Empty when the
+    // deployment didn't wire any ops-tagged handlers.
+    app.post("/ops", opsMcpHandler);
+    app.get("/ops", methodNotAllowed);
+    app.delete("/ops", methodNotAllowed);
+    // Isolated MCP services — each at its own HTTP path with its own
+    // tool namespace. Bypasses audience filtering (the path IS the
+    // audience). Each service builds its own MCP request handler via
+    // `makeMcpHandler(svc.handlers)`, reusing the same auth chain +
+    // identity-resolution as the canonical routes — the difference is
+    // ONLY the handler set the route exposes.
+    //
+    // Validation already ran in the composer via `validateMcpServices`;
+    // here we just iterate the validated list.
+    for (const svc of mcpServices) {
+        // `anonymous: true` skips the auth chain and synthesizes a
+        // builder-kind identity with `source: 'anonymous'`. Default
+        // (undefined / false) preserves the auth-required posture of
+        // every canonical route.
+        const svcMcpHandler = makeMcpHandler(svc.handlers, svc.anonymous ? { anonymous: true } : undefined);
+        app.post(svc.path, svcMcpHandler);
+        app.get(svc.path, methodNotAllowed);
+        app.delete(svc.path, methodNotAllowed);
+    }
+    app.get(universalMcpPath, methodNotAllowed);
+    app.delete(universalMcpPath, methodNotAllowed);
+}

package/dist/mcp-mounts.d.ts

@@ -20,45 +20,8 @@
  * `buildMcpServer` registration, `toolCount`, telemetry, and logging
  * all Just Work.
  */
-import type { HandlerContext, SharedHandler } from "@ggui-ai/mcp-server-handlers";
+import type { SharedHandler } from "@ggui-ai/mcp-server-handlers";
 import type { ZodRawShape } from "zod";
-import type { WiredActionContext, WiredActionRouter } from "./render-channel.js";
-/**
- * Runtime ctx the mount-router hands the mount handler. Structurally a
- * superset of `HandlerContext` (so the mount's `handler(input, ctx)`
- * signature stays unchanged) PLUS the wired-action-only fields from
- * {@link WiredActionContext}.
- *
- * Why the type is exported: TS-authored mount tools that want to read
- * `ctx.sendPropsUpdate` / `ctx.renderId` import this and narrow their
- * `handler` parameter (e.g. `async handler(input, ctx) { const wired =
- * ctx as WiredMountContext; … }`). JS-authored mounts (.mjs) read the
- * fields structurally — they're present on the runtime object whether
- * or not the static type knows about them.
- *
- * The static `SharedHandler.handler` signature deliberately stays
- * narrow on `HandlerContext`. Widening that type would force every
- * shared handler (ggui-native + mounted) to acknowledge a wired-only
- * surface, even handlers that never run through the wired-action path
- * (e.g. `ggui_render`, blueprint search). The structural superset here
- * keeps the canonical contract narrow without sacrificing access for
- * mount tools that opt in.
- */
-/**
- * Intersection (not interface-extension) because `HandlerContext` declares
- * `renderId?` as optional — the canonical context shape any handler may
- * see — whereas `WiredActionContext` declares it as required (the
- * wired-action dispatcher always knows the active render at invocation
- * time). Interface-extends rejects "narrowing optional → required" via
- * TS2320 ("cannot simultaneously extend"), but an intersection composes
- * the two perfectly: optional ∧ required ≡ required.
- *
- * Surface for consumers stays identical — a TS-authored mount that types
- * its `handler` parameter as `WiredMountContext` reads `renderId: string`
- * (no `| undefined`) + every `HandlerContext` field
- * (`appId`, `requestId`, optional `apiKeyHash`).
- */
-export type WiredMountContext = Omit<HandlerContext, "renderId"> & WiredActionContext;
 /**
  * One named bundle of tool handlers the server should aggregate onto
  * its MCP surface.
@@ -111,7 +74,7 @@ export declare function validateServicePath(p: string): ServicePath;
  * MCP server with its own tool namespace.
  *
  * Use a **service** when the handler set is conceptually a distinct
- * MCP server (`mcp.ggui.ai/docs`, `mcp.ggui.ai/playground/todos`).
+ * MCP server (e.g. `<host>/docs`, `<host>/playground/todos`).
  * Use a **mount** when the handlers should appear alongside
  * ggui-native tools on the shared `/mcp` surface (fixtures, external
  * MCPs aggregated for one session's view).
@@ -200,41 +163,4 @@ export declare function validateMcpServices(services: ReadonlyArray<McpService>
  * `mounts` is empty, so callers never mutate the input reference.
  */
 export declare function composeHandlersWithMounts(baseHandlers: ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>, mounts: ReadonlyArray<McpServerMount> | undefined): ReadonlyArray<SharedHandler<ZodRawShape, ZodRawShape>>;
-/**
- * Build a {@link WiredActionRouter} that dispatches wired-action
- * hits to the matching mount handler's `handler(input, ctx)`. Zero-config composition for
- * OSS `ggui serve` — when the operator declares `ggui.json#mcpMounts`,
- * every mounted tool automatically becomes wire-dispatchable from
- * a generated UI's `useAction` without additional glue.
- *
- * Ownership + scoping:
- *   - Only MOUNT handlers participate. ggui-native handlers
- *     (`ggui_render`, `ggui_handshake`, etc.) are platform tools and
- *     deliberately NOT exposed as wire-dispatchable actions — a
- *     component that tried to dispatch `ggui_render` would bypass the
- *     agentic-loop contract.
- *   - Name collisions across mounts are prevented at aggregation
- *     time by {@link composeHandlersWithMounts}, so the first-match
- *     lookup here is safe.
- *
- * Context synthesis:
- *   - Each invocation gets a fresh {@link HandlerContext} with the
- *     caller-supplied `appId` (typically the session's appId) + a
- *     fresh request id. Mount handlers that read from storage scope
- *     to this appId, matching the `/mcp` ingress behavior.
- *   - The session-channel dispatcher additionally hands a
- *     {@link WiredActionContext}. The runtime ctx the mount handler
- *     sees is a structural superset
- *     ({@link WiredMountContext}) so a JS-authored mount can call
- *     `ctx.sendPropsUpdate({...})` directly (closed over `ctx.renderId`).
- *     The static
- *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
- *     untouched — tooling that doesn't read the wired fields keeps its
- *     existing types.
- *
- * Returns `null` when `mounts` is empty/absent, signaling the
- * composer to OMIT the `wiredActionRouter` opt entirely so servers
- * with no mounts behave as if the router did not exist.
- */
-export declare function composeWiredActionRouterFromMounts(mounts: ReadonlyArray<McpServerMount> | undefined, resolveContext: () => HandlerContext): WiredActionRouter | null;
 //# sourceMappingURL=mcp-mounts.d.ts.map

package/dist/mcp-mounts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-mounts.d.ts","sourceRoot":"","sources":["../src/mcp-mounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GAAG,kBAAkB,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAsBvE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAiB1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,SAAS,GAC9C,aAAa,CAAC,UAAU,CAAC,CAyC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EACpE,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,GAChD,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAoDxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,EACjD,cAAc,EAAE,MAAM,cAAc,GACnC,iBAAiB,GAAG,IAAI,CAyC1B"}
+{"version":3,"file":"mcp-mounts.d.ts","sourceRoot":"","sources":["../src/mcp-mounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAsBvE;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,WAAW,CAiB1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1E;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,SAAS,GAC9C,aAAa,CAAC,UAAU,CAAC,CAyC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,EACpE,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,GAAG,SAAS,GAChD,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAoDxD"}

package/dist/mcp-mounts.js

@@ -140,79 +140,3 @@ export function composeHandlersWithMounts(baseHandlers, mounts) {
     }
     return aggregated;
 }
-/**
- * Build a {@link WiredActionRouter} that dispatches wired-action
- * hits to the matching mount handler's `handler(input, ctx)`. Zero-config composition for
- * OSS `ggui serve` — when the operator declares `ggui.json#mcpMounts`,
- * every mounted tool automatically becomes wire-dispatchable from
- * a generated UI's `useAction` without additional glue.
- *
- * Ownership + scoping:
- *   - Only MOUNT handlers participate. ggui-native handlers
- *     (`ggui_render`, `ggui_handshake`, etc.) are platform tools and
- *     deliberately NOT exposed as wire-dispatchable actions — a
- *     component that tried to dispatch `ggui_render` would bypass the
- *     agentic-loop contract.
- *   - Name collisions across mounts are prevented at aggregation
- *     time by {@link composeHandlersWithMounts}, so the first-match
- *     lookup here is safe.
- *
- * Context synthesis:
- *   - Each invocation gets a fresh {@link HandlerContext} with the
- *     caller-supplied `appId` (typically the session's appId) + a
- *     fresh request id. Mount handlers that read from storage scope
- *     to this appId, matching the `/mcp` ingress behavior.
- *   - The session-channel dispatcher additionally hands a
- *     {@link WiredActionContext}. The runtime ctx the mount handler
- *     sees is a structural superset
- *     ({@link WiredMountContext}) so a JS-authored mount can call
- *     `ctx.sendPropsUpdate({...})` directly (closed over `ctx.renderId`).
- *     The static
- *     `SharedHandler.handler(input, ctx: HandlerContext)` shape stays
- *     untouched — tooling that doesn't read the wired fields keeps its
- *     existing types.
- *
- * Returns `null` when `mounts` is empty/absent, signaling the
- * composer to OMIT the `wiredActionRouter` opt entirely so servers
- * with no mounts behave as if the router did not exist.
- */
-export function composeWiredActionRouterFromMounts(mounts, resolveContext) {
-    if (!mounts || mounts.length === 0)
-        return null;
-    const byName = new Map();
-    for (const mount of mounts) {
-        for (const h of mount.handlers) {
-            // First-write-wins matches `composeHandlersWithMounts`'s
-            // collision-rejection order; the compose path throws before
-            // reaching this builder, so a duplicate here is dead code.
-            if (!byName.has(h.name))
-                byName.set(h.name, h);
-        }
-    }
-    return {
-        has(toolName) {
-            return byName.has(toolName);
-        },
-        async invoke(toolName, input, wiredCtx) {
-            const handler = byName.get(toolName);
-            if (!handler) {
-                // Unreachable in normal use — the session channel has()-gates
-                // before calling invoke. Thrown errors surface as TOOL_THREW
-                // envelopes, so the caller still gets a canonical shape.
-                throw new Error(`wiredActionRouter(mounts): no handler registered for '${toolName}'`);
-            }
-            // Synthesize the runtime ctx — structural superset of
-            // HandlerContext + WiredActionContext. The static
-            // `SharedHandler.handler` accepts `HandlerContext`; mounts that
-            // need the wired fields read them off the same `ctx` argument
-            // (TS via `WiredMountContext`, JS structurally).
-            const baseCtx = resolveContext();
-            const ctx = {
-                ...baseCtx,
-                renderId: wiredCtx.renderId,
-                sendPropsUpdate: wiredCtx.sendPropsUpdate,
-            };
-            return handler.handler(input, ctx);
-        },
-    };
-}