🔄 refactor: MCP Registry System with Distributed Caching (#10191)

* refactor: Restructure MCP registry system with caching

- Split MCPServersRegistry into modular components:
  - MCPServerInspector: handles server inspection and health checks
  - MCPServersInitializer: manages server initialization logic
  - MCPServersRegistry: simplified registry coordination
- Add distributed caching layer:
  - ServerConfigsCacheRedis: Redis-backed configuration cache
  - ServerConfigsCacheInMemory: in-memory fallback cache
  - RegistryStatusCache: distributed leader election state
- Add promise utilities (withTimeout) replacing Promise.race patterns
- Add comprehensive cache integration tests for all cache implementations
- Remove unused MCPManager.getAllToolFunctions method

* fix: Update OAuth flow to include user-specific headers

* chore: Update Jest configuration to ignore additional test files

- Added patterns to ignore files ending with .helper.ts and .helper.d.ts in testPathIgnorePatterns for cleaner test runs.

* fix: oauth headers in callback

* chore: Update Jest testPathIgnorePatterns to exclude helper files

- Modified testPathIgnorePatterns in package.json to ignore files ending with .helper.ts and .helper.d.ts for cleaner test execution.

* ci: update test mocks

---------

Co-authored-by: Danny Avila <danny@librechat.ai>

packages/api/src/mcp/registry/MCPServerInspector.ts

@@ -0,0 +1,123 @@
+import { Constants } from 'librechat-data-provider';
+import type { JsonSchemaType } from '@librechat/data-schemas';
+import type { MCPConnection } from '~/mcp/connection';
+import type * as t from '~/mcp/types';
+import { detectOAuthRequirement } from '~/mcp/oauth';
+import { isEnabled } from '~/utils';
+import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';
+
+/**
+ * Inspects MCP servers to discover their metadata, capabilities, and tools.
+ * Connects to servers and populates configuration with OAuth requirements,
+ * server instructions, capabilities, and available tools.
+ */
+export class MCPServerInspector {
+  private constructor(
+    private readonly serverName: string,
+    private readonly config: t.ParsedServerConfig,
+    private connection: MCPConnection | undefined,
+  ) {}
+
+  /**
+   * Inspects a server and returns an enriched configuration with metadata.
+   * Detects OAuth requirements and fetches server capabilities.
+   * @param serverName - The name of the server (used for tool function naming)
+   * @param rawConfig - The raw server configuration
+   * @param connection - The MCP connection
+   * @returns A fully processed and enriched configuration with server metadata
+   */
+  public static async inspect(
+    serverName: string,
+    rawConfig: t.MCPOptions,
+    connection?: MCPConnection,
+  ): Promise<t.ParsedServerConfig> {
+    const start = Date.now();
+    const inspector = new MCPServerInspector(serverName, rawConfig, connection);
+    await inspector.inspectServer();
+    inspector.config.initDuration = Date.now() - start;
+    return inspector.config;
+  }
+
+  private async inspectServer(): Promise<void> {
+    await this.detectOAuth();
+
+    if (this.config.startup !== false && !this.config.requiresOAuth) {
+      let tempConnection = false;
+      if (!this.connection) {
+        tempConnection = true;
+        this.connection = await MCPConnectionFactory.create({
+          serverName: this.serverName,
+          serverConfig: this.config,
+        });
+      }
+
+      await Promise.allSettled([
+        this.fetchServerInstructions(),
+        this.fetchServerCapabilities(),
+        this.fetchToolFunctions(),
+      ]);
+
+      if (tempConnection) await this.connection.disconnect();
+    }
+  }
+
+  private async detectOAuth(): Promise<void> {
+    if (this.config.requiresOAuth != null) return;
+    if (this.config.url == null || this.config.startup === false) {
+      this.config.requiresOAuth = false;
+      return;
+    }
+
+    const result = await detectOAuthRequirement(this.config.url);
+    this.config.requiresOAuth = result.requiresOAuth;
+    this.config.oauthMetadata = result.metadata;
+  }
+
+  private async fetchServerInstructions(): Promise<void> {
+    if (isEnabled(this.config.serverInstructions)) {
+      this.config.serverInstructions = this.connection!.client.getInstructions();
+    }
+  }
+
+  private async fetchServerCapabilities(): Promise<void> {
+    const capabilities = this.connection!.client.getServerCapabilities();
+    this.config.capabilities = JSON.stringify(capabilities);
+    const tools = await this.connection!.client.listTools();
+    this.config.tools = tools.tools.map((tool) => tool.name).join(', ');
+  }
+
+  private async fetchToolFunctions(): Promise<void> {
+    this.config.toolFunctions = await MCPServerInspector.getToolFunctions(
+      this.serverName,
+      this.connection!,
+    );
+  }
+
+  /**
+   * Converts server tools to LibreChat-compatible tool functions format.
+   * @param serverName - The name of the server
+   * @param connection - The MCP connection
+   * @returns Tool functions formatted for LibreChat
+   */
+  public static async getToolFunctions(
+    serverName: string,
+    connection: MCPConnection,
+  ): Promise<t.LCAvailableTools> {
+    const { tools }: t.MCPToolListResponse = await connection.client.listTools();
+
+    const toolFunctions: t.LCAvailableTools = {};
+    tools.forEach((tool) => {
+      const name = `${tool.name}${Constants.mcp_delimiter}${serverName}`;
+      toolFunctions[name] = {
+        type: 'function',
+        ['function']: {
+          name,
+          description: tool.description,
+          parameters: tool.inputSchema as JsonSchemaType,
+        },
+      };
+    });
+
+    return toolFunctions;
+  }
+}