@adminforth/mcp 1.0.3 → 1.1.0

package/dist/apiTools.d.ts

@@ -4,7 +4,8 @@ export interface McpToolDefinition {
     description?: string;
     inputSchema: Record<string, unknown>;
     annotations?: {
-        destructiveHint: boolean;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
     };
 }
 export declare class AdminForthApiTools {
@@ -12,7 +13,7 @@ export declare class AdminForthApiTools {
     private readonly hiddenResourceIds;
     constructor(adminforth: IAdminForth, hiddenResourceIds: ReadonlySet<string>);
     private schemas;
-    list(): McpToolDefinition[];
+    list(readOnly: boolean): McpToolDefinition[];
     call(params: {
         name: string;
         arguments?: Record<string, unknown>;
@@ -20,6 +21,7 @@ export declare class AdminForthApiTools {
         headers: Record<string, any>;
         requestUrl: string;
         abortSignal: AbortSignal;
+        readOnly: boolean;
     }): Promise<{
         output: unknown;
         isError: boolean;

package/dist/apiTools.js

@@ -1,6 +1,6 @@
 const METHODS_WITHOUT_REQUEST_BODY = new Set(['GET', 'HEAD']);
 function isRegisteredToolSchema(schema) {
-    return typeof schema.handler === 'function';
+    return typeof schema.handler === 'function' && !schema.agent?.hiddenFromAgents;
 }
 function endpointPathToToolName(path) {
     return path
@@ -34,20 +34,19 @@ export class AdminForthApiTools {
         this.adminforth = adminforth;
         this.hiddenResourceIds = hiddenResourceIds;
     }
-    schemas() {
+    schemas(readOnly) {
         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/'))
+            if (readOnly && !schema.agent?.onlyReadsData)
                 continue;
-            schemas.set(endpointPathToToolName(path), schema);
+            schemas.set(endpointPathToToolName(stripAdminApiPrefix(schema.path, this.adminforth)), schema);
         }
         return schemas;
     }
-    list() {
-        return Array.from(this.schemas().entries())
+    list(readOnly) {
+        return Array.from(this.schemas(readOnly).entries())
             .sort(([left], [right]) => left.localeCompare(right))
             .map(([name, schema]) => ({
             name,
@@ -57,13 +56,16 @@ export class AdminForthApiTools {
                 properties: {},
                 additionalProperties: true,
             },
-            ...(schema.agent?.isDangerous && {
+            ...(schema.agent?.onlyReadsData && {
+                annotations: { readOnlyHint: true },
+            }),
+            ...(schema.agent?.requiresHumanApproval && {
                 annotations: { destructiveHint: true },
             }),
         }));
     }
     async call(params) {
-        const schema = this.schemas().get(params.name);
+        const schema = this.schemas(params.readOnly).get(params.name);
         if (!schema) {
             return { output: { error: `Unknown tool: ${params.name}` }, isError: true };
         }

package/dist/authSecretStore.d.ts

@@ -7,6 +7,7 @@ export interface AuthenticatedMcpSecret {
     adminUser: AdminUserWithExecutor;
     client: McpClientInfo | null;
     name: string;
+    readOnly: boolean;
     recordId: string;
 }
 export declare class McpAuthSecretStore {
@@ -20,8 +21,9 @@ export declare class McpAuthSecretStore {
         createdAt: any;
         lastUsedAt: any;
         lastUsedByAgent: McpClientInfo | null;
+        readOnly: any;
     }[]>;
-    create(name: string, adminUser: AdminUser, extra: HttpExtra): Promise<{
+    create(name: string, readOnly: boolean, adminUser: AdminUser, extra: HttpExtra): Promise<{
         error: string;
         secret?: undefined;
     } | {

package/dist/authSecretStore.js

@@ -42,9 +42,10 @@ export class McpAuthSecretStore {
             createdAt: record[fields.createdAtField],
             lastUsedAt: record[fields.lastUsedAtField] ?? null,
             lastUsedByAgent: parseStoredClient(record[fields.lastUsedByAgentField]),
+            readOnly: record[fields.readOnlyField],
         }));
     }
-    async create(name, adminUser, extra) {
+    async create(name, readOnly, adminUser, extra) {
         const fields = this.options;
         const secret = `${SECRET_PREFIX}${randomBytes(32).toString('base64url')}`;
         const result = await this.adminforth.createResourceRecord({
@@ -59,6 +60,7 @@ export class McpAuthSecretStore {
                 [fields.createdAtField]: new Date().toISOString(),
                 [fields.lastUsedAtField]: null,
                 [fields.lastUsedByAgentField]: null,
+                [fields.readOnlyField]: readOnly,
             },
         });
         return result.error ? { error: result.error } : { secret };
@@ -95,6 +97,7 @@ export class McpAuthSecretStore {
             },
             client: parseStoredClient(record[fields.lastUsedByAgentField]),
             name: record[fields.nameField],
+            readOnly: record[fields.readOnlyField],
             recordId: record[fields.idField],
         };
     }

package/dist/custom/McpSettings.vue

@@ -35,8 +35,16 @@
       :pageSize="10"
     >
       <template #cell:name="{ item }">
-        <p class="font-medium text-gray-900 dark:text-white">{{ item.name }}</p>
-        <p class="mt-0.5 text-xs text-gray-500 dark:text-gray-400">{{ formatDate(item.createdAt) }}</p>
+        <p class="font-medium text-gray-900 dark:text-white">
+          {{ item.name }}
+          <span
+            v-if="serverReadOnly || item.readOnly"
+            class="ml-2 rounded bg-gray-100 px-1.5 py-0.5 text-xs font-medium text-gray-600 dark:bg-gray-700 dark:text-gray-300"
+          >
+            {{ $t('Read only') }}
+          </span>
+        </p>
+        <p class="mt-0.5 text-xs text-gray-500 dark:text-gray-400">{{ formatDateTime(item.createdAt) }}</p>
       </template>
 
       <template #cell:lastUsedByAgent="{ item }">
@@ -48,7 +56,7 @@
       </template>
 
       <template #cell:lastUsedAt="{ item }">
-        {{ item.lastUsedAt ? formatDate(item.lastUsedAt) : $t('Never') }}
+        {{ item.lastUsedAt ? formatDateTime(item.lastUsedAt) : $t('Never') }}
       </template>
 
       <template #cell:actions="{ item }">
@@ -78,11 +86,19 @@
         <div class="mt-2">
           <Input v-model="secretName" type="text" fullWidth placeholder="Claude Code" />
         </div>
+        <Checkbox v-if="!serverReadOnly" v-model="secretReadOnly" class="mt-4">
+          {{ $t('Read only: the agent can only read data') }}
+        </Checkbox>
       </div>
       <div v-else>
         <p class="text-sm text-amber-700 dark:text-amber-300">{{ $t('Copy it now. You will not be able to view it again.') }}</p>
         <p class="mt-3 rounded-default border border-amber-300 bg-amber-50 p-3 text-sm text-amber-800 dark:border-amber-700 dark:bg-amber-950 dark:text-amber-200">
-          {{ $t('This secret lets an agent do everything you can do in the admin panel, including deleting data and changing your security settings. Keep it like a password, give it to one agent only, and revoke it if that agent or its device is compromised.') }}
+          <template v-if="createdSecretReadOnly">
+            {{ $t('This secret lets an agent read all data you can see in the admin panel. Keep it like a password, give it to one agent only, and revoke it if that agent or its device is compromised.') }}
+          </template>
+          <template v-else>
+            {{ $t('This secret lets an agent do everything you can do in the admin panel, including deleting data and changing your security settings. Keep it like a password, give it to one agent only, and revoke it if that agent or its device is compromised.') }}
+          </template>
         </p>
         <code class="mt-4 block overflow-x-auto rounded-default 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>
@@ -95,9 +111,9 @@
 <script setup lang="ts">
 import { computed, onMounted, ref } from 'vue';
 import { useI18n } from 'vue-i18n';
-import { Button, Dialog, Input, Table } from '@/afcl';
+import { Button, Checkbox, Dialog, Input, Table } from '@/afcl';
 import adminforth from '@/adminforth';
-import { callAdminForthApi } from '@/utils';
+import { callAdminForthApi, formatDateTime } from '@/utils';
 import claudeCodeIcon from './icons/claude-code.svg';
 import codexIcon from './icons/codex.svg';
 import geminiIcon from './icons/gemini.svg';
@@ -109,6 +125,7 @@ type AuthSecret = {
   createdAt: string;
   lastUsedAt: string | null;
   lastUsedByAgent: Agent | null;
+  readOnly: boolean;
 };
 
 const { t } = useI18n();
@@ -117,6 +134,8 @@ const authSecrets = ref<AuthSecret[]>([]);
 const loading = ref(true);
 const dialogRef = ref();
 const secretName = ref('');
+const secretReadOnly = ref(false);
+const serverReadOnly = ref(false);
 const createdSecret = ref('');
 const creating = ref(false);
 const revokingId = ref<string | null>(null);
@@ -154,6 +173,8 @@ const dialogButtons = computed(() => createdSecret.value
     ]
 );
 
+const createdSecretReadOnly = computed(() => serverReadOnly.value || secretReadOnly.value);
+
 const mcpUrl = computed(() => {
   const baseUrl = (import.meta.env.VITE_ADMINFORTH_PUBLIC_PATH || '').replace(/\/$/, '');
   return `${window.location.origin}${baseUrl}/adminapi/v1/mcp`;
@@ -171,7 +192,10 @@ async function loadAuthSecrets() {
   loading.value = true;
   try {
     const response = await callAdminForthApi({ method: 'GET', path: '/mcp/auth-secrets' });
-    if (response) authSecrets.value = response.authSecrets;
+    if (response) {
+      authSecrets.value = response.authSecrets;
+      serverReadOnly.value = response.serverReadOnly;
+    }
   } finally {
     loading.value = false;
   }
@@ -179,6 +203,7 @@ async function loadAuthSecrets() {
 
 function openCreateDialog() {
   secretName.value = '';
+  secretReadOnly.value = false;
   createdSecret.value = '';
   dialogRef.value?.open();
 }
@@ -190,7 +215,7 @@ async function createAuthSecret() {
     const response = await callAdminForthApi({
       method: 'POST',
       path: '/mcp/auth-secrets',
-      body: { name: secretName.value.trim() },
+      body: { name: secretName.value.trim(), readOnly: secretReadOnly.value },
     });
     if (response?.secret) {
       createdSecret.value = response.secret;
@@ -238,10 +263,6 @@ function describeAgent(agent: Agent) {
   return { label: agent.ver ? `${name} v${agent.ver}` : name, icon };
 }
 
-function formatDate(value: string) {
-  return new Date(value).toLocaleString();
-}
-
 async function copy(value: string, message: string) {
   await navigator.clipboard.writeText(value);
   adminforth.alert({ message, variant: 'success' });

package/dist/custom/icons/gemini.svg

@@ -1 +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>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><defs><linearGradient id="gemini" x1="2" y1="22" x2="22" y2="2" gradientUnits="userSpaceOnUse"><stop stop-color="#4285F4"/><stop offset=".52" stop-color="#9B72CB"/><stop offset="1" stop-color="#D96570"/></linearGradient></defs><path fill="url(#gemini)" d="M11.04 19.32Q12 21.51 12 24q0-2.49.93-4.68.96-2.19 2.58-3.81t3.81-2.55Q21.51 12 24 12q-2.49 0-4.68-.93a12.3 12.3 0 0 1-3.81-2.58 12.3 12.3 0 0 1-2.58-3.81Q12 2.49 12 0q0 2.49-.96 4.68-.93 2.19-2.55 3.81a12.3 12.3 0 0 1-3.81 2.58Q2.49 12 0 12q2.49 0 4.68.96 2.19.93 3.81 2.55t2.55 3.81"/></svg>

package/dist/index.d.ts

@@ -5,7 +5,6 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
     pluginsScope: 'global';
     private authSecretStore;
     private apiTools;
-    private serverPresentation;
     constructor(options: PluginOptions);
     instanceUniqueRepresentation(): string;
     modifyGlobalConfig(adminforth: IAdminForth): void;

package/dist/index.js

@@ -1,11 +1,35 @@
 import { AdminForthPlugin, } from 'adminforth';
 import { AdminForthApiTools } from './apiTools.js';
 import { formatMcpExecutedBy, readMcpClient, UNKNOWN_CLIENT } from './clientInfo.js';
-import { createMcpServerPresentation, handleMcpProtocol, } from './mcpProtocol.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';
 const CREDENTIAL_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie']);
+const RESOURCES_LIST_RESPONSE_SCHEMA = {
+    type: 'object',
+    required: ['resources'],
+    properties: {
+        resources: {
+            type: 'array',
+            description: 'Resources the authenticated admin user can access. A resource is not listed when list, show, create, edit and delete are all forbidden for the user.',
+            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,
@@ -35,7 +59,6 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
     pluginsScope = 'global';
     authSecretStore;
     apiTools;
-    serverPresentation;
     constructor(options) {
         super(options, import.meta.url);
         this.options = options;
@@ -73,7 +96,6 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
         }
         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;
@@ -85,6 +107,7 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
             fields.createdAtField,
             fields.lastUsedAtField,
             fields.lastUsedByAgentField,
+            fields.readOnlyField,
         ]) {
             if (!resource.columns.some((column) => column.name === fieldName)) {
                 throw new Error(`AdminForthMcpPlugin: column "${fieldName}" not found in auth secret resource "${resource.resourceId}"`);
@@ -95,28 +118,54 @@ 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). 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),
+                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)
@@ -127,9 +176,25 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
         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');
+            },
+        });
     }
     async handleMcpRequest(input) {
         if (input.headers.origin) {
@@ -164,11 +229,12 @@ 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.options.adminPanelOrigin, this.adminforth.config.baseUrl, readOnly),
             body: input.body,
             headers: toolHeaders,
-            listTools: () => this.apiTools.list(),
+            listTools: () => this.apiTools.list(readOnly),
             callTool: (name, arguments_) => this.apiTools.call({
                 name,
                 arguments: arguments_,
@@ -176,6 +242,7 @@ export default class AdminForthMcpPlugin extends AdminForthPlugin {
                 headers: toolHeaders,
                 requestUrl: input.requestUrl,
                 abortSignal: input.abortSignal,
+                readOnly,
             }),
         });
         input.response.setStatus(protocolResponse.status);

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, adminPanelOrigin?: string, baseUrl?: string, readOnly?: boolean): McpServerPresentation;
 export interface McpProtocolContext {
     body: Record<string, any>;
     headers: Record<string, any>;

package/dist/mcpProtocol.js

@@ -8,7 +8,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 = '') {
+export function createMcpServerPresentation(brandName, adminPanelOrigin, baseUrl = '', readOnly = false) {
     const adminPanelUrl = adminPanelOrigin
         ? new URL(baseUrl || '/', adminPanelOrigin).toString()
         : undefined;
@@ -21,7 +21,7 @@ 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.`,
     };
 }
 function errorResponse(id, code, message, status = 400) {

package/dist/types.d.ts

@@ -8,11 +8,17 @@ export interface McpAuthSecretResourceOptions {
     createdAtField: string;
     lastUsedAtField: string;
     lastUsedByAgentField: string;
+    readOnlyField: string;
 }
 export interface PluginOptions extends PluginsCommonOptions {
     authSecretResource: McpAuthSecretResourceOptions;
     /** Public origin of this AdminForth installation, without the AdminForth baseUrl path. */
     adminPanelOrigin?: string;
+    /**
+     * Expose only endpoints marked with `agent: { onlyReadsData: true }` to every auth secret.
+     * Without it, read-only mode is chosen per auth secret.
+     */
+    readOnly?: boolean;
 }
 export interface McpClientInfo {
     client: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Expose AdminForth APIs as an authenticated MCP server",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,13 +41,13 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "latest",
-    "adminforth": "^3.20.0",
+    "adminforth": "^3.32.0",
     "semantic-release": "^24.2.1",
     "semantic-release-slack-bot": "^4.0.2",
     "typescript": "^5.7.3"
   },
   "peerDependencies": {
-    "adminforth": "^3.20.0"
+    "adminforth": "^3.32.0"
   },
   "release": {
     "plugins": [