@adminforth/mcp 1.1.2 → 1.2.0

package/dist/{oauthClientMetadata.js → oauth/clientMetadata.js}

@@ -2,12 +2,11 @@ import dns from 'node:dns';
 import https from 'node:https';
 import net from 'node:net';
 import { logger } from 'adminforth';
-import { OAuthError } from './oauthError.js';
+import { clientMetadataDocumentSchema } from '../schemas/oAuth.js';
+import { OAuthError } from './errors.js';
 const MAX_DOCUMENT_BYTES = 5 * 1024;
 const FETCH_TIMEOUT_MS = 5000;
-// client_name is shown on the consent page and stored as the connection name.
 const MAX_CLIENT_NAME_LENGTH = 100;
-const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const specialPurposeAddresses = new net.BlockList();
 [
     ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
@@ -57,23 +56,6 @@ export function isClientIdUrl(clientId) {
         && !net.isIP(url.hostname)
         && !url.hostname.startsWith('[');
 }
-export function isLoopbackUrl(url) {
-    return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
-}
-/** Native clients listen on a random loopback port, so RFC 8252 lets the port differ from the registered one. */
-export function redirectUriMatches(requested, registered) {
-    const registeredUrl = new URL(registered);
-    if (!isLoopbackUrl(registeredUrl))
-        return requested.href === registeredUrl.href;
-    return requested.protocol === registeredUrl.protocol
-        && requested.hostname === registeredUrl.hostname
-        && requested.pathname === registeredUrl.pathname
-        && requested.search === registeredUrl.search
-        && requested.hash === registeredUrl.hash;
-}
-export function isAllowedRedirectUri(redirectUri) {
-    return redirectUri.protocol === 'https:' || isLoopbackUrl(redirectUri);
-}
 function fetchJson(url) {
     return new Promise((resolve, reject) => {
         const request = https.get(url, {
@@ -116,9 +98,9 @@ function fetchJson(url) {
  * that passed isClientIdUrl.
  */
 export async function fetchClientMetadata(clientId) {
-    let document;
+    let fetched;
     try {
-        document = await fetchJson(clientId);
+        fetched = await fetchJson(clientId);
     }
     catch (error) {
         // The reason stays in the log: resolved addresses, HTTP statuses and parse errors quoting the response
@@ -126,13 +108,11 @@ export async function fetchClientMetadata(clientId) {
         logger.warn(`AdminForthMcpPlugin: failed to fetch client metadata document ${clientId}: ${error.message}`);
         throw new OAuthError('invalid_client', 'Could not fetch the client metadata document');
     }
-    if (typeof document?.client_name !== 'string'
-        || !Array.isArray(document.redirect_uris)
-        || !document.redirect_uris.length
-        || !document.redirect_uris.every((uri) => typeof uri === 'string' && URL.canParse(uri))
-        || document.token_endpoint_auth_method !== 'none') {
-        throw new OAuthError('invalid_client', 'Client metadata document must have client_name, redirect_uris and token_endpoint_auth_method "none"');
+    const parsed = clientMetadataDocumentSchema.safeParse(fetched);
+    if (!parsed.success) {
+        throw new OAuthError('invalid_client', 'Client metadata document must have client_id, client_name, redirect_uris and token_endpoint_auth_method "none"');
     }
+    const document = parsed.data;
     if (document.client_id !== clientId) {
         throw new OAuthError('invalid_client', 'client_id in the client metadata document does not match its URL');
     }

package/dist/oauth/redirectUris.d.ts

@@ -0,0 +1,4 @@
+export declare function isLoopbackUrl(url: URL): boolean;
+/** Native clients listen on a random loopback port, so RFC 8252 lets the port differ from the registered one. */
+export declare function redirectUriMatches(requested: URL, registered: string): boolean;
+export declare function isAllowedRedirectUri(redirectUri: URL): boolean;

package/dist/oauth/redirectUris.js

@@ -0,0 +1,18 @@
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+export function isLoopbackUrl(url) {
+    return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
+}
+/** Native clients listen on a random loopback port, so RFC 8252 lets the port differ from the registered one. */
+export function redirectUriMatches(requested, registered) {
+    const registeredUrl = new URL(registered);
+    if (!isLoopbackUrl(registeredUrl))
+        return requested.href === registeredUrl.href;
+    return requested.protocol === registeredUrl.protocol
+        && requested.hostname === registeredUrl.hostname
+        && requested.pathname === registeredUrl.pathname
+        && requested.search === registeredUrl.search
+        && requested.hash === registeredUrl.hash;
+}
+export function isAllowedRedirectUri(redirectUri) {
+    return redirectUri.protocol === 'https:' || isLoopbackUrl(redirectUri);
+}

package/dist/oauth/setup.d.ts

@@ -0,0 +1,6 @@
+import { type IAdminForth } from 'adminforth';
+import type { McpAuthSecretStore } from '../authSecretStore.js';
+import type { PluginOptions } from '../types.js';
+import { type McpUrls } from '../urls.js';
+import { McpOAuth } from './authorizationServer.js';
+export declare function setupOAuth(adminforth: IAdminForth, authSecretStore: McpAuthSecretStore, urls: McpUrls, options: PluginOptions, consentPageFile: string): McpOAuth;

package/dist/oauth/setup.js

@@ -0,0 +1,25 @@
+import { logger } from 'adminforth';
+import { CONSENT_PAGE_PATH } from '../urls.js';
+import { McpOAuth } from './authorizationServer.js';
+import { isLoopbackUrl } from './redirectUris.js';
+export function setupOAuth(adminforth, authSecretStore, urls, options, consentPageFile) {
+    // 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(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: consentPageFile,
+            meta: { sidebarAndHeader: 'none' },
+        },
+    });
+    const isProduction = process.env.NODE_ENV === 'production';
+    if (isProduction && options.devOAuthClients?.length) {
+        logger.warn('AdminForthMcpPlugin: devOAuthClients are ignored because NODE_ENV is "production"');
+    }
+    return new McpOAuth(adminforth, authSecretStore, urls, isProduction ? [] : options.devOAuthClients, options.readOnly);
+}

package/dist/repositories/authSecret.d.ts

@@ -0,0 +1,31 @@
+import { type AdminUser, type CreateResourceRecordResult, type DeleteResourceRecordResult, type HttpExtra, type IAdminForth } from 'adminforth';
+import type { McpAuthSecretResourceOptions, McpClientInfo } from '../types.js';
+export interface AuthSecret {
+    id: string;
+    name: string;
+    secretHash: string;
+    userId: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    lastUsedByAgent: McpClientInfo | null;
+    readOnly: boolean;
+    oauthClientId: string | null;
+}
+export type NewAuthSecret = Pick<AuthSecret, 'id' | 'name' | 'secretHash' | 'userId' | 'readOnly' | 'oauthClientId'>;
+export declare class AuthSecretRepository {
+    private readonly adminforth;
+    private readonly fields;
+    private readonly resource;
+    constructor(adminforth: IAdminForth, fields: McpAuthSecretResourceOptions);
+    listByUser(userId: string): Promise<AuthSecret[]>;
+    findById(id: string): Promise<AuthSecret | null>;
+    findBySecretHash(secretHash: string): Promise<AuthSecret | null>;
+    create(authSecret: NewAuthSecret, adminUser: AdminUser, extra: HttpExtra): Promise<CreateResourceRecordResult>;
+    deleteByIdAndUser(id: string, adminUser: AdminUser, extra: HttpExtra): Promise<DeleteResourceRecordResult | null>;
+    deleteById(id: string): Promise<void>;
+    updateSecretHash(id: string, secretHash: string): Promise<void>;
+    updateUsage(id: string, client?: McpClientInfo): Promise<void>;
+    private records;
+    private findOne;
+    private toAuthSecret;
+}

package/dist/repositories/authSecret.js

@@ -0,0 +1,86 @@
+import { Filters, Sorts, } from 'adminforth';
+export class AuthSecretRepository {
+    adminforth;
+    fields;
+    resource;
+    constructor(adminforth, fields) {
+        this.adminforth = adminforth;
+        this.fields = fields;
+        this.resource = adminforth.config.resources.find((resource) => resource.resourceId === fields.resourceId);
+    }
+    async listByUser(userId) {
+        const records = await this.records().list(Filters.EQ(this.fields.userIdField, userId), undefined, undefined, Sorts.DESC(this.fields.createdAtField));
+        return records.map((record) => this.toAuthSecret(record));
+    }
+    findById(id) {
+        return this.findOne(Filters.EQ(this.fields.idField, id));
+    }
+    findBySecretHash(secretHash) {
+        return this.findOne(Filters.EQ(this.fields.secretHashField, secretHash));
+    }
+    create(authSecret, adminUser, extra) {
+        const fields = this.fields;
+        return this.adminforth.createResourceRecord({
+            resource: this.resource,
+            adminUser,
+            extra,
+            record: {
+                [fields.idField]: authSecret.id,
+                [fields.nameField]: authSecret.name,
+                [fields.secretHashField]: authSecret.secretHash,
+                [fields.userIdField]: authSecret.userId,
+                [fields.createdAtField]: new Date().toISOString(),
+                [fields.lastUsedAtField]: null,
+                [fields.lastUsedByAgentField]: null,
+                [fields.readOnlyField]: authSecret.readOnly,
+                [fields.oauthClientIdField]: authSecret.oauthClientId,
+            },
+        });
+    }
+    async deleteByIdAndUser(id, adminUser, extra) {
+        const record = await this.records().get(Filters.AND(Filters.EQ(this.fields.idField, id), Filters.EQ(this.fields.userIdField, adminUser.pk)));
+        if (!record)
+            return null;
+        return this.adminforth.deleteResourceRecord({
+            resource: this.resource,
+            record,
+            recordId: id,
+            adminUser,
+            extra,
+        });
+    }
+    async deleteById(id) {
+        await this.records().delete(id);
+    }
+    async updateSecretHash(id, secretHash) {
+        await this.records().update(id, { [this.fields.secretHashField]: secretHash });
+    }
+    async updateUsage(id, client) {
+        await this.records().update(id, {
+            [this.fields.lastUsedAtField]: new Date().toISOString(),
+            ...(client && { [this.fields.lastUsedByAgentField]: JSON.stringify(client) }),
+        });
+    }
+    records() {
+        return this.adminforth.resource(this.fields.resourceId);
+    }
+    async findOne(filter) {
+        const record = await this.records().get(filter);
+        return record ? this.toAuthSecret(record) : null;
+    }
+    toAuthSecret(record) {
+        const fields = this.fields;
+        const lastUsedByAgent = record[fields.lastUsedByAgentField];
+        return {
+            id: record[fields.idField],
+            name: record[fields.nameField],
+            secretHash: record[fields.secretHashField],
+            userId: record[fields.userIdField],
+            createdAt: record[fields.createdAtField],
+            lastUsedAt: record[fields.lastUsedAtField],
+            lastUsedByAgent: lastUsedByAgent && JSON.parse(lastUsedByAgent),
+            readOnly: record[fields.readOnlyField],
+            oauthClientId: record[fields.oauthClientIdField],
+        };
+    }
+}

package/dist/requestExtra.d.ts

@@ -0,0 +1,2 @@
+import type { HttpExtra, IAdminForthEndpointHandlerInput } from 'adminforth';
+export declare function requestExtra(input: IAdminForthEndpointHandlerInput): HttpExtra;

package/dist/requestExtra.js

@@ -0,0 +1,10 @@
+export function requestExtra(input) {
+    return {
+        body: input.body,
+        query: input.query,
+        headers: input.headers,
+        cookies: input.cookies,
+        requestUrl: input.requestUrl,
+        response: input.response,
+    };
+}

package/dist/schemas/oAuth.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const resolveAuthorizationBodySchema: z.ZodObject<{
+    request: z.ZodString;
+    approved: z.ZodBoolean;
+    readOnly: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const clientMetadataDocumentSchema: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodString;
+    redirect_uris: z.ZodArray<z.ZodString>;
+    token_endpoint_auth_method: z.ZodLiteral<"none">;
+}, z.core.$strip>;
+export type ResolveAuthorizationBody = z.infer<typeof resolveAuthorizationBodySchema>;

package/dist/schemas/oAuth.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export const resolveAuthorizationBodySchema = z.object({
+    request: z.string(),
+    approved: z.boolean(),
+    readOnly: z.boolean(),
+});
+export const clientMetadataDocumentSchema = z.object({
+    client_id: z.string(),
+    client_name: z.string(),
+    redirect_uris: z.array(z.string().refine((uri) => URL.canParse(uri))).min(1),
+    token_endpoint_auth_method: z.literal('none'),
+});

package/dist/schemas/settings.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export declare const createAuthSecretBodySchema: z.ZodObject<{
+    name: z.ZodString;
+    readOnly: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const revokeAuthSecretBodySchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type CreateAuthSecretBody = z.infer<typeof createAuthSecretBodySchema>;
+export type RevokeAuthSecretBody = z.infer<typeof revokeAuthSecretBodySchema>;

package/dist/schemas/settings.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const createAuthSecretBodySchema = z.object({
+    name: z.string().min(1),
+    readOnly: z.boolean(),
+});
+export const revokeAuthSecretBodySchema = z.object({
+    id: z.string(),
+});

package/dist/schemas/tools.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const resourcesListResponseSchema: z.ZodObject<{
+    resources: z.ZodArray<z.ZodObject<{
+        resourceId: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/schemas/tools.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const resourcesListResponseSchema = z.object({
+    resources: z.array(z.object({
+        resourceId: z.string().describe('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: z.string().describe('Human readable resource name, translated for the current user.'),
+    })).describe('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.'),
+});

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
-import type { McpToolDefinition } from './apiTools.js';
+import type { Tool } from '@modelcontextprotocol/server';
 export declare const FETCH_SKILL_TOOL_NAME = "fetch_skill";
 type TemplateValues = Record<string, string | number>;
 /**
@@ -10,7 +10,7 @@ export declare class McpSkills {
     private readonly skills;
     constructor(customFolderPath: string, values: TemplateValues);
     serverInstructions(): string;
-    toolDefinition(): McpToolDefinition;
+    toolDefinition(): Tool;
     call(args: Record<string, unknown> | undefined): {
         output: unknown;
         isError: boolean;

package/dist/types.d.ts

@@ -9,11 +9,7 @@ export interface McpAuthSecretResourceOptions {
     lastUsedAtField: string;
     lastUsedByAgentField: string;
     readOnlyField: string;
-    /**
-     * Client ID Metadata Document URL of the MCP client connected through OAuth; empty for personal auth secrets.
-     * Setting it enables OAuth sign-in, which also needs adminPanelOrigin. Without it only auth secrets work.
-     */
-    oauthClientIdField?: string;
+    oauthClientIdField: string;
 }
 /** An MCP client allowed to connect through OAuth, as its Client ID Metadata Document describes it. */
 export interface McpOAuthClient {
@@ -22,9 +18,7 @@ export interface McpOAuthClient {
     redirectUris: string[];
 }
 export interface McpPageSize {
-    /** Rows get_resource_data returns when the client does not pass limit. */
     default: number;
-    /** Most rows get_resource_data returns per call; larger limits are capped. */
     max: number;
 }
 export interface PluginOptions extends PluginsCommonOptions {
@@ -32,10 +26,9 @@ export interface PluginOptions extends PluginsCommonOptions {
     /**
      * Public origin of this AdminForth installation, without the AdminForth baseUrl path, e.g. https://example.com.
      * The MCP server URL shown on the settings page, the OAuth issuer and resource URLs are built from it, so it must
-     * be the origin MCP clients connect to. Required with OAuth sign-in; without it the settings page shows the MCP URL
-     * of the address it was opened at.
+     * be the origin MCP clients connect to.
      */
-    adminPanelOrigin?: string;
+    adminPanelOrigin: string;
     /**
      * MCP clients resolved from this list instead of fetching their Client ID Metadata Document, so OAuth can be
      * tried locally without a public https URL. Ignored when NODE_ENV is "production": there every client_id is

package/dist/urls.d.ts

@@ -1,10 +1,14 @@
 export declare const MCP_PATH = "/mcp";
-/** Path prefix of AdminForth API endpoints, e.g. `/admin/adminapi/v1`. */
+export declare const CONSENT_PAGE_PATH = "/mcp-authorize";
+export declare const OAUTH_PATHS: {
+    protectedResourceMetadata: string;
+    authorizationServerMetadata: string;
+    jwks: string;
+    authorize: string;
+    token: string;
+    authorization: string;
+};
 export declare function adminApiPrefix(baseUrl: string): string;
-/**
- * Public URLs of the plugin, built once from adminPanelOrigin: the settings page, OAuth metadata and the MCP server
- * info must all name the same URL, because OAuth accepts tokens only for the exact MCP resource URL.
- */
 export interface McpUrls {
     apiUrl: string;
     mcpUrl: string;

package/dist/urls.js

@@ -1,5 +1,13 @@
 export const MCP_PATH = '/mcp';
-/** Path prefix of AdminForth API endpoints, e.g. `/admin/adminapi/v1`. */
+export const CONSENT_PAGE_PATH = '/mcp-authorize';
+export const OAUTH_PATHS = {
+    protectedResourceMetadata: `${MCP_PATH}/oauth-protected-resource`,
+    authorizationServerMetadata: `${MCP_PATH}/.well-known/openid-configuration`,
+    jwks: `${MCP_PATH}/oauth/jwks`,
+    authorize: `${MCP_PATH}/oauth/authorize`,
+    token: `${MCP_PATH}/oauth/token`,
+    authorization: `${MCP_PATH}/oauth/authorization`,
+};
 export function adminApiPrefix(baseUrl) {
     return `${baseUrl}/adminapi/v1`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/mcp",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Expose AdminForth APIs as an authenticated MCP server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,7 +26,7 @@
   },
   "scripts": {
     "build": "tsc && rsync -av --exclude 'node_modules' custom dist/",
-    "test": "pnpm build && node --test tests/*.test.mjs"
+    "test": "rm -rf dist && pnpm build && node --test tests/*.test.mjs"
   },
   "keywords": [
     "adminforth",
@@ -40,14 +40,17 @@
   "author": "DevForth (https://devforth.io)",
   "license": "MIT",
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "latest",
     "adminforth": "^3.32.0",
+    "express": "^5.2.1",
     "semantic-release": "^24.2.1",
     "semantic-release-slack-bot": "^4.0.2",
     "typescript": "^5.7.3"
   },
   "peerDependencies": {
-    "adminforth": "^3.32.0"
+    "adminforth": "^3.32.0",
+    "express": "^4.21.0 || ^5.0.0"
   },
   "release": {
     "plugins": [
@@ -75,6 +78,8 @@
     ]
   },
   "dependencies": {
-    "yaml": "^2.9.1"
+    "@modelcontextprotocol/server": "^2.3.1",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   }
 }

package/dist/oauthEndpoints.d.ts

@@ -1,3 +0,0 @@
-import { type IHttpServer } from 'adminforth';
-import { type McpOAuth } from './oauth.js';
-export declare function setupOAuthEndpoints(server: IHttpServer, oauth: McpOAuth, apiPrefix: string): void;