@adminforth/mcp 1.3.0 → 1.4.0

package/dist/adminPanelConfirmation.d.ts

@@ -10,6 +10,9 @@ type ToolCallResult = {
 type AdminUserWithExecutor = AdminUser & {
     executedBy?: string;
 };
+type ConfirmationInput = IAdminForthEndpointHandlerInput & {
+    adminUser: AdminUser;
+};
 export type McpConnection = {
     id: string;
     name: string;
@@ -25,23 +28,28 @@ export declare class McpAdminPanelConfirmation {
     toolDefinition(): Tool;
     runUnverified<T>(extra: HttpExtra, callback: () => Promise<T>): Promise<unknown>;
     offer(output: unknown, connection: McpConnection, adminUser: AdminUserWithExecutor, path: string, args: Record<string, unknown>): ToolCallResult | undefined;
+    /** The user confirms the other pending actions of the same agent together with the one of the link. */
     describe(confirmationId: string, adminUser: AdminUser): {
         error: string;
     } | {
-        actionDescription: string | undefined;
         connectionName: string;
-        path: string;
-        arguments: Record<string, unknown>;
+        actions: {
+            id: string;
+            actionDescription: string | undefined;
+            path: string;
+            arguments: Record<string, unknown>;
+        }[];
     };
-    run(confirmationId: string, verificationResult: Record<string, unknown>, input: IAdminForthEndpointHandlerInput & {
-        adminUser: AdminUser;
-    }): Promise<unknown>;
-    decline(confirmationId: string, adminUser: AdminUser): {
+    run(ids: string[], verificationResult: Record<string, unknown>, input: ConfirmationInput): Promise<unknown>;
+    decline(ids: string[], adminUser: AdminUser): {
         ok: true;
     } | {
         error: string;
     };
     wait(confirmationId: string, connectionId: string): Promise<ToolCallResult>;
+    private execute;
+    /** All actions of a group belong to one user and run as one agent, so they can share one verification. */
+    private openGroup;
     private open;
 }
 export {};

package/dist/adminPanelConfirmation.js

@@ -1,9 +1,17 @@
 import { randomUUID } from 'node:crypto';
+import { MAX_ACTIONS_PER_CONFIRMATION } from './schemas/confirmation.js';
 import { adminApiPrefix, CONFIRMATION_PAGE_PATH } from './urls.js';
 export const WAIT_FOR_CONFIRMATION_TOOL_NAME = 'wait_for_confirmation';
 const CONFIRMATION_TTL_MS = 10 * 60 * 1000;
 const WAIT_MS = 50_000;
 const TWO_FACTOR_REQUIRED_CODE = 'TWO_FACTOR_REQUIRED';
+/** The verification is cached per user, so it must be checked as the same agent identity the actions run with. */
+function actingUser(adminUser, pending) {
+    return { ...adminUser, executedBy: pending.executedBy };
+}
+function actsAsOne(pending, other) {
+    return pending.connection.id === other.connection.id && pending.executedBy === other.executedBy;
+}
 export class McpAdminPanelConfirmation {
     adminforth;
     twoFactorsAuth;
@@ -37,9 +45,10 @@ export class McpAdminPanelConfirmation {
         const { code, actionDescription } = (output ?? {});
         if (code !== TWO_FACTOR_REQUIRED_CODE)
             return undefined;
-        const confirmationId = randomUUID();
+        const id = randomUUID();
         let resolve;
         const pending = {
+            id,
             userPk: adminUser.pk,
             connection,
             executedBy: adminUser.executedBy,
@@ -54,35 +63,99 @@ export class McpAdminPanelConfirmation {
             },
             result: new Promise((settle) => { resolve = settle; }),
         };
-        this.pending.set(confirmationId, pending);
-        setTimeout(() => this.pending.delete(confirmationId), CONFIRMATION_TTL_MS).unref();
+        this.pending.set(id, pending);
+        setTimeout(() => this.pending.delete(id), CONFIRMATION_TTL_MS).unref();
         return {
             output: {
-                error: `This action needs a two-factor verification, which only the admin panel can ask for. Show the user the confirmationUrl, then call ${WAIT_FOR_CONFIRMATION_TOOL_NAME} with the confirmationId: it returns the result once the user confirms or declines the action there.`,
-                confirmationUrl: `${this.pageUrl}?id=${confirmationId}`,
-                confirmationId,
+                error: `This action needs a two-factor verification, which only the admin panel can ask for. Show the user the confirmationUrl, then call ${WAIT_FOR_CONFIRMATION_TOOL_NAME} with the confirmationId: it returns the result once the user confirms or declines the action there. A link confirms up to ${MAX_ACTIONS_PER_CONFIRMATION} pending actions of this connection at once, so after several such actions show the user only one link.`,
+                confirmationUrl: `${this.pageUrl}?id=${id}`,
+                confirmationId: id,
             },
             isError: true,
         };
     }
+    /** The user confirms the other pending actions of the same agent together with the one of the link. */
     describe(confirmationId, adminUser) {
         const pending = this.open(confirmationId, adminUser);
         if ('error' in pending)
             return pending;
+        const others = [...this.pending.values()].filter((other) => other !== pending
+            && actsAsOne(other, pending)
+            && !('error' in this.open(other.id, adminUser)));
         return {
-            actionDescription: pending.actionDescription,
             connectionName: pending.connection.name,
-            path: pending.path,
-            arguments: pending.arguments,
+            actions: [pending, ...others].slice(0, MAX_ACTIONS_PER_CONFIRMATION).map((action) => ({
+                id: action.id,
+                actionDescription: action.actionDescription,
+                path: action.path,
+                arguments: action.arguments,
+            })),
         };
     }
-    async run(confirmationId, verificationResult, input) {
-        const pending = this.open(confirmationId, input.adminUser);
-        if ('error' in pending) {
+    async run(ids, verificationResult, input) {
+        const group = this.openGroup(ids, input.adminUser);
+        if ('error' in group) {
             input.response.setStatus(400);
-            return pending;
+            return group;
+        }
+        group.forEach((pending) => { pending.running = true; });
+        const extra = {
+            body: {},
+            query: {},
+            headers: input.headers,
+            cookies: input.cookies,
+            requestUrl: input.requestUrl,
+            response: input.response,
+        };
+        const failAll = (output) => group.map(() => ({ output: { ok: false, ...output }, isError: true }));
+        let results;
+        try {
+            const outcome = await this.twoFactorsAuth.withVerificationContext(verificationResult, extra, async () => {
+                // A passkey can be used only once: the actions reuse this check, and a failed one ends the context with its code.
+                await this.twoFactorsAuth.verifyAuto(actingUser(input.adminUser, group[0]));
+                const results = [];
+                for (const pending of group)
+                    results.push(await this.execute(pending, verificationResult, input));
+                return results;
+            });
+            results = Array.isArray(outcome) ? outcome : failAll(outcome);
+        }
+        catch (error) {
+            results = failAll({ code: 'MCP_CONFIRMATION_FAILED', error: error instanceof Error ? error.message : String(error) });
+        }
+        group.forEach((pending, index) => {
+            pending.running = false;
+            pending.settle(results[index]);
+        });
+        return { results: group.map((pending, index) => ({ id: pending.id, ...results[index] })) };
+    }
+    decline(ids, adminUser) {
+        const group = this.openGroup(ids, adminUser);
+        if ('error' in group)
+            return group;
+        group.forEach((pending) => pending.settle({ output: { error: 'The user declined the action in the admin panel.' }, isError: true }));
+        return { ok: true };
+    }
+    async wait(confirmationId, connectionId) {
+        const pending = this.pending.get(confirmationId);
+        if (pending?.connection.id !== connectionId) {
+            return { output: { error: 'Unknown or expired confirmationId.' }, isError: true };
+        }
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({
+                output: { status: 'waiting', note: `The user has not confirmed or declined the action yet. Call ${WAIT_FOR_CONFIRMATION_TOOL_NAME} again to keep waiting.` },
+                isError: false,
+            }), WAIT_MS);
+        });
+        try {
+            return await Promise.race([pending.result, timeout]);
         }
-        pending.running = true;
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async execute(pending, verificationResult, input) {
         const controller = new AbortController();
         const abort = () => controller.abort();
         input.abortSignal?.addEventListener('abort', abort);
@@ -110,14 +183,14 @@ export class McpAdminPanelConfirmation {
                 requestUrl: schema.path,
                 response,
             };
-            const execution = this.twoFactorsAuth.withVerificationContext(verificationResult, request, async () => schema.handler({
+            const execution = schema.handler({
                 ...request,
-                adminUser: { ...input.adminUser, executedBy: pending.executedBy },
+                adminUser: actingUser(input.adminUser, pending),
                 abortSignal: controller.signal,
                 tr: input.tr,
                 _raw_express_req: undefined,
                 _raw_express_res: undefined,
-            }));
+            });
             const timeout = new Promise((resolve) => {
                 timer = setTimeout(() => {
                     controller.abort();
@@ -134,36 +207,22 @@ export class McpAdminPanelConfirmation {
         finally {
             clearTimeout(timer);
             input.abortSignal?.removeEventListener('abort', abort);
-            pending.running = false;
         }
-        pending.settle({ output, isError: responseStatus >= 400 || Boolean(output && typeof output === 'object' && ('error' in output || output.ok === false)) });
-        return output;
-    }
-    decline(confirmationId, adminUser) {
-        const pending = this.open(confirmationId, adminUser);
-        if ('error' in pending)
-            return pending;
-        pending.settle({ output: { error: 'The user declined the action in the admin panel.' }, isError: true });
-        return { ok: true };
+        return { output, isError: responseStatus >= 400 || Boolean(output && typeof output === 'object' && ('error' in output || output.ok === false)) };
     }
-    async wait(confirmationId, connectionId) {
-        const pending = this.pending.get(confirmationId);
-        if (pending?.connection.id !== connectionId) {
-            return { output: { error: 'Unknown or expired confirmationId.' }, isError: true };
-        }
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(() => resolve({
-                output: { status: 'waiting', note: `The user has not confirmed or declined the action yet. Call ${WAIT_FOR_CONFIRMATION_TOOL_NAME} again to keep waiting.` },
-                isError: false,
-            }), WAIT_MS);
-        });
-        try {
-            return await Promise.race([pending.result, timeout]);
-        }
-        finally {
-            clearTimeout(timer);
+    /** All actions of a group belong to one user and run as one agent, so they can share one verification. */
+    openGroup(ids, adminUser) {
+        const group = [];
+        for (const id of new Set(ids)) {
+            const pending = this.open(id, adminUser);
+            if ('error' in pending)
+                return pending;
+            if (group.length && !actsAsOne(pending, group[0])) {
+                return { error: 'These actions were requested by different MCP clients.' };
+            }
+            group.push(pending);
         }
+        return group;
     }
     open(confirmationId, adminUser) {
         const pending = this.pending.get(confirmationId);

package/dist/custom/McpConfirm.vue

@@ -5,18 +5,17 @@
         <h1 class="text-xl font-medium text-gray-900 dark:text-white">{{ title }}</h1>
         <p class="mt-3 text-sm text-gray-600 dark:text-gray-300">
           <b>{{ pending.connectionName }}</b>
-          {{ pending.actionDescription
-            ? $t('asks to run this action on your behalf.')
-            : $t('asks to run {path} on your behalf with these arguments:', { path: pending.path }) }}
+          {{ $t('asks to run this action on your behalf. | asks to run these actions on your behalf.', pending.actions.length) }}
         </p>
-        <pre v-if="!pending.actionDescription" class="mt-3 max-h-80 overflow-auto rounded-default bg-gray-100 p-3 text-xs text-gray-800 dark:bg-gray-900 dark:text-gray-100">{{ argumentsText }}</pre>
-        <p v-if="resultMessage" class="mt-4 text-sm font-medium" :class="failed ? 'text-red-700 dark:text-red-300' : 'text-green-700 dark:text-green-300'">
-          {{ resultMessage }}
-        </p>
-        <div v-if="!finished" class="mt-6 flex justify-end gap-2">
-          <Button variant="secondary" :disabled="running" @click="decline">{{ $t('Decline') }}</Button>
-          <Button :loader="running" :disabled="running" @click="confirm">{{ $t('Confirm') }}</Button>
-        </div>
+        <template v-if="resultMessage">
+          <p class="mt-4 text-sm font-medium" :class="failed ? 'text-red-700 dark:text-red-300' : 'text-green-700 dark:text-green-300'">
+            {{ resultMessage }}
+          </p>
+          <ul v-if="failedErrors.length" class="mt-2 list-disc space-y-1 pl-5 text-sm text-red-700 dark:text-red-300">
+            <li v-for="(failedError, i) in failedErrors" :key="i">{{ failedError }}</li>
+          </ul>
+        </template>
+        <Spinner v-else class="mx-auto mt-4 h-8 w-8" />
       </template>
       <template v-else-if="error">
         <h1 class="text-xl font-medium text-gray-900 dark:text-white">{{ $t('Cannot run the action') }}</h1>
@@ -31,67 +30,93 @@
 import { computed, onMounted, ref } from 'vue';
 import { useRoute } from 'vue-router';
 import { useI18n } from 'vue-i18n';
-import { Button, Spinner } from '@/afcl';
+import { Spinner } from '@/afcl';
 import { callAdminForthApi } from '@/utils';
 
-type PendingConfirmation = {
+type PendingAction = {
+  id: string;
   actionDescription?: string;
-  connectionName: string;
   path: string;
   arguments: Record<string, unknown>;
 };
+type PendingConfirmation = {
+  connectionName: string;
+  actions: PendingAction[];
+};
+type ActionResult = { id: string; output: { error?: string }; isError: boolean };
 const { t } = useI18n();
 const route = useRoute();
-const id = String(route.query.id);
 const pending = ref<PendingConfirmation | null>(null);
 const error = ref('');
-const running = ref(false);
-const finished = ref(false);
 const failed = ref(false);
 const resultMessage = ref('');
-const argumentsText = computed(() => JSON.stringify(pending.value?.arguments, null, 2));
-const title = computed(() => pending.value?.actionDescription ?? t('Confirm the action of your agent'));
+const failedErrors = ref<string[]>([]);
+const ids = computed(() => pending.value!.actions.map((action) => action.id));
+const title = computed(() => {
+  const actions = pending.value!.actions;
+  return actions.length > 1
+    ? t('Confirm {count} actions of your agent', { count: actions.length })
+    : actions[0].actionDescription ?? t('Confirm the action of your agent');
+});
+// Without a description of an action, the modal shows the raw call of the agent instead.
+const modalContent = computed(() => {
+  const actions = pending.value!.actions;
+  if (actions.length > 1) {
+    return { items: actions.map((action) => action.actionDescription ?? `${action.path} ${JSON.stringify(action.arguments)}`) };
+  }
+  const [action] = actions;
+  return action.actionDescription ? {} : { details: `${action.path}\n${JSON.stringify(action.arguments, null, 2)}` };
+});
 
 onMounted(async () => {
-  const response = await callAdminForthApi({ method: 'GET', path: `/mcp/confirmation?id=${encodeURIComponent(id)}` });
+  const response = await callAdminForthApi({ method: 'GET', path: `/mcp/confirmation?id=${encodeURIComponent(String(route.query.id))}` });
   if (response?.error) error.value = response.error;
-  else if (response) pending.value = response;
+  else if (response) {
+    pending.value = response;
+    await confirm();
+  }
 });
 
 async function confirm() {
-  running.value = true;
   try {
     let verificationResult;
     try {
-      verificationResult = await (window as any).adminforthTwoFaModal.get2FaConfirmationResult(title.value);
+      verificationResult = await (window as any).adminforthTwoFaModal.get2FaConfirmationResult(title.value, undefined, modalContent.value);
     } catch (error) {
       await decline();
-      if (error !== 'Cancel' && finished.value) {
+      if (error !== 'Cancel' && !failed.value) {
         failed.value = true;
         resultMessage.value = error instanceof Error ? error.message : String(error);
       }
       return;
     }
-    const response = await callAdminForthApi({ method: 'POST', path: '/mcp/confirmation/run', body: { id, verificationResult } });
-    failed.value = !response || Boolean(response.error) || response.ok === false;
-    finished.value = true;
-    resultMessage.value = failed.value
-      ? response?.error ?? t('The action failed.')
-      : t('Done. Your agent got the result. You can close this page.');
-  } catch (error) {
-    if (error !== 'Cancel') {
+    const response = await callAdminForthApi({ method: 'POST', path: '/mcp/confirmation/run', body: { ids: ids.value, verificationResult } });
+    if (!response || response.error) {
       failed.value = true;
-      resultMessage.value = error instanceof Error ? error.message : String(error);
+      resultMessage.value = response?.error ?? t('The action failed.');
+      return;
+    }
+    const errors = (response.results as ActionResult[])
+      .filter((result) => result.isError)
+      .map((result) => result.output?.error ?? t('The action failed.'));
+    failed.value = errors.length > 0;
+    if (!errors.length) {
+      resultMessage.value = t('Done. Your agent got the result. You can close this page.');
+    } else if (ids.value.length === 1) {
+      resultMessage.value = errors[0];
+    } else {
+      resultMessage.value = t('{failed} of {count} actions failed:', { failed: errors.length, count: ids.value.length });
+      failedErrors.value = errors;
     }
-  } finally {
-    running.value = false;
+  } catch (error) {
+    failed.value = true;
+    resultMessage.value = error instanceof Error ? error.message : String(error);
   }
 }
 
 async function decline() {
-  const response = await callAdminForthApi({ method: 'POST', path: '/mcp/confirmation/decline', body: { id } });
+  const response = await callAdminForthApi({ method: 'POST', path: '/mcp/confirmation/decline', body: { ids: ids.value } });
   failed.value = Boolean(response?.error);
-  finished.value = !failed.value;
   resultMessage.value = response?.error ?? t('Declined. Your agent was told.');
 }
 </script>

package/dist/endpoints/confirmation.js

@@ -19,7 +19,7 @@ export function registerConfirmationEndpoints(server, confirmation) {
         request_schema: runConfirmationBodySchema,
         handler: async (input) => {
             const body = input.body;
-            return confirmation.run(body.id, body.verificationResult, input);
+            return confirmation.run(body.ids, body.verificationResult, input);
         },
     });
     server.endpoint({
@@ -29,7 +29,7 @@ export function registerConfirmationEndpoints(server, confirmation) {
         request_schema: declineConfirmationBodySchema,
         handler: async (input) => {
             const body = input.body;
-            const result = confirmation.decline(body.id, input.adminUser);
+            const result = confirmation.decline(body.ids, input.adminUser);
             if ('error' in result)
                 input.response.setStatus(400);
             return result;

package/dist/schemas/confirmation.d.ts

@@ -1,18 +1,20 @@
 import { z } from 'zod';
+/** One confirmation in the admin panel covers at most this many pending actions, all shown to the user. */
+export declare const MAX_ACTIONS_PER_CONFIRMATION = 20;
 declare const runConfirmationBody: z.ZodObject<{
-    id: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
     verificationResult: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
 declare const declineConfirmationBody: z.ZodObject<{
-    id: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export type RunConfirmationBody = z.infer<typeof runConfirmationBody>;
 export type DeclineConfirmationBody = z.infer<typeof declineConfirmationBody>;
 export declare const runConfirmationBodySchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
-    id: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
     verificationResult: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>>;
 export declare const declineConfirmationBodySchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
-    id: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
 }, z.core.$strip>>;
 export {};

package/dist/schemas/confirmation.js

@@ -1,9 +1,12 @@
 import { z } from 'zod';
+/** One confirmation in the admin panel covers at most this many pending actions, all shown to the user. */
+export const MAX_ACTIONS_PER_CONFIRMATION = 20;
+const confirmationIds = z.array(z.string()).min(1).max(MAX_ACTIONS_PER_CONFIRMATION);
 const runConfirmationBody = z.object({
-    id: z.string(),
+    ids: confirmationIds,
     verificationResult: z.record(z.string(), z.unknown()),
 });
-const declineConfirmationBody = z.object({ id: z.string() });
+const declineConfirmationBody = z.object({ ids: confirmationIds });
 // Convert with the same Zod version that created the schema. AdminForth may use another version.
 export const runConfirmationBodySchema = z.toJSONSchema(runConfirmationBody, { target: 'draft-07' });
 export const declineConfirmationBodySchema = z.toJSONSchema(declineConfirmationBody, { target: 'draft-07' });

package/dist/twoFactorContext.d.ts

@@ -1,6 +1,7 @@
-import type { HttpExtra, IAdminForth } from 'adminforth';
+import type { AdminUser, HttpExtra, IAdminForth } from 'adminforth';
 export interface ContextualTwoFactorsAuth {
     withVerificationContext<T>(verificationResult: Record<string, unknown> | undefined, extra: HttpExtra, callback: () => Promise<T>): Promise<unknown>;
+    verifyAuto(adminUser: AdminUser, actionDescription?: string): Promise<unknown>;
 }
 /** Only newer 2FA plugins can verify verifyAuto calls within an external request. */
 export declare function findContextualTwoFactorsAuth(adminforth: IAdminForth): ContextualTwoFactorsAuth | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Expose AdminForth APIs as an authenticated MCP server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",