@lenne.tech/nest-server 12.2.0 → 12.3.0

package/src/core/modules/ai/services/core-ai-mcp.service.ts

@@ -1,12 +1,30 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable, Logger, Optional } from '@nestjs/common';
 
-import { AiToolContext } from '../interfaces/ai-tool.interface.js';
+import { RequestContext } from '../../../common/services/request-context.service.js';
+import {
+  authorizeToolCall,
+  effectiveMcpConfirmation,
+  mcpConfirmationPolicy,
+  toolRequiresConfirmation,
+} from '../helpers/ai-tool-authorization.helper.js';
+import { AiToolContext, IAiTool } from '../interfaces/ai-tool.interface.js';
 import { AiToolRegistry, AiToolUser } from '../tools/ai-tool.registry.js';
+import type { AiToolPolicyDecision } from './core-ai-tool-policy.service.js';
+import { CoreAiToolPolicyService } from './core-ai-tool-policy.service.js';
+import { CoreAiUserSettingService } from './core-ai-user-setting.service.js';
 
 /**
- * MCP tool descriptor (name + description + JSON-schema input).
+ * MCP tool descriptor (name + description + JSON-schema input + behaviour hints).
  */
 export interface McpToolDescriptor {
+  /**
+   * MCP tool annotations for a tool that declares what it does: `destructive` → `destructiveHint: true`,
+   * `mutating` → `destructiveHint: false`, both with `readOnlyHint: false`. Absent for a tool with neither flag:
+   * such a tool may still write (the flags used to matter for the chat only), so it is never advertised as
+   * read-only and clients keep the spec's cautious defaults. Hints for the client's own confirmation UI, never a
+   * security boundary — the server enforces `authorize()` and its confirmation gate itself.
+   */
+  annotations?: { destructiveHint: boolean; readOnlyHint: boolean };
   description: string;
   inputSchema: Record<string, any>;
   name: string;
@@ -20,6 +38,30 @@ export interface McpCallResult {
   isError?: boolean;
 }
 
+/**
+ * The question put to the user before a tool that needs confirmation runs over MCP.
+ */
+export interface McpConfirmationPrompt {
+  /** The arguments the tool will run with. */
+  arguments: Record<string, any>;
+  /** The text the MCP client shows the user. */
+  message: string;
+  /** The tool's name. */
+  tool: string;
+}
+
+/**
+ * Options of {@link CoreAiMcpService.mcpCallTool}.
+ */
+export interface McpCallToolOptions {
+  /**
+   * Asks the user to confirm the call; resolves `true` only when they did. `createServer()` passes one that uses MCP
+   * elicitation when the client supports it. Absent: the client cannot ask, so a call that needs confirmation is
+   * refused.
+   */
+  confirm?: (prompt: McpConfirmationPrompt) => Promise<boolean>;
+}
+
 /**
  * Exposes the {@link AiToolRegistry} as a Model Context Protocol (MCP) server so
  * external MCP clients (e.g. desktop MCP clients) can use the same backend tools with
@@ -29,6 +71,11 @@ export interface McpCallResult {
  * `tools/list` and `tools/call` are filtered to that user's permitted tools and
  * executed with their permissions (via each tool's `execute()` → CrudService).
  *
+ * Since 12.3.0 `tools/call` also applies the gates of the chat orchestrator: the admin's tool policies (`deny`
+ * refuses, `ask` asks), the tool's `authorize()`, and the confirmation of a `destructive` tool (or a `mutating` one
+ * under `ai.confirmation.mutating`) through MCP elicitation. Whether MCP asks is `ai.mcp.confirmation` (on by default),
+ * which each user may switch for themselves (`PUT /ai/settings`) unless the server enforces it.
+ *
  * The `@modelcontextprotocol/sdk` is imported lazily in {@link createServer} so it
  * is only loaded when MCP is actually enabled — keeping the core lean.
  */
@@ -36,40 +83,75 @@ export interface McpCallResult {
 export class CoreAiMcpService {
   protected readonly logger = new Logger(CoreAiMcpService.name);
 
-  constructor(protected readonly toolRegistry: AiToolRegistry) {}
+  /** How long the server waits for the user's answer to a confirmation request. */
+  protected readonly confirmationTimeoutMs = 5 * 60_000;
+
+  constructor(
+    protected readonly toolRegistry: AiToolRegistry,
+    @Optional() protected readonly userSettingService?: CoreAiUserSettingService,
+    @Optional() protected readonly toolPolicyService?: CoreAiToolPolicyService,
+  ) {}
 
   /**
    * List the MCP tool descriptors the user is allowed to use.
    */
   mcpListTools(user: AiToolUser | null | undefined): McpToolDescriptor[] {
-    return this.toolRegistry
-      .forUser(user)
-      .map((tool) => ({ description: tool.description, inputSchema: tool.parameters, name: tool.name }));
+    return this.toolRegistry.forUser(user).map((tool) => ({
+      ...(tool.destructive || tool.mutating
+        ? { annotations: { destructiveHint: tool.destructive === true, readOnlyHint: false } }
+        : {}),
+      description: tool.description,
+      inputSchema: tool.parameters,
+      name: tool.name,
+    }));
   }
 
   /**
    * Execute an MCP tool call with the user's permissions. Returns an MCP content
-   * result; unknown/forbidden tools and execution errors yield `isError: true`.
+   * result; unknown/forbidden tools, a refused `authorize()`, a missing confirmation and
+   * execution errors yield `isError: true`.
    */
   async mcpCallTool(
     user: AiToolUser | null | undefined,
     name: string,
     args: Record<string, any>,
+    options: McpCallToolOptions = {},
   ): Promise<McpCallResult> {
     const tool = this.toolRegistry.forUser(user).find((t) => t.name === name);
     if (!tool) {
-      return { content: [{ text: `Unknown or not permitted tool: ${name}`, type: 'text' }], isError: true };
+      return this.errorResult(`Unknown or not permitted tool: ${name}`);
     }
+    const callArgs = args ?? {};
     const context: AiToolContext = {
       currentUser: (user ?? undefined) as AiToolContext['currentUser'],
       serviceOptions: { currentUser: (user ?? undefined) as AiToolContext['currentUser'] },
     };
+
+    const policy = await this.evaluateToolPolicy(tool, callArgs, user);
+    if (policy?.decision === 'deny') {
+      return this.errorResult(policy.reason || `"${name}" is not permitted by policy.`);
+    }
+    const authorization = await authorizeToolCall(tool, callArgs, context);
+    if (!authorization.allowed) {
+      return this.errorResult(authorization.reason || `Not permitted: ${name}`);
+    }
+    if (policy?.decision === 'ask' || (await this.confirmationRequired(tool, user))) {
+      if (!options.confirm) {
+        return this.errorResult(
+          `"${name}" needs the user's confirmation, and this MCP client cannot ask for it (elicitation). Nothing was run.`,
+        );
+      }
+      if (!(await this.askForConfirmation(tool, callArgs, options.confirm))) {
+        return this.errorResult(`"${name}" was not run: the user did not confirm it.`);
+      }
+    }
+
     try {
-      const result = await tool.execute(args ?? {}, context);
+      const result = await tool.execute(callArgs, tool.authorize ? { ...context, authorization } : context);
       return { content: [{ text: JSON.stringify(result), type: 'text' }] };
     } catch (err) {
       this.logger.warn(`MCP tool "${name}" failed: ${(err as Error).message}`);
-      return { content: [{ text: (err as Error).message, type: 'text' }], isError: true };
+      return this.errorResult((err as Error).message);
     }
   }
 
@@ -91,10 +173,121 @@ export class CoreAiMcpService {
     const server: any = new Server({ name: 'lt-nest-server-ai', version: '1.0.0' }, { capabilities: { tools: {} } });
 
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.mcpListTools(currentUser()) }));
-    server.setRequestHandler(CallToolRequestSchema, async (request: any) =>
-      this.mcpCallTool(currentUser(), request.params.name, request.params.arguments ?? {}),
+    server.setRequestHandler(CallToolRequestSchema, async (request: any, extra: any) =>
+      this.mcpCallTool(currentUser(), request.params.name, request.params.arguments ?? {}, {
+        // The SDK reads an empty `elicitation: {}` as form elicitation, the kind a yes/no question needs.
+        confirm: server.getClientCapabilities()?.elicitation?.form
+          ? (prompt: McpConfirmationPrompt) => this.elicitConfirmation(server, prompt, extra?.requestId)
+          : undefined,
+      }),
     );
 
     return server;
   }
+
+  /**
+   * Whether this call must be confirmed by the user: a tool that needs confirmation ({@link toolRequiresConfirmation},
+   * with `ai.confirmation.mutating`'s default for `mutating`), while MCP asks this user — `ai.mcp.confirmation`, or the
+   * user's own choice where the server allows one. An admin's `ask` policy is decided before and asks regardless.
+   */
+  protected async confirmationRequired(tool: IAiTool, user: AiToolUser | null | undefined): Promise<boolean> {
+    if (!toolRequiresConfirmation(tool)) {
+      return false;
+    }
+    if (this.userSettingService) {
+      return this.userSettingService.mcpConfirmationFor(user?.id);
+    }
+    return effectiveMcpConfirmation(mcpConfirmationPolicy());
+  }
+
+  /**
+   * The admin's tool policy for this call (`aiToolPolicies`), as the chat orchestrator evaluates it. `undefined`
+   * without the policy service, without a matching rule, or when the evaluation fails (logged).
+   */
+  protected async evaluateToolPolicy(
+    tool: IAiTool,
+    args: Record<string, any>,
+    user: AiToolUser | null | undefined,
+  ): Promise<AiToolPolicyDecision | undefined> {
+    if (!this.toolPolicyService) {
+      return undefined;
+    }
+    try {
+      return await this.toolPolicyService.evaluate(tool.name, args, {
+        roles: (user?.roles as string[]) ?? [],
+        tenantId: RequestContext.getTenantId(),
+        userId: user?.id,
+      });
+    } catch (err) {
+      this.logger.warn(`AI tool-policy evaluation for "${tool.name}" failed: ${(err as Error).message}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * The question shown to the user. English, because an MCP request carries no language; override to localize.
+   *
+   * Every argument gets a line of its own and only its value is shortened: the arguments come from the model, and
+   * a cut over the whole text would let a long first value push the one that decides the outcome (the target id)
+   * out of the question the user approves.
+   */
+  protected confirmationPrompt(tool: IAiTool, args: Record<string, any>): McpConfirmationPrompt {
+    const maxValueLength = 200;
+    const lines = Object.entries(args).map(([key, value]) => {
+      const text = typeof value === 'string' ? value : (JSON.stringify(value) ?? String(value));
+      const shown =
+        text.length > maxValueLength ? `${text.slice(0, maxValueLength)}… (${text.length} characters)` : text;
+      return `- ${key}: ${shown}`;
+    });
+    const consequence = tool.destructive ? 'This cannot be undone.' : 'This changes data.';
+    const argumentsText = lines.length ? `\nArguments:\n${lines.join('\n')}` : '';
+    return {
+      arguments: args,
+      message: `Allow the AI assistant to run "${tool.name}"? ${consequence}${argumentsText}`,
+      tool: tool.name,
+    };
+  }
+
+  /**
+   * Puts the question to the user. Anything but an explicit yes — a no, a cancelled dialog, an error, a timeout —
+   * counts as "not confirmed".
+   */
+  protected async askForConfirmation(
+    tool: IAiTool,
+    args: Record<string, any>,
+    confirm: NonNullable<McpCallToolOptions['confirm']>,
+  ): Promise<boolean> {
+    try {
+      return (await confirm(this.confirmationPrompt(tool, args))) === true;
+    } catch (err) {
+      this.logger.warn(`Confirmation of MCP tool "${tool.name}" failed, not run: ${(err as Error).message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Asks through MCP form elicitation, as part of the running `tools/call` request (`relatedRequestId`), so a
+   * Streamable HTTP client receives the question on that request's stream.
+   */
+  protected async elicitConfirmation(server: any, prompt: McpConfirmationPrompt, requestId: unknown): Promise<boolean> {
+    const result = await server.elicitInput(
+      {
+        message: prompt.message,
+        requestedSchema: {
+          properties: {
+            confirm: { description: `Run "${prompt.tool}" now`, title: 'Confirm', type: 'boolean' },
+          },
+          required: ['confirm'],
+          type: 'object',
+        },
+      },
+      { relatedRequestId: requestId, timeout: this.confirmationTimeoutMs },
+    );
+    return result?.action === 'accept' && result.content?.confirm === true;
+  }
+
+  /** An MCP error result with one text block. */
+  protected errorResult(text: string): McpCallResult {
+    return { content: [{ text, type: 'text' }], isError: true };
+  }
 }

package/src/core/modules/ai/services/core-ai-prompt-builder.service.ts

@@ -221,12 +221,19 @@ export class CoreAiPromptBuilderService {
             : '\n\n[Schemas deferred. Call `search_tools` with the tool name to fetch its parameter schema BEFORE you call it.]';
       }
     }
-    const toolCatalog = defer
-      ? (tools.map((t) => `- ${t.name}: ${this.summarizeToolDescription(t.description, summaryChars)}`).join('\n') ||
-          '(none)') + deferNote
-      : tools
-          .map((t) => `- ${t.name}: ${t.description}\n  parameters (JSON schema): ${JSON.stringify(t.parameters)}`)
-          .join('\n') || '(none)';
+    // A native connection receives every description and schema in the tool payload (`buildToolSchemas()`), so its
+    // catalog lists names only (12.3.0) — repeating them here paid for each tool twice. Emulated connections and plan
+    // mode have no tool payload; their catalog is the model's only source. `ai.nativeToolCatalog: 'full'` restores
+    // the full catalog for a model that picks tools better with it.
+    const namesOnly = supportsNativeTools && !planMode && ConfigService.get<string>('ai.nativeToolCatalog') !== 'full';
+    const toolCatalog = namesOnly
+      ? tools.map((t) => `- ${t.name}`).join('\n') || '(none)'
+      : defer
+        ? (tools.map((t) => `- ${t.name}: ${this.summarizeToolDescription(t.description, summaryChars)}`).join('\n') ||
+            '(none)') + deferNote
+        : tools
+            .map((t) => `- ${t.name}: ${t.description}\n  parameters (JSON schema): ${JSON.stringify(t.parameters)}`)
+            .join('\n') || '(none)';
 
     if (this.placeholderRegistry) {
       return this.placeholderRegistry.resolveAll({ toolCatalog, tools, user });

package/src/core/modules/ai/services/core-ai-user-setting.service.ts

@@ -0,0 +1,85 @@
+import { ForbiddenException, Inject, Injectable, Logger } from '@nestjs/common';
+import { InjectModel } from '../../../common/persistence/mongo/mongoose-compat.js';
+import type { Model } from 'mongoose';
+
+import { upsertRecord } from '../../../common/persistence/store-upsert.js';
+import { CrudService } from '../../../common/services/crud.service.js';
+import type { CoreModelConstructor } from '../../../common/types/core-model-constructor.type.js';
+import { ErrorCode } from '../../error-code/index.js';
+import { effectiveMcpConfirmation, mcpConfirmationPolicy } from '../helpers/ai-tool-authorization.helper.js';
+import type { CoreAiSettingsInput } from '../inputs/core-ai-settings.input.js';
+import { CoreAiSettings } from '../models/core-ai-settings.model.js';
+import { AiUserSettingDocument, CoreAiUserSetting } from '../models/core-ai-user-setting.model.js';
+
+import { AI_USER_SETTING_CLASS, AI_USER_SETTING_MODEL } from '../core-ai.constants.js';
+
+/**
+ * Personal AI settings (12.3.0+): what a user chose for themselves, combined with the server configuration into the
+ * settings that take effect. Today that is whether MCP asks the user before a tool that needs confirmation
+ * (`ai.mcp.confirmation`) — the user's own "bypass permissions" switch, unless the server enforces it.
+ *
+ * Reads and writes go through the routed store with the user id the caller passes; the endpoints pass the current
+ * user's, so nobody reaches another user's settings.
+ *
+ * Override via `CoreModule.forRoot(env, { ai: { userSettingService } })`.
+ */
+@Injectable()
+export class CoreAiUserSettingService extends CrudService<CoreAiUserSetting, CoreAiUserSetting, CoreAiUserSetting> {
+  protected readonly logger = new Logger(CoreAiUserSettingService.name);
+
+  constructor(
+    @InjectModel(AI_USER_SETTING_MODEL) protected override readonly mainDbModel: Model<AiUserSettingDocument>,
+    @Inject(AI_USER_SETTING_CLASS)
+    protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiUserSetting>,
+  ) {
+    super();
+  }
+
+  /**
+   * The user's settings as they take effect.
+   */
+  async getSettings(userId: string | undefined): Promise<CoreAiSettings> {
+    const policy = mcpConfirmationPolicy();
+    const stored = userId ? await this.findForUser(userId) : undefined;
+    const settings = new CoreAiSettings();
+    settings.mcpConfirmation = effectiveMcpConfirmation(policy, stored?.mcpConfirmation);
+    settings.mcpConfirmationEnforced = policy.enforced;
+    return settings;
+  }
+
+  /**
+   * Stores the user's choices and answers with the settings that take effect. A choice the server enforces is
+   * refused with 403 (`AI_SETTING_ENFORCED`) rather than stored and ignored.
+   */
+  async updateSettings(userId: string, input: CoreAiSettingsInput): Promise<CoreAiSettings> {
+    if (typeof input?.mcpConfirmation === 'boolean') {
+      if (mcpConfirmationPolicy().enforced) {
+        throw new ForbiddenException(ErrorCode.AI_SETTING_ENFORCED);
+      }
+      await upsertRecord(this.dataStore, { userId }, { mcpConfirmation: input.mcpConfirmation });
+    }
+    return this.getSettings(userId);
+  }
+
+  /**
+   * Whether MCP asks this user before a tool that needs confirmation. When the stored choice cannot be read, it asks
+   * — unless the policy is enforced, which needs no stored choice.
+   */
+  async mcpConfirmationFor(userId: string | undefined): Promise<boolean> {
+    const policy = mcpConfirmationPolicy();
+    if (policy.enforced || !userId) {
+      return policy.default;
+    }
+    try {
+      return effectiveMcpConfirmation(policy, (await this.findForUser(userId))?.mcpConfirmation);
+    } catch (err) {
+      this.logger.warn(`AI settings of user ${userId} could not be read, MCP asks: ${(err as Error).message}`);
+      return true;
+    }
+  }
+
+  /** The stored record of one user, if any. */
+  protected async findForUser(userId: string): Promise<CoreAiUserSetting | undefined> {
+    return ((await this.dataStore.findOne({ userId })) as CoreAiUserSetting | null) ?? undefined;
+  }
+}