Merge origin/main: combine read-only mode with MCP OAuth AdminForth/1970/please-introduce-same-oauth-au

Keeps both new MCP auth secret columns, read_only from main and
oauth_client_id from this branch, in the dev-demo resource, Prisma schema
and plugin config. The MCP docs describe the read-only checkbox for OAuth
connections and keep the page size, tool timeout and agent guidance
sections.

Author: srelon

.gitignore

@@ -10,3 +10,4 @@ connectors/*
 !connectors/AGENTS.md
 background-jobs-dbs
 tests/jest_tests/db/
+ads

adminforth/commands/createApp/templates/package.json.hbs

@@ -36,7 +36,6 @@
     "tsx": "4.11.2",
     "@types/express": "^5.0.6",
     "@types/node": "latest"{{#if includePrismaMigrations}},
-    "@prisma/client": "latest",
     "prisma": "^7.0.0"
     {{/if}}
   }

adminforth/commands/createApp/templates/schema.prisma.hbs

@@ -1,7 +1,3 @@
-generator client {
-  provider = "prisma-client-js"
-}
-
 datasource db {
   provider = "{{provider}}"
 }

adminforth/commands/createApp/utils.js

@@ -117,8 +117,8 @@ function providerToConnectorName(provider) {
 }
 
 // Returns the default-exported connector class for the given connector name.
-// Connectors are optional peer dependencies, so they are not present during a
-// fresh `npx adminforth create-app`. We first try to import an already-installed
+// Connectors are installed by the user's app, not by adminforth, so they are not
+// present during a fresh `npx adminforth create-app`. We first try to import an already-installed
 // one (local development / monorepo), then fall back to installing it on demand.
 async function loadConnectorClass(connectorName) {
   const pkg = `@adminforth/connector-${connectorName}`;

adminforth/documentation/blog/2024-10-01-ai-blog/index.md

@@ -131,10 +131,6 @@ Open `./schema.prisma` and put next content there:
 
 
 ```yaml title="./schema.prisma" 
-generator client {
-  provider = "prisma-client-js"
-}
-
 datasource db {
   provider = "sqlite"
   url      = env("PRISMA_DATABASE_URL")

adminforth/documentation/docs/tutorial/01-helloWorld.md

@@ -33,7 +33,7 @@ nvm use 24
 mkdir af-hello
 cd af-hello
 pnpm init
-pnpm add adminforth express@^4 @dotenvx/dotenvx @types/express typescript tsx @types/node prisma @prisma/client -D
+pnpm add adminforth express@^4 @dotenvx/dotenvx @types/express typescript tsx @types/node prisma -D
 npx --yes tsc --init --module NodeNext --target ESNext
 ```
 
@@ -419,10 +419,6 @@ Create new directory `./custom/tsconfig.json` with following content:
 Create `./schema.prisma` and put next content there:
 
 ```text title="./schema.prisma"
-generator client {
-  provider = "prisma-client-js"
-}
-
 datasource db {
   provider = "sqlite"
 }

adminforth/documentation/docs/tutorial/03-Customization/12-security.md

@@ -296,6 +296,8 @@ So to completely hide the email field from all users apart superadmins, you shou
 
 So if you will configure the email column in user resource like this, only superadmin will be able to see emails, and only in the list view.
 
+> ☝️ `backendOnly` cannot be set on a primary key column (neither `true` nor a function): frontend needs primary key values to build record links, so AdminForth refuses such config on startup.
+
 ## Blocking login attempts before credentials check
 
 `auth.beforeLoginAttempt` hooks are called on every request to the login endpoint, before AdminForth looks the user up in the database.

adminforth/documentation/docs/tutorial/09-Plugins/01-agent.md

@@ -668,28 +668,19 @@ To define a custom tool, register an API endpoint with `admin.express.endpoint`.
 
 By default, `admin.express.endpoint` applies AdminForth authorization. The endpoint handler receives `adminUser` from the user who is controlling the agent. In other words, all permissions and access rights of the agent are defined by that admin user. At the same time, actions done by the agent are automatically attributed in the audit log to the admin user who is controlling the agent.
 
-If a tool is risky, you can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
+You can attach AdminForth agent metadata directly to the endpoint with the `agent` field.
 
 ```ts
-type AgentRiskLevel = 'safe' | 'danger';
-
 type AgentToolMeta = {
-  riskLevel?: AgentRiskLevel;
-  confirmation?: {
-    title?: string;
-    message?: string;
-    confirmLabel?: string;
-  };
+  requiresHumanApproval?: boolean;
+  hiddenFromAgents?: boolean;
+  onlyReadsData?: boolean;
 };
 ```
 
-Use it in `.endpoint(...)` like this:
-
-- `riskLevel: 'safe'` marks the tool as low-risk.
-- `riskLevel: 'danger'` marks the tool as dangerous.
-- `confirmation` customizes the confirmation dialog shown before the tool is executed.
-
-This metadata is rendered into the generated OpenAPI document, so the agent can understand that a tool is dangerous and requires an explicit confirmation UI before execution.
+- `requiresHumanApproval: true` makes the agent ask the user for approval before it runs the tool. MCP clients receive the `destructiveHint` annotation.
+- `hiddenFromAgents: true` keeps the endpoint out of agent tools, both in the agent and in the [MCP server](/docs/tutorial/Plugins/mcp/). Use it for endpoints that serve your admin panel UI and must not be called by agents.
+- `onlyReadsData: true` declares that the endpoint does not change any data. MCP clients receive the `readOnlyHint` annotation, and a [read-only MCP server](/docs/tutorial/Plugins/mcp/#read-only-mode) exposes only such endpoints.
 
 This example uses the same email adapter pattern shown in the Email Invite and Email Password Reset plugins. The transport below uses Mailgun only to keep the snippet short; you can replace it with SES or any other adapter from [List of adapters](/docs/tutorial/ListOfAdapters/).
 
@@ -728,12 +719,7 @@ export function initApi(app: Express, admin: IAdminForth) {
     path: '/send_email_to_user',
     description: 'Send an email to one AdminForth user by id. Use this after the user row is resolved.',
     agent: {
-      riskLevel: 'danger',
-      confirmation: {
-        title: 'Send email to user',
-        message: 'This action will send a real email to the selected user.',
-        confirmLabel: 'Send email',
-      },
+      requiresHumanApproval: true,
     },
     request_schema: {
       type: 'object',

adminforth/documentation/docs/tutorial/09-Plugins/23-background-jobs.md

@@ -387,7 +387,7 @@ type JobTask = {
     task_number: number;
     task_counter: number;
   };
-  status: 'SCHEDULED' | 'IN_PROGRESS' | 'DONE' | 'FAILED';
+  status: 'SCHEDULED' | 'IN_PROGRESS' | 'DONE' | 'FAILED' | 'DELETED';
 };
 
 const tasks = ref<JobTask[]>([]);
@@ -406,6 +406,7 @@ const taskStatusLabels: Record<JobTask['status'], string> = {
   IN_PROGRESS: 'running',
   DONE: 'done',
   FAILED: 'failed',
+  DELETED: 'deleted',
 };
 
 const props = defineProps<{
@@ -699,7 +700,7 @@ getJobStateField(jobId: string, key: string)
 getJobState(jobId: string)
 //add task to the running job
 addNewTasksToExistingJob(jobId: string, tasks: taskType[])
-//delete task from the running job (if not started yet)
+//delete task from the running job (if not started yet). The task is not removed, it gets the DELETED status and keeps its index
 deleteTasksFromExistingJob(jobId: string, taskIndex: number)
 /**
  * 

adminforth/documentation/docs/tutorial/09-Plugins/30-mcp.md

@@ -8,6 +8,8 @@ slug: /tutorial/Plugins/mcp
 
 The MCP plugin exposes AdminForth API methods as remote MCP tools. An agent connects either through OAuth sign-in, where the user approves it in the browser, or with an auth secret the user creates. Every request runs as that AdminForth user, so the same resource permissions, validation, and hooks apply.
 
+Endpoints marked with `agent: { hiddenFromAgents: true }` are not exposed. AdminForth and its plugins mark the endpoints the admin panel uses internally, such as login, two-factor authentication, passkeys, and agent chat. Mark your own endpoints the same way to keep them away from agents.
+
 ## Installation
 
 ```bash
@@ -27,6 +29,7 @@ model mcp_auth_secrets {
   created_at         DateTime
   last_used_at       DateTime?
   last_used_by_agent String?
+  read_only          Boolean   @default(false)
   oauth_client_id    String?
 
   @@index([user_id])
@@ -59,6 +62,7 @@ export default {
     { name: 'created_at', type: AdminForthDataTypes.DATETIME },
     { name: 'last_used_at', type: AdminForthDataTypes.DATETIME, required: false },
     { name: 'last_used_by_agent', type: AdminForthDataTypes.STRING, required: false },
+    { name: 'read_only', type: AdminForthDataTypes.BOOLEAN },
     { name: 'oauth_client_id', type: AdminForthDataTypes.STRING, required: false },
   ],
   options: {
@@ -98,6 +102,7 @@ new AdminForth({
         createdAtField: 'created_at',
         lastUsedAtField: 'last_used_at',
         lastUsedByAgentField: 'last_used_by_agent',
+        readOnlyField: 'read_only',
         oauthClientIdField: 'oauth_client_id',
       },
     }),
@@ -131,7 +136,7 @@ The plugin adds **MCP Settings** under the user profile. With OAuth sign-in enab
 
 OAuth sign-in is enabled by `oauthClientIdField` together with `adminPanelOrigin`, see [Plugin setup](#plugin-setup).
 
-When an agent calls the MCP endpoint without a token, the server answers `401` with a `WWW-Authenticate` header that leads the agent to the OAuth metadata. The agent then opens the browser on the consent page `/mcp-authorize`. If the user is not logged in, AdminForth shows its login page first, including two-factor authentication if it is enabled, and returns to the consent page. After the user clicks **Allow**, the agent gets an access token and a refresh token and the connection appears in **MCP Settings** under the client's name.
+When an agent calls the MCP endpoint without a token, the server answers `401` with a `WWW-Authenticate` header that leads the agent to the OAuth metadata. The agent then opens the browser on the consent page `/mcp-authorize`. If the user is not logged in, AdminForth shows its login page first, including two-factor authentication if it is enabled, and returns to the consent page. The consent page has a **Read only** checkbox, see [Read-only mode](#read-only-mode). After the user clicks **Allow**, the agent gets an access token and a refresh token and the connection appears in **MCP Settings** under the client's name.
 
 The plugin is an OAuth 2.1 authorization server for public clients:
 
@@ -265,6 +270,21 @@ Tool responses are trimmed to save the agent's context:
 - `get_resource_data` rows leave out columns with `null`, empty array and empty object values, and datetimes come without milliseconds.
 - Tool outputs are serialized as YAML instead of JSON.
 
+## Read-only mode
+
+A read-only connection lets an agent only read data. Check **Read only** when you create an auth secret in **MCP Settings**, or on the consent page when you connect an agent with OAuth sign-in. The mode is stored in `read_only` and cannot be changed later: create a new auth secret or connect the agent again instead.
+
+To make every connection read-only, set `readOnly: true` in the plugin options. The **Read only** checkbox is then hidden, the consent page says that the agent can only read data, and new auth secrets and OAuth connections are stored as read-only, so they stay read-only if you remove the option later:
+
+```ts
+new AdminForthMcpPlugin({
+  readOnly: true,
+  // ...
+}),
+```
+
+In read-only mode the server exposes only endpoints marked with `agent: { onlyReadsData: true }`, such as `get_resource`, `get_resource_data`, and `aggregate`. Creating, updating, and deleting records and running actions are not available. To make your own endpoint available in read-only mode, mark it with `onlyReadsData: true`.
+
 ## Audit attribution
 
 To show which agent acted on behalf of a user, add a nullable field to the audit log table: