@nocobase/ai 2.1.0-beta.14 → 2.1.0-beta.16

package/src/loader/mcp.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { 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';
+
+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;
+
+  constructor(
+    protected readonly ai: AIManager,
+    protected readonly options: MCPLoaderOptions,
+  ) {
+    super(ai, options);
+    this.log = options.log;
+    this.scanner = new DirectoryScanner(this.options.scan);
+  }
+
+  protected async scan(): Promise<void> {
+    this.files = await this.scanner.scan();
+  }
+
+  protected async import(): Promise<void> {
+    if (!this.files.length) {
+      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) {
+      return;
+    }
+
+    const { mcpManager } = this.ai;
+    for (const descriptor of this.mcpDescriptors) {
+      try {
+        await mcpManager.registerMCP({
+          [descriptor.name]: descriptor.options,
+        });
+      } catch (e) {
+        this.log?.error(`mcp [${descriptor.name}] register ignored: error occur when invoke registerMCP`, e);
+      }
+    }
+  }
+}
+
+export type MCPDescriptor = {
+  name: string;
+  file: FileDescriptor;
+  options: MCPOptions;
+};

package/src/loader/skills.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { DirectoryScanner, DirectoryScannerOptions, FileDescriptor } from './scanner';
+import { readFile } from 'fs/promises';
+import _ from 'lodash';
+import { existsSync } from 'fs';
+import { AIManager } from '../ai-manager';
+import { LoadAndRegister } from './types';
+import { Logger } from '@nocobase/logger';
+import matter from 'gray-matter';
+import path from 'path';
+import { SkillsScope } from '../skills-manager';
+
+export type SkillsLoaderOptions = { pluginName: string; scan: DirectoryScannerOptions; log?: Logger };
+export class SkillsLoader extends LoadAndRegister<SkillsLoaderOptions> {
+  protected readonly scanner: DirectoryScanner;
+
+  protected files: FileDescriptor[] = [];
+  protected skillsDescriptors: SkillsDescriptor[] = [];
+  protected log: Logger;
+
+  constructor(
+    protected readonly ai: AIManager,
+    protected readonly options: SkillsLoaderOptions,
+  ) {
+    super(ai, options);
+    this.log = options.log;
+    this.scanner = new DirectoryScanner(this.options.scan);
+  }
+
+  protected async scan(): Promise<void> {
+    this.files = await this.scanner.scan();
+  }
+
+  protected async import(): Promise<void> {
+    if (!this.files.length) {
+      return;
+    }
+
+    this.skillsDescriptors = await Promise.all(
+      this.files
+        .map(async (skillsFile) => {
+          if (skillsFile.basename !== 'SKILLS.md') {
+            return null;
+          }
+          if (!existsSync(skillsFile.path)) {
+            this.log?.error(`skills [${skillsFile.directory}] ignored: can not find SKILLS.md at ${skillsFile.path}`);
+            return null;
+          }
+          const skillsDir = new FileDescriptor(path.dirname(skillsFile.path));
+          const name = skillsFile.directory;
+          const entry: Partial<SkillsDescriptor> = { name, skillsFile, skillsDir };
+          try {
+            const skills = await readFile(skillsFile.path, 'utf-8');
+            const { data, content } = matter(skills);
+            entry.scope = data['scope'] ?? 'SPECIFIED';
+            entry.name = data['name'];
+            entry.description = data['description'];
+            entry.content = content;
+            entry.introduction = data['introduction'];
+            entry.tools = data['tools'] ?? [];
+          } catch (e) {
+            this.log?.error(`skills [${name}] load fail: error occur when reading SKILLS.md at ${skillsFile.path}`, e);
+            return null;
+          }
+
+          try {
+            const toolsScanner = new DirectoryScanner({
+              basePath: skillsDir.path,
+              pattern: ['tools/**/*.ts', 'tools/**/*.js', '!tools/**/*.d.ts'],
+            });
+            const toolsFiles = await toolsScanner.scan();
+            entry.tools = Array.from(
+              new Set([
+                ...entry.tools,
+                ...toolsFiles.map((it) =>
+                  it.basename === 'index.ts' || it.basename === 'index.js' ? it.directory : it.name,
+                ),
+              ]),
+            );
+          } catch (e) {
+            this.log?.error(`skills [${name}] load fail: error occur when loading tools at ${skillsDir.path}`, e);
+            return null;
+          }
+
+          return entry as SkillsDescriptor;
+        })
+        .filter((it) => it != null),
+    );
+  }
+
+  protected async register(): Promise<void> {
+    if (!this.skillsDescriptors.length) {
+      return;
+    }
+    const { skillsManager } = this.ai;
+    for (const descriptor of this.skillsDescriptors) {
+      await skillsManager.registerSkills({
+        scope: descriptor.scope,
+        name: descriptor.name,
+        description: descriptor.description,
+        content: descriptor.content,
+        tools: descriptor.tools,
+        introduction: descriptor.introduction,
+      });
+    }
+  }
+}
+
+export type SkillsDescriptor = {
+  scope: SkillsScope;
+  name: string;
+  description: string;
+  content: string;
+  skillsFile: FileDescriptor;
+  skillsDir: FileDescriptor;
+  tools?: string[];
+  introduction?: {
+    title: string;
+    about?: string;
+  };
+};

package/src/loader/tools.ts

@@ -18,7 +18,7 @@ import { LoadAndRegister } from './types';
 import { Logger } from '@nocobase/logger';
 import { isNonEmptyObject } from './utils';
 
-export type ToolsLoaderOptions = { scan: DirectoryScannerOptions; log?: Logger };
+export type ToolsLoaderOptions = { pluginName: string; scan: DirectoryScannerOptions; log?: Logger };
 export class ToolsLoader extends LoadAndRegister<ToolsLoaderOptions> {
   protected readonly scanner: DirectoryScanner;
 
@@ -106,7 +106,7 @@ export class ToolsLoader extends LoadAndRegister<ToolsLoaderOptions> {
         continue;
       }
       const { name, toolsOptions, description } = descriptor;
-      if (await toolsManager.getTools(name)) {
+      if (toolsManager.isToolsExisted(name)) {
         this.log?.warn(`tools [${descriptor.name}] register ignored: duplicate register for tools`);
         continue;
       }
@@ -118,6 +118,7 @@ export class ToolsLoader extends LoadAndRegister<ToolsLoaderOptions> {
       }
       try {
         toolsManager.registerTools(toolsOptions);
+        this.log?.info(`tools [${toolsOptions.definition.name}] registered from plugin [${this.options.pluginName}]`);
       } catch (e) {
         this.log?.error(`tools [${descriptor.name}] register ignored: error occur when invoke registerTools`, e);
         continue;

package/src/mcp-manager/index.ts

@@ -0,0 +1,364 @@
+/**
+ * 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 { SequelizeCollectionManager } from '@nocobase/data-source-manager';
+import { Op } 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 { Context } from '@nocobase/actions';
+
+export class DefaultMCPManager implements MCPManager {
+  private readonly mcpRegistry = new Registry<MCPEntry>();
+  private readonly provideCollectionManager: () => { collectionManager: SequelizeCollectionManager };
+  private mode = 'memory';
+  private client: MultiServerMCPClient | null = null;
+  private toolsMap: Record<string, StructuredToolInterface[]> = {};
+  private toolsPermissionMap: Record<string, Permission> = {};
+
+  constructor(private readonly app: any) {
+    this.provideCollectionManager = () => app.mainDataSource;
+  }
+
+  async init() {
+    if (this.mode === 'memory') {
+      await this.persistence();
+      this.mode = 'database';
+    }
+    try {
+      await this.rebuildClient();
+    } catch (e) {
+      this.app.log.error('fail to init mcp clients', e);
+    }
+  }
+
+  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));
+      }
+    } else {
+      for (const [name, options] of Object.entries(registration)) {
+        await this.persistenceEntry({
+          name,
+          ...this.normalizeEntry(name, options),
+        });
+      }
+    }
+  }
+
+  async getMCP(name: string): Promise<MCPEntry> {
+    return (await this.aiMcpClientsModel?.findOne({ where: { name } }))?.toJSON() as MCPEntry;
+  }
+
+  async listMCP(filter: MCPFilter = {}): Promise<MCPEntry[]> {
+    const where = {};
+    if (filter.name) {
+      where['name'] = {
+        [Op.substring]: filter.name,
+      };
+    }
+    if (filter.enabled != null) {
+      where['enabled'] = filter.enabled;
+    }
+    if (filter.transport) {
+      where['transport'] = filter.transport;
+    }
+    return (await this.aiMcpClientsModel?.findAll({ where }))?.map((item) => item.toJSON() as MCPEntry) ?? [];
+  }
+
+  async rebuildClient(): Promise<void> {
+    // Close existing client if exists
+    if (this.client) {
+      try {
+        await this.client.close();
+      } catch (e) {
+        // Ignore close errors
+      }
+      this.client = null;
+      this.toolsMap = {};
+    }
+
+    // Get all enabled MCP entries
+    const entries = await this.listMCP({ enabled: true });
+
+    if (entries.length === 0) {
+      return;
+    }
+
+    // Build connections object
+    const connections: Record<string, StdioConnection | StreamableHTTPConnection> = {};
+    for (const entry of entries) {
+      connections[entry.name] = this.buildMCPConnection(entry);
+    }
+
+    // Create new client and initialize connections
+    this.client = new MultiServerMCPClient(connections);
+    const toolsMap = await this.client.initializeConnections();
+
+    // 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';
+        }
+      }
+    }
+  }
+
+  getClient(): MultiServerMCPClient | null {
+    return this.client;
+  }
+
+  getMCPToolsProvider(): DynamicToolsProvider {
+    return async (register: ToolsRegistration): Promise<void> => {
+      // Use cached tools from rebuildClient
+      for (const [serverName, tools] of Object.entries(this.toolsMap)) {
+        for (const tool of tools) {
+          const toolName = `mcp-${serverName}-${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);
+        }
+      }
+    };
+  }
+
+  async listMCPTools(): Promise<Record<string, MCPToolEntry[]>> {
+    return Object.fromEntries(
+      Object.entries(this.toolsMap).map(([serverName, tools]) => [
+        serverName,
+        tools.map((tool) => {
+          const toolName = `mcp-${serverName}-${tool.name}`;
+          return {
+            name: toolName,
+            title: tool.name,
+            description: tool.description,
+            serverName,
+            permission: this.toolsPermissionMap[toolName] ?? 'ASK',
+          };
+        }),
+      ]),
+    );
+  }
+
+  async updateMCPToolPermission(toolName: string, permission: Permission): Promise<void> {
+    this.toolsPermissionMap[toolName] = permission;
+  }
+
+  async testConnection(options: MCPOptions): Promise<MCPTestResult> {
+    const { transport } = options;
+
+    // Validate required fields
+    if (!transport) {
+      return {
+        success: false,
+        error: 'Transport type is required',
+      };
+    }
+
+    if (transport === 'stdio' && !options.command) {
+      return {
+        success: false,
+        error: 'Command is required for stdio transport',
+      };
+    }
+
+    if ((transport === 'http' || transport === 'sse') && !options.url) {
+      return {
+        success: false,
+        error: 'URL is required for HTTP/SSE transport',
+      };
+    }
+
+    let client: MultiServerMCPClient | null = null;
+
+    try {
+      const connection = this.buildMCPConnection(options);
+      const serverName = 'test-server';
+
+      client = new MultiServerMCPClient({
+        [serverName]: connection,
+      });
+
+      // Initialize connections with timeout
+      const toolsMap = await Promise.race([
+        client.initializeConnections(),
+        new Promise<never>((_resolve, reject) =>
+          setTimeout(() => reject(new Error('Connection timeout (60s)')), 60000),
+        ),
+      ]);
+      const tools = toolsMap[serverName] || [];
+
+      // Get tool names for display
+      const toolNames = tools.map((tool) => tool.name);
+
+      return {
+        success: true,
+        message: 'Connection successful',
+        toolsCount: tools.length,
+        tools: toolNames.slice(0, 20), // Limit to 20 tools for display
+        toolsTruncated: toolNames.length > 20,
+      };
+    } catch (error: any) {
+      const errorMessage = error?.message || 'Failed to connect to MCP server';
+
+      // Provide helpful hints for common errors
+      let hint: string | undefined;
+      if (errorMessage.includes('EACCES') || errorMessage.includes('permission denied')) {
+        hint = 'Try running: npm cache clean --force';
+      } else if (errorMessage.includes('ENOENT') || errorMessage.includes('not found')) {
+        hint = 'Make sure the command exists and is accessible';
+      } else if (errorMessage.includes('timeout')) {
+        hint = 'The server took too long to respond. Check if the server is running correctly.';
+      }
+
+      return {
+        success: false,
+        error: errorMessage,
+        details: hint ? `Hint: ${hint}\n\n${error?.stack || ''}` : error?.stack || '',
+      };
+    } finally {
+      if (client) {
+        try {
+          await client.close();
+        } catch (e) {
+          // Ignore close errors
+        }
+      }
+    }
+  }
+
+  private buildMCPConnection(options: MCPOptions): StdioConnection | StreamableHTTPConnection {
+    const { transport, command, args, env, url, headers, restart } = options;
+
+    if (transport === 'stdio') {
+      const connection: StdioConnection = {
+        transport: 'stdio',
+        command: command || '',
+        args: args || [],
+      };
+
+      if (env && Object.keys(env).length > 0) {
+        connection.env = env;
+      }
+
+      if (restart && typeof restart === 'object' && !Array.isArray(restart)) {
+        connection.restart = restart;
+      }
+
+      return connection;
+    }
+
+    // For http or sse transport
+    const connection: StreamableHTTPConnection = {
+      transport: transport === 'sse' ? 'sse' : 'http',
+      url: url || '',
+    };
+
+    if (headers && Object.keys(headers).length > 0) {
+      connection.headers = headers;
+    }
+
+    return connection;
+  }
+
+  async persistence(): Promise<void> {
+    for (const entry of this.mcpRegistry.getValues()) {
+      await this.persistenceEntry(entry);
+    }
+  }
+
+  private async persistenceEntry(entry: MCPEntry): Promise<void> {
+    await this.sequelize.transaction(async (transaction) => {
+      const existed = await this.aiMcpClientsModel.findOne({ where: { name: entry.name }, transaction });
+      if (existed) {
+        await existed.update(
+          {
+            transport: entry.transport,
+            command: entry.command,
+            args: entry.args,
+            env: entry.env,
+            url: entry.url,
+            headers: entry.headers,
+            restart: entry.restart,
+          },
+          { transaction },
+        );
+        return;
+      }
+
+      await this.aiMcpClientsModel.create(
+        {
+          ...entry,
+        },
+        { transaction },
+      );
+    });
+  }
+
+  private normalizeEntry(name: string, options: MCPOptions): MCPEntry {
+    return {
+      name,
+      enabled: true,
+      ...options,
+      args: options.args ?? [],
+      env: options.env ?? {},
+    };
+  }
+
+  private get aiMcpClientsCollection() {
+    return this.collectionManager.getCollection('aiMcpClients');
+  }
+
+  private get aiMcpClientsModel() {
+    return this.aiMcpClientsCollection?.model;
+  }
+
+  private get sequelize() {
+    return this.collectionManager.db.sequelize;
+  }
+
+  private get collectionManager() {
+    return this.provideCollectionManager().collectionManager;
+  }
+}
+
+export function defineMCP(options: MCPOptions) {
+  return options;
+}
+
+export * from './types';

package/src/mcp-manager/types.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 type { MultiServerMCPClient } from '@langchain/mcp-adapters';
+import type { DynamicToolsProvider, Permission } from '../tools-manager/types';
+
+export interface MCPManager extends MCPRegistration {
+  init(): Promise<void>;
+  getMCP(name: string): Promise<MCPEntry>;
+  listMCP(filter: MCPFilter): Promise<MCPEntry[]>;
+  testConnection(options: MCPOptions): Promise<MCPTestResult>;
+  rebuildClient(): Promise<void>;
+  getClient(): MultiServerMCPClient | null;
+  getMCPToolsProvider(): DynamicToolsProvider;
+  listMCPTools(): Promise<Record<string, MCPToolEntry[]>>;
+  updateMCPToolPermission(toolName: string, permission: Permission): Promise<void>;
+}
+
+export interface MCPRegistration {
+  registerMCP(registration: { [key: string | symbol]: MCPOptions }): Promise<void>;
+}
+
+export type MCPOptions = {
+  transport: MCPTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+  restart?: Record<string, any>;
+};
+
+export type MCPEntry = MCPOptions & {
+  name: string;
+  enabled: boolean;
+};
+
+export type MCPFilter = {
+  name?: string;
+  enabled?: boolean;
+  transport?: MCPTransport;
+};
+
+export type MCPTransport = 'stdio' | 'sse' | 'http';
+
+export type MCPTestResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  details?: string;
+  toolsCount?: number;
+  tools?: string[];
+  toolsTruncated?: boolean;
+};
+
+export type MCPToolEntry = {
+  name: string;
+  title: string;
+  description?: string;
+  serverName: string;
+  permission: Permission;
+};