@adminforth/mcp 1.0.4 → 1.1.1

package/dist/index.js

@@ -1,11 +1,43 @@
-import { AdminForthPlugin, } from 'adminforth';
+import { AdminForthPlugin, logger, } from 'adminforth';
 import { AdminForthApiTools } from './apiTools.js';
 import { formatMcpExecutedBy, readMcpClient, UNKNOWN_CLIENT } from './clientInfo.js';
-import { createMcpServerPresentation, handleMcpProtocol, } from './mcpProtocol.js';
-import { McpAuthSecretStore } from './authSecretStore.js';
-const BEARER_SECRET_RE = /^Bearer (afmcp_[A-Za-z0-9_-]+)$/i;
-const MCP_PATH = '/mcp';
+import { createMcpServerPresentation, handleMcpProtocol } from './mcpProtocol.js';
+import { McpAuthSecretStore, SECRET_PREFIX } from './authSecretStore.js';
+import { CONSENT_PAGE_PATH, McpOAuth } from './oauth.js';
+import { isLoopbackUrl } from './oauthClientMetadata.js';
+import { setupOAuthEndpoints } from './oauthEndpoints.js';
+import { FETCH_SKILL_TOOL_NAME, McpSkills } from './skills.js';
+import { adminApiPrefix, createMcpUrls, MCP_PATH } from './urls.js';
+const BEARER_TOKEN_RE = /^Bearer (\S+)$/i;
 const CREDENTIAL_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie']);
+const DEFAULT_PAGE_SIZE = 10;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_TOOL_TIMEOUT_MS = 15_000;
+const DEFAULT_TOOL_CALLS_PER_REQUEST = 10;
+const RESOURCES_LIST_RESPONSE_SCHEMA = {
+    type: 'object',
+    required: ['resources'],
+    properties: {
+        resources: {
+            type: 'array',
+            description: 'Every resource of the admin panel. Access is checked when a resource is used, so the user may still be forbidden to list, show, create, edit or delete records of a listed resource.',
+            items: {
+                type: 'object',
+                required: ['resourceId', 'label'],
+                properties: {
+                    resourceId: {
+                        type: 'string',
+                        description: 'Resource identifier. Pass it as resourceId to get_resource, get_resource_data, aggregate, create_record, update_record, delete_record and other resource tools. Call get_resource with it to get the columns and allowed actions of the resource.',
+                    },
+                    label: {
+                        type: 'string',
+                        description: 'Human readable resource name, translated for the current user.',
+                    },
+                },
+            },
+        },
+    },
+};
 function requestExtra(input) {
     return {
         body: input.body,
@@ -27,15 +59,19 @@ function jsonRpcAuthError(id = null) {
     return {
         jsonrpc: '2.0',
         id,
-        error: { code: -32001, message: 'Invalid or revoked MCP auth secret.' },
+        error: { code: -32001, message: 'Authentication required: the MCP auth secret or OAuth access token is missing, invalid or revoked.' },
     };
 }
 export default class AdminForthMcpPlugin extends AdminForthPlugin {
     options;
     pluginsScope = 'global';
     authSecretStore;
+    /** Null when OAuth sign-in is not configured; then only auth secrets authenticate. */
+    oauth;
     apiTools;
-    serverPresentation;
+    skills;
+    /** Null without adminPanelOrigin; then the settings page shows the MCP URL of the address it was opened at. */
+    urls;
     constructor(options) {
         super(options, import.meta.url);
         this.options = options;
@@ -71,9 +107,46 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
                 isVisible: () => true,
             });
         }
+        this.urls = this.options.adminPanelOrigin
+            ? createMcpUrls(this.options.adminPanelOrigin, adminforth.config.baseUrl)
+            : null;
         this.authSecretStore = new McpAuthSecretStore(adminforth, this.options.authSecretResource);
-        this.apiTools = new AdminForthApiTools(adminforth, new Set([this.options.authSecretResource.resourceId]));
-        this.serverPresentation = createMcpServerPresentation(adminforth.config.customization.brandName, this.options.adminPanelOrigin, adminforth.config.baseUrl);
+        this.oauth = this.options.authSecretResource.oauthClientIdField ? this.createOAuth(adminforth) : null;
+        const pageSize = {
+            default: this.options.pageSize?.default ?? DEFAULT_PAGE_SIZE,
+            max: this.options.pageSize?.max ?? MAX_PAGE_SIZE,
+        };
+        this.apiTools = new AdminForthApiTools(adminforth, new Set([this.options.authSecretResource.resourceId]), pageSize, this.options.toolTimeoutMs ?? DEFAULT_TOOL_TIMEOUT_MS);
+        this.skills = new McpSkills(this.customFolderPath, {
+            'pageSize.default': pageSize.default,
+            'pageSize.max': pageSize.max,
+            toolCallsPerRequest: this.options.toolCallsPerRequest ?? DEFAULT_TOOL_CALLS_PER_REQUEST,
+        });
+    }
+    createOAuth(adminforth) {
+        if (!this.urls) {
+            throw new Error('AdminForthMcpPlugin: adminPanelOrigin is required with authSecretResource.oauthClientIdField, '
+                + 'OAuth issuer and MCP resource URLs are built from it');
+        }
+        // OAuth sends codes and tokens through these endpoints, so they must be served over TLS (RFC 6749 §3.1);
+        // plain http is left for a local admin panel.
+        const origin = new URL(this.urls.adminPanelUrl);
+        if (origin.protocol !== 'https:' && !isLoopbackUrl(origin)) {
+            throw new Error(`AdminForthMcpPlugin: adminPanelOrigin must use https with OAuth sign-in, got "${origin.origin}"; `
+                + 'http is allowed only for localhost and 127.0.0.1');
+        }
+        adminforth.config.customization.customPages.push({
+            path: CONSENT_PAGE_PATH,
+            component: {
+                file: this.componentPath('McpAuthorize.vue'),
+                meta: { sidebarAndHeader: 'none' },
+            },
+        });
+        const isProduction = process.env.NODE_ENV === 'production';
+        if (isProduction && this.options.devOAuthClients?.length) {
+            logger.warn('AdminForthMcpPlugin: devOAuthClients are ignored because NODE_ENV is "production"');
+        }
+        return new McpOAuth(adminforth, this.authSecretStore, this.urls, isProduction ? [] : this.options.devOAuthClients, this.options.readOnly);
     }
     validateAuthSecretResource(resource) {
         const fields = this.options.authSecretResource;
@@ -85,6 +158,8 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
             fields.createdAtField,
             fields.lastUsedAtField,
             fields.lastUsedByAgentField,
+            fields.readOnlyField,
+            ...(fields.oauthClientIdField ? [fields.oauthClientIdField] : []),
         ]) {
             if (!resource.columns.some((column) => column.name === fieldName)) {
                 throw new Error(`AdminForthMcpPlugin: column "${fieldName}" not found in auth secret resource "${resource.resourceId}"`);
@@ -95,28 +170,56 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
         }
     }
     setupEndpoints(server) {
+        server.endpoint({
+            method: 'GET',
+            path: '/get_resources_list',
+            description: 'Lists the resourceId and label of every resource (data table), including resources the user cannot access: access is checked when a resource is used. Call this first to discover valid resourceId values before using get_resource, get_resource_data, aggregate, create_record, update_record, delete_record or other resource tools.',
+            agent: {
+                onlyReadsData: true,
+            },
+            response_schema: RESOURCES_LIST_RESPONSE_SCHEMA,
+            handler: async ({ tr }) => {
+                const resources = await Promise.all(this.adminforth.config.resources.map(async (resource) => ({
+                    resourceId: resource.resourceId,
+                    label: await tr(resource.label, `resource.${resource.resourceId}`),
+                })));
+                return { resources };
+            },
+        });
         server.endpoint({
             method: 'GET',
             path: `${MCP_PATH}/auth-secrets`,
+            agent: {
+                hiddenFromAgents: true,
+            },
             handler: async ({ adminUser }) => ({
                 authSecrets: await this.authSecretStore.list(adminUser),
+                oauthEnabled: Boolean(this.oauth),
+                mcpUrl: this.urls?.mcpUrl ?? null,
+                serverReadOnly: this.options.readOnly ?? false,
             }),
         });
         server.endpoint({
             method: 'POST',
             path: `${MCP_PATH}/auth-secrets`,
+            agent: {
+                hiddenFromAgents: true,
+            },
             handler: async (input) => {
                 const name = String(input.body.name ?? '').trim();
                 if (!name) {
                     input.response.setStatus(400);
                     return { error: 'Auth secret name is required' };
                 }
-                return this.authSecretStore.create(name, input.adminUser, requestExtra(input));
+                return this.authSecretStore.create(name, this.options.readOnly || input.body.readOnly === true, input.adminUser, requestExtra(input));
             },
         });
         server.endpoint({
             method: 'DELETE',
             path: `${MCP_PATH}/auth-secrets`,
+            agent: {
+                hiddenFromAgents: true,
+            },
             handler: async (input) => {
                 const result = await this.authSecretStore.revoke(String(input.body.id), input.adminUser, requestExtra(input));
                 if (result.error)
@@ -124,12 +227,40 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
                 return result;
             },
         });
+        if (this.oauth) {
+            setupOAuthEndpoints(server, this.oauth, adminApiPrefix(this.adminforth.config.baseUrl));
+        }
         server.endpoint({
             method: 'POST',
             path: MCP_PATH,
+            agent: {
+                hiddenFromAgents: true,
+            },
             noAuth: true,
             handler: async (input) => this.handleMcpRequest(input),
         });
+        // Streamable HTTP clients open a GET stream for server-initiated messages; 405 tells them this server has none.
+        server.endpoint({
+            method: 'GET',
+            path: MCP_PATH,
+            agent: {
+                hiddenFromAgents: true,
+            },
+            noAuth: true,
+            handler: async ({ response }) => {
+                response.setHeader('Allow', 'POST');
+                response.setStatus(405, 'Method Not Allowed');
+            },
+        });
+    }
+    /** Accepts personal auth secrets and OAuth access tokens; access tokens are JWTs, secrets have their prefix. */
+    async authenticate(token) {
+        if (token.startsWith(SECRET_PREFIX))
+            return this.authSecretStore.authenticate(token);
+        if (!this.oauth)
+            return null;
+        const accessToken = await this.oauth.verifyAccessToken(token);
+        return accessToken && this.authSecretStore.authenticateOAuthGrant(accessToken.grantId, accessToken.pk);
     }
     async handleMcpRequest(input) {
         if (input.headers.origin) {
@@ -140,12 +271,13 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
                 error: { code: -32003, message: 'Browser-originated MCP requests are not allowed.' },
             };
         }
-        const bearerMatch = String(input.headers.authorization ?? '').match(BEARER_SECRET_RE);
-        const authenticated = bearerMatch
-            ? await this.authSecretStore.authenticate(bearerMatch[1])
-            : null;
+        const token = String(input.headers.authorization ?? '').match(BEARER_TOKEN_RE)?.[1];
+        const authenticated = token ? await this.authenticate(token) : null;
         if (!authenticated) {
-            input.response.setHeader('WWW-Authenticate', 'Bearer');
+            // resource_metadata leads OAuth clients to the authorization server; invalid_token makes them refresh.
+            input.response.setHeader('WWW-Authenticate', this.oauth
+                ? `Bearer ${token ? 'error="invalid_token", ' : ''}resource_metadata="${this.oauth.resourceMetadataUrl}"`
+                : 'Bearer');
             input.response.setStatus(401);
             return jsonRpcAuthError(input.body.id ?? null);
         }
@@ -164,19 +296,25 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
             ...authenticated.adminUser,
             executedBy: formatMcpExecutedBy(client, authenticated.name),
         };
+        const readOnly = this.options.readOnly || authenticated.readOnly;
         const protocolResponse = await handleMcpProtocol({
-            ...this.serverPresentation,
+            ...createMcpServerPresentation(this.adminforth.config.customization.brandName, this.urls?.adminPanelUrl, this.skills.serverInstructions(), readOnly),
             body: input.body,
             headers: toolHeaders,
-            listTools: () => this.apiTools.list(),
-            callTool: (name, arguments_) => this.apiTools.call({
-                name,
-                arguments: arguments_,
-                adminUser,
-                headers: toolHeaders,
-                requestUrl: input.requestUrl,
-                abortSignal: input.abortSignal,
-            }),
+            listTools: () => [...this.apiTools.list(readOnly), this.skills.toolDefinition()],
+            callTool: async (name, arguments_) => {
+                if (name === FETCH_SKILL_TOOL_NAME)
+                    return this.skills.call(arguments_);
+                return this.apiTools.call({
+                    name,
+                    arguments: arguments_,
+                    adminUser,
+                    headers: toolHeaders,
+                    requestUrl: input.requestUrl,
+                    abortSignal: input.abortSignal,
+                    readOnly,
+                });
+            },
         });
         input.response.setStatus(protocolResponse.status);
         if (!protocolResponse.body) {

package/dist/inputSchema.d.ts

@@ -0,0 +1,3 @@
+type JsonSchema = Record<string, unknown>;
+export declare function compactInputSchema(schema: JsonSchema): JsonSchema;
+export {};

package/dist/inputSchema.js

@@ -0,0 +1,63 @@
+// Endpoint request schemas are written for OpenAPI docs. MCP clients keep tool schemas in the model context,
+// so annotations that do not help to build a call and definitions the tool never references are dropped.
+const DOCUMENTATION_ONLY_KEYWORDS = new Set(['title', 'examples']);
+// Keywords whose value maps names to subschemas: their keys are names, not keywords.
+const SUBSCHEMA_MAP_KEYWORDS = new Set(['properties', 'patternProperties', '$defs']);
+// Keywords whose value is data, not a schema.
+const DATA_KEYWORDS = new Set(['enum', 'const', 'default']);
+const DEFS_REF_PREFIX = '#/$defs/';
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function stripDocumentationKeywords(node) {
+    if (Array.isArray(node))
+        return node.map(stripDocumentationKeywords);
+    if (!isObject(node))
+        return node;
+    return Object.fromEntries(Object.entries(node)
+        .filter(([keyword]) => !DOCUMENTATION_ONLY_KEYWORDS.has(keyword))
+        .map(([keyword, value]) => {
+        if (DATA_KEYWORDS.has(keyword))
+            return [keyword, value];
+        if (SUBSCHEMA_MAP_KEYWORDS.has(keyword) && isObject(value)) {
+            return [keyword, Object.fromEntries(Object.entries(value).map(([name, subschema]) => [name, stripDocumentationKeywords(subschema)]))];
+        }
+        return [keyword, stripDocumentationKeywords(value)];
+    }));
+}
+function collectDefRefs(node, refs) {
+    if (Array.isArray(node)) {
+        node.forEach((item) => collectDefRefs(item, refs));
+        return;
+    }
+    if (!isObject(node))
+        return;
+    for (const [keyword, value] of Object.entries(node)) {
+        if (keyword === '$ref' && typeof value === 'string' && value.startsWith(DEFS_REF_PREFIX)) {
+            refs.add(value.slice(DEFS_REF_PREFIX.length));
+        }
+        else if (!DATA_KEYWORDS.has(keyword)) {
+            collectDefRefs(value, refs);
+        }
+    }
+}
+// Shared $defs are attached to every endpoint schema, even to endpoints that use only some of them.
+function pruneUnusedDefs(schema) {
+    const { $defs, ...rest } = schema;
+    if (!isObject($defs))
+        return schema;
+    const used = new Set();
+    const pending = new Set();
+    collectDefRefs(rest, pending);
+    for (const name of pending) {
+        if (used.has(name))
+            continue;
+        used.add(name);
+        collectDefRefs($defs[name], pending);
+    }
+    const usedDefs = Object.fromEntries(Object.entries($defs).filter(([name]) => used.has(name)));
+    return Object.keys(usedDefs).length > 0 ? { ...rest, $defs: usedDefs } : rest;
+}
+export function compactInputSchema(schema) {
+    return pruneUnusedDefs(stripDocumentationKeywords(schema));
+}

package/dist/keyedLock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs tasks with the same key one at a time, within this process. A key is kept only while a task with it runs
+ * or waits, so keys taken by many different callers do not pile up in memory.
+ */
+export declare class KeyedLock {
+    private readonly tails;
+    run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}

package/dist/keyedLock.js

@@ -0,0 +1,20 @@
+/**
+ * Runs tasks with the same key one at a time, within this process. A key is kept only while a task with it runs
+ * or waits, so keys taken by many different callers do not pile up in memory.
+ */
+export class KeyedLock {
+    tails = new Map();
+    async run(key, task) {
+        const result = (this.tails.get(key) ?? Promise.resolve()).then(task);
+        // The next task with this key waits for this one even when it fails.
+        const tail = result.catch(() => { });
+        this.tails.set(key, tail);
+        try {
+            return await result;
+        }
+        finally {
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        }
+    }
+}

package/dist/mcpProtocol.d.ts

@@ -12,7 +12,7 @@ export interface McpServerPresentation {
     serverInfo: McpServerInfo;
     instructions: string;
 }
-export declare function createMcpServerPresentation(brandName: string, adminPanelOrigin?: string, baseUrl?: string): McpServerPresentation;
+export declare function createMcpServerPresentation(brandName: string, adminPanelUrl?: string, guidance?: string, readOnly?: boolean): McpServerPresentation;
 export interface McpProtocolContext {
     body: Record<string, any>;
     headers: Record<string, any>;

package/dist/mcpProtocol.js

@@ -1,3 +1,4 @@
+import YAML from 'yaml';
 export const MODERN_PROTOCOL_VERSION = '2026-07-28';
 export const LEGACY_PROTOCOL_VERSION = '2025-11-25';
 const LEGACY_PROTOCOL_VERSIONS = new Set([
@@ -8,10 +9,7 @@ const LEGACY_PROTOCOL_VERSIONS = new Set([
 const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
 const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
 const SERVER_INFO_META_KEY = 'io.modelcontextprotocol/serverInfo';
-export function createMcpServerPresentation(brandName, adminPanelOrigin, baseUrl = '') {
-    const adminPanelUrl = adminPanelOrigin
-        ? new URL(baseUrl || '/', adminPanelOrigin).toString()
-        : undefined;
+export function createMcpServerPresentation(brandName, adminPanelUrl, guidance = '', readOnly = false) {
     const adminPanel = `AdminForth admin panel for "${brandName}"${adminPanelUrl ? ` at ${adminPanelUrl}` : ''}`;
     return {
         serverInfo: {
@@ -21,7 +19,10 @@ export function createMcpServerPresentation(brandName, adminPanelOrigin, baseUrl
             description: `${adminPanel}.`,
             ...(adminPanelUrl && { websiteUrl: adminPanelUrl }),
         },
-        instructions: `This is the ${adminPanel}. Use its tools to read and update data allowed for the authenticated user.`,
+        instructions: [
+            `This is the ${adminPanel}. Use its tools to ${readOnly ? 'read' : 'read and update'} data allowed for the authenticated user.`,
+            guidance,
+        ].filter(Boolean).join('\n\n'),
     };
 }
 function errorResponse(id, code, message, status = 400) {
@@ -67,8 +68,9 @@ function validateModernHeaders(body, headers) {
     }
     return null;
 }
+// The JSON round trip drops functions and undefined values that handler responses may carry, which YAML cannot serialize.
 function serializeToolOutput(output) {
-    return typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+    return typeof output === 'string' ? output : YAML.stringify(JSON.parse(JSON.stringify(output ?? null)));
 }
 export async function handleMcpProtocol(context) {
     const { body, headers, serverInfo, instructions } = context;

package/dist/oauth.d.ts

@@ -0,0 +1,96 @@
+import type { AdminUser, IAdminForth } from 'adminforth';
+import type { McpAuthSecretStore } from './authSecretStore.js';
+import type { McpOAuthClient } from './types.js';
+import { type McpUrls } from './urls.js';
+/** Endpoint paths relative to the AdminForth API prefix (`<baseUrl>/adminapi/v1`). */
+export declare const OAUTH_PATHS: {
+    protectedResourceMetadata: string;
+    authorizationServerMetadata: string;
+    jwks: string;
+    authorize: string;
+    token: string;
+    authorization: string;
+};
+export declare const CONSENT_PAGE_PATH = "/mcp-authorize";
+interface AccessToken {
+    pk: string;
+    grantId: string;
+    aud: string;
+}
+/**
+ * OAuth 2.1 authorization server for the MCP endpoint: authorization code flow with PKCE for public clients
+ * identified by Client ID Metadata Documents. Authorization requests and codes are signed JWTs, so only the
+ * resulting grants are stored, as records of the auth secret resource.
+ */
+export declare class McpOAuth {
+    private readonly adminforth;
+    private readonly store;
+    private readonly serverReadOnly;
+    readonly mcpUrl: string;
+    readonly resourceMetadataUrl: string;
+    private readonly issuer;
+    private readonly apiUrl;
+    private readonly consentPageUrl;
+    private readonly configuredClients;
+    private readonly fetchedClients;
+    /**
+     * `configuredClients` are trusted as is, without fetching their client metadata documents. `serverReadOnly` is
+     * the plugin readOnly option: it makes every connection read-only, whatever the user chooses on the consent page.
+     */
+    constructor(adminforth: IAdminForth, store: McpAuthSecretStore, urls: McpUrls, configuredClients?: McpOAuthClient[], serverReadOnly?: boolean);
+    protectedResourceMetadata(): {
+        resource: string;
+        authorization_servers: string[];
+        bearer_methods_supported: string[];
+    };
+    authorizationServerMetadata(): {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        response_types_supported: string[];
+        grant_types_supported: string[];
+        code_challenge_methods_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+        client_id_metadata_document_supported: boolean;
+        authorization_response_iss_parameter_supported: boolean;
+        jwks_uri: string;
+        subject_types_supported: string[];
+        id_token_signing_alg_values_supported: string[];
+    };
+    /**
+     * Validates the authorization request and returns the consent page URL to redirect the browser to.
+     * This endpoint needs no sign-in, so the client metadata document is fetched only once the user opens the
+     * consent page: otherwise anyone could make this server send requests to any URL passed as client_id.
+     */
+    authorize(query: Record<string, unknown>): Promise<string>;
+    /** What the consent page shows about a pending authorization request. */
+    describeAuthorization(signedRequest: string): Promise<{
+        clientName: string;
+        clientHost: string | null;
+        redirectHost: string;
+        loopbackRedirect: boolean;
+        serverReadOnly: boolean;
+    }>;
+    /**
+     * Approves or denies a pending authorization request and returns where to send the browser. `readOnly` is the
+     * choice of the user on the consent page; the connection is read-only with it or with the plugin readOnly option.
+     */
+    resolveAuthorization(signedRequest: string, approved: boolean, adminUser: AdminUser, readOnly?: boolean): Promise<string>;
+    exchangeToken(body: Record<string, unknown>): Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in: number;
+        refresh_token: string;
+    }>;
+    /** Returns the grant an OAuth access token was issued for, or null for an invalid, expired or foreign token. */
+    verifyAccessToken(token: string): Promise<AccessToken | null>;
+    private checkResource;
+    private verifyAuthorizationRequest;
+    /** The consent page loads the client to describe it and again to resolve the request, hence the cache. */
+    private lookUpClient;
+    private redeemAuthorizationCode;
+    private refreshAccessToken;
+    private issueRefreshToken;
+    private tokenResponse;
+}
+export {};