@nocobase/ai 2.4.0-alpha.16 → 2.4.0-alpha.18

package/src/__tests__/mcp.test.ts

@@ -8,44 +8,74 @@
  */
 
 import { createMockServer, MockServer } from '@nocobase/test';
-import path from 'path';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { AIManager } from '../ai-manager';
 import { MCPLoader } from '../loader';
-import { MCPManager } from '../mcp-manager';
+import { DefaultMCPManager, MCPManager } from '../mcp-manager';
+vi.mock('@langchain/mcp-adapters', () => ({
+  MultiServerMCPClient: class {
+    async initializeConnections() {
+      return {};
+    }
+    async close() {}
+  },
+}));
 
 describe('MCP loader test cases', () => {
-  const basePath = path.resolve(__dirname, 'resource', 'ai');
+  let storage: string;
+  let filePath: string;
   let app: MockServer;
   let aiManager: AIManager;
   let mcpManager: MCPManager;
   let loader: MCPLoader;
 
   beforeEach(async () => {
+    storage = await mkdtemp(join(tmpdir(), 'mcp-persistence-'));
+    vi.stubEnv('STORAGE_PATH', storage);
+    // SQLite fixtures must not inherit a PostgreSQL schema from the CI matrix.
+    vi.stubEnv('DB_SCHEMA', 'public');
+    filePath = join(storage, 'ai', 'mcp', 'servers.json');
+    await mkdir(join(storage, 'ai', 'mcp'), { recursive: true });
     app = await createMockServer({
       plugins: ['nocobase'],
+      database: { dialect: 'sqlite', storage: join(storage, 'test.sqlite') },
     });
     await app.pm.enable('ai');
     aiManager = app.aiManager;
     mcpManager = aiManager.mcpManager;
-    loader = new MCPLoader(aiManager, {
-      scan: {
-        basePath,
-        pattern: ['**/mcp/*.ts', '!**/mcp/*.d.ts'],
-      },
-    });
+    loader = new MCPLoader(mcpManager);
   });
 
   afterEach(async () => {
     await app.destroy();
+    vi.unstubAllEnvs();
+    await rm(storage, { recursive: true, force: true });
   });
 
-  it('should load mcp definitions in mcp root directory', async () => {
+  it('loads JSON deployment definitions into the database', async () => {
+    await writeFile(
+      filePath,
+      JSON.stringify([
+        {
+          name: 'weather',
+          transport: 'http',
+          url: 'http://localhost:8123/mcp',
+          headers: { Authorization: 'Bearer test-token' },
+          env: { MCP_ENV: 'test' },
+          args: ['--foo'],
+          restart: { enabled: true },
+        },
+      ]),
+    );
     await loader.load();
 
     const entry = await mcpManager.getMCP('weather');
     expect(entry).toBeDefined();
     expect(entry.name).toBe('weather');
     expect(entry.enabled).toBe(true);
+    expect(entry.fromFile).toBe(true);
     expect(entry.transport).toBe('http');
     expect(entry.url).toBe('http://localhost:8123/mcp');
     expect(entry.headers).toEqual({
@@ -63,9 +93,82 @@ describe('MCP loader test cases', () => {
     expect(enabledEntries.map((item) => item.name)).toEqual(['weather']);
   });
 
+  it('preserves disabled state and management through updates, repeated loads and removed entries', async () => {
+    const definitions = [
+      { name: 'local', transport: 'stdio', command: 'node', useUserContext: true },
+      { name: 'remote', transport: 'http', url: 'http://127.0.0.1/old', useUserContext: true },
+    ];
+    await writeFile(filePath, JSON.stringify(definitions));
+    await loader.load();
+    expect(await mcpManager.getMCP('local')).toMatchObject({ enabled: true, fromFile: true, useUserContext: false });
+    const repo = app.db.getRepository('aiMcpClients');
+    await repo.update({ filterByTk: 'remote', values: { enabled: false } });
+    definitions[1].url = 'http://127.0.0.1/new';
+    await writeFile(filePath, JSON.stringify(definitions));
+    await loader.load();
+    await loader.load();
+    expect(await repo.count()).toBe(2);
+    expect(await mcpManager.getMCP('remote')).toMatchObject({
+      enabled: false,
+      fromFile: true,
+      url: definitions[1].url,
+      useUserContext: true,
+    });
+    await writeFile(filePath, '[]');
+    await loader.load();
+    await rm(filePath);
+    await loader.load();
+    await mcpManager.registerMCP({ remote: { transport: 'http', url: 'http://127.0.0.1/trusted', fromFile: false } });
+    expect(await mcpManager.getMCP('remote')).toMatchObject({ enabled: false, fromFile: true });
+    expect(await repo.count()).toBe(2);
+  });
+  it('validates before memory registration and persists before initializing connections', async () => {
+    const manager = new DefaultMCPManager(app);
+    const memoryLoader = new MCPLoader(manager);
+    await manager.registerMCP({ local: { transport: 'stdio', command: 'old' } });
+    await writeFile(filePath, JSON.stringify([{ name: 'local', transport: 'stdio', command: 'node' }]));
+    await memoryLoader.load();
+    await memoryLoader.load();
+    await manager.registerMCP({ local: { transport: 'stdio', command: 'trusted', fromFile: false } });
+    expect(await app.db.getRepository('aiMcpClients').count()).toBe(0);
+    const rebuild = vi.spyOn(manager, 'rebuildClient').mockImplementation(async () => {
+      expect(await manager.getMCP('local')).toMatchObject({ command: 'trusted', fromFile: true, enabled: true });
+    });
+    await manager.init();
+    expect(rebuild).toHaveBeenCalledTimes(1);
+    expect(await app.db.getRepository('aiMcpClients').count()).toBe(1);
+  });
+
+  it('loads deployment configuration through the actual afterStart lifecycle', async () => {
+    await writeFile(
+      filePath,
+      JSON.stringify([{ name: 'startup', transport: 'http', url: 'http://127.0.0.1/startup' }]),
+    );
+    await app.stop();
+    await app.start();
+    expect(await app.aiManager.mcpManager.getMCP('startup')).toMatchObject({ enabled: true, fromFile: true });
+  });
+
+  it('adds the source column on upgrade without changing existing enabled state', async () => {
+    const collection = app.db.getCollection('aiMcpClients');
+    await app.db.getRepository('aiMcpClients').create({
+      values: {
+        name: 'legacy',
+        transport: 'stdio',
+        command: 'node',
+        enabled: false,
+      },
+    });
+    await app.db.sequelize.getQueryInterface().removeColumn(collection.model.getTableName(), 'fromFile');
+    await app.upgrade();
+    expect(await app.aiManager.mcpManager.getMCP('legacy')).toMatchObject({ enabled: false, fromFile: false });
+    await app.db.getRepository('aiMcpClients').create({ values: { name: 'after-upgrade', transport: 'http' } });
+    expect(await app.aiManager.mcpManager.getMCP('after-upgrade')).toMatchObject({ fromFile: false });
+  });
+
   it('should expose cached mcp tools and allow updating permissions', async () => {
-    const manager = mcpManager as any;
-    manager.toolsMap = {
+    await app.db.getRepository('aiMcpClients').create({ values: { name: 'weather', transport: 'http' } });
+    Reflect.set(mcpManager, 'toolsMap', {
       weather: [
         {
           name: 'getForecast',
@@ -76,7 +179,7 @@ describe('MCP loader test cases', () => {
           description: 'Set default city',
         },
       ],
-    };
+    });
 
     const tools = await mcpManager.listMCPTools();
     expect(tools.weather).toEqual([

package/src/loader/mcp.ts

@@ -7,95 +7,84 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { importModule } from '@nocobase/utils';
-import { existsSync } from 'fs';
-import { Logger } from '@nocobase/logger';
-import { AIManager } from '../ai-manager';
-import { MCPOptions } from '../mcp-manager';
-import { LoadAndRegister } from './types';
-import { DirectoryScanner, DirectoryScannerOptions, FileDescriptor } from './scanner';
-import { isNonEmptyObject } from './utils';
+import { storagePathJoin } from '@nocobase/utils';
+import type { Logger } from '@nocobase/logger';
+import { readFile } from 'node:fs/promises';
+import type { MCPOptions, MCPRegistration } from '../mcp-manager/types';
+import { normalizeMCPOptions } from '../mcp-manager/options-renderer';
 
-export type MCPLoaderOptions = { pluginName: string; scan: DirectoryScannerOptions; log?: Logger };
-
-export class MCPLoader extends LoadAndRegister<MCPLoaderOptions> {
-  protected readonly scanner: DirectoryScanner;
-
-  protected files: FileDescriptor[] = [];
-  protected mcpDescriptors: MCPDescriptor[] = [];
-  protected log: Logger;
+export type MCPLoaderOptions = { log?: Pick<Logger, 'error'> };
 
+export class MCPLoader {
   constructor(
-    protected readonly ai: AIManager,
-    protected readonly options: MCPLoaderOptions,
-  ) {
-    super(ai, options);
-    this.log = options.log;
-    this.scanner = new DirectoryScanner(this.options.scan);
-  }
+    private readonly manager: MCPRegistration,
+    private readonly options: MCPLoaderOptions = {},
+  ) {}
 
-  protected async scan(): Promise<void> {
-    this.files = await this.scanner.scan();
-  }
-
-  protected async import(): Promise<void> {
-    if (!this.files.length) {
+  async load(): Promise<void> {
+    const filePath = storagePathJoin('ai', 'mcp', 'servers.json');
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf8');
+    } catch (error) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+        return;
+      }
+      this.options.log?.error(`MCP file ignored at ${filePath}: unable to read file`);
       return;
     }
 
-    const descriptors = await Promise.all(
-      this.files.map(async (file) => {
-        const name = file.name;
-        if (!existsSync(file.path)) {
-          this.log?.error(`mcp [${name}] ignored: can not find definition file at ${file.path}`);
-          return null;
-        }
-
-        try {
-          const imported = await importModule(file.path);
-          const mod = imported?.default ?? imported;
-          const options = typeof mod === 'function' ? mod() : mod;
-
-          if (!isNonEmptyObject(options)) {
-            this.log?.warn(`mcp [${name}] register ignored: invalid definition at ${file.path}`);
-            return null;
-          }
-
-          return {
-            name,
-            file,
-            options: options as MCPOptions,
-          } satisfies MCPDescriptor;
-        } catch (e) {
-          this.log?.error(`mcp [${name}] load fail: error occur when import ${file.path}`, e);
-          return null;
-        }
-      }),
-    );
-
-    this.mcpDescriptors = descriptors.filter((item): item is MCPDescriptor => Boolean(item));
-  }
-
-  protected async register(): Promise<void> {
-    if (!this.mcpDescriptors.length) {
+    let definitions: unknown;
+    try {
+      definitions = JSON.parse(content);
+    } catch {
+      // JSON parser messages may contain configuration fragments, including secrets.
+      this.options.log?.error(`MCP file ignored at ${filePath}: invalid JSON`);
+      return;
+    }
+    if (!Array.isArray(definitions)) {
+      this.options.log?.error(`MCP file ignored at ${filePath}: expected an array`);
       return;
     }
 
-    const { mcpManager } = this.ai;
-    for (const descriptor of this.mcpDescriptors) {
+    const registration: Record<string, MCPOptions> = Object.create(null);
+    for (const [index, value] of (definitions as unknown[]).entries()) {
+      const definition = value as Record<string, unknown>;
+      let reason: string | undefined;
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        reason = 'expected an object';
+      } else if (typeof definition.name !== 'string' || !definition.name.trim()) {
+        reason = 'name is required';
+      } else if (!(['stdio', 'http', 'sse'] as unknown[]).includes(definition.transport)) {
+        reason = 'unsupported or missing transport';
+      } else if (Object.hasOwn(value, 'enabled') || Object.hasOwn(value, 'fromFile')) {
+        reason = 'enabled and fromFile cannot be specified';
+      } else if (Object.hasOwn(registration, definition.name as string)) {
+        reason = 'duplicate name';
+      }
+      if (reason) {
+        this.options.log?.error(`MCP file ignored at ${filePath}, entry ${index + 1}: ${reason}`);
+        return;
+      }
+      // Keep the existing permissive connection-field normalization; only the file envelope is validated here.
       try {
-        await mcpManager.registerMCP({
-          [descriptor.name]: descriptor.options,
-        });
-      } catch (e) {
-        this.log?.error(`mcp [${descriptor.name}] register ignored: error occur when invoke registerMCP`, e);
+        registration[definition.name as string] = normalizeMCPOptions({ ...definition, fromFile: true } as MCPOptions);
+      } catch {
+        this.options.log?.error(
+          `MCP file ignored at ${filePath}, entry ${index + 1}: unable to normalize configuration`,
+        );
+        return;
       }
     }
+
+    if (!Object.keys(registration).length) {
+      return;
+    }
+    try {
+      // Register only after the entire file passes validation.
+      await this.manager.registerMCP(registration);
+    } catch {
+      this.options.log?.error(`MCP registration failed at ${filePath}`);
+    }
   }
 }
-
-export type MCPDescriptor = {
-  name: string;
-  file: FileDescriptor;
-  options: MCPOptions;
-};

package/src/mcp-manager/errors.ts

@@ -0,0 +1,15 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+export class MCPToolPermissionError extends Error {
+  constructor(readonly code: 'INVALID_PERMISSION' | 'TOOL_NOT_FOUND_OR_AMBIGUOUS') {
+    super(code);
+    this.name = 'MCPToolPermissionError';
+  }
+}

package/src/mcp-manager/index.ts

@@ -8,23 +8,23 @@
  */
 
 import { SequelizeCollectionManager } from '@nocobase/data-source-manager';
-import { Op } from '@nocobase/database';
+import { Op, Transaction } from '@nocobase/database';
 import { Registry } from '@nocobase/utils';
 import { MultiServerMCPClient, StdioConnection, StreamableHTTPConnection } from '@langchain/mcp-adapters';
 import { StructuredToolInterface } from '@langchain/core/tools';
 import { MCPEntry, MCPFilter, MCPManager, MCPOptions, MCPTestResult, MCPToolEntry } from './types';
-import type { DynamicToolsProvider, Permission, ToolsRegistration, ToolsOptions } from '../tools-manager/types';
+import type { DynamicToolsProvider, Permission, ToolsRegistration } from '../tools-manager/types';
 import type { Context } from '@nocobase/actions';
 import { normalizeMCPOptions, renderMCPOptions } from './options-renderer';
 import { UserContextMCPClientManager } from './user-context-client-manager';
+import { MCPToolPermissionError } from './errors';
 
 export class DefaultMCPManager implements MCPManager {
-  private readonly mcpRegistry = new Registry<MCPEntry>();
+  private readonly mcpRegistry = new Registry<MCPEntry>({ override: true });
   private readonly provideCollectionManager: () => { collectionManager: SequelizeCollectionManager };
   private mode = 'memory';
   private client: MultiServerMCPClient | null = null;
   private toolsMap: Record<string, StructuredToolInterface[]> = {};
-  private toolsPermissionMap: Record<string, Permission> = {};
   private readonly userContextClientManager: UserContextMCPClientManager;
 
   constructor(private readonly app: any) {
@@ -51,7 +51,9 @@ export class DefaultMCPManager implements MCPManager {
   async registerMCP(registration: { [key: string | symbol]: MCPOptions }): Promise<void> {
     if (this.mode === 'memory') {
       for (const [name, options] of Object.entries(registration)) {
-        this.mcpRegistry.register(name, this.normalizeEntry(name, options));
+        const entry = this.normalizeEntry(name, options);
+        entry.fromFile = entry.fromFile === true || this.mcpRegistry.get(name)?.fromFile === true;
+        this.mcpRegistry.register(name, entry);
       }
     } else {
       for (const [name, options] of Object.entries(registration)) {
@@ -100,8 +102,8 @@ export class DefaultMCPManager implements MCPManager {
         // Ignore close errors
       }
       this.client = null;
-      this.toolsMap = {};
     }
+    this.toolsMap = {};
 
     // Get all enabled MCP entries
     const entries = await this.listMCP({ enabled: true, useUserContext: false });
@@ -123,12 +125,6 @@ export class DefaultMCPManager implements MCPManager {
     // Cache tools for each server
     for (const [serverName, tools] of Object.entries(toolsMap)) {
       this.toolsMap[serverName] = tools as StructuredToolInterface[];
-      for (const tool of tools as StructuredToolInterface[]) {
-        const toolName = `mcp-${serverName}-${tool.name}`;
-        if (!(toolName in this.toolsPermissionMap)) {
-          this.toolsPermissionMap[toolName] = tool.name.startsWith('get') ? 'ALLOW' : 'ASK';
-        }
-      }
     }
   }
 
@@ -138,95 +134,123 @@ export class DefaultMCPManager implements MCPManager {
 
   getMCPToolsProvider(): DynamicToolsProvider {
     return async (register: ToolsRegistration, filter): Promise<void> => {
-      // Use cached tools from rebuildClient
-      for (const [serverName, tools] of Object.entries(this.toolsMap)) {
-        this.registerToolsFromMap(register, serverName, tools);
-      }
-
-      if (!filter?.ctx) {
-        return;
-      }
-
-      const userToolsMap = await this.userContextClientManager.getToolsMap(filter.ctx);
-      for (const [serverName, tools] of Object.entries(userToolsMap)) {
-        this.registerToolsFromMap(register, serverName, tools);
+      const toolsMap = await this.getActiveToolsMap(filter?.ctx);
+      const permissions = await this.readToolPermissions(Object.keys(toolsMap));
+      for (const [serverName, tools] of Object.entries(toolsMap)) {
+        for (const tool of tools) {
+          register.registerTools({
+            scope: 'GENERAL',
+            from: 'mcp',
+            defaultPermission: this.resolveToolPermission(permissions, serverName, tool.name),
+            introduction: { title: tool.name, about: tool.description },
+            definition: {
+              name: `mcp-${serverName}-${tool.name}`,
+              description: tool.description || `MCP tool: ${tool.name} from ${serverName}`,
+              schema: tool.schema,
+            },
+            invoke: async (ctx: Context, args: Parameters<typeof tool.invoke>[0]) => {
+              const entry = await this.getMCP(serverName);
+              if (!entry?.enabled) {
+                throw new Error(ctx.t('MCP server is disabled or deleted', { ns: '@nocobase/plugin-ai' }));
+              }
+              try {
+                return await tool.invoke(args);
+              } catch (error: unknown) {
+                return {
+                  status: 'error' as const,
+                  content: error instanceof Error ? error.message : 'Tool invocation failed',
+                };
+              }
+            },
+          });
+        }
       }
     };
   }
 
-  private registerToolsFromMap(
-    register: ToolsRegistration,
-    serverName: string,
-    tools: StructuredToolInterface[],
-  ): void {
-    for (const tool of tools) {
-      const toolName = `mcp-${serverName}-${tool.name}`;
-      this.ensureToolPermission(toolName, tool.name);
-      const toolOptions: ToolsOptions = {
-        scope: 'GENERAL',
-        from: 'mcp',
-        defaultPermission: this.toolsPermissionMap[toolName],
-        introduction: {
-          title: tool.name,
-          about: tool.description,
-        },
-        definition: {
-          name: toolName,
-          description: tool.description || `MCP tool: ${tool.name} from ${serverName}`,
-          schema: tool.schema,
-        },
-        invoke: async (_ctx: Context, args: any) => {
-          try {
-            const result = await tool.invoke(args);
-            return result;
-          } catch (error: any) {
-            return {
-              status: 'error' as const,
-              content: error?.message || 'Tool invocation failed',
-            };
-          }
-        },
-      };
-      register.registerTools(toolOptions);
-    }
+  private async getActiveToolsMap(ctx?: Context): Promise<Record<string, StructuredToolInterface[]>> {
+    // Connection caches are not configuration authorities, including on other application instances.
+    const entries = await this.listMCP({ enabled: true });
+    const sharedServers = new Set(entries.filter((entry) => !entry.useUserContext).map((entry) => entry.name));
+    const userServers = new Set(entries.filter((entry) => entry.useUserContext).map((entry) => entry.name));
+    const userToolsMap = ctx ? await this.userContextClientManager.getToolsMap(ctx) : {};
+    return {
+      ...Object.fromEntries(Object.entries(this.toolsMap).filter(([name]) => sharedServers.has(name))),
+      ...Object.fromEntries(Object.entries(userToolsMap).filter(([name]) => userServers.has(name))),
+    };
   }
 
-  private ensureToolPermission(toolName: string, rawToolName: string) {
-    if (!(toolName in this.toolsPermissionMap)) {
-      this.toolsPermissionMap[toolName] = rawToolName.startsWith('get') ? 'ALLOW' : 'ASK';
+  private async readToolPermissions(serverNames: string[]): Promise<Map<string, Permission>> {
+    if (!serverNames.length) {
+      return new Map();
     }
+    const records = await this.collectionManager.getCollection('aiMcpToolPermissions').model.findAll({
+      where: { serverName: { [Op.in]: serverNames } },
+    });
+    return new Map(
+      records.map((record) => [
+        JSON.stringify([record.get('serverName'), record.get('toolName')]),
+        record.get('permission') === 'ALLOW' ? 'ALLOW' : 'ASK',
+      ]),
+    );
   }
 
-  async listMCPTools(ctx?: Context): Promise<Record<string, MCPToolEntry[]>> {
-    const toolsMap = {
-      ...this.toolsMap,
-      ...(ctx ? await this.userContextClientManager.getToolsMap(ctx) : {}),
-    };
-
-    return this.formatMCPTools(toolsMap);
+  private resolveToolPermission(
+    permissions: Map<string, Permission>,
+    serverName: string,
+    toolName: string,
+  ): Permission {
+    return permissions.get(JSON.stringify([serverName, toolName])) ?? (toolName.startsWith('get') ? 'ALLOW' : 'ASK');
   }
 
-  private formatMCPTools(toolsMap: Record<string, StructuredToolInterface[]>): Record<string, MCPToolEntry[]> {
+  async listMCPTools(ctx?: Context): Promise<Record<string, MCPToolEntry[]>> {
+    const toolsMap = await this.getActiveToolsMap(ctx);
+    const permissions = await this.readToolPermissions(Object.keys(toolsMap));
     return Object.fromEntries(
       Object.entries(toolsMap).map(([serverName, tools]) => [
         serverName,
-        tools.map((tool) => {
-          const toolName = `mcp-${serverName}-${tool.name}`;
-          this.ensureToolPermission(toolName, tool.name);
-          return {
-            name: toolName,
-            title: tool.name,
-            description: tool.description,
-            serverName,
-            permission: this.toolsPermissionMap[toolName] ?? 'ASK',
-          };
-        }),
+        tools.map((tool) => ({
+          name: `mcp-${serverName}-${tool.name}`,
+          title: tool.name,
+          description: tool.description,
+          serverName,
+          permission: this.resolveToolPermission(permissions, serverName, tool.name),
+        })),
       ]),
     );
   }
 
-  async updateMCPToolPermission(toolName: string, permission: Permission): Promise<void> {
-    this.toolsPermissionMap[toolName] = permission;
+  async updateMCPToolPermission(toolName: string, permission: Permission, ctx?: Context): Promise<void> {
+    if (typeof toolName !== 'string' || !toolName.trim() || !['ASK', 'ALLOW'].includes(permission)) {
+      throw new MCPToolPermissionError('INVALID_PERMISSION');
+    }
+    // Resolve from metadata, never by splitting the public name: both identifiers may contain hyphens.
+    const matches = Object.values(await this.listMCPTools(ctx))
+      .flat()
+      .filter((tool) => tool.name === toolName);
+    if (matches.length !== 1) {
+      throw new MCPToolPermissionError('TOOL_NOT_FOUND_OR_AMBIGUOUS');
+    }
+    const tool = matches[0];
+    await this.sequelize.transaction({ type: Transaction.TYPES.IMMEDIATE }, async (transaction) => {
+      const server = await this.aiMcpClientsModel.findOne({
+        where: { name: tool.serverName, enabled: true },
+        transaction,
+        lock: transaction.LOCK.UPDATE,
+      });
+      if (!server) {
+        throw new MCPToolPermissionError('TOOL_NOT_FOUND_OR_AMBIGUOUS');
+      }
+      const permissionModel = this.collectionManager.getCollection('aiMcpToolPermissions').model;
+      await permissionModel.upsert(
+        { serverName: tool.serverName, toolName: tool.title, permission },
+        {
+          transaction,
+          // Sequelize expects physical column names here, including when underscored is enabled.
+          conflictFields: ['serverName', 'toolName'].map((name) => permissionModel.getAttributes()[name].field || name),
+        },
+      );
+    });
   }
 
   async clearUserContextCache(): Promise<void> {
@@ -372,6 +396,7 @@ export class DefaultMCPManager implements MCPManager {
             headers: normalizedEntry.headers,
             restart: normalizedEntry.restart,
             useUserContext: normalizedEntry.useUserContext,
+            fromFile: normalizedEntry.fromFile === true || existed.get('fromFile') === true,
           },
           { transaction },
         );
@@ -421,3 +446,4 @@ export function defineMCP(options: MCPOptions) {
 }
 
 export * from './types';
+export * from './errors';

package/src/mcp-manager/types.ts

@@ -20,7 +20,7 @@ export interface MCPManager extends MCPRegistration {
   getClient(): MultiServerMCPClient | null;
   getMCPToolsProvider(): DynamicToolsProvider;
   listMCPTools(ctx?: Context): Promise<Record<string, MCPToolEntry[]>>;
-  updateMCPToolPermission(toolName: string, permission: Permission): Promise<void>;
+  updateMCPToolPermission(toolName: string, permission: Permission, ctx?: Context): Promise<void>;
   clearUserContextCache(): Promise<void>;
 }
 
@@ -37,10 +37,13 @@ export type MCPOptions = {
   headers?: Record<string, string>;
   restart?: Record<string, any>;
   useUserContext?: boolean;
+  fromFile?: boolean;
 };
 
 export type MCPEntry = MCPOptions & {
   name: string;
+  title?: string;
+  description?: string;
   enabled: boolean;
 };