@layers/amba-mcp 4.0.8 → 4.0.9

package/dist/auto/collection-tools.d.ts

@@ -51,6 +51,8 @@ export interface CollectionPolicy {
 export interface AppMcpClientAuth {
     apiKey: string;
     sessionToken?: string;
+    /** Verified by the client API on every request; never trusted locally. */
+    groupContext?: string;
     baseUrl: string;
 }
 export interface RegisterCollectionToolsOptions {

package/dist/auto/function-tools.d.ts

@@ -26,12 +26,14 @@
  * named `recipes`.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { type AppMcpClientAuth } from './collection-tools.js';
 /** One exposed function from the app-MCP manifest. */
 export interface AppMcpManifestFunction {
     name: string;
     description?: string | null;
     input_schema?: Record<string, unknown> | null;
+    annotations?: ToolAnnotations | null;
     public?: boolean;
     invoke_url: string;
 }

package/dist/index.js

@@ -641,9 +641,9 @@ function registerTool(server, apiClient, name, description, schema, handler, ali
 * `amba_developer_login`, `amba_developer_refresh`) — anything else
 * should go through `registerTool`.
 */
-function registerPublicTool(server, name, description, schema, handler, aliases = []) {
-	server.tool(name, description, schema, deriveToolAnnotations(name), handler);
-	for (const alias of aliases) server.tool(alias, description, schema, deriveToolAnnotations(alias), (async (args) => {
+function registerPublicTool(server, name, description, schema, handler, aliases = [], annotations) {
+	server.tool(name, description, schema, annotations ?? deriveToolAnnotations(name), handler);
+	for (const alias of aliases) server.tool(alias, description, schema, annotations ?? deriveToolAnnotations(alias), (async (args) => {
 		warnDeprecatedAlias(alias, name);
 		return handler(args);
 	}));
@@ -1489,6 +1489,13 @@ function jsonResult$1(payload) {
 		text: JSON.stringify(payload, null, 2)
 	}] };
 }
+/** Preserve an HTTP response wrapper while mapping failures to MCP isError. */
+function httpResult(result) {
+	return {
+		...jsonResult$1(result),
+		...result.status >= 400 ? { isError: true } : {}
+	};
+}
 /**
 * Flatten an upstream HTTP response into the agent-facing tool payload.
 * Body fields are spread FIRST so a future top-level `status` key in
@@ -1496,10 +1503,13 @@ function jsonResult$1(payload) {
 * `parsed.status` to distinguish 2xx from 4xx/5xx.
 */
 function passthroughResult(result) {
-	return jsonResult$1({
-		...result.body ?? {},
-		status: result.status
-	});
+	return {
+		...jsonResult$1({
+			...result.body !== null && typeof result.body === "object" ? result.body : {},
+			status: result.status
+		}),
+		...result.status >= 400 ? { isError: true } : {}
+	};
 }
 //#endregion
 //#region src/tools/users.ts
@@ -5755,14 +5765,17 @@ function registerTools$18(server, apiClient) {
 		"Function name must match /^[a-z][a-z0-9_-]*$/ and be ≤58 chars. Bundle size cap: 10 MiB (enforced client-side too — oversize uploads are rejected before the round-trip).",
 		"Optional `rate_limit` declares a per-function rate-limit config (validated server-side). Pass null/omit for no rate limit.",
 		"Optional `public` (default false) deploys the function WITHOUT the X-Api-Key gate, so third-party webhook senders (RevenueCat, Stripe, GitHub, Slack) that cannot attach a custom header can reach it. SECURITY: when public, YOU must verify the webhook signature (HMAC) inside the function body — the runtime no longer requires a caller credential. `public: true` only skips the key requirement; rate-limiting and the per-request signed identity context still apply. Leave it false for functions only your own app calls.",
+		"Optional `forward_authorization` (default false) forwards a verified client Bearer to customer code. X-Api-Key and platform internal-trigger credentials are always stripped. Enable only when the function must validate or proxy the end-user session.",
 		"Returns the function deployment row + the public URL (`fn_url`: `https://{project_slug}.fn.amba.host/{name}`)."
 	].join(" "), {
 		project_id: z.string().describe("The Amba project ID."),
 		name: z.string().describe("Function name. Lowercase, /^[a-z][a-z0-9_-]*$/, ≤58 chars."),
 		code: z.string().describe("Bundled JavaScript module source (one entry file)."),
 		rate_limit: z.unknown().optional().describe("Optional rate-limit config object. Shape: see @layers/amba-shared:RateLimitConfig."),
-		public: z.boolean().optional().describe("Deploy the function as PUBLIC (no X-Api-Key required) so external webhook senders can reach it. Default false. When true, you MUST verify the webhook HMAC signature inside the function body — public skips the credential gate only; rate-limiting and signed identity context still apply.")
-	}, async ({ project_id, name, code, rate_limit, public: isPublic }, { pat }) => {
+		public: z.boolean().optional().describe("Deploy the function as PUBLIC (no X-Api-Key required) so external webhook senders can reach it. Default false. When true, you MUST verify the webhook HMAC signature inside the function body — public skips the credential gate only; rate-limiting and signed identity context still apply."),
+		forward_authorization: z.boolean().optional().describe("Forward a verified client Authorization Bearer to customer code. Default false. X-Api-Key and platform internal credentials are never forwarded."),
+		mcp: z.unknown().optional().describe("Optional app-MCP tool config: {description?, input_schema?, annotations?}. Safety annotations support readOnlyHint, destructiveHint, idempotentHint, and openWorldHint booleans.")
+	}, async ({ project_id, name, code, rate_limit, public: isPublic, forward_authorization: forwardAuthorization, mcp }, { pat }) => {
 		const byteLen = Buffer.byteLength(code, "utf8");
 		if (byteLen > MAX_BUNDLE_BYTES) throw new Error(`Bundle size ${byteLen} bytes exceeds ${MAX_BUNDLE_BYTES}-byte cap (10 MiB).`);
 		const form = new FormData();
@@ -5770,6 +5783,8 @@ function registerTools$18(server, apiClient) {
 		const metadata = { name };
 		if (rate_limit !== void 0 && rate_limit !== null) metadata.rate_limit = rate_limit;
 		if (isPublic === true) metadata.public = true;
+		if (forwardAuthorization === true) metadata.forward_authorization = true;
+		if (mcp !== void 0) metadata.mcp = mcp;
 		form.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }), "metadata.json");
 		return jsonResult(await callWithPat(apiClient, pat, "POST", `/projects/${encodeURIComponent(project_id)}/functions/deploy`, { formData: form }));
 	}, ["amba_deploy_function"]);
@@ -5859,6 +5874,9 @@ function registerTools$18(server, apiClient) {
 			deleted: true
 		});
 	});
+	registerTool(server, apiClient, "amba_functions_list_schedules", "List function schedules with their cron expression, timezone, pause state, next fire time, and most recent fire time. Rows degrade with enriched=false if one provider describe call fails.", { project_id: z.string().describe("The Amba project ID.") }, async ({ project_id }, { pat }) => {
+		return jsonResult(await callWithPat(apiClient, pat, "GET", `/projects/${encodeURIComponent(project_id)}/functions/schedules`));
+	});
 	registerTool(server, apiClient, "amba_functions_schedule", [
 		"Register a cron Schedule for a function. The schedule is keyed deterministically per (project, function) — re-calling with a different cron/timezone replaces the prior schedule rather than creating a duplicate.",
 		"Cron must be a standard 5- or 6-field whitespace-separated expression. `timezone` defaults to \"UTC\" if omitted. Timezones are IANA strings (e.g. \"America/Los_Angeles\").",
@@ -10148,6 +10166,7 @@ const TOOL_CATEGORY = {
 	amba_functions_get_logs: "infrastructure",
 	amba_get_function_logs: "infrastructure",
 	amba_functions_schedule: "infrastructure",
+	amba_functions_list_schedules: "infrastructure",
 	amba_schedule_function: "infrastructure",
 	amba_functions_pause_schedule: "infrastructure",
 	amba_pause_function_schedule: "infrastructure",
@@ -10706,6 +10725,7 @@ async function adminFetch(apiClient, bearer, call) {
 async function clientFetch(clientAuth, call) {
 	const headers = { "X-Api-Key": clientAuth.apiKey };
 	if (clientAuth.sessionToken) headers["Authorization"] = `Bearer ${clientAuth.sessionToken}`;
+	if (clientAuth.groupContext) headers["X-Group-Context"] = clientAuth.groupContext;
 	return proxyFetch(clientAuth.baseUrl, headers, call);
 }
 /**
@@ -11067,23 +11087,23 @@ function registerFunctionToolsFor(server, options) {
 	});
 	if (declaredShape) {
 		registerPublicTool(server, toolName, description, declaredShape, async (args) => {
-			return jsonResult$1(await invokeFunction({
+			return httpResult(await invokeFunction({
 				invokeUrl: fn.invoke_url,
 				clientAuth,
 				body: args
 			}));
-		});
+		}, [], fn.annotations ?? void 0);
 		return;
 	}
 	registerPublicTool(server, toolName, description, GENERIC_FUNCTION_SHAPE, async (args) => {
 		const { body, query } = args;
-		return jsonResult$1(await invokeFunction({
+		return httpResult(await invokeFunction({
 			invokeUrl: fn.invoke_url,
 			clientAuth,
 			body,
 			...query ? { query } : {}
 		}));
-	});
+	}, [], fn.annotations ?? void 0);
 }
 //#endregion
 //#region src/auto/index.ts
@@ -11222,7 +11242,8 @@ async function registerAutoMcpTools(server, apiClient, options) {
 		fn,
 		clientAuth: {
 			apiKey: clientAuth.apiKey,
-			...clientAuth.sessionToken ? { sessionToken: clientAuth.sessionToken } : {}
+			...clientAuth.sessionToken ? { sessionToken: clientAuth.sessionToken } : {},
+			...clientAuth.groupContext ? { groupContext: clientAuth.groupContext } : {}
 		}
 	});
 	return {

package/dist/lib/tool-result.d.ts

@@ -34,6 +34,17 @@ export declare function jsonResult(payload: unknown): {
         text: string;
     }[];
 };
+/** Preserve an HTTP response wrapper while mapping failures to MCP isError. */
+export declare function httpResult(result: {
+    status: number;
+    body: unknown;
+}): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
 /**
  * Flatten an upstream HTTP response into the agent-facing tool payload.
  * Body fields are spread FIRST so a future top-level `status` key in
@@ -44,6 +55,7 @@ export declare function passthroughResult(result: {
     status: number;
     body: unknown;
 }): {
+    isError?: boolean | undefined;
     content: {
         type: "text";
         text: string;

package/dist/lib/with-pat.d.ts

@@ -41,6 +41,7 @@
  * the same call shape without the pat machinery.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z, type ZodRawShape } from 'zod';
 import type { ApiClient } from '../api-client.js';
 /** Wire-shape returned by an MCP tool handler. */
@@ -49,6 +50,8 @@ export interface ToolResult {
         type: 'text';
         text: string;
     }>;
+    /** MCP-native failure signal. Tool transports still return HTTP 200. */
+    isError?: boolean;
 }
 /** Context passed to handlers registered via `registerTool`. */
 export interface WithPatHandlerContext {
@@ -122,4 +125,6 @@ export declare function registerPublicTool<S extends ZodRawShape>(server: McpSer
  * warning per alias per process. No active auth-tool rename uses this
  * yet, but the parameter exists so future renames stay consistent.
  */
-aliases?: readonly string[]): void;
+aliases?: readonly string[], 
+/** Explicit app-declared safety hints; absent keeps conservative derivation. */
+annotations?: ToolAnnotations): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba-mcp",
-  "version": "4.0.8",
+  "version": "4.0.9",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"