@agent-native/core 0.17.1 → 0.18.0

package/dist/mcp/builtin-tools.js

@@ -0,0 +1,299 @@
+/**
+ * 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, response }`                      |
+ * | `create_workspace_app`| scaffolds    | `{ name, url, port, deepLink }` (+ link) |
+ * | `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 { buildDeepLink } from "../server/deep-link.js";
+/**
+ * Build an `ActionTool`. `parameters` is wrapped in the
+ * `{ type:"object", properties, required }` shape `createMCPServerForRequest`
+ * forwards verbatim as the MCP tool `inputSchema`.
+ */
+function tool(description, parameters, required) {
+    if (!parameters)
+        return { description };
+    return {
+        description,
+        parameters: {
+            type: "object",
+            properties: parameters,
+            ...(required && required.length ? { required } : {}),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// list_apps
+// ---------------------------------------------------------------------------
+function listAppsTool() {
+    return {
+        tool: tool("List the workspace apps and their local dev URLs/ports. Use this to " +
+            "discover which apps exist before opening or asking one. In a single-" +
+            "app project this returns just that app."),
+        readOnly: true,
+        parallelSafe: true,
+        run: async () => {
+            const { resolveWorkspace } = await import("./workspace-resolve.js");
+            const ws = await resolveWorkspace();
+            return {
+                workspace: ws.isWorkspace,
+                gatewayUrl: ws.gatewayUrl,
+                apps: ws.apps.map((a) => ({
+                    id: a.id,
+                    url: a.url,
+                    port: a.port,
+                    running: a.running,
+                })),
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// open_app
+// ---------------------------------------------------------------------------
+function openAppTool() {
+    return {
+        tool: tool("Build a deep link that opens an app at a specific view/record. No side " +
+            "effects — returns a URL the user can click to land in the running UI. " +
+            'After calling, surface the returned "Open in … →" link to the user.', {
+            app: { type: "string", description: "App id, e.g. 'mail'" },
+            view: {
+                type: "string",
+                description: "Target view, e.g. 'inbox' (maps to navigate command)",
+            },
+            params: {
+                type: "object",
+                description: "Optional record-focus / filter params, e.g. { threadId: 'abc' }",
+            },
+        }, ["app", "view"]),
+        readOnly: true,
+        parallelSafe: true,
+        run: async (args) => {
+            const app = String(args.app ?? "").trim();
+            const view = String(args.view ?? "").trim();
+            if (!app || !view) {
+                throw new Error("open_app requires both 'app' and 'view'.");
+            }
+            let params;
+            const raw = args.params;
+            if (raw && typeof raw === "object") {
+                params = raw;
+            }
+            else if (typeof raw === "string" && raw.trim()) {
+                try {
+                    params = JSON.parse(raw);
+                }
+                catch {
+                    params = undefined;
+                }
+            }
+            const url = buildDeepLink({ app, view, params });
+            return { app, view, url };
+        },
+        link: ({ result }) => {
+            if (!result || typeof result !== "object")
+                return null;
+            const r = result;
+            if (!r.url)
+                return null;
+            return {
+                url: r.url,
+                label: `Open ${r.app ?? "app"}`,
+                view: r.view,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// ask_app
+// ---------------------------------------------------------------------------
+function askAppTool(config) {
+    return {
+        tool: tool("Send a natural-language message to an app's AI agent and get its " +
+            "response. Use for complex, multi-step tasks needing the agent's " +
+            "reasoning and full app context. In a single-app project the 'app' " +
+            "param is optional (defaults to this app).", {
+            app: {
+                type: "string",
+                description: "App id to route to (optional in a single-app project)",
+            },
+            message: {
+                type: "string",
+                description: "The message to send to the app's agent",
+            },
+        }, ["message"]),
+        run: async (args) => {
+            const message = String(args.message ?? "").trim();
+            if (!message)
+                throw new Error("ask_app requires a 'message'.");
+            const requestedApp = String(args.app ?? "").trim();
+            // This MCP server is mounted for a single app (`config`). Delegate to
+            // its own ask-agent handler — that is the same entry point the HTTP MCP
+            // mount + A2A use, so there is no second agent runner. Cross-app routing
+            // (talking to a *different* workspace app's agent) is intentionally not
+            // done here: the stdio proxy connects to one app, and cross-app fan-out
+            // is the workspace control plane's job (Dispatch / A2A).
+            if (!config.askAgent) {
+                throw new Error("This app does not expose an agent (no ask-agent handler).");
+            }
+            const response = await config.askAgent(message);
+            return {
+                app: requestedApp || config.name,
+                response,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// list_templates
+// ---------------------------------------------------------------------------
+function listTemplatesTool() {
+    return {
+        tool: tool("List the first-party templates that can be scaffolded into a workspace " +
+            "(allow-listed templates only)."),
+        readOnly: true,
+        parallelSafe: true,
+        run: async () => {
+            const { visibleTemplates } = await import("../cli/templates-meta.js");
+            return {
+                templates: visibleTemplates().map((t) => ({
+                    name: t.name,
+                    label: t.label,
+                    hint: t.hint,
+                })),
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// create_workspace_app
+// ---------------------------------------------------------------------------
+function createWorkspaceAppTool() {
+    return {
+        tool: tool("Scaffold a new app into the current workspace from an allow-listed " +
+            "template, then return a deep link to open it. Idempotent: if an app " +
+            "with that name already exists it is reused. After calling, surface " +
+            'the returned "Open … →" link to the user.', {
+            name: {
+                type: "string",
+                description: "New app id (directory under apps/), e.g. 'mymail'",
+            },
+            template: {
+                type: "string",
+                description: "Template to scaffold from — must be allow-listed (see list_templates)",
+            },
+        }, ["name", "template"]),
+        run: async (args) => {
+            const name = String(args.name ?? "").trim();
+            const template = String(args.template ?? "").trim();
+            if (!name || !template) {
+                throw new Error("create_workspace_app requires both 'name' and 'template'.");
+            }
+            // Enforce the strict public template allow-list. The authoritative,
+            // dependency-free source inside @agent-native/core is cli/templates-meta
+            // (kept in sync with packages/shared-app-config/templates.ts; CI guard).
+            const { visibleTemplates } = await import("../cli/templates-meta.js");
+            const allowed = new Set(visibleTemplates().map((t) => t.name));
+            if (!allowed.has(template)) {
+                throw new Error(`Template "${template}" is not allow-listed. Allowed: ${[...allowed]
+                    .sort()
+                    .join(", ")}`);
+            }
+            const { findWorkspaceRoot, resolveWorkspace } = await import("./workspace-resolve.js");
+            const fs = await import("node:fs");
+            const path = await import("node:path");
+            const root = findWorkspaceRoot(process.cwd());
+            if (!root) {
+                throw new Error("Not inside a workspace. create_workspace_app only works in a " +
+                    "multi-app workspace (run from the workspace root).");
+            }
+            const appDir = path.join(root, "apps", name);
+            const alreadyExisted = fs.existsSync(appDir);
+            if (!alreadyExisted) {
+                // Reuse the CLI scaffolder directly (no second `agent-native`
+                // subprocess). `addAppToWorkspace(name, { template })` takes the
+                // non-interactive single-template path when name + one template are
+                // given. Run it from the workspace root so detectWorkspace resolves.
+                const prevCwd = process.cwd();
+                try {
+                    process.chdir(root);
+                    const { addAppToWorkspace } = await import("../cli/create.js");
+                    await addAppToWorkspace(name, { template, noInstall: true });
+                }
+                finally {
+                    try {
+                        process.chdir(prevCwd);
+                    }
+                    catch {
+                        // best-effort cwd restore
+                    }
+                }
+            }
+            // The workspace gateway auto-detects new apps/* dirs (fs.watch +
+            // 2s sync) and lazily boots the dev server on first request, so we
+            // don't spawn vite ourselves — opening the deep link warms it. Resolve
+            // the port the gateway will use so we can report it.
+            const ws = await resolveWorkspace(root);
+            const appInfo = ws.apps.find((a) => a.id === name);
+            const port = appInfo?.port;
+            const deepLink = buildDeepLink({ app: name, view: "home" });
+            return {
+                name,
+                template,
+                created: !alreadyExisted,
+                reused: alreadyExisted,
+                port,
+                url: appInfo?.url,
+                gatewayUrl: ws.gatewayUrl,
+                deepLink,
+            };
+        },
+        link: ({ result }) => {
+            if (!result || typeof result !== "object")
+                return null;
+            const r = result;
+            if (!r.deepLink)
+                return null;
+            return {
+                url: r.deepLink,
+                label: `Open ${r.name ?? "app"}`,
+                view: "home",
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+/**
+ * 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 function getBuiltinCrossAppTools(config) {
+    return {
+        list_apps: listAppsTool(),
+        open_app: openAppTool(),
+        ask_app: askAppTool(config),
+        create_workspace_app: createWorkspaceAppTool(),
+        list_templates: listTemplatesTool(),
+    };
+}
+//# sourceMappingURL=builtin-tools.js.map

package/dist/mcp/builtin-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-tools.js","sourceRoot":"","sources":["../../src/mcp/builtin-tools.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generic cross-app MCP tools — a stable verb set every external agent gets\n * regardless of which template it is talking to.\n *\n * These are merged into the MCP action registry by\n * `createMCPServerForRequest` (see `build-server.ts`). **Precedence: template\n * actions win.** If a template defines an action named `list_apps` /\n * `open_app` / `ask_app` / `create_workspace_app` / `list_templates`, the\n * template's `ActionEntry` overwrites the builtin of the same name. This is\n * the same template-over-framework precedence `autoDiscoverActions` uses.\n *\n * | Tool                  | Side effects | Returns                                  |\n * | --------------------- | ------------ | ---------------------------------------- |\n * | `list_apps`           | none         | `{ apps: [{ id, url, running }] }`       |\n * | `open_app`            | none         | `{ url }` (+ deep-link `link`)           |\n * | `ask_app`             | agent loop   | `{ app, response }`                      |\n * | `create_workspace_app`| scaffolds    | `{ name, url, port, deepLink }` (+ link) |\n * | `list_templates`      | none         | `{ templates: [...] }` (allow-list only) |\n *\n * Node-only at call time (workspace resolution + scaffolding use `fs`), but\n * the module has no top-level Node imports so it bundles fine alongside\n * `mountMCP` — the Node bits are dynamically imported inside `run()`.\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport { buildDeepLink } from \"../server/deep-link.js\";\nimport type { MCPConfig } from \"./build-server.js\";\n\nimport type { ActionTool } from \"../agent/types.js\";\n\n/** Flat map of param name → JSON-schema property. */\ntype Params = Record<\n  string,\n  { type: string; description?: string; enum?: string[] }\n>;\n\n/**\n * Build an `ActionTool`. `parameters` is wrapped in the\n * `{ type:\"object\", properties, required }` shape `createMCPServerForRequest`\n * forwards verbatim as the MCP tool `inputSchema`.\n */\nfunction tool(\n  description: string,\n  parameters?: Params,\n  required?: string[],\n): ActionTool {\n  if (!parameters) return { description };\n  return {\n    description,\n    parameters: {\n      type: \"object\",\n      properties: parameters,\n      ...(required && required.length ? { required } : {}),\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// list_apps\n// ---------------------------------------------------------------------------\n\nfunction listAppsTool(): ActionEntry {\n  return {\n    tool: tool(\n      \"List the workspace apps and their local dev URLs/ports. Use this to \" +\n        \"discover which apps exist before opening or asking one. In a single-\" +\n        \"app project this returns just that app.\",\n    ),\n    readOnly: true,\n    parallelSafe: true,\n    run: async () => {\n      const { resolveWorkspace } = await import(\"./workspace-resolve.js\");\n      const ws = await resolveWorkspace();\n      return {\n        workspace: ws.isWorkspace,\n        gatewayUrl: ws.gatewayUrl,\n        apps: ws.apps.map((a) => ({\n          id: a.id,\n          url: a.url,\n          port: a.port,\n          running: a.running,\n        })),\n      };\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// open_app\n// ---------------------------------------------------------------------------\n\nfunction openAppTool(): ActionEntry {\n  return {\n    tool: tool(\n      \"Build a deep link that opens an app at a specific view/record. No side \" +\n        \"effects — returns a URL the user can click to land in the running UI. \" +\n        'After calling, surface the returned \"Open in … →\" link to the user.',\n      {\n        app: { type: \"string\", description: \"App id, e.g. 'mail'\" },\n        view: {\n          type: \"string\",\n          description: \"Target view, e.g. 'inbox' (maps to navigate command)\",\n        },\n        params: {\n          type: \"object\",\n          description:\n            \"Optional record-focus / filter params, e.g. { threadId: 'abc' }\",\n        },\n      },\n      [\"app\", \"view\"],\n    ),\n    readOnly: true,\n    parallelSafe: true,\n    run: async (args: Record<string, any>) => {\n      const app = String(args.app ?? \"\").trim();\n      const view = String(args.view ?? \"\").trim();\n      if (!app || !view) {\n        throw new Error(\"open_app requires both 'app' and 'view'.\");\n      }\n      let params: Record<string, string | number | boolean> | undefined;\n      const raw = args.params;\n      if (raw && typeof raw === \"object\") {\n        params = raw as Record<string, string | number | boolean>;\n      } else if (typeof raw === \"string\" && raw.trim()) {\n        try {\n          params = JSON.parse(raw);\n        } catch {\n          params = undefined;\n        }\n      }\n      const url = buildDeepLink({ app, view, params });\n      return { app, view, url };\n    },\n    link: ({ result }) => {\n      if (!result || typeof result !== \"object\") return null;\n      const r = result as { url?: string; app?: string; view?: string };\n      if (!r.url) return null;\n      return {\n        url: r.url,\n        label: `Open ${r.app ?? \"app\"}`,\n        view: r.view,\n      };\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// ask_app\n// ---------------------------------------------------------------------------\n\nfunction askAppTool(config: MCPConfig): ActionEntry {\n  return {\n    tool: tool(\n      \"Send a natural-language message to an app's AI agent and get its \" +\n        \"response. Use for complex, multi-step tasks needing the agent's \" +\n        \"reasoning and full app context. In a single-app project the 'app' \" +\n        \"param is optional (defaults to this app).\",\n      {\n        app: {\n          type: \"string\",\n          description: \"App id to route to (optional in a single-app project)\",\n        },\n        message: {\n          type: \"string\",\n          description: \"The message to send to the app's agent\",\n        },\n      },\n      [\"message\"],\n    ),\n    run: async (args: Record<string, any>) => {\n      const message = String(args.message ?? \"\").trim();\n      if (!message) throw new Error(\"ask_app requires a 'message'.\");\n      const requestedApp = String(args.app ?? \"\").trim();\n\n      // This MCP server is mounted for a single app (`config`). Delegate to\n      // its own ask-agent handler — that is the same entry point the HTTP MCP\n      // mount + A2A use, so there is no second agent runner. Cross-app routing\n      // (talking to a *different* workspace app's agent) is intentionally not\n      // done here: the stdio proxy connects to one app, and cross-app fan-out\n      // is the workspace control plane's job (Dispatch / A2A).\n      if (!config.askAgent) {\n        throw new Error(\n          \"This app does not expose an agent (no ask-agent handler).\",\n        );\n      }\n      const response = await config.askAgent(message);\n      return {\n        app: requestedApp || config.name,\n        response,\n      };\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// list_templates\n// ---------------------------------------------------------------------------\n\nfunction listTemplatesTool(): ActionEntry {\n  return {\n    tool: tool(\n      \"List the first-party templates that can be scaffolded into a workspace \" +\n        \"(allow-listed templates only).\",\n    ),\n    readOnly: true,\n    parallelSafe: true,\n    run: async () => {\n      const { visibleTemplates } = await import(\"../cli/templates-meta.js\");\n      return {\n        templates: visibleTemplates().map((t) => ({\n          name: t.name,\n          label: t.label,\n          hint: t.hint,\n        })),\n      };\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// create_workspace_app\n// ---------------------------------------------------------------------------\n\nfunction createWorkspaceAppTool(): ActionEntry {\n  return {\n    tool: tool(\n      \"Scaffold a new app into the current workspace from an allow-listed \" +\n        \"template, then return a deep link to open it. Idempotent: if an app \" +\n        \"with that name already exists it is reused. After calling, surface \" +\n        'the returned \"Open … →\" link to the user.',\n      {\n        name: {\n          type: \"string\",\n          description: \"New app id (directory under apps/), e.g. 'mymail'\",\n        },\n        template: {\n          type: \"string\",\n          description:\n            \"Template to scaffold from — must be allow-listed (see list_templates)\",\n        },\n      },\n      [\"name\", \"template\"],\n    ),\n    run: async (args: Record<string, any>) => {\n      const name = String(args.name ?? \"\").trim();\n      const template = String(args.template ?? \"\").trim();\n      if (!name || !template) {\n        throw new Error(\n          \"create_workspace_app requires both 'name' and 'template'.\",\n        );\n      }\n\n      // Enforce the strict public template allow-list. The authoritative,\n      // dependency-free source inside @agent-native/core is cli/templates-meta\n      // (kept in sync with packages/shared-app-config/templates.ts; CI guard).\n      const { visibleTemplates } = await import(\"../cli/templates-meta.js\");\n      const allowed = new Set(visibleTemplates().map((t) => t.name));\n      if (!allowed.has(template)) {\n        throw new Error(\n          `Template \"${template}\" is not allow-listed. Allowed: ${[...allowed]\n            .sort()\n            .join(\", \")}`,\n        );\n      }\n\n      const { findWorkspaceRoot, resolveWorkspace } =\n        await import(\"./workspace-resolve.js\");\n      const fs = await import(\"node:fs\");\n      const path = await import(\"node:path\");\n\n      const root = findWorkspaceRoot(process.cwd());\n      if (!root) {\n        throw new Error(\n          \"Not inside a workspace. create_workspace_app only works in a \" +\n            \"multi-app workspace (run from the workspace root).\",\n        );\n      }\n\n      const appDir = path.join(root, \"apps\", name);\n      const alreadyExisted = fs.existsSync(appDir);\n\n      if (!alreadyExisted) {\n        // Reuse the CLI scaffolder directly (no second `agent-native`\n        // subprocess). `addAppToWorkspace(name, { template })` takes the\n        // non-interactive single-template path when name + one template are\n        // given. Run it from the workspace root so detectWorkspace resolves.\n        const prevCwd = process.cwd();\n        try {\n          process.chdir(root);\n          const { addAppToWorkspace } = await import(\"../cli/create.js\");\n          await addAppToWorkspace(name, { template, noInstall: true });\n        } finally {\n          try {\n            process.chdir(prevCwd);\n          } catch {\n            // best-effort cwd restore\n          }\n        }\n      }\n\n      // The workspace gateway auto-detects new apps/* dirs (fs.watch +\n      // 2s sync) and lazily boots the dev server on first request, so we\n      // don't spawn vite ourselves — opening the deep link warms it. Resolve\n      // the port the gateway will use so we can report it.\n      const ws = await resolveWorkspace(root);\n      const appInfo = ws.apps.find((a) => a.id === name);\n      const port = appInfo?.port;\n      const deepLink = buildDeepLink({ app: name, view: \"home\" });\n\n      return {\n        name,\n        template,\n        created: !alreadyExisted,\n        reused: alreadyExisted,\n        port,\n        url: appInfo?.url,\n        gatewayUrl: ws.gatewayUrl,\n        deepLink,\n      };\n    },\n    link: ({ result }) => {\n      if (!result || typeof result !== \"object\") return null;\n      const r = result as { deepLink?: string; name?: string };\n      if (!r.deepLink) return null;\n      return {\n        url: r.deepLink,\n        label: `Open ${r.name ?? \"app\"}`,\n        view: \"home\",\n      };\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Registry\n// ---------------------------------------------------------------------------\n\n/**\n * Build the generic cross-app builtin tool registry. Called by\n * `createMCPServerForRequest`; the result is merged UNDER the config's\n * actions so template actions of the same name win.\n */\nexport function getBuiltinCrossAppTools(\n  config: MCPConfig,\n): Record<string, ActionEntry> {\n  return {\n    list_apps: listAppsTool(),\n    open_app: openAppTool(),\n    ask_app: askAppTool(config),\n    create_workspace_app: createWorkspaceAppTool(),\n    list_templates: listTemplatesTool(),\n  };\n}\n"]}

package/dist/mcp/index.d.ts

@@ -1,3 +1,10 @@
 export { mountMCP } from "./server.js";
 export type { MCPConfig } from "./server.js";
+export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, } from "./build-server.js";
+export type { MCPCallerIdentity, MCPRequestMeta } from "./build-server.js";
+export { runMCPStdio } from "./stdio.js";
+export type { RunMCPStdioOptions } from "./stdio.js";
+export { getBuiltinCrossAppTools } from "./builtin-tools.js";
+export { resolveWorkspace, resolveLocalAppOrigin, findWorkspaceRoot, } from "./workspace-resolve.js";
+export type { ResolvedApp, ResolvedWorkspace } from "./workspace-resolve.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAG3E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/mcp/index.js

@@ -1,2 +1,10 @@
 export { mountMCP } from "./server.js";
+// Shared MCP server builder (also re-exported from ./server.js for back-compat).
+export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, } from "./build-server.js";
+// stdio transport for `agent-native mcp serve` (Node-only).
+export { runMCPStdio } from "./stdio.js";
+// Generic cross-app builtin tools (merged into the registry, template wins).
+export { getBuiltinCrossAppTools } from "./builtin-tools.js";
+// Workspace / app resolution helpers (Node-only).
+export { resolveWorkspace, resolveLocalAppOrigin, findWorkspaceRoot, } from "./workspace-resolve.js";
 //# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC","sourcesContent":["export { mountMCP } from \"./server.js\";\nexport type { MCPConfig } from \"./server.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,iFAAiF;AACjF,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,4DAA4D;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,6EAA6E;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,kDAAkD;AAClD,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC","sourcesContent":["export { mountMCP } from \"./server.js\";\nexport type { MCPConfig } from \"./server.js\";\n\n// Shared MCP server builder (also re-exported from ./server.js for back-compat).\nexport {\n  createMCPServerForRequest,\n  verifyAuth,\n  getAccessTokens,\n  resolveOrgIdFromDomain,\n  buildLinkArtifacts,\n} from \"./build-server.js\";\nexport type { MCPCallerIdentity, MCPRequestMeta } from \"./build-server.js\";\n\n// stdio transport for `agent-native mcp serve` (Node-only).\nexport { runMCPStdio } from \"./stdio.js\";\nexport type { RunMCPStdioOptions } from \"./stdio.js\";\n\n// Generic cross-app builtin tools (merged into the registry, template wins).\nexport { getBuiltinCrossAppTools } from \"./builtin-tools.js\";\n\n// Workspace / app resolution helpers (Node-only).\nexport {\n  resolveWorkspace,\n  resolveLocalAppOrigin,\n  findWorkspaceRoot,\n} from \"./workspace-resolve.js\";\nexport type { ResolvedApp, ResolvedWorkspace } from \"./workspace-resolve.js\";\n"]}

package/dist/mcp/server.d.ts

@@ -1,16 +1,6 @@
-import type { ActionEntry } from "../agent/production-agent.js";
-export interface MCPConfig {
-    /** App name shown in MCP server info */
-    name: 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>;
-}
+import { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, type MCPConfig, type MCPCallerIdentity, type MCPRequestMeta } from "./build-server.js";
+export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, };
+export type { MCPConfig, MCPCallerIdentity, MCPRequestMeta };
 /**
  * Mount an MCP remote server on an H3/Nitro app.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAIhE,MAAM,WAAW,SAAS;IACxB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,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;CACjD;AAkOD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,SAAS,EACjB,WAAW,SAAmB,GAC7B,IAAI,CA4EN"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,CAAC;AACF,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAM7D;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,SAAS,EACjB,WAAW,SAAmB,GAC7B,IAAI,CAkGN"}

package/dist/mcp/server.js

@@ -1,180 +1,11 @@
-import * as jose from "jose";
 import { getH3App } from "../server/framework-request-handler.js";
 import { defineEventHandler, setResponseStatus, getMethod, getRequestHeader, } from "h3";
 import { readBody } from "../server/h3-helpers.js";
-import { runWithRequestContext } from "../server/request-context.js";
-// ---------------------------------------------------------------------------
-// Auth — reuses the same pattern as A2A (Bearer token or JWT)
-// ---------------------------------------------------------------------------
-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;
-}
-/**
- * Verify the inbound auth header. Returns:
- *   - { authed: true, identity } when verified — `identity` may be empty
- *     when authed via a static ACCESS_TOKEN (no caller email available).
- *   - { 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.
- */
-async function verifyAuth(authHeader) {
-    // No auth configured → allow (dev mode), but no identity to propagate.
-    const accessTokens = getAccessTokens();
-    const hasA2ASecret = !!process.env.A2A_SECRET;
-    if (accessTokens.length === 0 && !hasA2ASecret) {
-        return { authed: true };
-    }
-    if (!authHeader?.startsWith("Bearer "))
-        return { authed: false };
-    const token = authHeader.slice(7);
-    // Try JWT via A2A_SECRET
-    if (hasA2ASecret) {
-        try {
-            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 (no per-caller identity).
-    if (accessTokens.length > 0 && accessTokens.includes(token)) {
-        return { authed: true };
-    }
-    return { authed: false };
-}
-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;
-    }
-}
-// ---------------------------------------------------------------------------
-// MCP Server creation — converts ActionEntry registry to MCP tools
-// ---------------------------------------------------------------------------
-async function createMCPServerForRequest(config, identity) {
-    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: {} } });
-    // Resolve orgId once per request (DB lookup) so subsequent wraps are
-    // synchronous. The caller identity may be undefined for ACCESS_TOKEN
-    // auth — 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(identity?.orgDomain);
-    /**
-     * Wrap a callback in `runWithRequestContext({ userEmail, orgId }, 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.
-     */
-    async function withCallerContext(fn) {
-        const orgId = await orgIdPromise;
-        return runWithRequestContext({ userEmail: identity?.userEmail, orgId }, 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(config.actions).map(([name, entry]) => ({
-                name,
-                description: entry.tool.description ?? name,
-                inputSchema: entry.tool.parameters ?? {
-                    type: "object",
-                    properties: {},
-                },
-            }));
-            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 = config.actions[name];
-            if (!entry) {
-                return {
-                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
-                    isError: true,
-                };
-            }
-            try {
-                const result = await entry.run(args ?? {});
-                return { content: [{ type: "text", text: result }] };
-            }
-            catch (err) {
-                return {
-                    content: [{ type: "text", text: `Error: ${err.message}` }],
-                    isError: true,
-                };
-            }
-        });
-    });
-    return server;
-}
+import { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, } from "./build-server.js";
+// Re-export the shared MCP server builder + types so the stdio transport and
+// any (future) external importer of `@agent-native/core/mcp` keep resolving
+// against `./server.js` exactly as before this refactor.
+export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, };
 // ---------------------------------------------------------------------------
 // mountMCP — register MCP Streamable HTTP endpoint on H3/Nitro
 // ---------------------------------------------------------------------------
@@ -228,7 +59,22 @@ export function mountMCP(nitroApp, config, routePrefix = "/_agent-native") {
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined, // stateless
         });
-        const server = await createMCPServerForRequest(config, authResult.identity);
+        // Derive the running app's origin so relative deep links become
+        // absolute URLs the external agent can open (same approach as A2A).
+        const forwardedProto = getRequestHeader(event, "x-forwarded-proto");
+        const host = getRequestHeader(event, "host");
+        const proto = forwardedProto?.split(",")[0]?.trim() ||
+            (host && /^(localhost|127\.0\.0\.1)(:|$)/.test(host)
+                ? "http"
+                : "https");
+        const origin = host ? `${proto}://${host}` : undefined;
+        const targetHeader = getRequestHeader(event, "x-agent-native-open-target")?.toLowerCase();
+        const target = targetHeader === "desktop" ||
+            targetHeader === "terminal" ||
+            targetHeader === "browser"
+            ? targetHeader
+            : undefined;
+        const server = await createMCPServerForRequest(config, authResult.identity, { origin, target });
         await server.connect(transport);
         // Delegate to the transport — it writes directly to the Node response.
         // MCP's HTTP transport requires Node streams; this route is Node-only.