@agent-native/core 0.17.2 → 0.18.1

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

@@ -0,0 +1,152 @@
+/**
+ * Shared MCP server builder.
+ *
+ * Extracted from `server.ts` so the stateless Streamable-HTTP mount
+ * (`mountMCP`) and the stdio transport (`runMCPStdio --standalone`) build the
+ * *same* MCP server from the *same* `ActionEntry` registry. Both surfaces:
+ *
+ *   - expose every action as an MCP tool (+ the `ask-agent` meta-tool),
+ *   - append the framework deep-link block / `_meta` to every tool result,
+ *   - wrap `run()` / `askAgent()` in `runWithRequestContext` so per-user /
+ *     per-org scoping (accessFilter, resolveCredential, MCP visibility) is
+ *     honoured.
+ *
+ * `server.ts` re-exports `createMCPServerForRequest` and the auth helpers so
+ * any (future) external importer of `@agent-native/core/mcp` keeps resolving.
+ *
+ * Node-only at the SDK level, but this module itself has no Node-only imports
+ * — it can be bundled into the serverless function alongside `mountMCP`.
+ */
+import type { ActionEntry } from "../agent/production-agent.js";
+export interface MCPConfig {
+    /** App name shown in MCP server info */
+    name: string;
+    /**
+     * Canonical app id (directory under `apps/`, e.g. `mail`) this MCP server
+     * is mounted for. Optional & back-compat: when omitted the builtin
+     * cross-app tools fall back to lowercasing `name`. Used by `open_app` /
+     * `ask_app` / `create_workspace_app` to tell "this app" from a cross-app
+     * target so they resolve the *target* app's origin rather than echoing the
+     * current request origin.
+     */
+    appId?: string;
+    /** App description */
+    description: string;
+    /** Version string (default "1.0.0") */
+    version?: string;
+    /** Action registry — same as agent chat and A2A */
+    actions: Record<string, ActionEntry>;
+    /** Handler for the ask-agent meta-tool — runs the full agent loop */
+    askAgent?: (message: string) => Promise<string>;
+    /**
+     * Disable the generic cross-app builtin tools (`list_apps`, `open_app`,
+     * `ask_app`, `create_workspace_app`, `list_templates`). They are merged in
+     * by default so external agents get a stable verb set; a template action of
+     * the same name always wins (template precedence). Set to `false` only for
+     * a constrained / locked-down mount.
+     */
+    builtinCrossAppTools?: boolean;
+}
+/**
+ * Identity extracted from a verified MCP bearer token / JWT. Used to wrap
+ * `entry.run()` and `config.askAgent()` calls in `runWithRequestContext`
+ * so downstream tools (db-query, accessFilter, resolveCredential) honour
+ * per-user / per-org scoping. Without this wrap the MCP endpoint would
+ * silently bypass tenant isolation. See finding #6 in
+ * /tmp/security-audit/12-mcp-a2a-agent.md.
+ */
+export interface MCPCallerIdentity {
+    userEmail: string | undefined;
+    orgDomain: string | undefined;
+}
+/** Per-request context used to turn an action's relative deep link into the
+ *  absolute web URL (and desktop `agentnative://` URL) the external agent
+ *  surfaces. Derived from the inbound request headers in `mountMCP`, or from
+ *  the resolved local app origin in the stdio standalone path. */
+export interface MCPRequestMeta {
+    /** Origin of the running app, e.g. `http://localhost:8100`. */
+    origin?: string;
+    /** Optional client preference for which URL the *markdown* link uses. */
+    target?: "browser" | "desktop" | "terminal";
+}
+/**
+ * Build the deep-link content block + structured `_meta` for a tool result.
+ * Best-effort: any throw / nullish link is swallowed so a bad `link` builder
+ * never fails the tool call.
+ */
+export declare function buildLinkArtifacts(entry: ActionEntry, args: Record<string, any>, result: any, meta: MCPRequestMeta | undefined): {
+    block?: {
+        type: "text";
+        text: string;
+    };
+    _meta?: Record<string, unknown>;
+};
+/**
+ * Build a fully-wired MCP `Server` for a single request / session.
+ *
+ * Shared by the stateless Streamable-HTTP mount (`mountMCP`) and the stdio
+ * standalone transport. The HTTP mount passes the per-request origin via
+ * `requestMeta`; the stdio standalone path passes the resolved local app
+ * origin so deep links still become absolute URLs.
+ */
+export declare function createMCPServerForRequest(config: MCPConfig, identity: MCPCallerIdentity | undefined, requestMeta?: MCPRequestMeta): Promise<import("@modelcontextprotocol/sdk/server").Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            };
+        };
+    };
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            };
+        };
+    };
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        };
+    };
+}>>;
+export declare function getAccessTokens(): string[];
+/**
+ * Verify the inbound auth header. Returns:
+ *   - { authed: true, identity } when verified — `identity` is derived from
+ *     the JWT (`sub` / `org_domain`) for JWT auth, or from the
+ *     `AGENT_NATIVE_OWNER_EMAIL` env / `X-Agent-Native-Owner-Email` header
+ *     for static-token auth (the `agent-native mcp install` flow). `identity`
+ *     is undefined only for true dev-open with no owner hint.
+ *   - { authed: false } on rejection.
+ *
+ * When A2A_SECRET is set we extract the JWT's `sub` (caller email) and
+ * `org_domain` claims so the MCP endpoint can wrap tool runs in
+ * `runWithRequestContext({ userEmail, orgId })`. Without that wrap, the
+ * MCP endpoint loses tenant identity and downstream `accessFilter` /
+ * `resolveCredential` calls fall back to platform-wide defaults.
+ *
+ * `ownerEmailHeader` is the forwarded `X-Agent-Native-Owner-Email` value; it
+ * is consulted ONLY on the static-token / dev-open path (never to influence
+ * verified JWT identity), so the install flow runs tools as the configured
+ * owner instead of an unscoped anonymous caller.
+ */
+export declare function verifyAuth(authHeader: string | undefined, ownerEmailHeader?: string | undefined): Promise<{
+    authed: boolean;
+    identity?: MCPCallerIdentity;
+}>;
+export declare function resolveOrgIdFromDomain(orgDomain: string | undefined): Promise<string | undefined>;
+//# sourceMappingURL=build-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-server.d.ts","sourceRoot":"","sources":["../../src/mcp/build-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAKhE,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;kEAGkE;AAClE,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;CAC7C;AAED;;;;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,CAsBA;AA2BD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,iBAAiB,GAAG,SAAS,EACvC,WAAW,CAAC,EAAE,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8J7B;AAOD,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAc1C;AAyCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,GACpC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAiD5D;AAED,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B"}

package/dist/mcp/build-server.js

@@ -0,0 +1,349 @@
+/**
+ * Shared MCP server builder.
+ *
+ * Extracted from `server.ts` so the stateless Streamable-HTTP mount
+ * (`mountMCP`) and the stdio transport (`runMCPStdio --standalone`) build the
+ * *same* MCP server from the *same* `ActionEntry` registry. Both surfaces:
+ *
+ *   - expose every action as an MCP tool (+ the `ask-agent` meta-tool),
+ *   - append the framework deep-link block / `_meta` to every tool result,
+ *   - wrap `run()` / `askAgent()` in `runWithRequestContext` so per-user /
+ *     per-org scoping (accessFilter, resolveCredential, MCP visibility) is
+ *     honoured.
+ *
+ * `server.ts` re-exports `createMCPServerForRequest` and the auth helpers so
+ * any (future) external importer of `@agent-native/core/mcp` keeps resolving.
+ *
+ * Node-only at the SDK level, but this module itself has no Node-only imports
+ * — it can be bundled into the serverless function alongside `mountMCP`.
+ */
+import { runWithRequestContext } from "../server/request-context.js";
+import { toAbsoluteOpenUrl, toDesktopOpenUrl } from "../server/deep-link.js";
+import { getBuiltinCrossAppTools } from "./builtin-tools.js";
+/**
+ * Build the deep-link content block + structured `_meta` for a tool result.
+ * Best-effort: any throw / nullish link is swallowed so a bad `link` builder
+ * never fails the tool call.
+ */
+export function buildLinkArtifacts(entry, args, result, meta) {
+    if (typeof entry.link !== "function")
+        return {};
+    try {
+        const lk = entry.link({ args: args ?? {}, result });
+        if (!lk?.url)
+            return {};
+        const webUrl = toAbsoluteOpenUrl(lk.url, meta?.origin);
+        const desktopUrl = toDesktopOpenUrl(lk.url);
+        const markdownUrl = meta?.target === "desktop" ? desktopUrl : webUrl;
+        return {
+            block: { type: "text", text: `\n\n[${lk.label} →](${markdownUrl})` },
+            _meta: {
+                "agent-native/openLink": {
+                    label: lk.label,
+                    view: lk.view,
+                    webUrl,
+                    desktopUrl,
+                },
+            },
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge the generic cross-app builtin tools into the config's action
+ * registry. **Template actions take precedence**: if a template defines an
+ * action with the same name as a builtin (e.g. its own `list_apps`), the
+ * template entry wins and the builtin is dropped. This mirrors the
+ * template-over-workspace-core precedence in `autoDiscoverActions`.
+ *
+ * The builtins are pure-ish navigators / scaffolders; they call back into the
+ * same `config.actions` / `config.askAgent` so there is no second agent loop.
+ */
+function mergeBuiltinTools(config) {
+    if (config.builtinCrossAppTools === false)
+        return config.actions;
+    const builtins = getBuiltinCrossAppTools(config);
+    const merged = { ...builtins };
+    // Template / app actions overwrite same-named builtins.
+    for (const [name, entry] of Object.entries(config.actions)) {
+        merged[name] = entry;
+    }
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// MCP Server creation — converts ActionEntry registry to MCP tools
+// ---------------------------------------------------------------------------
+/**
+ * Build a fully-wired MCP `Server` for a single request / session.
+ *
+ * Shared by the stateless Streamable-HTTP mount (`mountMCP`) and the stdio
+ * standalone transport. The HTTP mount passes the per-request origin via
+ * `requestMeta`; the stdio standalone path passes the resolved local app
+ * 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 } = await import("@modelcontextprotocol/sdk/types.js");
+    const server = new Server({ name: config.name, version: config.version ?? "1.0.0" }, { capabilities: { tools: {} } });
+    // The action set the request handlers operate on = template actions +
+    // generic cross-app builtins (template wins on name collision).
+    const actions = mergeBuiltinTools(config);
+    // 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
+    // `AGENT_NATIVE_OWNER_EMAIL` env the `agent-native mcp install` flow writes
+    // into the `agent-native mcp serve` process env, so standalone tool runs are
+    // tenant-scoped to the configured owner instead of running unscoped. Stays
+    // undefined for true dev-open (no token, no secret, no owner) — behavior
+    // there is unchanged.
+    const ownerFromEnv = process.env.AGENT_NATIVE_OWNER_EMAIL?.trim();
+    const effectiveIdentity = identity ??
+        (ownerFromEnv
+            ? { userEmail: ownerFromEnv, orgDomain: undefined }
+            : undefined);
+    // 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 = resolveOrgIdFromDomain(effectiveIdentity?.orgDomain);
+    /**
+     * Wrap a callback in
+     * `runWithRequestContext({ userEmail, orgId, requestOrigin }, fn)`.
+     * Both the tools/list and tools/call handlers go through this so
+     * downstream `accessFilter`, `resolveCredential`, and per-user MCP
+     * visibility checks see the verified caller's identity. `requestOrigin`
+     * is the live server origin derived from the inbound request (same value
+     * used to absolutize deep links) so actions that build fetchable URLs
+     * (e.g. design `export-coding-handoff`'s signed raw-code URL) resolve the
+     * correct local-workspace origin instead of a prod/localhost fallback.
+     */
+    async function withCallerContext(fn) {
+        const orgId = await orgIdPromise;
+        return runWithRequestContext({
+            userEmail: effectiveIdentity?.userEmail,
+            orgId,
+            ...(requestMeta?.origin ? { requestOrigin: requestMeta.origin } : {}),
+        }, fn);
+    }
+    // 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 () => {
+        return withCallerContext(async () => {
+            const tools = Object.entries(actions).map(([name, entry]) => {
+                const hasLink = typeof entry.link === "function";
+                const baseDescription = entry.tool.description ?? name;
+                return {
+                    name,
+                    description: hasLink
+                        ? `${baseDescription} After calling, surface the returned "Open in … →" link to the user.`
+                        : baseDescription,
+                    inputSchema: entry.tool.parameters ?? {
+                        type: "object",
+                        properties: {},
+                    },
+                    ...(hasLink
+                        ? { annotations: { "agent-native/producesOpenLink": true } }
+                        : {}),
+                };
+            });
+            if (config.askAgent) {
+                tools.push({
+                    name: "ask-agent",
+                    description: "Send a natural-language message to the app's AI agent and get a response. " +
+                        "Use this for complex, multi-step tasks that require the agent's reasoning " +
+                        "and full context about the app.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            message: {
+                                type: "string",
+                                description: "The message to send to the agent",
+                            },
+                        },
+                        required: ["message"],
+                    },
+                });
+            }
+            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) => {
+        return withCallerContext(async () => {
+            const { name, arguments: args } = request.params;
+            if (name === "ask-agent" && config.askAgent) {
+                const message = args?.message ?? "";
+                try {
+                    const result = await config.askAgent(message);
+                    return { content: [{ type: "text", text: result }] };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Error: ${err.message}` }],
+                        isError: true,
+                    };
+                }
+            }
+            const entry = actions[name];
+            if (!entry) {
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+            }
+            try {
+                const result = await entry.run(args ?? {});
+                const text = typeof result === "string" ? result : JSON.stringify(result);
+                const content = [{ type: "text", text }];
+                const { block, _meta } = buildLinkArtifacts(entry, args ?? {}, result, requestMeta);
+                if (block)
+                    content.push(block);
+                return { content, ...(_meta ? { _meta } : {}) };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `Error: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        });
+    });
+    return server;
+}
+// ---------------------------------------------------------------------------
+// Auth — reuses the same pattern as A2A (Bearer token or JWT). Shared so the
+// HTTP mount and any stdio-side auth-aware helper resolve identity identically.
+// ---------------------------------------------------------------------------
+export function getAccessTokens() {
+    const single = process.env.ACCESS_TOKEN;
+    const multi = process.env.ACCESS_TOKENS;
+    const tokens = [];
+    if (single)
+        tokens.push(single);
+    if (multi) {
+        tokens.push(...multi
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean));
+    }
+    return tokens;
+}
+/**
+ * Resolve the caller identity for a static-token (or dev-open) auth path.
+ *
+ * Static `ACCESS_TOKEN` / `ACCESS_TOKENS` auth carries no per-caller claims,
+ * so without this the MCP endpoint would run every tool with
+ * `userEmail === undefined` and per-user / per-org scoped actions
+ * (`accessFilter`, `resolveAccess`, `resolveCredential`) would return
+ * empty / wrong data. The `agent-native mcp install` flow writes
+ * `AGENT_NATIVE_OWNER_EMAIL` into the client config env and the stdio proxy
+ * forwards it as the `X-Agent-Native-Owner-Email` request header (see
+ * `mcp/stdio.ts#authHeaders`). We trust that owner hint *only* on the
+ * static-token path — JWT auth already carries a cryptographically verified
+ * `sub`, so the header is ignored there and never widens JWT scope.
+ *
+ * Precedence is server-trusted-first: the server process's
+ * `AGENT_NATIVE_OWNER_EMAIL` env (set out-of-band by the operator / deploy)
+ * ALWAYS wins, and a client-supplied `X-Agent-Native-Owner-Email` header is
+ * honored *only as a fallback when that env is unset*. A static `ACCESS_TOKEN`
+ * is a shared bearer secret; letting a request header override a
+ * server-configured owner would let anyone holding a leaked token act as any
+ * user. The header path remains for the single-tenant local-dev install flow
+ * where the app server process has no owner env and the token *is* the
+ * workspace secret; multi-tenant deployments must use A2A JWT (verified `sub`),
+ * not a static token, for per-user scope.
+ *
+ * Returns `undefined` when no owner email is available (true dev-open: no
+ * token, no secret, no owner) so behavior there stays unchanged.
+ */
+function deriveStaticTokenIdentity(ownerEmailHeader) {
+    const owner = process.env.AGENT_NATIVE_OWNER_EMAIL?.trim() ||
+        (typeof ownerEmailHeader === "string" && ownerEmailHeader.trim()) ||
+        "";
+    if (!owner)
+        return undefined;
+    return { userEmail: owner, orgDomain: undefined };
+}
+/**
+ * Verify the inbound auth header. Returns:
+ *   - { authed: true, identity } when verified — `identity` is derived from
+ *     the JWT (`sub` / `org_domain`) for JWT auth, or from the
+ *     `AGENT_NATIVE_OWNER_EMAIL` env / `X-Agent-Native-Owner-Email` header
+ *     for static-token auth (the `agent-native mcp install` flow). `identity`
+ *     is undefined only for true dev-open with no owner hint.
+ *   - { authed: false } on rejection.
+ *
+ * When A2A_SECRET is set we extract the JWT's `sub` (caller email) and
+ * `org_domain` claims so the MCP endpoint can wrap tool runs in
+ * `runWithRequestContext({ userEmail, orgId })`. Without that wrap, the
+ * MCP endpoint loses tenant identity and downstream `accessFilter` /
+ * `resolveCredential` calls fall back to platform-wide defaults.
+ *
+ * `ownerEmailHeader` is the forwarded `X-Agent-Native-Owner-Email` value; it
+ * is consulted ONLY on the static-token / dev-open path (never to influence
+ * verified JWT identity), so the install flow runs tools as the configured
+ * owner instead of an unscoped anonymous caller.
+ */
+export async function verifyAuth(authHeader, ownerEmailHeader) {
+    // No auth configured → allow (dev mode). Still honour an owner hint
+    // (env or forwarded header) so the install flow stays tenant-scoped.
+    const accessTokens = getAccessTokens();
+    const hasA2ASecret = !!process.env.A2A_SECRET;
+    if (accessTokens.length === 0 && !hasA2ASecret) {
+        return {
+            authed: true,
+            identity: deriveStaticTokenIdentity(ownerEmailHeader),
+        };
+    }
+    if (!authHeader?.startsWith("Bearer "))
+        return { authed: false };
+    const token = authHeader.slice(7);
+    // Try JWT via A2A_SECRET
+    if (hasA2ASecret) {
+        try {
+            const jose = await import("jose");
+            const { payload } = await jose.jwtVerify(token, new TextEncoder().encode(process.env.A2A_SECRET));
+            return {
+                authed: true,
+                identity: {
+                    userEmail: typeof payload.sub === "string" ? payload.sub : undefined,
+                    orgDomain: typeof payload.org_domain === "string"
+                        ? payload.org_domain
+                        : undefined,
+                },
+            };
+        }
+        catch {
+            // Not a valid JWT — fall through to token check
+        }
+    }
+    // Try ACCESS_TOKEN / ACCESS_TOKENS exact match. Static tokens carry no
+    // per-caller claims, so derive identity from the forwarded owner-email
+    // hint (install flow) — otherwise tools would run unscoped.
+    if (accessTokens.length > 0 && accessTokens.includes(token)) {
+        return {
+            authed: true,
+            identity: deriveStaticTokenIdentity(ownerEmailHeader),
+        };
+    }
+    return { authed: false };
+}
+export async function resolveOrgIdFromDomain(orgDomain) {
+    if (!orgDomain)
+        return undefined;
+    try {
+        const { resolveOrgByDomain } = await import("../org/context.js");
+        const org = await resolveOrgByDomain(orgDomain);
+        return org?.orgId ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=build-server.js.map

package/dist/mcp/build-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-server.js","sourceRoot":"","sources":["../../src/mcp/build-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared MCP server builder.\n *\n * Extracted from `server.ts` so the stateless Streamable-HTTP mount\n * (`mountMCP`) and the stdio transport (`runMCPStdio --standalone`) build the\n * *same* MCP server from the *same* `ActionEntry` registry. Both surfaces:\n *\n *   - expose every action as an MCP tool (+ the `ask-agent` meta-tool),\n *   - append the framework deep-link block / `_meta` to every tool result,\n *   - wrap `run()` / `askAgent()` in `runWithRequestContext` so per-user /\n *     per-org scoping (accessFilter, resolveCredential, MCP visibility) is\n *     honoured.\n *\n * `server.ts` re-exports `createMCPServerForRequest` and the auth helpers so\n * any (future) external importer of `@agent-native/core/mcp` keeps resolving.\n *\n * Node-only at the SDK level, but this module itself has no Node-only imports\n * — it can be bundled into the serverless function alongside `mountMCP`.\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport { runWithRequestContext } from \"../server/request-context.js\";\nimport { toAbsoluteOpenUrl, toDesktopOpenUrl } from \"../server/deep-link.js\";\nimport { getBuiltinCrossAppTools } from \"./builtin-tools.js\";\n\nexport interface MCPConfig {\n  /** App name shown in MCP server info */\n  name: string;\n  /**\n   * Canonical app id (directory under `apps/`, e.g. `mail`) this MCP server\n   * is mounted for. Optional & back-compat: when omitted the builtin\n   * cross-app tools fall back to lowercasing `name`. Used by `open_app` /\n   * `ask_app` / `create_workspace_app` to tell \"this app\" from a cross-app\n   * target so they resolve the *target* app's origin rather than echoing the\n   * current request origin.\n   */\n  appId?: string;\n  /** App description */\n  description: string;\n  /** Version string (default \"1.0.0\") */\n  version?: string;\n  /** Action registry — same as agent chat and A2A */\n  actions: Record<string, ActionEntry>;\n  /** Handler for the ask-agent meta-tool — runs the full agent loop */\n  askAgent?: (message: string) => Promise<string>;\n  /**\n   * Disable the generic cross-app builtin tools (`list_apps`, `open_app`,\n   * `ask_app`, `create_workspace_app`, `list_templates`). They are merged in\n   * by default so external agents get a stable verb set; a template action of\n   * the same name always wins (template precedence). Set to `false` only for\n   * a constrained / locked-down mount.\n   */\n  builtinCrossAppTools?: boolean;\n}\n\n/**\n * Identity extracted from a verified MCP bearer token / JWT. Used to wrap\n * `entry.run()` and `config.askAgent()` calls in `runWithRequestContext`\n * so downstream tools (db-query, accessFilter, resolveCredential) honour\n * per-user / per-org scoping. Without this wrap the MCP endpoint would\n * silently bypass tenant isolation. See finding #6 in\n * /tmp/security-audit/12-mcp-a2a-agent.md.\n */\nexport interface MCPCallerIdentity {\n  userEmail: string | undefined;\n  orgDomain: string | undefined;\n}\n\n/** Per-request context used to turn an action's relative deep link into the\n *  absolute web URL (and desktop `agentnative://` URL) the external agent\n *  surfaces. Derived from the inbound request headers in `mountMCP`, or from\n *  the resolved local app origin in the stdio standalone path. */\nexport interface MCPRequestMeta {\n  /** Origin of the running app, e.g. `http://localhost:8100`. */\n  origin?: string;\n  /** Optional client preference for which URL the *markdown* link uses. */\n  target?: \"browser\" | \"desktop\" | \"terminal\";\n}\n\n/**\n * Build the deep-link content block + structured `_meta` for a tool result.\n * Best-effort: any throw / nullish link is swallowed so a bad `link` builder\n * never fails the tool call.\n */\nexport function buildLinkArtifacts(\n  entry: ActionEntry,\n  args: Record<string, any>,\n  result: any,\n  meta: MCPRequestMeta | undefined,\n): {\n  block?: { type: \"text\"; text: string };\n  _meta?: Record<string, unknown>;\n} {\n  if (typeof entry.link !== \"function\") return {};\n  try {\n    const lk = entry.link({ args: args ?? {}, result });\n    if (!lk?.url) return {};\n    const webUrl = toAbsoluteOpenUrl(lk.url, meta?.origin);\n    const desktopUrl = toDesktopOpenUrl(lk.url);\n    const markdownUrl = meta?.target === \"desktop\" ? desktopUrl : webUrl;\n    return {\n      block: { type: \"text\", text: `\\n\\n[${lk.label} →](${markdownUrl})` },\n      _meta: {\n        \"agent-native/openLink\": {\n          label: lk.label,\n          view: lk.view,\n          webUrl,\n          desktopUrl,\n        },\n      },\n    };\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Merge the generic cross-app builtin tools into the config's action\n * registry. **Template actions take precedence**: if a template defines an\n * action with the same name as a builtin (e.g. its own `list_apps`), the\n * template entry wins and the builtin is dropped. This mirrors the\n * template-over-workspace-core precedence in `autoDiscoverActions`.\n *\n * The builtins are pure-ish navigators / scaffolders; they call back into the\n * same `config.actions` / `config.askAgent` so there is no second agent loop.\n */\nfunction mergeBuiltinTools(config: MCPConfig): Record<string, ActionEntry> {\n  if (config.builtinCrossAppTools === false) return config.actions;\n  const builtins = getBuiltinCrossAppTools(config);\n  const merged: Record<string, ActionEntry> = { ...builtins };\n  // Template / app actions overwrite same-named builtins.\n  for (const [name, entry] of Object.entries(config.actions)) {\n    merged[name] = entry;\n  }\n  return merged;\n}\n\n// ---------------------------------------------------------------------------\n// MCP Server creation — converts ActionEntry registry to MCP tools\n// ---------------------------------------------------------------------------\n\n/**\n * Build a fully-wired MCP `Server` for a single request / session.\n *\n * Shared by the stateless Streamable-HTTP mount (`mountMCP`) and the stdio\n * standalone transport. The HTTP mount passes the per-request origin via\n * `requestMeta`; the stdio standalone path passes the resolved local app\n * origin so deep links still become absolute URLs.\n */\nexport async function createMCPServerForRequest(\n  config: MCPConfig,\n  identity: MCPCallerIdentity | undefined,\n  requestMeta?: MCPRequestMeta,\n) {\n  const { Server } = await import(\"@modelcontextprotocol/sdk/server/index.js\");\n  const { ListToolsRequestSchema, CallToolRequestSchema } =\n    await import(\"@modelcontextprotocol/sdk/types.js\");\n\n  const server = new Server(\n    { name: config.name, version: config.version ?? \"1.0.0\" },\n    { capabilities: { tools: {} } },\n  );\n\n  // The action set the request handlers operate on = template actions +\n  // generic cross-app builtins (template wins on name collision).\n  const actions = mergeBuiltinTools(config);\n\n  // Resolve the effective caller identity. JWT / header-derived identity\n  // (passed by `mountMCP` via `verifyAuth`) wins. When the caller passed no\n  // identity — the stdio **standalone** path — fall back to the\n  // `AGENT_NATIVE_OWNER_EMAIL` env the `agent-native mcp install` flow writes\n  // into the `agent-native mcp serve` process env, so standalone tool runs are\n  // tenant-scoped to the configured owner instead of running unscoped. Stays\n  // undefined for true dev-open (no token, no secret, no owner) — behavior\n  // there is unchanged.\n  const ownerFromEnv = process.env.AGENT_NATIVE_OWNER_EMAIL?.trim();\n  const effectiveIdentity: MCPCallerIdentity | undefined =\n    identity ??\n    (ownerFromEnv\n      ? { userEmail: ownerFromEnv, orgDomain: undefined }\n      : undefined);\n\n  // Resolve orgId once per request (DB lookup) so subsequent wraps are\n  // synchronous. The caller identity may be undefined for true dev-open —\n  // in that case we run with no userEmail/orgId, which makes downstream\n  // tools that require per-user scope return empty results rather than\n  // cross-tenant data (the safe default).\n  const orgIdPromise = resolveOrgIdFromDomain(effectiveIdentity?.orgDomain);\n\n  /**\n   * Wrap a callback in\n   * `runWithRequestContext({ userEmail, orgId, requestOrigin }, fn)`.\n   * Both the tools/list and tools/call handlers go through this so\n   * downstream `accessFilter`, `resolveCredential`, and per-user MCP\n   * visibility checks see the verified caller's identity. `requestOrigin`\n   * is the live server origin derived from the inbound request (same value\n   * used to absolutize deep links) so actions that build fetchable URLs\n   * (e.g. design `export-coding-handoff`'s signed raw-code URL) resolve the\n   * correct local-workspace origin instead of a prod/localhost fallback.\n   */\n  async function withCallerContext<T>(fn: () => Promise<T>): Promise<T> {\n    const orgId = await orgIdPromise;\n    return runWithRequestContext(\n      {\n        userEmail: effectiveIdentity?.userEmail,\n        orgId,\n        ...(requestMeta?.origin ? { requestOrigin: requestMeta.origin } : {}),\n      },\n      fn,\n    ) as Promise<T>;\n  }\n\n  // tools/list — return all actions + ask-agent meta-tool. Wrapped in the\n  // request context so per-user MCP visibility (mcp-client/visibility.ts)\n  // applies to the listing too.\n  server.setRequestHandler(ListToolsRequestSchema, async () => {\n    return withCallerContext(async () => {\n      const tools = Object.entries(actions).map(([name, entry]) => {\n        const hasLink = typeof entry.link === \"function\";\n        const baseDescription = entry.tool.description ?? name;\n        return {\n          name,\n          description: hasLink\n            ? `${baseDescription} After calling, surface the returned \"Open in … →\" link to the user.`\n            : baseDescription,\n          inputSchema: entry.tool.parameters ?? {\n            type: \"object\" as const,\n            properties: {},\n          },\n          ...(hasLink\n            ? { annotations: { \"agent-native/producesOpenLink\": true } }\n            : {}),\n        };\n      });\n\n      if (config.askAgent) {\n        tools.push({\n          name: \"ask-agent\",\n          description:\n            \"Send a natural-language message to the app's AI agent and get a response. \" +\n            \"Use this for complex, multi-step tasks that require the agent's reasoning \" +\n            \"and full context about the app.\",\n          inputSchema: {\n            type: \"object\" as const,\n            properties: {\n              message: {\n                type: \"string\",\n                description: \"The message to send to the agent\",\n              },\n            },\n            required: [\"message\"],\n          },\n        });\n      }\n\n      return { tools };\n    });\n  });\n\n  // tools/call — dispatch to action registry or ask-agent. Wrapped in the\n  // request context so the action's `run(args)` and `askAgent()` execute\n  // with the verified caller's identity, not the platform default.\n  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {\n    return withCallerContext(async () => {\n      const { name, arguments: args } = request.params;\n\n      if (name === \"ask-agent\" && config.askAgent) {\n        const message = args?.message ?? \"\";\n        try {\n          const result = await config.askAgent(message);\n          return { content: [{ type: \"text\", text: result }] };\n        } catch (err: any) {\n          return {\n            content: [{ type: \"text\", text: `Error: ${err.message}` }],\n            isError: true,\n          };\n        }\n      }\n\n      const entry = actions[name];\n      if (!entry) {\n        return {\n          content: [{ type: \"text\", text: `Unknown tool: ${name}` }],\n          isError: true,\n        };\n      }\n\n      try {\n        const result = await entry.run((args as Record<string, string>) ?? {});\n        const text =\n          typeof result === \"string\" ? result : JSON.stringify(result);\n        const content: any[] = [{ type: \"text\", text }];\n        const { block, _meta } = buildLinkArtifacts(\n          entry,\n          (args as Record<string, any>) ?? {},\n          result,\n          requestMeta,\n        );\n        if (block) content.push(block);\n        return { content, ...(_meta ? { _meta } : {}) };\n      } catch (err: any) {\n        return {\n          content: [{ type: \"text\", text: `Error: ${err.message}` }],\n          isError: true,\n        };\n      }\n    });\n  });\n\n  return server;\n}\n\n// ---------------------------------------------------------------------------\n// Auth — reuses the same pattern as A2A (Bearer token or JWT). Shared so the\n// HTTP mount and any stdio-side auth-aware helper resolve identity identically.\n// ---------------------------------------------------------------------------\n\nexport function getAccessTokens(): string[] {\n  const single = process.env.ACCESS_TOKEN;\n  const multi = process.env.ACCESS_TOKENS;\n  const tokens: string[] = [];\n  if (single) tokens.push(single);\n  if (multi) {\n    tokens.push(\n      ...multi\n        .split(\",\")\n        .map((t) => t.trim())\n        .filter(Boolean),\n    );\n  }\n  return tokens;\n}\n\n/**\n * Resolve the caller identity for a static-token (or dev-open) auth path.\n *\n * Static `ACCESS_TOKEN` / `ACCESS_TOKENS` auth carries no per-caller claims,\n * so without this the MCP endpoint would run every tool with\n * `userEmail === undefined` and per-user / per-org scoped actions\n * (`accessFilter`, `resolveAccess`, `resolveCredential`) would return\n * empty / wrong data. The `agent-native mcp install` flow writes\n * `AGENT_NATIVE_OWNER_EMAIL` into the client config env and the stdio proxy\n * forwards it as the `X-Agent-Native-Owner-Email` request header (see\n * `mcp/stdio.ts#authHeaders`). We trust that owner hint *only* on the\n * static-token path — JWT auth already carries a cryptographically verified\n * `sub`, so the header is ignored there and never widens JWT scope.\n *\n * Precedence is server-trusted-first: the server process's\n * `AGENT_NATIVE_OWNER_EMAIL` env (set out-of-band by the operator / deploy)\n * ALWAYS wins, and a client-supplied `X-Agent-Native-Owner-Email` header is\n * honored *only as a fallback when that env is unset*. A static `ACCESS_TOKEN`\n * is a shared bearer secret; letting a request header override a\n * server-configured owner would let anyone holding a leaked token act as any\n * user. The header path remains for the single-tenant local-dev install flow\n * where the app server process has no owner env and the token *is* the\n * workspace secret; multi-tenant deployments must use A2A JWT (verified `sub`),\n * not a static token, for per-user scope.\n *\n * Returns `undefined` when no owner email is available (true dev-open: no\n * token, no secret, no owner) so behavior there stays unchanged.\n */\nfunction deriveStaticTokenIdentity(\n  ownerEmailHeader: string | undefined,\n): MCPCallerIdentity | undefined {\n  const owner =\n    process.env.AGENT_NATIVE_OWNER_EMAIL?.trim() ||\n    (typeof ownerEmailHeader === \"string\" && ownerEmailHeader.trim()) ||\n    \"\";\n  if (!owner) return undefined;\n  return { userEmail: owner, orgDomain: undefined };\n}\n\n/**\n * Verify the inbound auth header. Returns:\n *   - { authed: true, identity } when verified — `identity` is derived from\n *     the JWT (`sub` / `org_domain`) for JWT auth, or from the\n *     `AGENT_NATIVE_OWNER_EMAIL` env / `X-Agent-Native-Owner-Email` header\n *     for static-token auth (the `agent-native mcp install` flow). `identity`\n *     is undefined only for true dev-open with no owner hint.\n *   - { authed: false } on rejection.\n *\n * When A2A_SECRET is set we extract the JWT's `sub` (caller email) and\n * `org_domain` claims so the MCP endpoint can wrap tool runs in\n * `runWithRequestContext({ userEmail, orgId })`. Without that wrap, the\n * MCP endpoint loses tenant identity and downstream `accessFilter` /\n * `resolveCredential` calls fall back to platform-wide defaults.\n *\n * `ownerEmailHeader` is the forwarded `X-Agent-Native-Owner-Email` value; it\n * is consulted ONLY on the static-token / dev-open path (never to influence\n * verified JWT identity), so the install flow runs tools as the configured\n * owner instead of an unscoped anonymous caller.\n */\nexport async function verifyAuth(\n  authHeader: string | undefined,\n  ownerEmailHeader?: string | undefined,\n): Promise<{ authed: boolean; identity?: MCPCallerIdentity }> {\n  // No auth configured → allow (dev mode). Still honour an owner hint\n  // (env or forwarded header) so the install flow stays tenant-scoped.\n  const accessTokens = getAccessTokens();\n  const hasA2ASecret = !!process.env.A2A_SECRET;\n  if (accessTokens.length === 0 && !hasA2ASecret) {\n    return {\n      authed: true,\n      identity: deriveStaticTokenIdentity(ownerEmailHeader),\n    };\n  }\n\n  if (!authHeader?.startsWith(\"Bearer \")) return { authed: false };\n  const token = authHeader.slice(7);\n\n  // Try JWT via A2A_SECRET\n  if (hasA2ASecret) {\n    try {\n      const jose = await import(\"jose\");\n      const { payload } = await jose.jwtVerify(\n        token,\n        new TextEncoder().encode(process.env.A2A_SECRET!),\n      );\n      return {\n        authed: true,\n        identity: {\n          userEmail: typeof payload.sub === \"string\" ? payload.sub : undefined,\n          orgDomain:\n            typeof payload.org_domain === \"string\"\n              ? (payload.org_domain as string)\n              : undefined,\n        },\n      };\n    } catch {\n      // Not a valid JWT — fall through to token check\n    }\n  }\n\n  // Try ACCESS_TOKEN / ACCESS_TOKENS exact match. Static tokens carry no\n  // per-caller claims, so derive identity from the forwarded owner-email\n  // hint (install flow) — otherwise tools would run unscoped.\n  if (accessTokens.length > 0 && accessTokens.includes(token)) {\n    return {\n      authed: true,\n      identity: deriveStaticTokenIdentity(ownerEmailHeader),\n    };\n  }\n\n  return { authed: false };\n}\n\nexport async function resolveOrgIdFromDomain(\n  orgDomain: string | undefined,\n): Promise<string | undefined> {\n  if (!orgDomain) return undefined;\n  try {\n    const { resolveOrgByDomain } = await import(\"../org/context.js\");\n    const org = await resolveOrgByDomain(orgDomain);\n    return org?.orgId ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n"]}

package/dist/mcp/builtin-tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generic cross-app MCP tools — a stable verb set every external agent gets
+ * regardless of which template it is talking to.
+ *
+ * These are merged into the MCP action registry by
+ * `createMCPServerForRequest` (see `build-server.ts`). **Precedence: template
+ * actions win.** If a template defines an action named `list_apps` /
+ * `open_app` / `ask_app` / `create_workspace_app` / `list_templates`, the
+ * template's `ActionEntry` overwrites the builtin of the same name. This is
+ * the same template-over-framework precedence `autoDiscoverActions` uses.
+ *
+ * | Tool                  | Side effects | Returns                                  |
+ * | --------------------- | ------------ | ---------------------------------------- |
+ * | `list_apps`           | none         | `{ apps: [{ id, url, running }] }`       |
+ * | `open_app`            | none         | `{ url }` (+ deep-link `link`)           |
+ * | `ask_app`             | agent loop   | `{ app, routedVia, response }`           |
+ * | `create_workspace_app`| scaffolds    | `{ name, url, port, deepLink }` (+ link) |
+ *
+ * `open_app` / `create_workspace_app` return an **absolute** URL on the
+ * *target* app's origin when it differs from this app (so a workspace link
+ * lands in the right app), and a relative path for the same app / standalone.
+ * `ask_app` routes to a *different* workspace app over A2A when possible and
+ * reports `routedVia: "a2a"`; otherwise it answers locally
+ * (`routedVia: "local"`) and never falsely claims cross-app delegation.
+ * | `list_templates`      | none         | `{ templates: [...] }` (allow-list only) |
+ *
+ * Node-only at call time (workspace resolution + scaffolding use `fs`), but
+ * the module has no top-level Node imports so it bundles fine alongside
+ * `mountMCP` — the Node bits are dynamically imported inside `run()`.
+ */
+import type { ActionEntry } from "../agent/production-agent.js";
+import type { MCPConfig } from "./build-server.js";
+/**
+ * Build the generic cross-app builtin tool registry. Called by
+ * `createMCPServerForRequest`; the result is merged UNDER the config's
+ * actions so template actions of the same name win.
+ */
+export declare function getBuiltinCrossAppTools(config: MCPConfig): Record<string, ActionEntry>;
+//# sourceMappingURL=builtin-tools.d.ts.map

package/dist/mcp/builtin-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/builtin-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA+ZnD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,GAChB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAQ7B"}