@adminforth/mcp 1.1.2 → 1.3.0

package/README.md

@@ -1,8 +1,8 @@
 # AdminForth MCP
 
-`@adminforth/mcp` exposes the AdminForth API tool surface as an authenticated remote MCP server. Each MCP auth secret belongs to one AdminForth user, so resource permissions and hooks are preserved.
+`@adminforth/mcp` exposes the AdminForth API tool surface as an authenticated remote MCP server. Agents connect through OAuth sign-in or with an auth secret, and act as the AdminForth user who connected them, so resource permissions and hooks are preserved.
 
-The server identifies itself to agents using the configured AdminForth `brandName`. An optional `adminPanelOrigin` can distinguish deployments further; the plugin combines it with the AdminForth `baseUrl`.
+The required `adminPanelOrigin` is the public origin agents connect to; the plugin combines it with the AdminForth `baseUrl` to build the MCP URL and the OAuth issuer.
 
 > **Security:** an MCP auth secret carries the full permissions of the user who created it. An agent
 > holding it can do everything that user can do in the admin panel, including destructive actions and

package/dist/adminPanelConfirmation.d.ts

@@ -0,0 +1,47 @@
+import type { Tool } from '@modelcontextprotocol/server';
+import type { AdminUser, HttpExtra, IAdminForth, IAdminForthEndpointHandlerInput } from 'adminforth';
+import type { ContextualTwoFactorsAuth } from './twoFactorContext.js';
+import { type McpUrls } from './urls.js';
+export declare const WAIT_FOR_CONFIRMATION_TOOL_NAME = "wait_for_confirmation";
+type ToolCallResult = {
+    output: unknown;
+    isError: boolean;
+};
+type AdminUserWithExecutor = AdminUser & {
+    executedBy?: string;
+};
+export type McpConnection = {
+    id: string;
+    name: string;
+};
+export declare class McpAdminPanelConfirmation {
+    private readonly adminforth;
+    private readonly twoFactorsAuth;
+    private readonly executionTimeoutMs;
+    private readonly pageUrl;
+    private readonly apiPrefix;
+    private readonly pending;
+    constructor(adminforth: IAdminForth, urls: McpUrls, twoFactorsAuth: ContextualTwoFactorsAuth, executionTimeoutMs: number);
+    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;
+    describe(confirmationId: string, adminUser: AdminUser): {
+        error: string;
+    } | {
+        actionDescription: string | undefined;
+        connectionName: string;
+        path: string;
+        arguments: Record<string, unknown>;
+    };
+    run(confirmationId: string, verificationResult: Record<string, unknown>, input: IAdminForthEndpointHandlerInput & {
+        adminUser: AdminUser;
+    }): Promise<unknown>;
+    decline(confirmationId: string, adminUser: AdminUser): {
+        ok: true;
+    } | {
+        error: string;
+    };
+    wait(confirmationId: string, connectionId: string): Promise<ToolCallResult>;
+    private open;
+}
+export {};

package/dist/adminPanelConfirmation.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+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';
+export class McpAdminPanelConfirmation {
+    adminforth;
+    twoFactorsAuth;
+    executionTimeoutMs;
+    pageUrl;
+    apiPrefix;
+    pending = new Map();
+    constructor(adminforth, urls, twoFactorsAuth, executionTimeoutMs) {
+        this.adminforth = adminforth;
+        this.twoFactorsAuth = twoFactorsAuth;
+        this.executionTimeoutMs = executionTimeoutMs;
+        this.pageUrl = new URL(`${adminforth.config.baseUrl}${CONFIRMATION_PAGE_PATH}`, urls.apiUrl).href;
+        this.apiPrefix = adminApiPrefix(adminforth.config.baseUrl);
+    }
+    toolDefinition() {
+        return {
+            name: WAIT_FOR_CONFIRMATION_TOOL_NAME,
+            description: 'Waits until the user confirms or declines in the admin panel an action that returned a confirmationUrl, and returns the result of the action. Returns a waiting status after about a minute; call it again to keep waiting.',
+            inputSchema: {
+                type: 'object',
+                required: ['confirmationId'],
+                properties: { confirmationId: { type: 'string' } },
+            },
+            annotations: { readOnlyHint: true },
+        };
+    }
+    runUnverified(extra, callback) {
+        return this.twoFactorsAuth.withVerificationContext(undefined, extra, callback);
+    }
+    offer(output, connection, adminUser, path, args) {
+        const { code, actionDescription } = (output ?? {});
+        if (code !== TWO_FACTOR_REQUIRED_CODE)
+            return undefined;
+        const confirmationId = randomUUID();
+        let resolve;
+        const pending = {
+            userPk: adminUser.pk,
+            connection,
+            executedBy: adminUser.executedBy,
+            actionDescription,
+            path,
+            arguments: args,
+            settled: false,
+            running: false,
+            settle: (result) => {
+                pending.settled = true;
+                resolve(result);
+            },
+            result: new Promise((settle) => { resolve = settle; }),
+        };
+        this.pending.set(confirmationId, pending);
+        setTimeout(() => this.pending.delete(confirmationId), 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,
+            },
+            isError: true,
+        };
+    }
+    describe(confirmationId, adminUser) {
+        const pending = this.open(confirmationId, adminUser);
+        if ('error' in pending)
+            return pending;
+        return {
+            actionDescription: pending.actionDescription,
+            connectionName: pending.connection.name,
+            path: pending.path,
+            arguments: pending.arguments,
+        };
+    }
+    async run(confirmationId, verificationResult, input) {
+        const pending = this.open(confirmationId, input.adminUser);
+        if ('error' in pending) {
+            input.response.setStatus(400);
+            return pending;
+        }
+        pending.running = true;
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        input.abortSignal?.addEventListener('abort', abort);
+        let timer;
+        let output;
+        let responseStatus = 200;
+        const response = {
+            setHeader: (key, value) => input.response.setHeader(key, value),
+            setStatus: (status, message) => {
+                responseStatus = status;
+                input.response.setStatus(status, message);
+            },
+            blobStream: () => input.response.blobStream(),
+        };
+        try {
+            const schema = this.adminforth.openApi.registeredSchemas.find((candidate) => (candidate.path === `${this.apiPrefix}${pending.path}`));
+            const hasBody = !['GET', 'HEAD'].includes(schema.method.toUpperCase());
+            const extra = pending.arguments.extra;
+            const args = { ...pending.arguments, extra: { ...extra, verificationResult } };
+            const request = {
+                body: hasBody ? args : {},
+                query: hasBody ? {} : args,
+                headers: input.headers,
+                cookies: input.cookies,
+                requestUrl: schema.path,
+                response,
+            };
+            const execution = this.twoFactorsAuth.withVerificationContext(verificationResult, request, async () => schema.handler({
+                ...request,
+                adminUser: { ...input.adminUser, executedBy: pending.executedBy },
+                abortSignal: controller.signal,
+                tr: input.tr,
+                _raw_express_req: undefined,
+                _raw_express_res: undefined,
+            }));
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    resolve({ ok: false, code: 'MCP_CONFIRMATION_TIMEOUT', error: `Action timed out after ${this.executionTimeoutMs / 1000} seconds. It may still complete; check the result before trying again.` });
+                }, this.executionTimeoutMs);
+            });
+            output = await Promise.race([execution, timeout]);
+            if (output === undefined)
+                output = { ok: false, error: 'Action handler completed without returning a response.' };
+        }
+        catch (error) {
+            output = { ok: false, code: 'MCP_CONFIRMATION_FAILED', error: error instanceof Error ? error.message : String(error) };
+        }
+        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 };
+    }
+    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);
+        }
+    }
+    open(confirmationId, adminUser) {
+        const pending = this.pending.get(confirmationId);
+        if (!pending)
+            return { error: 'This confirmation link is invalid or expired. Ask your agent for a new one.' };
+        if (pending.userPk !== adminUser.pk)
+            return { error: 'This confirmation link was created for another user.' };
+        if (pending.running)
+            return { error: 'This action is already running.' };
+        if (pending.settled)
+            return { error: 'This action was already confirmed or declined.' };
+        return pending;
+    }
+}

package/dist/apiTools.d.ts

@@ -1,24 +1,21 @@
+import type { Tool } from '@modelcontextprotocol/server';
+import type { McpAdminPanelConfirmation, McpConnection } from './adminPanelConfirmation.js';
 import type { McpPageSize } from './types.js';
 import type { AdminUser, IAdminForth } from 'adminforth';
-export interface McpToolDefinition {
-    name: string;
-    description?: string;
-    inputSchema: Record<string, unknown>;
-    annotations?: {
-        readOnlyHint?: boolean;
-        destructiveHint?: boolean;
-    };
-}
 export declare class AdminForthApiTools {
     private readonly adminforth;
     private readonly hiddenResourceIds;
     private readonly toolTimeoutMs;
-    constructor(adminforth: IAdminForth, hiddenResourceIds: ReadonlySet<string>, pageSize: McpPageSize, toolTimeoutMs: number);
+    private readonly adminPanelConfirmation;
+    constructor(adminforth: IAdminForth, hiddenResourceIds: ReadonlySet<string>, pageSize: McpPageSize, toolTimeoutMs: number, adminPanelConfirmation: McpAdminPanelConfirmation | undefined);
     private readonly toolOverrides;
-    private schemas;
+    private fullCatalog?;
+    private readOnlyCatalog?;
+    private catalog;
+    private buildCatalog;
     private description;
     private withTimeout;
-    list(readOnly: boolean): McpToolDefinition[];
+    list(readOnly: boolean): Tool[];
     call(params: {
         name: string;
         arguments?: Record<string, unknown>;
@@ -27,6 +24,7 @@ export declare class AdminForthApiTools {
         requestUrl: string;
         abortSignal: AbortSignal;
         readOnly: boolean;
+        connection: McpConnection;
     }): Promise<{
         output: unknown;
         isError: boolean;

package/dist/apiTools.js

@@ -1,7 +1,9 @@
-import { compactInputSchema } from './inputSchema.js';
+import { compactInputSchema } from './compactInputSchema.js';
 import { adminApiPrefix } from './urls.js';
 import { AdminForthDataTypes } from 'adminforth';
 const METHODS_WITHOUT_REQUEST_BODY = new Set(['GET', 'HEAD']);
+const NON_TOOL_NAME_CHARACTER_RE = /[^a-zA-Z0-9_]+/g;
+const EDGE_UNDERSCORE_RE = /^_+|_+$/g;
 // Milliseconds cost tokens on every datetime value and are never needed to answer the user.
 const ISO_MILLISECONDS_RE = /\.\d+(?=Z$)/;
 const TOOL_TIMEOUT = Symbol('TOOL_TIMEOUT');
@@ -44,15 +46,7 @@ function isRegisteredToolSchema(schema) {
     return typeof schema.handler === 'function' && !schema.agent?.hiddenFromAgents;
 }
 function endpointPathToToolName(path) {
-    return path
-        .replace(/^\/+/, '')
-        .replace(/[^a-zA-Z0-9_]+/g, '_')
-        .replace(/^_+|_+$/g, '');
-}
-function stripAdminApiPrefix(path, adminforth) {
-    const apiPrefix = adminApiPrefix(adminforth.config.baseUrl);
-    const strippedPath = path.startsWith(apiPrefix) ? path.slice(apiPrefix.length) : path;
-    return strippedPath.startsWith('/') ? strippedPath : `/${strippedPath}`;
+    return path.replace(NON_TOOL_NAME_CHARACTER_RE, '_').replace(EDGE_UNDERSCORE_RE, '');
 }
 // Drops frontend-only parts of the get_resource response that are useless for MCP clients and only waste their context.
 // Copies instead of deleting: the response shares nested objects with the AdminForth config.
@@ -167,23 +161,46 @@ export class AdminForthApiTools {
     adminforth;
     hiddenResourceIds;
     toolTimeoutMs;
-    constructor(adminforth, hiddenResourceIds, pageSize, toolTimeoutMs) {
+    adminPanelConfirmation;
+    constructor(adminforth, hiddenResourceIds, pageSize, toolTimeoutMs, adminPanelConfirmation) {
         this.adminforth = adminforth;
         this.hiddenResourceIds = hiddenResourceIds;
         this.toolTimeoutMs = toolTimeoutMs;
+        this.adminPanelConfirmation = adminPanelConfirmation;
         this.toolOverrides = createToolOverrides(pageSize, adminforth);
     }
     toolOverrides;
-    schemas(readOnly) {
-        const schemas = new Map();
-        for (const schema of this.adminforth.openApi.registeredSchemas) {
-            if (!isRegisteredToolSchema(schema))
-                continue;
-            if (readOnly && !schema.agent?.onlyReadsData)
-                continue;
-            schemas.set(endpointPathToToolName(stripAdminApiPrefix(schema.path, this.adminforth)), schema);
-        }
-        return schemas;
+    fullCatalog;
+    readOnlyCatalog;
+    catalog(readOnly) {
+        return readOnly
+            ? (this.readOnlyCatalog ??= this.buildCatalog(true))
+            : (this.fullCatalog ??= this.buildCatalog(false));
+    }
+    buildCatalog(readOnly) {
+        const apiPrefix = adminApiPrefix(this.adminforth.config.baseUrl);
+        const schemas = new Map(this.adminforth.openApi.registeredSchemas
+            .filter(isRegisteredToolSchema)
+            .filter((schema) => !readOnly || schema.agent?.onlyReadsData)
+            .map((schema) => [endpointPathToToolName(schema.path.slice(apiPrefix.length)), schema]));
+        const tools = Array.from(schemas.entries())
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, schema]) => ({
+            name,
+            ...this.description(name, schema),
+            inputSchema: compactInputSchema(overrideInputSchema(schema.request_schema ?? {
+                type: 'object',
+                properties: {},
+                additionalProperties: true,
+            }, this.toolOverrides[name])),
+            ...(schema.agent?.onlyReadsData && {
+                annotations: { readOnlyHint: true },
+            }),
+            ...(schema.agent?.requiresHumanApproval && {
+                annotations: { destructiveHint: true },
+            }),
+        }));
+        return { schemas, tools };
     }
     description(name, schema) {
         const description = [
@@ -215,26 +232,10 @@ export class AdminForthApiTools {
         }
     }
     list(readOnly) {
-        return Array.from(this.schemas(readOnly).entries())
-            .sort(([left], [right]) => left.localeCompare(right))
-            .map(([name, schema]) => ({
-            name,
-            ...this.description(name, schema),
-            inputSchema: compactInputSchema(overrideInputSchema(schema.request_schema ?? {
-                type: 'object',
-                properties: {},
-                additionalProperties: true,
-            }, this.toolOverrides[name])),
-            ...(schema.agent?.onlyReadsData && {
-                annotations: { readOnlyHint: true },
-            }),
-            ...(schema.agent?.requiresHumanApproval && {
-                annotations: { destructiveHint: true },
-            }),
-        }));
+        return this.catalog(readOnly).tools;
     }
     async call(params) {
-        const schema = this.schemas(params.readOnly).get(params.name);
+        const schema = this.catalog(params.readOnly).schemas.get(params.name);
         if (!schema) {
             return { output: { error: `Unknown tool: ${params.name}` }, isError: true };
         }
@@ -261,20 +262,25 @@ export class AdminForthApiTools {
             };
         }
         const response = createDirectResponse();
-        const language = String(params.headers['accept-language'] ?? 'en');
-        const output = await this.withTimeout(params.abortSignal, (abortSignal) => schema.handler({
+        const request = {
             body,
-            query,
+            query: query,
             headers: params.headers,
             cookies: [],
-            adminUser: params.adminUser,
-            response,
             requestUrl: params.requestUrl,
-            abortSignal,
-            _raw_express_req: undefined,
-            _raw_express_res: undefined,
-            tr: (message, category, translationParams, pluralizationNumber) => this.adminforth.tr(message, category, language, translationParams, pluralizationNumber),
-        }));
+            response,
+        };
+        const output = await this.withTimeout(params.abortSignal, (abortSignal) => {
+            const execute = async () => schema.handler({
+                ...request,
+                adminUser: params.adminUser,
+                abortSignal,
+                _raw_express_req: undefined,
+                _raw_express_res: undefined,
+                tr: (message, category, translationParams, pluralizationNumber) => this.adminforth.tr(message, category, params.headers['accept-language'], translationParams, pluralizationNumber),
+            });
+            return this.adminPanelConfirmation ? this.adminPanelConfirmation.runUnverified(request, execute) : execute();
+        });
         if (output === TOOL_TIMEOUT) {
             return {
                 output: {
@@ -295,6 +301,9 @@ export class AdminForthApiTools {
                 isError: true,
             };
         }
+        const confirmation = this.adminPanelConfirmation?.offer(output, params.connection, params.adminUser, schema.path.slice(adminApiPrefix(this.adminforth.config.baseUrl).length), handlerArguments);
+        if (confirmation)
+            return confirmation;
         const responseValidation = this.adminforth.openApi.validateResponseSchema(schema, output);
         if (!responseValidation.valid) {
             return {

package/dist/authSecretStore.d.ts

@@ -1,5 +1,6 @@
 import { type AdminUser, type HttpExtra, type IAdminForth } from 'adminforth';
-import type { McpAuthSecretResourceOptions, McpClientInfo } from './types.js';
+import type { AuthSecretRepository } from './repositories/authSecret.js';
+import type { McpClientInfo } from './types.js';
 export declare const SECRET_PREFIX = "afmcp_";
 type AdminUserWithExecutor = AdminUser & {
     executedBy?: string;
@@ -20,18 +21,17 @@ export interface AuthenticatedMcpSecret {
 }
 export declare class McpAuthSecretStore {
     private readonly adminforth;
-    private readonly options;
-    private readonly resource;
+    private readonly repository;
     private readonly refreshLock;
-    constructor(adminforth: IAdminForth, options: McpAuthSecretResourceOptions);
+    constructor(adminforth: IAdminForth, repository: AuthSecretRepository);
     list(adminUser: AdminUser): Promise<{
-        id: any;
-        name: any;
-        createdAt: any;
-        lastUsedAt: any;
+        id: string;
+        name: string;
+        createdAt: string;
+        lastUsedAt: string | null;
         lastUsedByAgent: McpClientInfo | null;
-        readOnly: any;
-        oauthClientId: any;
+        readOnly: boolean;
+        oauthClientId: string | null;
     }[]>;
     create(name: string, readOnly: boolean, adminUser: AdminUser, extra: HttpExtra): Promise<{
         error: string;
@@ -59,8 +59,6 @@ export declare class McpAuthSecretStore {
     rotateRefreshToken(grantId: string, refreshToken: string, clientId: string, newRefreshToken: string): Promise<string | null>;
     /** Access tokens are checked against their grant on every request, so revoking the grant applies at once. */
     authenticateOAuthGrant(grantId: string, userId: string): Promise<AuthenticatedMcpSecret | null>;
-    /** The OAuth grant methods are called only when OAuth is enabled, which requires this field. */
-    private get oauthClientIdField();
     private loadAdminUser;
     private toAuthenticated;
     touch(recordId: string, client: McpClientInfo): void;