@agent-native/core 0.128.4 → 0.129.0

package/dist/mcp/build-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-server.d.ts","sourceRoot":"","sources":["../../src/mcp/build-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AA0BhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAOtE,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC1B,CAAC,CAAC;IACH,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAChD,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;kEAGkE;AAClE,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC5C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA+BD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GACtC,OAAO,CAgBT;AAmFD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CASrE;AAkDD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKlE;AA2ZD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,MAAM,EAAE,GAAG,EACX,IAAI,EAAE,cAAc,GAAG,SAAS,GAC/B;IACD,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CA2BA;AAkiBD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,WAAW,CAAC,EAAE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA+iB7B;AAOD,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAc1C;AAyCD,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,SAAS,CAIpB;AA+FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,gBAAgB,CAAC,EAAE,MAAM,EACzB,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CAAO,GACxE,OAAO,CAAC;IACT,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC,CA4ID;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GACtC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc7B"}
+{"version":3,"file":"build-server.d.ts","sourceRoot":"","sources":["../../src/mcp/build-server.ts"],"names":[],"mappings":"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"}

package/dist/mcp/build-server.js

@@ -24,10 +24,65 @@ import { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, }
 import { getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "../shared/agent-sidebar-url.js";
 import { MCP_APP_CHAT_BRIDGE_QUERY_PARAM } from "../shared/embed-auth.js";
+import { consumeMcpApprovalGrant, createMcpApprovalGrant, } from "./approval-store.js";
 import { getBuiltinCrossAppTools } from "./builtin-tools.js";
 import { MCP_CONNECT_OAUTH_CLIENT_ID, MCP_CONNECT_SCOPE, } from "./connect-store.js";
 import { MCP_APP_REQUEST_ORIGIN_CSP_SOURCE } from "./embed-app.js";
 import { hasMcpOAuthScope, verifyMcpOAuthAccessToken, } from "./oauth-token.js";
+const MCP_ACTION_APPROVAL_TTL_SECONDS = 10 * 60;
+const MCP_ACTION_APPROVAL_INPUT_KEY = "actionApproval";
+function canonicalJson(value) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError("MCP action arguments must contain finite numbers");
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(",")}}`;
+    }
+    throw new TypeError("MCP action arguments must be JSON values");
+}
+async function sha256Base64Url(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    const bytes = new Uint8Array(digest);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function mcpApprovalPrincipal(identity, orgId, requestMeta) {
+    return canonicalJson({
+        caller: "mcp",
+        userEmail: identity?.userEmail?.trim().toLowerCase() ?? "",
+        orgId: orgId ?? identity?.orgId ?? "",
+        orgDomain: identity?.orgDomain?.trim().toLowerCase() ?? "",
+        oauthClientId: identity?.oauthClientId ?? "",
+        firstPartyMcp: identity?.firstPartyMcp === true,
+        origin: requestMeta?.origin ?? "",
+    });
+}
+function actionApprovalError(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
 const ASK_AGENT_DEFAULT_INLINE_WAIT_MS = 20_000;
 const ASK_AGENT_MAX_INLINE_WAIT_MS = 25_000;
 function boundedAskAgentWaitMs(raw) {
@@ -639,6 +694,9 @@ function mcpServerInfo(config, requestMeta) {
         ...(icons?.length ? { icons } : {}),
     };
 }
+function compareMcpCatalogValues(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
 function safeUiSegment(value, fallback) {
     const normalized = (value || fallback)
         .trim()
@@ -1016,8 +1074,7 @@ function conciseToolResultText(name, result, options) {
  * origin so deep links still become absolute URLs.
  */
 export async function createMCPServerForRequest(config, identity, requestMeta) {
-    const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
-    const { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, } = await import("@modelcontextprotocol/sdk/types.js");
+    const { ResourceNotFoundError, Server, acceptedContent, createRequestStateCodec, inputRequired, } = await import("@modelcontextprotocol/server");
     // Resolve the effective caller identity. JWT / header-derived identity
     // (passed by `mountMCP` via `verifyAuth`) wins. When the caller passed no
     // identity — the stdio **standalone** path — fall back to the
@@ -1101,6 +1158,37 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     if (fullCatalogRequested) {
         warnFullCatalogServed(Object.keys(advertisedActions).length);
     }
+    // Resolve orgId once per request (DB lookup) so approval state and every
+    // downstream action see the same authenticated principal.
+    const orgIdPromise = resolveMcpIdentityOrgId(effectiveIdentity);
+    const hasApprovalActions = Object.values(actions).some((entry) => entry.needsApproval !== undefined);
+    const approvalOrgId = hasApprovalActions ? await orgIdPromise : undefined;
+    const approvalPrincipal = hasApprovalActions
+        ? mcpApprovalPrincipal(effectiveIdentity, approvalOrgId, requestMeta)
+        : undefined;
+    const approvalCallerKey = approvalPrincipal
+        ? await sha256Base64Url(approvalPrincipal)
+        : undefined;
+    let approvalCodec;
+    let approvalConfigurationError = false;
+    if (hasApprovalActions && approvalPrincipal) {
+        try {
+            const { getAuthSecret } = await import("../server/better-auth-instance.js");
+            approvalCodec = createRequestStateCodec({
+                key: getAuthSecret(),
+                ttlSeconds: MCP_ACTION_APPROVAL_TTL_SECONDS,
+                bind: (ctx) => `${ctx.mcpReq.method}\0${approvalPrincipal}`,
+            });
+        }
+        catch {
+            // Production secret resolution deliberately throws when neither the
+            // explicit Better Auth secret nor the workspace-derived A2A secret is
+            // stable. Keep the MCP server available for reads, but refuse every
+            // approval-gated action rather than minting replayable/ephemeral hosted
+            // authorization state.
+            approvalConfigurationError = true;
+        }
+    }
     const supportsMcpApps = compactMcpAppCatalog ||
         Object.values(advertisedActions).some((entry) => Boolean(entry.mcpApp?.resource));
     const server = new Server(mcpServerInfo(config, requestMeta), {
@@ -1117,13 +1205,27 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 }
                 : {}),
         },
+        // Every catalog and resource is identity-scoped and can change at runtime
+        // through app configuration/HMR. Explicitly mark modern cacheable results
+        // private and immediately stale; the 2026 codec adds the required
+        // ttlMs/cacheScope fields while 2025 responses remain byte-compatible.
+        cacheHints: {
+            "server/discover": { ttlMs: 0, cacheScope: "private" },
+            "tools/list": { ttlMs: 0, cacheScope: "private" },
+            "resources/list": { ttlMs: 0, cacheScope: "private" },
+            "resources/templates/list": { ttlMs: 0, cacheScope: "private" },
+            "resources/read": { ttlMs: 0, cacheScope: "private" },
+        },
+        ...(approvalCodec
+            ? {
+                inputRequired: {
+                    maxRounds: 2,
+                    roundTimeoutMs: 10 * 60_000,
+                },
+                requestState: { verify: approvalCodec.verify },
+            }
+            : {}),
     });
-    // Resolve orgId once per request (DB lookup) so subsequent wraps are
-    // synchronous. The caller identity may be undefined for true dev-open —
-    // in that case we run with no userEmail/orgId, which makes downstream
-    // tools that require per-user scope return empty results rather than
-    // cross-tenant data (the safe default).
-    const orgIdPromise = resolveMcpIdentityOrgId(effectiveIdentity);
     /**
      * Wrap a callback in
      * `runWithRequestContext({ userEmail, orgId, requestOrigin }, fn)`.
@@ -1143,12 +1245,100 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
             ...(requestMeta?.origin ? { requestOrigin: requestMeta.origin } : {}),
         }, fn);
     }
+    async function requireMcpActionApproval(entry, name, args, ctx) {
+        const verifiedState = ctx.mcpReq.requestState() ?? undefined;
+        const argumentsHash = await sha256Base64Url(canonicalJson(args));
+        if (verifiedState !== undefined) {
+            if (verifiedState.version !== 1 ||
+                typeof verifiedState.nonce !== "string" ||
+                verifiedState.actionName !== name ||
+                verifiedState.argumentsHash !== argumentsHash ||
+                !Number.isFinite(verifiedState.expiresAt) ||
+                verifiedState.expiresAt < Date.now() ||
+                !approvalCallerKey) {
+                return actionApprovalError(`Approval for ${name} is invalid or does not match this exact call.`);
+            }
+            const consumed = await consumeMcpApprovalGrant({
+                nonce: verifiedState.nonce,
+                callerKey: approvalCallerKey,
+                actionName: name,
+                argumentsHash,
+                expiresAt: verifiedState.expiresAt,
+            });
+            if (!consumed) {
+                return actionApprovalError(`Approval for ${name} is invalid, expired, or already used.`);
+            }
+            const approval = acceptedContent(ctx.mcpReq.inputResponses, MCP_ACTION_APPROVAL_INPUT_KEY);
+            if (approval?.decision !== "approve") {
+                return actionApprovalError(`${name} was not approved.`);
+            }
+            return undefined;
+        }
+        if (entry.needsApproval === undefined)
+            return undefined;
+        let mustApprove = false;
+        try {
+            mustApprove =
+                typeof entry.needsApproval === "function"
+                    ? Boolean(await entry.needsApproval(args, {
+                        userEmail: getRequestUserEmail(),
+                        orgId: getRequestOrgId() ?? null,
+                        caller: "mcp",
+                        actionName: name,
+                    }))
+                    : entry.needsApproval === true;
+        }
+        catch {
+            mustApprove = true;
+        }
+        if (!mustApprove)
+            return undefined;
+        if (approvalConfigurationError || !approvalCodec || !approvalCallerKey) {
+            return actionApprovalError(`${name} requires approval, but secure MCP approval is not configured on this server.`);
+        }
+        const now = Date.now();
+        const approvalState = {
+            version: 1,
+            nonce: globalThis.crypto.randomUUID(),
+            actionName: name,
+            argumentsHash,
+            expiresAt: now + MCP_ACTION_APPROVAL_TTL_SECONDS * 1000,
+        };
+        await createMcpApprovalGrant({
+            ...approvalState,
+            callerKey: approvalCallerKey,
+        });
+        const requestState = await approvalCodec.mint(approvalState, ctx);
+        return inputRequired({
+            inputRequests: {
+                [MCP_ACTION_APPROVAL_INPUT_KEY]: inputRequired.elicit({
+                    message: `Action "${name}" requires your approval before it can run. ` +
+                        "Review the exact tool arguments in your MCP client, then explicitly choose Approve or Deny.",
+                    requestedSchema: {
+                        type: "object",
+                        properties: {
+                            decision: {
+                                type: "string",
+                                title: `Run ${name}?`,
+                                description: "Approve runs this exact call once. Deny leaves it unexecuted.",
+                                enum: ["approve", "deny"],
+                            },
+                        },
+                        required: ["decision"],
+                    },
+                }),
+            },
+            requestState,
+        });
+    }
     // tools/list — return all actions + ask-agent meta-tool. Wrapped in the
     // request context so per-user MCP visibility (mcp-client/visibility.ts)
     // applies to the listing too.
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
+    server.setRequestHandler("tools/list", async () => {
         return withCallerContext(async () => {
-            const tools = await Promise.all(Object.entries(advertisedActions).map(async ([name, entry]) => {
+            const tools = await Promise.all(Object.entries(advertisedActions)
+                .sort(([a], [b]) => compareMcpCatalogValues(a, b))
+                .map(async ([name, entry]) => {
                 const hasLink = typeof entry.link === "function";
                 const mcpAppResource = await resolveMcpAppResourceSafely(config, name, entry, requestMeta);
                 const rawToolMeta = entry.tool._meta &&
@@ -1159,8 +1349,8 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 const toolMeta = {
                     ...rawToolMeta,
                     // Advertisement path: only tag the tool with its inline-embed
-                    // descriptor when the kill switch is on, so disabled embeds never
-                    // prompt a host to render/read the `ui://` resource.
+                    // descriptor when the kill switch is on, so disabled embeds
+                    // never prompt a host to render/read the `ui://` resource.
                     ...(mcpAppResource && requestMeta?.inlineMcpApps
                         ? {
                             ...openAiToolDescriptorMeta(mcpAppResource),
@@ -1173,7 +1363,8 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 const baseDescription = entry.tool.description ?? name;
                 const annotations = {
                     readOnlyHint: entry.readOnly === true,
-                    destructiveHint: entry.publicAgent?.isConsequential === true,
+                    destructiveHint: entry.publicAgent?.isConsequential === true ||
+                        entry.needsApproval !== undefined,
                     openWorldHint: false,
                 };
                 if (hasLink)
@@ -1227,13 +1418,14 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     },
                 });
             }
+            tools.sort((a, b) => compareMcpCatalogValues(a.name, b.name));
             return { tools };
         });
     });
     // tools/call — dispatch to action registry or ask-agent. Wrapped in the
     // request context so the action's `run(args)` and `askAgent()` execute
     // with the verified caller's identity, not the platform default.
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler("tools/call", async (request, ctx) => {
         return withCallerContext(async () => {
             const { name, arguments: args } = request.params;
             if (name === "ask-agent" && config.askAgent) {
@@ -1309,6 +1501,9 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 };
             }
             try {
+                const approvalResult = await requireMcpActionApproval(entry, name, args ?? {}, ctx);
+                if (approvalResult !== undefined)
+                    return approvalResult;
                 // We're inside `withCallerContext`, so the request-context getters
                 // resolve the verified MCP caller's identity (do NOT inject a dev
                 // fallback). Tag the call as an external-agent MCP dispatch.
@@ -1404,11 +1599,13 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
         });
     });
     if (supportsMcpApps) {
-        server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        server.setRequestHandler("resources/list", async () => {
             return withCallerContext(async () => {
                 const mcpAppResources = await getMcpAppResources(config, advertisedActions, requestMeta);
                 return {
-                    resources: mcpAppResources.map((resource) => ({
+                    resources: mcpAppResources
+                        .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
+                        .map((resource) => ({
                         uri: resource.uri,
                         name: resource.name,
                         ...(resource.title ? { title: resource.title } : {}),
@@ -1421,11 +1618,13 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 };
             });
         });
-        server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        server.setRequestHandler("resources/templates/list", async () => {
             return withCallerContext(async () => {
                 const mcpAppResources = await getMcpAppResources(config, advertisedActions, requestMeta);
                 return {
-                    resourceTemplates: mcpAppResources.map((resource) => ({
+                    resourceTemplates: mcpAppResources
+                        .sort((a, b) => compareMcpCatalogValues(a.uri, b.uri))
+                        .map((resource) => ({
                         uriTemplate: resource.uri,
                         name: resource.name,
                         ...(resource.title ? { title: resource.title } : {}),
@@ -1438,7 +1637,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                 };
             });
         });
-        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        server.setRequestHandler("resources/read", async (request) => {
             return withCallerContext(async () => {
                 const uri = request.params?.uri;
                 let found = null;
@@ -1457,7 +1656,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                     // aborting and reporting the resource as missing.
                 }
                 if (!found) {
-                    throw new Error(`MCP App resource not found: ${uri}`);
+                    throw new ResourceNotFoundError(String(uri ?? ""), `MCP App resource not found: ${uri}`);
                 }
                 return {
                     contents: [
@@ -1465,9 +1664,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
                             uri,
                             mimeType: found.resource.mimeType,
                             text: renderMcpAppHtml(found.resource, found.actionName, config, requestMeta),
-                            ...(found.resource._meta
-                                ? { _meta: found.resource._meta }
-                                : {}),
+                            ...(found.resource._meta ? { _meta: found.resource._meta } : {}),
                         },
                     ],
                 };