@nocobase/ai 2.3.0-beta.21 → 2.3.0-beta.23

package/lib/loader/mcp.d.ts

@@ -6,30 +6,14 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-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 type { Logger } from '@nocobase/logger';
+import type { MCPRegistration } from '../mcp-manager/types';
 export type MCPLoaderOptions = {
-    pluginName: string;
-    scan: DirectoryScannerOptions;
-    log?: Logger;
+    log?: Pick<Logger, 'error'>;
 };
-export declare class MCPLoader extends LoadAndRegister<MCPLoaderOptions> {
-    protected readonly ai: AIManager;
-    protected readonly options: MCPLoaderOptions;
-    protected readonly scanner: DirectoryScanner;
-    protected files: FileDescriptor[];
-    protected mcpDescriptors: MCPDescriptor[];
-    protected log: Logger;
-    constructor(ai: AIManager, options: MCPLoaderOptions);
-    protected scan(): Promise<void>;
-    protected import(): Promise<void>;
-    protected register(): Promise<void>;
+export declare class MCPLoader {
+    private readonly manager;
+    private readonly options;
+    constructor(manager: MCPRegistration, options?: MCPLoaderOptions);
+    load(): Promise<void>;
 }
-export type MCPDescriptor = {
-    name: string;
-    file: FileDescriptor;
-    options: MCPOptions;
-};

package/lib/loader/mcp.js

@@ -31,73 +31,73 @@ __export(mcp_exports, {
 });
 module.exports = __toCommonJS(mcp_exports);
 var import_utils = require("@nocobase/utils");
-var import_fs = require("fs");
-var import_types = require("./types");
-var import_scanner = require("./scanner");
-var import_utils2 = require("./utils");
-const _MCPLoader = class _MCPLoader extends import_types.LoadAndRegister {
-  constructor(ai, options) {
-    super(ai, options);
-    this.ai = ai;
+var import_promises = require("node:fs/promises");
+var import_options_renderer = require("../mcp-manager/options-renderer");
+const _MCPLoader = class _MCPLoader {
+  constructor(manager, options = {}) {
+    this.manager = manager;
     this.options = options;
-    this.log = options.log;
-    this.scanner = new import_scanner.DirectoryScanner(this.options.scan);
   }
-  scanner;
-  files = [];
-  mcpDescriptors = [];
-  log;
-  async scan() {
-    this.files = await this.scanner.scan();
-  }
-  async import() {
-    if (!this.files.length) {
+  async load() {
+    var _a, _b, _c, _d, _e, _f;
+    const filePath = (0, import_utils.storagePathJoin)("ai", "mcp", "servers.json");
+    let content;
+    try {
+      content = await (0, import_promises.readFile)(filePath, "utf8");
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        return;
+      }
+      (_a = this.options.log) == null ? void 0 : _a.error(`MCP file ignored at ${filePath}: unable to read file`);
       return;
     }
-    const descriptors = await Promise.all(
-      this.files.map(async (file) => {
-        var _a, _b, _c;
-        const name = file.name;
-        if (!(0, import_fs.existsSync)(file.path)) {
-          (_a = this.log) == null ? void 0 : _a.error(`mcp [${name}] ignored: can not find definition file at ${file.path}`);
-          return null;
-        }
-        try {
-          const imported = await (0, import_utils.importModule)(file.path);
-          const mod = (imported == null ? void 0 : imported.default) ?? imported;
-          const options = typeof mod === "function" ? mod() : mod;
-          if (!(0, import_utils2.isNonEmptyObject)(options)) {
-            (_b = this.log) == null ? void 0 : _b.warn(`mcp [${name}] register ignored: invalid definition at ${file.path}`);
-            return null;
-          }
-          return {
-            name,
-            file,
-            options
-          };
-        } catch (e) {
-          (_c = this.log) == null ? void 0 : _c.error(`mcp [${name}] load fail: error occur when import ${file.path}`, e);
-          return null;
-        }
-      })
-    );
-    this.mcpDescriptors = descriptors.filter((item) => Boolean(item));
-  }
-  async register() {
-    var _a;
-    if (!this.mcpDescriptors.length) {
+    let definitions;
+    try {
+      definitions = JSON.parse(content);
+    } catch {
+      (_b = this.options.log) == null ? void 0 : _b.error(`MCP file ignored at ${filePath}: invalid JSON`);
+      return;
+    }
+    if (!Array.isArray(definitions)) {
+      (_c = this.options.log) == null ? void 0 : _c.error(`MCP file ignored at ${filePath}: expected an array`);
       return;
     }
-    const { mcpManager } = this.ai;
-    for (const descriptor of this.mcpDescriptors) {
+    const registration = /* @__PURE__ */ Object.create(null);
+    for (const [index, value] of definitions.entries()) {
+      const definition = value;
+      let reason;
+      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"].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)) {
+        reason = "duplicate name";
+      }
+      if (reason) {
+        (_d = this.options.log) == null ? void 0 : _d.error(`MCP file ignored at ${filePath}, entry ${index + 1}: ${reason}`);
+        return;
+      }
       try {
-        await mcpManager.registerMCP({
-          [descriptor.name]: descriptor.options
-        });
-      } catch (e) {
-        (_a = this.log) == null ? void 0 : _a.error(`mcp [${descriptor.name}] register ignored: error occur when invoke registerMCP`, e);
+        registration[definition.name] = (0, import_options_renderer.normalizeMCPOptions)({ ...definition, fromFile: true });
+      } catch {
+        (_e = this.options.log) == null ? void 0 : _e.error(
+          `MCP file ignored at ${filePath}, entry ${index + 1}: unable to normalize configuration`
+        );
+        return;
       }
     }
+    if (!Object.keys(registration).length) {
+      return;
+    }
+    try {
+      await this.manager.registerMCP(registration);
+    } catch {
+      (_f = this.options.log) == null ? void 0 : _f.error(`MCP registration failed at ${filePath}`);
+    }
   }
 };
 __name(_MCPLoader, "MCPLoader");

package/lib/mcp-manager/index.js

@@ -48,7 +48,7 @@ const _DefaultMCPManager = class _DefaultMCPManager {
       buildConnection: /* @__PURE__ */ __name((options) => this.buildMCPConnection(options), "buildConnection")
     });
   }
-  mcpRegistry = new import_utils.Registry();
+  mcpRegistry = new import_utils.Registry({ override: true });
   provideCollectionManager;
   mode = "memory";
   client = null;
@@ -67,9 +67,12 @@ const _DefaultMCPManager = class _DefaultMCPManager {
     }
   }
   async registerMCP(registration) {
+    var _a;
     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 || ((_a = this.mcpRegistry.get(name)) == null ? void 0 : _a.fromFile) === true;
+        this.mcpRegistry.register(name, entry);
       }
     } else {
       for (const [name, options] of Object.entries(registration)) {
@@ -333,7 +336,8 @@ ${(error == null ? void 0 : error.stack) || ""}` : (error == null ? void 0 : err
             url: normalizedEntry.url,
             headers: normalizedEntry.headers,
             restart: normalizedEntry.restart,
-            useUserContext: normalizedEntry.useUserContext
+            useUserContext: normalizedEntry.useUserContext,
+            fromFile: normalizedEntry.fromFile === true || existed.get("fromFile") === true
           },
           { transaction }
         );

package/lib/mcp-manager/types.d.ts

@@ -35,9 +35,12 @@ 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;
 };
 export type MCPFilter = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/ai",
-  "version": "2.3.0-beta.21",
+  "version": "2.3.0-beta.23",
   "description": "",
   "license": "Apache-2.0",
   "main": "./lib/index.js",
@@ -17,10 +17,10 @@
     "@langchain/mcp-adapters": "1.1.3",
     "@langchain/ollama": "1.2.7",
     "@langchain/openai": "1.4.7",
-    "@nocobase/data-source-manager": "2.3.0-beta.21",
-    "@nocobase/logger": "2.3.0-beta.21",
-    "@nocobase/resourcer": "2.3.0-beta.21",
-    "@nocobase/utils": "2.3.0-beta.21",
+    "@nocobase/data-source-manager": "2.3.0-beta.23",
+    "@nocobase/logger": "2.3.0-beta.23",
+    "@nocobase/resourcer": "2.3.0-beta.23",
+    "@nocobase/utils": "2.3.0-beta.23",
     "d3-dsv": "2",
     "fast-glob": "^3.3.2",
     "flexsearch": "^0.8.2",
@@ -37,5 +37,5 @@
     "url": "git+https://github.com/nocobase/nocobase.git",
     "directory": "packages/ai"
   },
-  "gitHead": "a2bdd27cc7bc8ced9ad395b3a7468fc1850eef4a"
+  "gitHead": "53ad17b1117bae431d21cddaac7af7da484967fc"
 }

package/src/__tests__/mcp-file-loader.test.ts

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MCPLoader } from '../loader/mcp';
+
+describe('deployment MCP file validation', () => {
+  let storage: string;
+  let filePath: string;
+  const registerMCP = vi.fn();
+  const log = { error: vi.fn() };
+
+  beforeEach(async () => {
+    storage = await mkdtemp(join(tmpdir(), 'mcp-file-'));
+    // Include backslashes on POSIX too, so JSON-escaped path assertions fail outside Windows CI.
+    const configStorage = join(storage, 'deployment\\config');
+    vi.stubEnv('STORAGE_PATH', configStorage);
+    filePath = join(configStorage, 'ai', 'mcp', 'servers.json');
+    await mkdir(join(configStorage, 'ai', 'mcp'), { recursive: true });
+    registerMCP.mockReset();
+    log.error.mockReset();
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    await rm(storage, { recursive: true, force: true });
+  });
+
+  const load = () => new MCPLoader({ registerMCP }, { log }).load();
+
+  it('uses STORAGE_PATH and treats a missing file or an empty array as a no-op', async () => {
+    await load();
+    await writeFile(filePath, '[]');
+    await load();
+    expect(registerMCP).not.toHaveBeenCalled();
+    expect(log.error).not.toHaveBeenCalled();
+  });
+
+  it('registers all transports with a trusted source marker', async () => {
+    await writeFile(
+      filePath,
+      JSON.stringify([
+        { name: 'local', transport: 'stdio', command: 'node', args: [1, null, '--test'], useUserContext: true },
+        { name: 'remote', transport: 'http', url: 'http://127.0.0.1/mcp', headers: { count: 2 }, useUserContext: true },
+        { name: 'events', transport: 'sse', env: { count: 3 }, extraMetadata: 'kept' },
+      ]),
+    );
+    await load();
+    expect(registerMCP).toHaveBeenCalledTimes(1);
+    expect(registerMCP).toHaveBeenCalledWith({
+      local: expect.objectContaining({
+        transport: 'stdio',
+        fromFile: true,
+        args: ['1', '--test'],
+        useUserContext: false,
+      }),
+      remote: expect.objectContaining({
+        transport: 'http',
+        fromFile: true,
+        headers: { count: '2' },
+        useUserContext: true,
+      }),
+      events: expect.objectContaining({ transport: 'sse', fromFile: true, env: { count: '3' }, extraMetadata: 'kept' }),
+    });
+  });
+
+  it.each([
+    '{"secret":"do-not-log",',
+    '{}',
+    'null',
+    '[null]',
+    '[[]]',
+    '[1]',
+    '[{"transport":"http"}]',
+    '[{"name":"  ","transport":"http"}]',
+    '[{"name":1,"transport":"http"}]',
+    '[{"name":"a"}]',
+    '[{"name":"a","transport":"websocket"}]',
+    '[{"name":"a","transport":"http","enabled":true}]',
+    '[{"name":"a","transport":"http","fromFile":false}]',
+    '[{"name":"a","transport":"http"},{"name":"a","transport":"sse"}]',
+    '[{"name":"good","transport":"http","env":{"TOKEN":"do-not-log"}},{"name":"bad"}]',
+    '[{"name":"good","transport":"http"},{"name":"bad","transport":"stdio","args":[{"toString":"do-not-log"}]}]',
+    '[{"name":"good","transport":"http"},{"name":"bad","transport":"stdio","env":{"TOKEN":{"toString":"do-not-log"}}}]',
+    '[{"name":"good","transport":"http"},{"name":"bad","transport":"http","headers":{"TOKEN":{"toString":"do-not-log"}}}]',
+  ])('ignores the entire invalid file without exposing configuration: %s', async (contents) => {
+    await writeFile(filePath, contents);
+    await expect(load()).resolves.toBeUndefined();
+    expect(registerMCP).not.toHaveBeenCalled();
+    expect(log.error).toHaveBeenCalledTimes(1);
+    expect(JSON.stringify(log.error.mock.calls)).not.toContain('do-not-log');
+    expect(log.error).toHaveBeenCalledWith(expect.stringContaining(filePath));
+  });
+
+  it('does not log arbitrary registration errors that may contain credentials', async () => {
+    await writeFile(filePath, '[{"name":"safe","transport":"http"}]');
+    registerMCP.mockRejectedValueOnce(new Error('do-not-log'));
+    await expect(load()).resolves.toBeUndefined();
+    expect(log.error).toHaveBeenCalledTimes(1);
+    expect(JSON.stringify(log.error.mock.calls)).not.toContain('do-not-log');
+  });
+});

package/src/__tests__/mcp.test.ts

@@ -8,44 +8,72 @@
  */
 
 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);
+    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 +91,81 @@ 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 = {
+    Reflect.set(mcpManager, 'toolsMap', {
       weather: [
         {
           name: 'getForecast',
@@ -76,7 +176,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/index.ts

@@ -19,7 +19,7 @@ import { normalizeMCPOptions, renderMCPOptions } from './options-renderer';
 import { UserContextMCPClientManager } from './user-context-client-manager';
 
 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;
@@ -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)) {
@@ -372,6 +374,7 @@ export class DefaultMCPManager implements MCPManager {
             headers: normalizedEntry.headers,
             restart: normalizedEntry.restart,
             useUserContext: normalizedEntry.useUserContext,
+            fromFile: normalizedEntry.fromFile === true || existed.get('fromFile') === true,
           },
           { transaction },
         );

package/src/mcp-manager/types.ts

@@ -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;
 };