@adminforth/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devforth.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# 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.
+
+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`.
+
+Install with:
+
+```bash
+pnpm add @adminforth/mcp
+```
+
+See the [AdminForth MCP documentation](https://adminforth.dev/docs/tutorial/Plugins/mcp/) for the auth secret table and plugin configuration.

package/dist/apiTools.d.ts

@@ -0,0 +1,27 @@
+import type { AdminUser, IAdminForth } from 'adminforth';
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: {
+        destructiveHint: boolean;
+    };
+}
+export declare class AdminForthApiTools {
+    private readonly adminforth;
+    private readonly hiddenResourceIds;
+    constructor(adminforth: IAdminForth, hiddenResourceIds: ReadonlySet<string>);
+    private schemas;
+    list(): McpToolDefinition[];
+    call(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        adminUser: AdminUser;
+        headers: Record<string, any>;
+        requestUrl: string;
+        abortSignal: AbortSignal;
+    }): Promise<{
+        output: unknown;
+        isError: boolean;
+    }>;
+}

package/dist/apiTools.js

@@ -0,0 +1,127 @@
+const METHODS_WITHOUT_REQUEST_BODY = new Set(['GET', 'HEAD']);
+function isRegisteredToolSchema(schema) {
+    return typeof schema.handler === 'function';
+}
+function endpointPathToToolName(path) {
+    return path
+        .replace(/^\/+/, '')
+        .replace(/[^a-zA-Z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function stripAdminApiPrefix(path, adminforth) {
+    const baseUrl = (adminforth.config.baseUrl ?? '').replace(/\/$/, '');
+    const apiPrefix = `${baseUrl}/adminapi/v1`;
+    const strippedPath = path.startsWith(apiPrefix) ? path.slice(apiPrefix.length) : path;
+    return strippedPath.startsWith('/') ? strippedPath : `/${strippedPath}`;
+}
+function createDirectResponse() {
+    return {
+        status: 200,
+        setHeader() { },
+        setStatus(status, message) {
+            this.status = status;
+            this.message = message;
+        },
+        blobStream() {
+            throw new Error('File streaming is not available through MCP tools');
+        },
+    };
+}
+export class AdminForthApiTools {
+    adminforth;
+    hiddenResourceIds;
+    constructor(adminforth, hiddenResourceIds) {
+        this.adminforth = adminforth;
+        this.hiddenResourceIds = hiddenResourceIds;
+    }
+    schemas() {
+        const schemas = new Map();
+        for (const schema of this.adminforth.openApi.registeredSchemas) {
+            if (!isRegisteredToolSchema(schema))
+                continue;
+            const path = stripAdminApiPrefix(schema.path, this.adminforth);
+            if (path === '/mcp' || path.startsWith('/mcp/'))
+                continue;
+            schemas.set(endpointPathToToolName(path), schema);
+        }
+        return schemas;
+    }
+    list() {
+        return Array.from(this.schemas().entries())
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, schema]) => ({
+            name,
+            ...(schema.description && { description: schema.description }),
+            inputSchema: schema.request_schema ?? {
+                type: 'object',
+                properties: {},
+                additionalProperties: true,
+            },
+            ...(schema.agent?.isDangerous && {
+                annotations: { destructiveHint: true },
+            }),
+        }));
+    }
+    async call(params) {
+        const schema = this.schemas().get(params.name);
+        if (!schema) {
+            return { output: { error: `Unknown tool: ${params.name}` }, isError: true };
+        }
+        if (typeof params.arguments?.resourceId === 'string'
+            && this.hiddenResourceIds.has(params.arguments.resourceId)) {
+            return {
+                output: { error: 'This resource is not available through MCP.' },
+                isError: true,
+            };
+        }
+        const method = schema.method.toUpperCase();
+        const hasBody = !METHODS_WITHOUT_REQUEST_BODY.has(method);
+        const body = hasBody ? (params.arguments ?? {}) : {};
+        const query = hasBody ? {} : (params.arguments ?? {});
+        const requestValidation = this.adminforth.openApi.validateRequestSchema(schema, body);
+        if (!requestValidation.valid) {
+            return {
+                output: { error: 'REQUEST_VALIDATION_FAILED', details: requestValidation.errors },
+                isError: true,
+            };
+        }
+        const response = createDirectResponse();
+        const language = String(params.headers['accept-language'] ?? 'en');
+        const output = await schema.handler({
+            body,
+            query,
+            headers: params.headers,
+            cookies: [],
+            adminUser: params.adminUser,
+            response,
+            requestUrl: params.requestUrl,
+            abortSignal: params.abortSignal,
+            _raw_express_req: undefined,
+            _raw_express_res: undefined,
+            tr: (message, category, translationParams, pluralizationNumber) => this.adminforth.tr(message, category, language, translationParams, pluralizationNumber),
+        });
+        if (response.message) {
+            return {
+                output: response.message,
+                isError: response.status >= 400,
+            };
+        }
+        if (output === undefined) {
+            return {
+                output: { error: 'Tool handler completed without returning a response.' },
+                isError: true,
+            };
+        }
+        const responseValidation = this.adminforth.openApi.validateResponseSchema(schema, output);
+        if (!responseValidation.valid) {
+            return {
+                output: { error: 'RESPONSE_VALIDATION_FAILED', details: responseValidation.errors },
+                isError: true,
+            };
+        }
+        return {
+            output,
+            isError: response.status >= 400 || Boolean(output && typeof output === 'object' && 'error' in output),
+        };
+    }
+}

package/dist/authSecretStore.d.ts

@@ -0,0 +1,35 @@
+import { type AdminUser, type HttpExtra, type IAdminForth } from 'adminforth';
+import type { McpAuthSecretResourceOptions, McpClientInfo } from './types.js';
+type AdminUserWithExecutor = AdminUser & {
+    executedBy?: string;
+};
+export interface AuthenticatedMcpSecret {
+    adminUser: AdminUserWithExecutor;
+    client: McpClientInfo | null;
+    name: string;
+    recordId: string;
+}
+export declare class McpAuthSecretStore {
+    private readonly adminforth;
+    private readonly options;
+    private readonly resource;
+    constructor(adminforth: IAdminForth, options: McpAuthSecretResourceOptions);
+    list(adminUser: AdminUser): Promise<{
+        id: any;
+        name: any;
+        createdAt: any;
+        lastUsedAt: any;
+        lastUsedByAgent: any;
+    }[]>;
+    create(name: string, adminUser: AdminUser, extra: HttpExtra): Promise<{
+        error: string;
+        secret?: undefined;
+    } | {
+        secret: string;
+        error?: undefined;
+    }>;
+    revoke(id: string, adminUser: AdminUser, extra: HttpExtra): Promise<import("adminforth").DeleteResourceRecordResult>;
+    authenticate(secret: string): Promise<AuthenticatedMcpSecret | null>;
+    touch(recordId: string, client: McpClientInfo): void;
+}
+export {};

package/dist/authSecretStore.js

@@ -0,0 +1,98 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { Filters, Sorts, logger, } from 'adminforth';
+import { UNKNOWN_CLIENT } from './clientInfo.js';
+const SECRET_PREFIX = 'afmcp_';
+function hashSecret(secret) {
+    return createHash('sha256').update(secret).digest('hex');
+}
+export class McpAuthSecretStore {
+    adminforth;
+    options;
+    resource;
+    constructor(adminforth, options) {
+        this.adminforth = adminforth;
+        this.options = options;
+        this.resource = adminforth.config.resources.find((resource) => resource.resourceId === options.resourceId);
+    }
+    async list(adminUser) {
+        const fields = this.options;
+        const records = await this.adminforth.resource(fields.resourceId).list(Filters.EQ(fields.userIdField, adminUser.pk), undefined, undefined, Sorts.DESC(fields.createdAtField));
+        return records.map((record) => ({
+            id: record[fields.idField],
+            name: record[fields.nameField],
+            createdAt: record[fields.createdAtField],
+            lastUsedAt: record[fields.lastUsedAtField] ?? null,
+            lastUsedByAgent: record[fields.lastUsedByAgentField]
+                ? JSON.parse(record[fields.lastUsedByAgentField])
+                : null,
+        }));
+    }
+    async create(name, adminUser, extra) {
+        const fields = this.options;
+        const secret = `${SECRET_PREFIX}${randomBytes(32).toString('base64url')}`;
+        const result = await this.adminforth.createResourceRecord({
+            resource: this.resource,
+            adminUser,
+            extra,
+            record: {
+                [fields.idField]: randomUUID(),
+                [fields.nameField]: name,
+                [fields.secretHashField]: hashSecret(secret),
+                [fields.userIdField]: adminUser.pk,
+                [fields.createdAtField]: new Date().toISOString(),
+                [fields.lastUsedAtField]: null,
+                [fields.lastUsedByAgentField]: null,
+            },
+        });
+        return result.error ? { error: result.error } : { secret };
+    }
+    async revoke(id, adminUser, extra) {
+        const fields = this.options;
+        const record = await this.adminforth.resource(fields.resourceId).get(Filters.AND(Filters.EQ(fields.idField, id), Filters.EQ(fields.userIdField, adminUser.pk)));
+        if (!record)
+            return { error: 'MCP auth secret not found' };
+        return this.adminforth.deleteResourceRecord({
+            resource: this.resource,
+            record,
+            recordId: id,
+            adminUser,
+            extra,
+        });
+    }
+    async authenticate(secret) {
+        const fields = this.options;
+        const record = await this.adminforth.resource(fields.resourceId).get(Filters.EQ(fields.secretHashField, hashSecret(secret)));
+        if (!record)
+            return null;
+        const auth = this.adminforth.config.auth;
+        const usersResource = this.adminforth.config.resources.find((resource) => resource.resourceId === auth.usersResourceId);
+        const userPrimaryKeyField = usersResource.columns.find((column) => column.primaryKey).name;
+        const dbUser = await this.adminforth.resource(usersResource.resourceId).get(Filters.EQ(userPrimaryKeyField, record[fields.userIdField]));
+        if (!dbUser)
+            return null;
+        return {
+            adminUser: {
+                pk: record[fields.userIdField],
+                username: dbUser[auth.usernameField],
+                dbUser,
+            },
+            client: record[fields.lastUsedByAgentField]
+                ? JSON.parse(record[fields.lastUsedByAgentField])
+                : null,
+            name: record[fields.nameField],
+            recordId: record[fields.idField],
+        };
+    }
+    touch(recordId, client) {
+        const fields = this.options;
+        const updates = {
+            [fields.lastUsedAtField]: new Date().toISOString(),
+        };
+        if (client.client !== UNKNOWN_CLIENT) {
+            updates[fields.lastUsedByAgentField] = JSON.stringify(client);
+        }
+        void this.adminforth.resource(fields.resourceId).update(recordId, updates).catch((error) => {
+            logger.error(`AdminForthMcpPlugin: failed to update MCP auth secret usage: ${String(error)}`);
+        });
+    }
+}

package/dist/clientInfo.d.ts

@@ -0,0 +1,5 @@
+import type { McpClientInfo } from './types.js';
+export declare const UNKNOWN_CLIENT = "unknown-agent";
+export declare function readMcpClient(body: Record<string, any>, headers: Record<string, any>): McpClientInfo;
+export declare function canonicalAgentName(client: string): string;
+export declare function formatMcpExecutedBy(client: McpClientInfo, authSecretName: string): string;

package/dist/clientInfo.js

@@ -0,0 +1,40 @@
+const CLIENT_INFO_META_KEY = 'io.modelcontextprotocol/clientInfo';
+const NON_CLIENT_NAME_CHARACTER_RE = /[^a-z0-9]+/g;
+const EDGE_HYPHEN_RE = /^-+|-+$/g;
+const USER_AGENT_PRODUCT_RE = /^([^/\s]+)(?:\/(\S+))?/;
+export const UNKNOWN_CLIENT = 'unknown-agent';
+function normalizeClientName(name) {
+    return name.toLowerCase().replace(NON_CLIENT_NAME_CHARACTER_RE, '-').replace(EDGE_HYPHEN_RE, '');
+}
+function parseUserAgent(userAgent) {
+    const [, name, version] = userAgent.match(USER_AGENT_PRODUCT_RE) ?? [];
+    return name ? { client: normalizeClientName(name), ver: version ?? null } : null;
+}
+export function readMcpClient(body, headers) {
+    const clientInfo = body.params?._meta?.[CLIENT_INFO_META_KEY] ?? (body.method === 'initialize' ? body.params?.clientInfo : undefined);
+    if (clientInfo?.name) {
+        return {
+            client: normalizeClientName(clientInfo.name),
+            ver: clientInfo.version ?? null,
+        };
+    }
+    return parseUserAgent(String(headers['user-agent'] ?? '')) ?? {
+        client: UNKNOWN_CLIENT,
+        ver: null,
+    };
+}
+export function canonicalAgentName(client) {
+    if (client.includes('claude') && client.includes('code'))
+        return 'claude-code';
+    if (client.includes('claude'))
+        return 'claude';
+    if (client.includes('codex') || client.includes('openai') || client === 'undici')
+        return 'codex';
+    if (client.includes('gemini'))
+        return 'gemini';
+    return client;
+}
+export function formatMcpExecutedBy(client, authSecretName) {
+    const version = client.ver ? `@${client.ver}` : '';
+    return `${canonicalAgentName(client.client)}${version} | ${authSecretName}`;
+}

package/dist/custom/McpSettings.vue

@@ -0,0 +1,230 @@
+<template>
+  <div class="flex flex-col justify-center mr-6 md:mr-12">
+    <div class="flex flex-wrap items-start justify-between gap-4">
+      <div>
+        <h2 class="text-3xl font-semibold leading-none text-gray-800 dark:text-gray-50">
+          {{ $t('MCP Settings') }}
+        </h2>
+        <p class="mt-3 text-sm text-gray-600 dark:text-gray-300">
+          {{ $t('Create a separate auth secret for each AI agent. Secrets are shown only once.') }}
+        </p>
+      </div>
+      <button
+        type="button"
+        class="rounded-lg bg-blue-700 px-4 py-2 text-sm font-medium text-white hover:bg-blue-800 dark:bg-blue-600 dark:hover:bg-blue-700"
+        @click="openCreateDialog"
+      >
+        {{ $t('Create auth secret') }}
+      </button>
+    </div>
+
+    <div class="mt-6 rounded-lg border border-gray-200 bg-gray-50 p-4 dark:border-gray-700 dark:bg-gray-800">
+      <p class="text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('MCP server URL') }}</p>
+      <div class="mt-2 flex items-center gap-2">
+        <code class="min-w-0 flex-1 overflow-x-auto rounded bg-white px-3 py-2 text-sm text-gray-800 dark:bg-gray-900 dark:text-gray-100">{{ mcpUrl }}</code>
+        <button class="text-sm font-medium text-blue-700 dark:text-blue-400" @click="copy(mcpUrl)">
+          {{ $t('Copy') }}
+        </button>
+      </div>
+      <p class="mt-3 text-sm text-gray-600 dark:text-gray-300">
+        <code>Authorization: Bearer &lt;secret&gt;</code>
+      </p>
+    </div>
+
+    <div v-if="authSecrets.length" class="mt-6 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+      <table class="min-w-full divide-y divide-gray-200 dark:divide-gray-700">
+        <thead class="bg-gray-50 dark:bg-gray-800">
+          <tr>
+            <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('Name') }}</th>
+            <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('Last used by') }}</th>
+            <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('Last usage') }}</th>
+            <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('Actions') }}</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-gray-200 bg-white dark:divide-gray-700 dark:bg-gray-900">
+          <tr v-for="authSecret in authSecrets" :key="authSecret.id">
+            <td class="px-4 py-3">
+              <p class="font-medium text-gray-900 dark:text-white">{{ authSecret.name }}</p>
+              <p class="mt-0.5 text-xs text-gray-500 dark:text-gray-400">{{ formatDate(authSecret.createdAt) }}</p>
+            </td>
+            <td class="px-4 py-3 text-sm text-gray-700 dark:text-gray-200">
+              <div v-if="authSecret.lastUsedByAgent" class="flex items-center gap-2">
+                <img v-if="describeAgent(authSecret.lastUsedByAgent).icon" :src="describeAgent(authSecret.lastUsedByAgent).icon" class="h-5 w-5" alt="" />
+                <span>{{ describeAgent(authSecret.lastUsedByAgent).label }}</span>
+              </div>
+              <span v-else class="text-gray-400">{{ $t('Not used yet') }}</span>
+            </td>
+            <td class="px-4 py-3 text-sm text-gray-500 dark:text-gray-400">
+              {{ authSecret.lastUsedAt ? formatDate(authSecret.lastUsedAt) : $t('Never') }}
+            </td>
+            <td class="px-4 py-3 text-right">
+              <button
+                type="button"
+                class="rounded-md border border-red-300 px-3 py-1.5 text-sm font-medium text-red-700 hover:bg-red-50 disabled:opacity-50 dark:border-red-700 dark:text-red-300 dark:hover:bg-red-950"
+                :disabled="revokingId === authSecret.id"
+                @click="revoke(authSecret)"
+              >
+                {{ revokingId === authSecret.id ? $t('Revoking') : $t('Revoke') }}
+              </button>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+    <p v-else-if="!loading" class="mt-6 text-sm text-gray-500 dark:text-gray-400">
+      {{ $t('No MCP auth secrets yet.') }}
+    </p>
+
+    <div v-if="dialogOpen" class="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4">
+      <div class="w-full max-w-xl rounded-xl bg-white p-6 shadow-xl dark:bg-gray-800">
+        <template v-if="!createdSecret">
+          <h3 class="text-xl font-semibold text-gray-900 dark:text-white">{{ $t('Create MCP auth secret') }}</h3>
+          <p class="mt-2 text-sm text-gray-500 dark:text-gray-400">{{ $t('Use one auth secret for one agent.') }}</p>
+          <label class="mt-5 block text-sm font-medium text-gray-700 dark:text-gray-200">{{ $t('Secret name') }}</label>
+          <input
+            v-model="secretName"
+            class="mt-2 block w-full rounded-lg border border-gray-300 bg-gray-50 p-2.5 text-sm text-gray-900 dark:border-gray-600 dark:bg-gray-700 dark:text-white"
+            placeholder="Claude Code"
+            @keydown.enter="createAuthSecret"
+          />
+          <div class="mt-6 flex justify-end gap-3">
+            <button class="px-4 py-2 text-sm text-gray-600 dark:text-gray-300" @click="closeDialog">{{ $t('Cancel') }}</button>
+            <button
+              class="rounded-lg bg-blue-700 px-4 py-2 text-sm font-medium text-white disabled:opacity-50 dark:bg-blue-600"
+              :disabled="creating || !secretName.trim()"
+              @click="createAuthSecret"
+            >
+              {{ creating ? $t('Creating') : $t('Create') }}
+            </button>
+          </div>
+        </template>
+        <template v-else>
+          <h3 class="text-xl font-semibold text-gray-900 dark:text-white">{{ $t('Auth secret created') }}</h3>
+          <p class="mt-2 text-sm text-amber-700 dark:text-amber-300">{{ $t('Copy it now. You will not be able to view it again.') }}</p>
+          <code class="mt-4 block overflow-x-auto rounded-lg bg-gray-100 p-3 text-sm text-gray-900 dark:bg-gray-900 dark:text-gray-100">{{ createdSecret }}</code>
+          <p class="mt-5 text-xs font-medium uppercase text-gray-500 dark:text-gray-400">{{ $t('Prompt for your agent') }}</p>
+          <pre class="mt-2 whitespace-pre-wrap rounded-lg bg-gray-100 p-3 text-sm text-gray-800 dark:bg-gray-900 dark:text-gray-100">{{ setupPrompt }}</pre>
+          <div class="mt-6 flex justify-end gap-3">
+            <button class="text-sm font-medium text-blue-700 dark:text-blue-400" @click="copy(setupPrompt)">{{ $t('Copy prompt') }}</button>
+            <button class="rounded-lg bg-blue-700 px-4 py-2 text-sm font-medium text-white dark:bg-blue-600" @click="closeDialog">{{ $t('Done') }}</button>
+          </div>
+        </template>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue';
+import { callAdminForthApi } from '@/utils';
+import claudeCodeIcon from './icons/claude-code.svg';
+import codexIcon from './icons/codex.svg';
+import geminiIcon from './icons/gemini.svg';
+
+type Agent = { client: string; ver: string | null };
+type AuthSecret = {
+  id: string;
+  name: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+  lastUsedByAgent: Agent | null;
+};
+
+const authSecrets = ref<AuthSecret[]>([]);
+const loading = ref(true);
+const dialogOpen = ref(false);
+const secretName = ref('');
+const createdSecret = ref('');
+const creating = ref(false);
+const revokingId = ref<string | null>(null);
+
+const mcpUrl = computed(() => {
+  const baseUrl = (import.meta.env.VITE_ADMINFORTH_PUBLIC_PATH || '').replace(/\/$/, '');
+  return `${window.location.origin}${baseUrl}/adminapi/v1/mcp`;
+});
+const setupPrompt = computed(() => [
+  'Add this remote MCP server to the current agent:',
+  `URL: ${mcpUrl.value}`,
+  `Header: Authorization: Bearer ${createdSecret.value || '<secret>'}`,
+  'Use this auth secret only for this agent.',
+].join('\n'));
+
+onMounted(loadAuthSecrets);
+
+async function loadAuthSecrets() {
+  loading.value = true;
+  try {
+    const response = await callAdminForthApi({ method: 'GET', path: '/mcp/auth-secrets' });
+    if (response) authSecrets.value = response.authSecrets;
+  } finally {
+    loading.value = false;
+  }
+}
+
+function openCreateDialog() {
+  secretName.value = '';
+  createdSecret.value = '';
+  dialogOpen.value = true;
+}
+
+function closeDialog() {
+  dialogOpen.value = false;
+  createdSecret.value = '';
+}
+
+async function createAuthSecret() {
+  creating.value = true;
+  try {
+    const response = await callAdminForthApi({
+      method: 'POST',
+      path: '/mcp/auth-secrets',
+      body: { name: secretName.value.trim() },
+    });
+    if (response?.secret) {
+      createdSecret.value = response.secret;
+      await loadAuthSecrets();
+    }
+  } finally {
+    creating.value = false;
+  }
+}
+
+async function revoke(authSecret: AuthSecret) {
+  if (!window.confirm(`Revoke MCP auth secret "${authSecret.name}"?`)) return;
+  revokingId.value = authSecret.id;
+  try {
+    await callAdminForthApi({ method: 'DELETE', path: '/mcp/auth-secrets', body: { id: authSecret.id } });
+    await loadAuthSecrets();
+  } finally {
+    revokingId.value = null;
+  }
+}
+
+function describeAgent(agent: Agent) {
+  const client = agent.client;
+  let name = client.split('-').map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+  let icon: string | null = null;
+  if (client.includes('claude') && client.includes('code')) {
+    name = 'Claude Code';
+    icon = claudeCodeIcon;
+  } else if (client.includes('claude')) {
+    name = 'Claude';
+    icon = claudeCodeIcon;
+  } else if (client.includes('codex') || client.includes('openai') || client === 'undici') {
+    name = 'Codex';
+    icon = codexIcon;
+  } else if (client.includes('gemini')) {
+    name = 'Gemini';
+    icon = geminiIcon;
+  }
+  return { label: agent.ver ? `${name} v${agent.ver}` : name, icon };
+}
+
+function formatDate(value: string) {
+  return new Date(value).toLocaleString();
+}
+
+async function copy(value: string) {
+  await navigator.clipboard.writeText(value);
+}
+</script>

package/dist/custom/icons/claude-code.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#d97757" fill-rule="evenodd" d="M21 10.95h3v3.1h-3v3.03h-1.49V20H18v-2.92h-1.49V20H15v-2.92H9V20H7.49v-2.92H6V20H4.49v-2.92H3v-3.03H0v-3.1h3V5h18zM6 10.95h1.49V8.1H6zm10.51 0H18V8.1h-1.49z" clip-rule="evenodd"/></svg>

package/dist/custom/icons/codex.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#2f80ed" fill-rule="evenodd" d="M8.09.46a6.1 6.1 0 0 1 6.61 1.28 6.1 6.1 0 0 1 7.54 7.46 6.1 6.1 0 0 1-2.79 10.26 6.1 6.1 0 0 1-10.22 2.78 6.1 6.1 0 0 1-7.53-7.43A6.1 6.1 0 0 1 4.55 4.53 6 6 0 0 1 8.09.46M7.28 8.31a.85.85 0 0 0-1.47.84l1.69 2.96-1.69 2.85a.85.85 0 0 0 1.46.87l1.94-3.28a.85.85 0 0 0 .01-.85zm5.45 6.24a.85.85 0 0 0 0 1.69h4.85a.85.85 0 0 0 0-1.69z" clip-rule="evenodd"/></svg>

package/dist/custom/icons/gemini.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><defs><linearGradient id="g" x1="3" y1="20" x2="21" y2="4" gradientUnits="userSpaceOnUse"><stop stop-color="#14b86e"/><stop offset=".45" stop-color="#3689ff"/><stop offset="1" stop-color="#fa4340"/></linearGradient></defs><path fill="url(#g)" d="M12 0c.7 6.8 5.2 11.3 12 12-6.8.7-11.3 5.2-12 12C11.3 17.2 6.8 12.7 0 12 6.8 11.3 11.3 6.8 12 0"/></svg>

package/dist/custom/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".", // This should point to your project root
+    "paths": {
+      "@/*": [
+        "../node_modules/adminforth/dist/spa/src/*"
+      ],
+      "*": [
+        "../node_modules/adminforth/dist/spa/node_modules/*"
+      ],
+      "@@/*": [
+        "."
+      ]
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { AdminForthPlugin, type IAdminForth, type IHttpServer } from 'adminforth';
+import type { PluginOptions } from './types.js';
+export default class AdminForthMcpPlugin extends AdminForthPlugin {
+    options: PluginOptions;
+    pluginsScope: 'global';
+    private authSecretStore;
+    private apiTools;
+    private serverPresentation;
+    constructor(options: PluginOptions);
+    instanceUniqueRepresentation(): string;
+    modifyGlobalConfig(adminforth: IAdminForth): void;
+    private validateAuthSecretResource;
+    setupEndpoints(server: IHttpServer): void;
+    private handleMcpRequest;
+}
+export type { McpAuthSecretResourceOptions, PluginOptions } from './types.js';
+export { canonicalAgentName, formatMcpExecutedBy, readMcpClient } from './clientInfo.js';
+export { handleMcpProtocol } from './mcpProtocol.js';

package/dist/index.js

@@ -0,0 +1,181 @@
+import { AdminForthPlugin, } 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';
+function requestExtra(input) {
+    return {
+        body: input.body,
+        query: input.query,
+        headers: input.headers,
+        cookies: input.cookies,
+        requestUrl: input.requestUrl,
+        response: input.response,
+    };
+}
+function jsonRpcAuthError(id = null) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32001, message: 'Invalid or revoked MCP auth secret.' },
+    };
+}
+export default class AdminForthMcpPlugin extends AdminForthPlugin {
+    options;
+    pluginsScope = 'global';
+    authSecretStore;
+    apiTools;
+    serverPresentation;
+    constructor(options) {
+        super(options, import.meta.url);
+        this.options = options;
+        this.shouldHaveSingleInstancePerWholeApp = () => true;
+    }
+    instanceUniqueRepresentation() {
+        return 'single';
+    }
+    modifyGlobalConfig(adminforth) {
+        super.modifyGlobalConfig(adminforth);
+        const authSecretResource = adminforth.config.resources.find((resource) => resource.resourceId === this.options.authSecretResource.resourceId);
+        if (!authSecretResource) {
+            throw new Error(`AdminForthMcpPlugin: auth secret resource "${this.options.authSecretResource.resourceId}" not found`);
+        }
+        this.validateAuthSecretResource(authSecretResource);
+        const secretHashColumn = authSecretResource.columns.find((column) => column.name === this.options.authSecretResource.secretHashField);
+        secretHashColumn.backendOnly = true;
+        secretHashColumn.showIn = {
+            show: false,
+            list: false,
+            create: false,
+            edit: false,
+            filter: false,
+        };
+        const auth = adminforth.config.auth;
+        auth.userMenuSettingsPages ??= [];
+        if (!auth.userMenuSettingsPages.some((page) => page.slug === 'mcp')) {
+            auth.userMenuSettingsPages.push({
+                icon: 'flowbite:server-outline',
+                pageLabel: 'MCP Settings',
+                slug: 'mcp',
+                component: this.componentPath('McpSettings.vue'),
+                isVisible: () => true,
+            });
+        }
+        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);
+    }
+    validateAuthSecretResource(resource) {
+        const fields = this.options.authSecretResource;
+        for (const fieldName of [
+            fields.idField,
+            fields.nameField,
+            fields.secretHashField,
+            fields.userIdField,
+            fields.createdAtField,
+            fields.lastUsedAtField,
+            fields.lastUsedByAgentField,
+        ]) {
+            if (!resource.columns.some((column) => column.name === fieldName)) {
+                throw new Error(`AdminForthMcpPlugin: column "${fieldName}" not found in auth secret resource "${resource.resourceId}"`);
+            }
+        }
+        if (!resource.columns.find((column) => column.name === fields.idField).primaryKey) {
+            throw new Error(`AdminForthMcpPlugin: column "${fields.idField}" must be the primary key of auth secret resource "${resource.resourceId}"`);
+        }
+    }
+    setupEndpoints(server) {
+        server.endpoint({
+            method: 'GET',
+            path: `${MCP_PATH}/auth-secrets`,
+            handler: async ({ adminUser }) => ({
+                authSecrets: await this.authSecretStore.list(adminUser),
+            }),
+        });
+        server.endpoint({
+            method: 'POST',
+            path: `${MCP_PATH}/auth-secrets`,
+            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));
+            },
+        });
+        server.endpoint({
+            method: 'DELETE',
+            path: `${MCP_PATH}/auth-secrets`,
+            handler: async (input) => {
+                const result = await this.authSecretStore.revoke(String(input.body.id), input.adminUser, requestExtra(input));
+                if (result.error)
+                    input.response.setStatus(404);
+                return result;
+            },
+        });
+        server.endpoint({
+            method: 'POST',
+            path: MCP_PATH,
+            noAuth: true,
+            handler: async (input) => this.handleMcpRequest(input),
+        });
+    }
+    async handleMcpRequest(input) {
+        if (input.headers.origin) {
+            input.response.setStatus(403);
+            return {
+                jsonrpc: '2.0',
+                id: input.body.id ?? null,
+                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;
+        if (!authenticated) {
+            input.response.setHeader('WWW-Authenticate', 'Bearer');
+            input.response.setStatus(401);
+            return jsonRpcAuthError(input.body.id ?? null);
+        }
+        const authorization = await this.adminforth.auth.runAdminUserAuthorizeHooks(authenticated.adminUser, input.response, requestExtra(input));
+        if (!authorization.allowed) {
+            input.response.setStatus(403);
+            return jsonRpcAuthError(input.body.id ?? null);
+        }
+        const reportedClient = readMcpClient(input.body, input.headers);
+        const client = reportedClient.client === UNKNOWN_CLIENT && authenticated.client
+            ? authenticated.client
+            : reportedClient;
+        this.authSecretStore.touch(authenticated.recordId, reportedClient);
+        const adminUser = {
+            ...authenticated.adminUser,
+            executedBy: formatMcpExecutedBy(client, authenticated.name),
+        };
+        const protocolResponse = await handleMcpProtocol({
+            ...this.serverPresentation,
+            body: input.body,
+            headers: input.headers,
+            listTools: () => this.apiTools.list(),
+            callTool: (name, arguments_) => this.apiTools.call({
+                name,
+                arguments: arguments_,
+                adminUser,
+                headers: input.headers,
+                requestUrl: input.requestUrl,
+                abortSignal: input.abortSignal,
+            }),
+        });
+        input.response.setStatus(protocolResponse.status);
+        if (!protocolResponse.body) {
+            input._raw_express_res.status(protocolResponse.status).end();
+            return null;
+        }
+        return protocolResponse.body;
+    }
+}
+export { canonicalAgentName, formatMcpExecutedBy, readMcpClient } from './clientInfo.js';
+export { handleMcpProtocol } from './mcpProtocol.js';

package/dist/mcpProtocol.d.ts

@@ -0,0 +1,31 @@
+import type { McpToolDefinition } from './apiTools.js';
+export declare const MODERN_PROTOCOL_VERSION = "2026-07-28";
+export declare const LEGACY_PROTOCOL_VERSION = "2025-11-25";
+export interface McpServerInfo {
+    name: string;
+    title: string;
+    version: string;
+    description: string;
+    websiteUrl?: string;
+}
+export interface McpServerPresentation {
+    serverInfo: McpServerInfo;
+    instructions: string;
+}
+export declare function createMcpServerPresentation(brandName: string, adminPanelOrigin?: string, baseUrl?: string): McpServerPresentation;
+export interface McpProtocolContext {
+    body: Record<string, any>;
+    headers: Record<string, any>;
+    serverInfo: McpServerInfo;
+    instructions: string;
+    listTools: () => McpToolDefinition[];
+    callTool: (name: string, arguments_: Record<string, unknown> | undefined) => Promise<{
+        output: unknown;
+        isError: boolean;
+    }>;
+}
+export interface McpProtocolResponse {
+    status: number;
+    body?: Record<string, unknown>;
+}
+export declare function handleMcpProtocol(context: McpProtocolContext): Promise<McpProtocolResponse>;

package/dist/mcpProtocol.js

@@ -0,0 +1,137 @@
+export const MODERN_PROTOCOL_VERSION = '2026-07-28';
+export const LEGACY_PROTOCOL_VERSION = '2025-11-25';
+const LEGACY_PROTOCOL_VERSIONS = new Set([
+    LEGACY_PROTOCOL_VERSION,
+    '2025-06-18',
+    '2025-03-26',
+]);
+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;
+    const adminPanel = `AdminForth admin panel for "${brandName}"${adminPanelUrl ? ` at ${adminPanelUrl}` : ''}`;
+    return {
+        serverInfo: {
+            name: 'adminforth-mcp',
+            title: `${brandName} Admin Panel`,
+            version: '1.0.0',
+            description: `${adminPanel}.`,
+            ...(adminPanelUrl && { websiteUrl: adminPanelUrl }),
+        },
+        instructions: `This is the ${adminPanel}. Use its tools to read and update data allowed for the authenticated user.`,
+    };
+}
+function errorResponse(id, code, message, status = 400) {
+    return {
+        status,
+        body: { jsonrpc: '2.0', id, error: { code, message } },
+    };
+}
+function isModernRequest(body) {
+    return body.params?._meta?.[PROTOCOL_VERSION_META_KEY] === MODERN_PROTOCOL_VERSION;
+}
+function completeResult(result, modern, serverInfo) {
+    if (!modern)
+        return result;
+    return {
+        resultType: 'complete',
+        ...result,
+        _meta: {
+            ...result._meta,
+            [SERVER_INFO_META_KEY]: serverInfo,
+        },
+    };
+}
+function successResponse(id, result, modern, serverInfo) {
+    return {
+        status: 200,
+        body: {
+            jsonrpc: '2.0',
+            id,
+            result: completeResult(result, modern, serverInfo),
+        },
+    };
+}
+function validateModernHeaders(body, headers) {
+    const meta = body.params?._meta;
+    if (!meta || !(CLIENT_CAPABILITIES_META_KEY in meta)) {
+        return errorResponse(body.id ?? null, -32602, 'Missing required MCP request metadata.');
+    }
+    if (headers['mcp-protocol-version'] !== MODERN_PROTOCOL_VERSION
+        || headers['mcp-method'] !== body.method
+        || (body.method === 'tools/call' && headers['mcp-name'] !== body.params?.name)) {
+        return errorResponse(body.id ?? null, -32020, 'MCP request headers do not match the JSON-RPC body.');
+    }
+    return null;
+}
+function serializeToolOutput(output) {
+    return typeof output === 'string' ? output : JSON.stringify(output, null, 2);
+}
+export async function handleMcpProtocol(context) {
+    const { body, headers, serverInfo, instructions } = context;
+    if (body.jsonrpc !== '2.0' || typeof body.method !== 'string') {
+        return errorResponse(body.id ?? null, -32600, 'Invalid JSON-RPC request.');
+    }
+    const modern = isModernRequest(body);
+    const requestedVersion = body.params?._meta?.[PROTOCOL_VERSION_META_KEY];
+    if (requestedVersion && requestedVersion !== MODERN_PROTOCOL_VERSION) {
+        return errorResponse(body.id ?? null, -32000, `Unsupported MCP protocol version: ${requestedVersion}`);
+    }
+    if (modern) {
+        const headerError = validateModernHeaders(body, headers);
+        if (headerError)
+            return headerError;
+    }
+    if (body.id === undefined) {
+        return { status: 202 };
+    }
+    if (typeof body.id !== 'string' && typeof body.id !== 'number') {
+        return errorResponse(null, -32600, 'JSON-RPC id must be a string or number.');
+    }
+    switch (body.method) {
+        case 'server/discover':
+            if (!modern) {
+                return errorResponse(body.id, -32602, 'server/discover requires modern MCP request metadata.');
+            }
+            return successResponse(body.id, {
+                supportedVersions: [MODERN_PROTOCOL_VERSION],
+                capabilities: { tools: {} },
+                instructions,
+                ttlMs: 0,
+                cacheScope: 'private',
+            }, true, serverInfo);
+        case 'initialize': {
+            const requestedVersion = body.params?.protocolVersion;
+            return successResponse(body.id, {
+                protocolVersion: typeof requestedVersion === 'string' && LEGACY_PROTOCOL_VERSIONS.has(requestedVersion)
+                    ? requestedVersion
+                    : LEGACY_PROTOCOL_VERSION,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo,
+                instructions,
+            }, false, serverInfo);
+        }
+        case 'ping':
+            return successResponse(body.id, {}, modern, serverInfo);
+        case 'tools/list':
+            return successResponse(body.id, {
+                tools: context.listTools(),
+                ...(modern && { ttlMs: 0, cacheScope: 'private' }),
+            }, modern, serverInfo);
+        case 'tools/call': {
+            if (typeof body.params?.name !== 'string') {
+                return errorResponse(body.id, -32602, 'Tool name is required.');
+            }
+            const result = await context.callTool(body.params.name, body.params.arguments);
+            return successResponse(body.id, {
+                content: [{ type: 'text', text: serializeToolOutput(result.output) }],
+                isError: result.isError,
+            }, modern, serverInfo);
+        }
+        default:
+            return errorResponse(body.id, -32601, `Method not found: ${body.method}`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type { PluginsCommonOptions } from 'adminforth';
+export interface McpAuthSecretResourceOptions {
+    resourceId: string;
+    idField: string;
+    nameField: string;
+    secretHashField: string;
+    userIdField: string;
+    createdAtField: string;
+    lastUsedAtField: string;
+    lastUsedByAgentField: string;
+}
+export interface PluginOptions extends PluginsCommonOptions {
+    authSecretResource: McpAuthSecretResourceOptions;
+    /** Public origin of this AdminForth installation, without the AdminForth baseUrl path. */
+    adminPanelOrigin?: string;
+}
+export interface McpClientInfo {
+    client: string;
+    ver: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@adminforth/mcp",
+  "version": "1.0.0",
+  "description": "Expose AdminForth APIs as an authenticated MCP server",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://adminforth.dev/docs/tutorial/Plugins/mcp/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devforth/adminforth-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devforth/adminforth-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && rsync -av --exclude 'node_modules' custom dist/",
+    "test": "pnpm build && node --test tests/*.test.mjs"
+  },
+  "keywords": [
+    "adminforth",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "codex",
+    "claude",
+    "gemini"
+  ],
+  "author": "DevForth (https://devforth.io)",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "latest",
+    "adminforth": "^3.20.0",
+    "semantic-release": "^24.2.1",
+    "semantic-release-slack-bot": "^4.0.2",
+    "typescript": "^5.7.3"
+  },
+  "peerDependencies": {
+    "adminforth": "^3.20.0"
+  },
+  "release": {
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "semantic-release-slack-bot",
+        {
+          "packageName": "@adminforth/mcp",
+          "notifyOnSuccess": true,
+          "notifyOnFail": true,
+          "slackIcon": ":package:",
+          "markdownReleaseNotes": true
+        }
+      ]
+    ],
+    "branches": [
+      "main",
+      {
+        "name": "next",
+        "prerelease": true
+      }
+    ]
+  }
+}