Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
♻️ refactor: MCPManager for Scalability, Fix App-Level Detection, Add Lazy Connections (#8930)
Theo N. Truong8780a7816503
diff --git a/.env.example b/.env.exampleindex d0435c746d..819b0dfab5 100644--- a/.env.example+++ b/.env.example@@ -698,3 +698,16 @@ OPENWEATHER_API_KEY=# JINA_API_KEY=your_jina_api_key# or# COHERE_API_KEY=your_cohere_api_key++#======================#+# MCP Configuration #+#======================#++# Treat 401/403 responses as OAuth requirement when no oauth metadata found+# MCP_OAUTH_ON_AUTH_ERROR=true++# Timeout for OAuth detection requests in milliseconds+# MCP_OAUTH_DETECTION_TIMEOUT=5000++# Cache connection status checks for this many milliseconds to avoid expensive verification+# MCP_CONNECTION_CHECK_TTL=60000diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex 207aa17e66..ad0a75ab9b 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -147,7 +147,7 @@ Apply the following naming conventions to branches, labels, and other Git-relate## 8. Module Import Conventions- `npm` packages first,- - from shortest line (top) to longest (bottom)+ - from longest line (top) to shortest (bottom)- Followed by typescript types (pertains to data-provider and client workspaces)- longest line (top) to shortest (bottom)@@ -157,6 +157,8 @@ Apply the following naming conventions to branches, labels, and other Git-relate- longest line (top) to shortest (bottom)- imports with alias `~` treated the same as relative import with respect to line length+**Note:** ESLint will automatically enforce these import conventions when you run `npm run lint --fix` or through pre-commit hooks.+---Please ensure that you adapt this summary to fit the specific context and nuances of your project.diff --git a/.gitignore b/.gitignoreindex 38b9bbc9ec..0796905501 100644--- a/.gitignore+++ b/.gitignore@@ -137,3 +137,4 @@ helm/**/.values.yaml/.openai//.tabnine//.codeium+*.local.mddiff --git a/api/config/index.js b/api/config/index.jsindex 2e69e87118..2ffcf1cdfd 100644--- a/api/config/index.js+++ b/api/config/index.js@@ -1,27 +1,13 @@+const { MCPManager, FlowStateManager } = require('@librechat/api');const { EventSource } = require('eventsource');const { Time } = require('librechat-data-provider');-const { MCPManager, FlowStateManager } = require('@librechat/api');const logger = require('./winston');global.EventSource = EventSource;/** @type {MCPManager} */-let mcpManager = null;let flowManager = null;-/**- * @param {string} [userId] - Optional user ID, to avoid disconnecting the current user.- * @returns {MCPManager}- */-function getMCPManager(userId) {- if (!mcpManager) {- mcpManager = MCPManager.getInstance();- } else {- mcpManager.checkIdleConnections(userId);- }- return mcpManager;-}-/*** @param {Keyv} flowsCache* @returns {FlowStateManager}@@ -37,6 +23,7 @@ function getFlowStateManager(flowsCache) {module.exports = {logger,- getMCPManager,+ createMCPManager: MCPManager.createInstance,+ getMCPManager: MCPManager.getInstance,getFlowStateManager,};diff --git a/api/server/routes/__tests__/mcp.spec.js b/api/server/routes/__tests__/mcp.spec.jsindex 272b9f7236..243711d764 100644--- a/api/server/routes/__tests__/mcp.spec.js+++ b/api/server/routes/__tests__/mcp.spec.js@@ -1,7 +1,7 @@-const express = require('express');+const { MongoMemoryServer } = require('mongodb-memory-server');const request = require('supertest');const mongoose = require('mongoose');-const { MongoMemoryServer } = require('mongodb-memory-server');+const express = require('express');jest.mock('@librechat/api', () => ({MCPOAuthHandler: {@@ -494,12 +494,9 @@ describe('MCP Routes', () => {});it('should return 500 when token retrieval throws an unexpected error', async () => {- const mockFlowManager = {- getFlowState: jest.fn().mockRejectedValue(new Error('Database connection failed')),- };-- getLogStores.mockReturnValue({});- require('~/config').getFlowStateManager.mockReturnValue(mockFlowManager);+ getLogStores.mockImplementation(() => {+ throw new Error('Database connection failed');+ });const response = await request(app).get('/api/mcp/oauth/tokens/test-user-id:error-flow');@@ -563,8 +560,8 @@ describe('MCP Routes', () => {});describe('POST /oauth/cancel/:serverName', () => {- const { getLogStores } = require('~/cache');const { MCPOAuthHandler } = require('@librechat/api');+ const { getLogStores } = require('~/cache');it('should cancel OAuth flow successfully', async () => {const mockFlowManager = {@@ -644,15 +641,15 @@ describe('MCP Routes', () => {});describe('POST /:serverName/reinitialize', () => {- const { loadCustomConfig } = require('~/server/services/Config');- const { getUserPluginAuthValue } = require('~/server/services/PluginService');-it('should return 404 when server is not found in configuration', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'other-server': {},- },- });+ const mockMcpManager = {+ getRawConfig: jest.fn().mockReturnValue(null),+ disconnectUserConnection: jest.fn().mockResolvedValue(),+ };++ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);+ require('~/config').getFlowStateManager.mockReturnValue({});+ require('~/cache').getLogStores.mockReturnValue({});const response = await request(app).post('/api/mcp/non-existent-server/reinitialize');@@ -663,16 +660,11 @@ describe('MCP Routes', () => {});it('should handle OAuth requirement during reinitialize', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'oauth-server': {- customUserVars: {},- },- },- });-const mockMcpManager = {- disconnectServer: jest.fn().mockResolvedValue(),+ getRawConfig: jest.fn().mockReturnValue({+ customUserVars: {},+ }),+ disconnectUserConnection: jest.fn().mockResolvedValue(),mcpConfigs: {},getUserConnection: jest.fn().mockImplementation(async ({ oauthStart }) => {if (oauthStart) {@@ -690,7 +682,7 @@ describe('MCP Routes', () => {expect(response.status).toBe(200);expect(response.body).toEqual({- success: 'https://oauth.example.com/auth',+ success: true,message: "MCP server 'oauth-server' ready for OAuth authentication",serverName: 'oauth-server',oauthRequired: true,@@ -699,14 +691,9 @@ describe('MCP Routes', () => {});it('should return 500 when reinitialize fails with non-OAuth error', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'error-server': {},- },- });-const mockMcpManager = {- disconnectServer: jest.fn().mockResolvedValue(),+ getRawConfig: jest.fn().mockReturnValue({}),+ disconnectUserConnection: jest.fn().mockResolvedValue(),mcpConfigs: {},getUserConnection: jest.fn().mockRejectedValue(new Error('Connection failed')),};@@ -724,7 +711,13 @@ describe('MCP Routes', () => {});it('should return 500 when unexpected error occurs', async () => {- loadCustomConfig.mockRejectedValue(new Error('Config loading failed'));+ const mockMcpManager = {+ getRawConfig: jest.fn().mockImplementation(() => {+ throw new Error('Config loading failed');+ }),+ };++ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);const response = await request(app).post('/api/mcp/test-server/reinitialize');@@ -747,29 +740,17 @@ describe('MCP Routes', () => {expect(response.body).toEqual({ error: 'User not authenticated' });});- it('should handle errors when fetching custom user variables', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': {- customUserVars: {- API_KEY: 'test-key-var',- SECRET_TOKEN: 'test-secret-var',- },- },- },- });-- getUserPluginAuthValue- .mockResolvedValueOnce('test-api-key-value')- .mockRejectedValueOnce(new Error('Database error'));-+ it('should successfully reinitialize server and cache tools', async () => {const mockUserConnection = {- fetchTools: jest.fn().mockResolvedValue([]),+ fetchTools: jest.fn().mockResolvedValue([+ { name: 'tool1', description: 'Test tool 1', inputSchema: { type: 'object' } },+ { name: 'tool2', description: 'Test tool 2', inputSchema: { type: 'object' } },+ ]),};const mockMcpManager = {- disconnectServer: jest.fn().mockResolvedValue(),- mcpConfigs: {},+ getRawConfig: jest.fn().mockReturnValue({ endpoint: 'http://test-server.com' }),+ disconnectUserConnection: jest.fn().mockResolvedValue(),getUserConnection: jest.fn().mockResolvedValue(mockUserConnection),};@@ -784,38 +765,54 @@ describe('MCP Routes', () => {const response = await request(app).post('/api/mcp/test-server/reinitialize');expect(response.status).toBe(200);- expect(response.body.success).toBe(true);+ expect(response.body).toEqual({+ success: true,+ message: "MCP server 'test-server' reinitialized successfully",+ serverName: 'test-server',+ oauthRequired: false,+ oauthUrl: null,+ });+ expect(mockMcpManager.disconnectUserConnection).toHaveBeenCalledWith(+ 'test-user-id',+ 'test-server',+ );+ expect(setCachedTools).toHaveBeenCalled();});- it('should return failure message when reinitialize completely fails', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': {},- },- });+ it('should handle server with custom user variables', async () => {+ const mockUserConnection = {+ fetchTools: jest.fn().mockResolvedValue([]),+ };const mockMcpManager = {- disconnectServer: jest.fn().mockResolvedValue(),- mcpConfigs: {},- getUserConnection: jest.fn().mockResolvedValue(null),+ getRawConfig: jest.fn().mockReturnValue({+ endpoint: 'http://test-server.com',+ customUserVars: {+ API_KEY: 'some-env-var',+ },+ }),+ disconnectUserConnection: jest.fn().mockResolvedValue(),+ getUserConnection: jest.fn().mockResolvedValue(mockUserConnection),};require('~/config').getMCPManager.mockReturnValue(mockMcpManager);require('~/config').getFlowStateManager.mockReturnValue({});require('~/cache').getLogStores.mockReturnValue({});+ require('~/server/services/PluginService').getUserPluginAuthValue.mockResolvedValue(+ 'api-key-value',+ );const { getCachedTools, setCachedTools } = require('~/server/services/Config');- const { Constants } = require('librechat-data-provider');- getCachedTools.mockResolvedValue({- [`existing-tool${Constants.mcp_delimiter}test-server`]: { type: 'function' },- });+ getCachedTools.mockResolvedValue({});setCachedTools.mockResolvedValue();const response = await request(app).post('/api/mcp/test-server/reinitialize');expect(response.status).toBe(200);- expect(response.body.success).toBe(false);- expect(response.body.message).toBe("Failed to reinitialize MCP server 'test-server'");+ expect(response.body.success).toBe(true);+ expect(+ require('~/server/services/PluginService').getUserPluginAuthValue,+ ).toHaveBeenCalledWith('test-user-id', 'API_KEY', false);});});@@ -984,21 +981,19 @@ describe('MCP Routes', () => {});describe('GET /:serverName/auth-values', () => {- const { loadCustomConfig } = require('~/server/services/Config');const { getUserPluginAuthValue } = require('~/server/services/PluginService');it('should return auth value flags for server', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': {- customUserVars: {- API_KEY: 'some-env-var',- SECRET_TOKEN: 'another-env-var',- },+ const mockMcpManager = {+ getRawConfig: jest.fn().mockReturnValue({+ customUserVars: {+ API_KEY: 'some-env-var',+ SECRET_TOKEN: 'another-env-var',},- },- });+ }),+ };+ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);getUserPluginAuthValue.mockResolvedValueOnce('some-api-key-value').mockResolvedValueOnce('');const response = await request(app).get('/api/mcp/test-server/auth-values');@@ -1017,11 +1012,11 @@ describe('MCP Routes', () => {});it('should return 404 when server is not found in configuration', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'other-server': {},- },- });+ const mockMcpManager = {+ getRawConfig: jest.fn().mockReturnValue(null),+ };++ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);const response = await request(app).get('/api/mcp/non-existent-server/auth-values');@@ -1032,16 +1027,15 @@ describe('MCP Routes', () => {});it('should handle errors when checking auth values', async () => {- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': {- customUserVars: {- API_KEY: 'some-env-var',- },+ const mockMcpManager = {+ getRawConfig: jest.fn().mockReturnValue({+ customUserVars: {+ API_KEY: 'some-env-var',},- },- });+ }),+ };+ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);getUserPluginAuthValue.mockRejectedValue(new Error('Database error'));const response = await request(app).get('/api/mcp/test-server/auth-values');@@ -1057,7 +1051,13 @@ describe('MCP Routes', () => {});it('should return 500 when auth values check throws unexpected error', async () => {- loadCustomConfig.mockRejectedValue(new Error('Config loading failed'));+ const mockMcpManager = {+ getRawConfig: jest.fn().mockImplementation(() => {+ throw new Error('Config loading failed');+ }),+ };++ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);const response = await request(app).get('/api/mcp/test-server/auth-values');@@ -1066,14 +1066,13 @@ describe('MCP Routes', () => {});it('should handle customUserVars that is not an object', async () => {- const { loadCustomConfig } = require('~/server/services/Config');- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': {- customUserVars: 'not-an-object',- },- },- });+ const mockMcpManager = {+ getRawConfig: jest.fn().mockReturnValue({+ customUserVars: 'not-an-object',+ }),+ };++ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);const response = await request(app).get('/api/mcp/test-server/auth-values');@@ -1097,98 +1096,6 @@ describe('MCP Routes', () => {});});- describe('POST /:serverName/reinitialize - Tool Deletion Coverage', () => {- it('should handle null cached tools during reinitialize (triggers || {} fallback)', async () => {- const { loadCustomConfig, getCachedTools } = require('~/server/services/Config');-- const mockUserConnection = {- fetchTools: jest.fn().mockResolvedValue([{ name: 'new-tool', description: 'A new tool' }]),- };-- const mockMcpManager = {- getUserConnection: jest.fn().mockResolvedValue(mockUserConnection),- disconnectServer: jest.fn(),- initializeServer: jest.fn(),- mcpConfigs: {},- };- require('~/config').getMCPManager.mockReturnValue(mockMcpManager);-- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': { env: { API_KEY: 'test-key' } },- },- });-- getCachedTools.mockResolvedValue(null);-- const response = await request(app).post('/api/mcp/test-server/reinitialize').expect(200);-- expect(response.body).toEqual({- message: "MCP server 'test-server' reinitialized successfully",- success: true,- oauthRequired: false,- oauthUrl: null,- serverName: 'test-server',- });- });-- it('should delete existing cached tools during successful reinitialize', async () => {- const {- loadCustomConfig,- getCachedTools,- setCachedTools,- } = require('~/server/services/Config');-- const mockUserConnection = {- fetchTools: jest.fn().mockResolvedValue([{ name: 'new-tool', description: 'A new tool' }]),- };-- const mockMcpManager = {- getUserConnection: jest.fn().mockResolvedValue(mockUserConnection),- disconnectServer: jest.fn(),- initializeServer: jest.fn(),- mcpConfigs: {},- };- require('~/config').getMCPManager.mockReturnValue(mockMcpManager);-- loadCustomConfig.mockResolvedValue({- mcpServers: {- 'test-server': { env: { API_KEY: 'test-key' } },- },- });-- const existingTools = {- 'old-tool_mcp_test-server': { type: 'function' },- 'other-tool_mcp_other-server': { type: 'function' },- };- getCachedTools.mockResolvedValue(existingTools);-- const response = await request(app).post('/api/mcp/test-server/reinitialize').expect(200);-- expect(response.body).toEqual({- message: "MCP server 'test-server' reinitialized successfully",- success: true,- oauthRequired: false,- oauthUrl: null,- serverName: 'test-server',- });-- expect(setCachedTools).toHaveBeenCalledWith(- expect.objectContaining({- 'new-tool_mcp_test-server': expect.any(Object),- 'other-tool_mcp_other-server': { type: 'function' },- }),- { userId: 'test-user-id' },- );- expect(setCachedTools).toHaveBeenCalledWith(- expect.not.objectContaining({- 'old-tool_mcp_test-server': expect.anything(),- }),- { userId: 'test-user-id' },- );- });- });-describe('GET /:serverName/oauth/callback - Edge Cases', () => {it('should handle OAuth callback without toolFlowId (falsy toolFlowId)', async () => {const { MCPOAuthHandler } = require('@librechat/api');diff --git a/api/server/routes/mcp.js b/api/server/routes/mcp.jsindex a725cf666a..5931ca02f6 100644--- a/api/server/routes/mcp.js+++ b/api/server/routes/mcp.js@@ -1,11 +1,11 @@-const { Router } = require('express');const { logger } = require('@librechat/data-schemas');const { MCPOAuthHandler } = require('@librechat/api');-const { CacheKeys, Constants } = require('librechat-data-provider');-const { findToken, updateToken, createToken, deleteTokens } = require('~/models');-const { setCachedTools, getCachedTools, loadCustomConfig } = require('~/server/services/Config');+const { Router } = require('express');const { getMCPSetupData, getServerConnectionStatus } = require('~/server/services/MCP');+const { findToken, updateToken, createToken, deleteTokens } = require('~/models');+const { setCachedTools, getCachedTools } = require('~/server/services/Config');const { getUserPluginAuthValue } = require('~/server/services/PluginService');+const { CacheKeys, Constants } = require('librechat-data-provider');const { getMCPManager, getFlowStateManager } = require('~/config');const { requireJwtAuth } = require('~/server/middleware');const { getLogStores } = require('~/cache');@@ -315,9 +315,9 @@ router.post('/:serverName/reinitialize', requireJwtAuth, async (req, res) => {logger.info(`[MCP Reinitialize] Reinitializing server: ${serverName}`);- const printConfig = false;- const config = await loadCustomConfig(printConfig);- if (!config || !config.mcpServers || !config.mcpServers[serverName]) {+ const mcpManager = getMCPManager();+ const serverConfig = mcpManager.getRawConfig(serverName);+ if (!serverConfig) {return res.status(404).json({error: `MCP server '${serverName}' not found in configuration`,});@@ -325,13 +325,12 @@ router.post('/:serverName/reinitialize', requireJwtAuth, async (req, res) => {const flowsCache = getLogStores(CacheKeys.FLOWS);const flowManager = getFlowStateManager(flowsCache);- const mcpManager = getMCPManager();- await mcpManager.disconnectServer(serverName);- logger.info(`[MCP Reinitialize] Disconnected existing server: ${serverName}`);+ await mcpManager.disconnectUserConnection(user.id, serverName);+ logger.info(+ `[MCP Reinitialize] Disconnected existing user connection for server: ${serverName}`,+ );- const serverConfig = config.mcpServers[serverName];- mcpManager.mcpConfigs[serverName] = serverConfig;let customUserVars = {};if (serverConfig.customUserVars && typeof serverConfig.customUserVars === 'object') {for (const varName of Object.keys(serverConfig.customUserVars)) {@@ -437,7 +436,7 @@ router.post('/:serverName/reinitialize', requireJwtAuth, async (req, res) => {};res.json({- success: (userConnection && !oauthRequired) || (oauthRequired && oauthUrl),+ success: Boolean((userConnection && !oauthRequired) || (oauthRequired && oauthUrl)),message: getResponseMessage(),serverName,oauthRequired,@@ -551,15 +550,14 @@ router.get('/:serverName/auth-values', requireJwtAuth, async (req, res) => {return res.status(401).json({ error: 'User not authenticated' });}- const printConfig = false;- const config = await loadCustomConfig(printConfig);- if (!config || !config.mcpServers || !config.mcpServers[serverName]) {+ const mcpManager = getMCPManager();+ const serverConfig = mcpManager.getRawConfig(serverName);+ if (!serverConfig) {return res.status(404).json({error: `MCP server '${serverName}' not found in configuration`,});}- const serverConfig = config.mcpServers[serverName];const pluginKey = `${Constants.mcp_prefix}${serverName}`;const authValueFlags = {};diff --git a/api/server/services/initializeMCPs.js b/api/server/services/initializeMCPs.jsindex 18edb2449d..40c75e1b0e 100644--- a/api/server/services/initializeMCPs.js+++ b/api/server/services/initializeMCPs.js@@ -1,8 +1,7 @@const { logger } = require('@librechat/data-schemas');-const { CacheKeys } = require('librechat-data-provider');-const { findToken, updateToken, createToken, deleteTokens } = require('~/models');-const { getMCPManager, getFlowStateManager } = require('~/config');const { getCachedTools, setCachedTools } = require('./Config');+const { CacheKeys } = require('librechat-data-provider');+const { createMCPManager } = require('~/config');const { getLogStores } = require('~/cache');/**@@ -31,33 +30,19 @@ async function initializeMCPs(app) {}logger.info('Initializing MCP servers...');- const mcpManager = getMCPManager();- const flowsCache = getLogStores(CacheKeys.FLOWS);- const flowManager = flowsCache ? getFlowStateManager(flowsCache) : null;+ const mcpManager = await createMCPManager(mcpServers);try {- await mcpManager.initializeMCPs({- mcpServers: filteredServers,- flowManager,- tokenMethods: {- findToken,- updateToken,- createToken,- deleteTokens,- },- });-delete app.locals.mcpConfig;- const availableTools = await getCachedTools();+ const cachedTools = await getCachedTools();- if (!availableTools) {+ if (!cachedTools) {logger.warn('No available tools found in cache during MCP initialization');return;}- const toolsCopy = { ...availableTools };- await mcpManager.mapAvailableTools(toolsCopy, flowManager);- await setCachedTools(toolsCopy, { isGlobal: true });+ const mcpTools = mcpManager.getAppToolFunctions();+ await setCachedTools({ ...cachedTools, ...mcpTools }, { isGlobal: true });const cache = getLogStores(CacheKeys.CONFIG_STORE);await cache.delete(CacheKeys.TOOLS);diff --git a/eslint.config.mjs b/eslint.config.mjsindex b602303047..f53e8cc694 100644--- a/eslint.config.mjs+++ b/eslint.config.mjs@@ -2,11 +2,11 @@ import { fileURLToPath } from 'node:url';import path from 'node:path';import typescriptEslintEslintPlugin from '@typescript-eslint/eslint-plugin';import { fixupConfigRules, fixupPluginRules } from '@eslint/compat';-// import perfectionist from 'eslint-plugin-perfectionist';+import perfectionist from 'eslint-plugin-perfectionist';import reactHooks from 'eslint-plugin-react-hooks';-import prettier from 'eslint-plugin-prettier';import tsParser from '@typescript-eslint/parser';import importPlugin from 'eslint-plugin-import';+import prettier from 'eslint-plugin-prettier';import { FlatCompat } from '@eslint/eslintrc';import jsxA11Y from 'eslint-plugin-jsx-a11y';import i18next from 'eslint-plugin-i18next';@@ -62,7 +62,7 @@ export default ['jsx-a11y': fixupPluginRules(jsxA11Y),'import/parsers': tsParser,i18next,- // perfectionist,+ perfectionist,prettier: fixupPluginRules(prettier),},@@ -140,32 +140,31 @@ export default ['react/prop-types': 'off','react/display-name': 'off',- // 'perfectionist/sort-imports': [- // 'error',- // {- // type: 'line-length',- // order: 'desc',- // newlinesBetween: 'never',- // customGroups: {- // value: {- // react: ['^react$'],- // // react: ['^react$', '^fs', '^zod', '^path'],- // local: ['^(\\.{1,2}|~)/', '^librechat-data-provider'],- // },- // },- // groups: [- // 'react',- // 'builtin',- // 'external',- // ['builtin-type', 'external-type'],- // ['internal-type'],- // 'local',- // ['parent', 'sibling', 'index'],- // 'object',- // 'unknown',- // ],- // },- // ],+ 'perfectionist/sort-imports': [+ 'error',+ {+ type: 'line-length',+ order: 'desc',+ newlinesBetween: 'never',+ customGroups: {+ value: {+ react: ['^react$'],+ local: ['^(\\.{1,2}|~)/', '^librechat-data-provider'],+ },+ },+ groups: [+ 'react',+ 'builtin',+ 'external',+ ['builtin-type', 'external-type'],+ ['internal-type'],+ 'local',+ ['parent', 'sibling', 'index'],+ 'object',+ 'unknown',+ ],+ },+ ],// 'perfectionist/sort-named-imports': [// 'error',diff --git a/packages/api/jest.config.mjs b/packages/api/jest.config.mjsindex eb6be102de..1533a3d213 100644--- a/packages/api/jest.config.mjs+++ b/packages/api/jest.config.mjs@@ -1,7 +1,7 @@export default {collectCoverageFrom: ['src/**/*.{js,jsx,ts,tsx}', '!<rootDir>/node_modules/'],coveragePathIgnorePatterns: ['/node_modules/', '/dist/'],- testPathIgnorePatterns: ['/node_modules/', '/dist/'],+ testPathIgnorePatterns: ['/node_modules/', '/dist/', '\\.dev\\.ts$'],coverageReporters: ['text', 'cobertura'],testResultsProcessor: 'jest-junit',moduleNameMapper: {diff --git a/packages/api/src/index.ts b/packages/api/src/index.tsindex 21f16734cb..fb8e63a000 100644--- a/packages/api/src/index.ts+++ b/packages/api/src/index.ts@@ -1,5 +1,5 @@/* MCP */-export * from './mcp/manager';+export * from './mcp/MCPManager';export * from './mcp/oauth';export * from './mcp/auth';export * from './mcp/zod';diff --git a/packages/api/src/mcp/ConnectionsRepository.ts b/packages/api/src/mcp/ConnectionsRepository.tsnew file mode 100644index 0000000000..7bfb95ad2c--- /dev/null+++ b/packages/api/src/mcp/ConnectionsRepository.ts@@ -0,0 +1,87 @@+import { logger } from '@librechat/data-schemas';+import { MCPConnectionFactory, OAuthConnectionOptions } from '~/mcp/MCPConnectionFactory';+import { MCPConnection } from './connection';+import type * as t from './types';++/**+ * Manages MCP connections with lazy loading and reconnection.+ * Maintains a pool of connections and handles connection lifecycle management.+ */+export class ConnectionsRepository {+ protected readonly serverConfigs: Record<string, t.MCPOptions>;+ protected connections: Map<string, MCPConnection> = new Map();+ protected oauthOpts: OAuthConnectionOptions | undefined;++ constructor(serverConfigs: t.MCPServers, oauthOpts?: OAuthConnectionOptions) {+ this.serverConfigs = serverConfigs;+ this.oauthOpts = oauthOpts;+ }++ /** Checks whether this repository can connect to a specific server */+ has(serverName: string): boolean {+ return !!this.serverConfigs[serverName];+ }++ /** Gets or creates a connection for the specified server with lazy loading */+ async get(serverName: string): Promise<MCPConnection> {+ const existingConnection = this.connections.get(serverName);+ if (existingConnection && (await existingConnection.isConnected())) return existingConnection;+ else await this.disconnect(serverName);++ const connection = await MCPConnectionFactory.create(+ {+ serverName,+ serverConfig: this.getServerConfig(serverName),+ },+ this.oauthOpts,+ );++ this.connections.set(serverName, connection);+ return connection;+ }++ /** Gets or creates connections for multiple servers concurrently */+ async getMany(serverNames: string[]): Promise<Map<string, MCPConnection>> {+ const connectionPromises = serverNames.map(async (name) => [name, await this.get(name)]);+ const connections = await Promise.all(connectionPromises);+ return new Map(connections as [string, MCPConnection][]);+ }++ /** Returns all currently loaded connections without creating new ones */+ async getLoaded(): Promise<Map<string, MCPConnection>> {+ return this.getMany(Array.from(this.connections.keys()));+ }++ /** Gets or creates connections for all configured servers */+ async getAll(): Promise<Map<string, MCPConnection>> {+ return this.getMany(Object.keys(this.serverConfigs));+ }++ /** Disconnects and removes a specific server connection from the pool */+ disconnect(serverName: string): Promise<void> {+ const connection = this.connections.get(serverName);+ if (!connection) return Promise.resolve();+ this.connections.delete(serverName);+ return connection.disconnect().catch((err) => {+ logger.error(`${this.prefix(serverName)} Error disconnecting`, err);+ });+ }++ /** Disconnects all active connections and returns array of disconnect promises */+ disconnectAll(): Promise<void>[] {+ const serverNames = Array.from(this.connections.keys());+ return serverNames.map((serverName) => this.disconnect(serverName));+ }++ // Retrieves server configuration by name or throws if not found+ protected getServerConfig(serverName: string): t.MCPOptions {+ const serverConfig = this.serverConfigs[serverName];+ if (serverConfig) return serverConfig;+ throw new Error(`${this.prefix(serverName)} Server not found in configuration`);+ }++ // Returns formatted log prefix for server messages+ protected prefix(serverName: string): string {+ return `[MCP][${serverName}]`;+ }+}diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.tsnew file mode 100644index 0000000000..f657f0255e--- /dev/null+++ b/packages/api/src/mcp/MCPConnectionFactory.ts@@ -0,0 +1,384 @@+import { logger } from '@librechat/data-schemas';+import type { OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';+import type { TokenMethods } from '@librechat/data-schemas';+import type { TUser } from 'librechat-data-provider';+import type { MCPOAuthTokens, MCPOAuthFlowMetadata } from '~/mcp/oauth';+import type { FlowStateManager } from '~/flow/manager';+import type { FlowMetadata } from '~/flow/types';+import { MCPTokenStorage, MCPOAuthHandler } from '~/mcp/oauth';+import { MCPConnection } from './connection';+import { processMCPEnv } from '~/utils';+import type * as t from './types';++export interface BasicConnectionOptions {+ serverName: string;+ serverConfig: t.MCPOptions;+}++export interface OAuthConnectionOptions {+ useOAuth: true;+ user: TUser;+ customUserVars?: Record<string, string>;+ flowManager: FlowStateManager<MCPOAuthTokens | null>;+ tokenMethods?: TokenMethods;+ signal?: AbortSignal;+ oauthStart?: (authURL: string) => Promise<void>;+ oauthEnd?: () => Promise<void>;+ returnOnOAuth?: boolean;+}++/**+ * Factory for creating MCP connections with optional OAuth authentication.+ * Handles OAuth flows, token management, and connection retry logic.+ * NOTE: Much of the OAuth logic was extracted from the old MCPManager class as is.+ */+export class MCPConnectionFactory {+ protected readonly serverName: string;+ protected readonly serverConfig: t.MCPOptions;+ protected readonly logPrefix: string;+ protected readonly useOAuth: boolean;++ // OAuth-related properties (only set when useOAuth is true)+ protected readonly userId?: string;+ protected readonly flowManager?: FlowStateManager<MCPOAuthTokens | null>;+ protected readonly tokenMethods?: TokenMethods;+ protected readonly signal?: AbortSignal;+ protected readonly oauthStart?: (authURL: string) => Promise<void>;+ protected readonly oauthEnd?: () => Promise<void>;+ protected readonly returnOnOAuth?: boolean;++ /** Creates a new MCP connection with optional OAuth support */+ static async create(+ basic: BasicConnectionOptions,+ oauth?: OAuthConnectionOptions,+ ): Promise<MCPConnection> {+ const factory = new this(basic, oauth);+ return factory.createConnection();+ }++ protected constructor(basic: BasicConnectionOptions, oauth?: OAuthConnectionOptions) {+ this.serverConfig = processMCPEnv(basic.serverConfig, oauth?.user, oauth?.customUserVars);+ this.serverName = basic.serverName;+ this.useOAuth = !!oauth?.useOAuth;+ this.logPrefix = oauth?.user+ ? `[MCP][${basic.serverName}][${oauth.user.id}]`+ : `[MCP][${basic.serverName}]`;++ if (oauth?.useOAuth) {+ this.userId = oauth.user.id;+ this.flowManager = oauth.flowManager;+ this.tokenMethods = oauth.tokenMethods;+ this.signal = oauth.signal;+ this.oauthStart = oauth.oauthStart;+ this.oauthEnd = oauth.oauthEnd;+ this.returnOnOAuth = oauth.returnOnOAuth;+ }+ }++ /** Creates the base MCP connection with OAuth tokens */+ protected async createConnection(): Promise<MCPConnection> {+ const oauthTokens = this.useOAuth ? await this.getOAuthTokens() : null;+ const connection = new MCPConnection({+ serverName: this.serverName,+ serverConfig: this.serverConfig,+ userId: this.userId,+ oauthTokens,+ });++ if (this.useOAuth) this.handleOAuthEvents(connection);+ await this.attemptToConnect(connection);+ return connection;+ }++ /** Retrieves existing OAuth tokens from storage or returns null */+ protected async getOAuthTokens(): Promise<MCPOAuthTokens | null> {+ if (!this.tokenMethods?.findToken) return null;++ try {+ const tokens = await this.flowManager!.createFlowWithHandler(+ `tokens:${this.userId}:${this.serverName}`,+ 'mcp_get_tokens',+ async () => {+ return await MCPTokenStorage.getTokens({+ userId: this.userId!,+ serverName: this.serverName,+ findToken: this.tokenMethods!.findToken!,+ createToken: this.tokenMethods!.createToken,+ updateToken: this.tokenMethods!.updateToken,+ refreshTokens: this.createRefreshTokensFunction(),+ });+ },+ this.signal,+ );++ if (tokens) logger.info(`${this.logPrefix} Loaded OAuth tokens`);+ return tokens;+ } catch (error) {+ logger.debug(`${this.logPrefix} No existing tokens found or error loading tokens`, error);+ return null;+ }+ }++ /** Creates a function to refresh OAuth tokens when they expire */+ protected createRefreshTokensFunction(): (+ refreshToken: string,+ metadata: {+ userId: string;+ serverName: string;+ identifier: string;+ clientInfo?: OAuthClientInformation;+ },+ ) => Promise<MCPOAuthTokens> {+ return async (refreshToken, metadata) => {+ return await MCPOAuthHandler.refreshOAuthTokens(+ refreshToken,+ {+ serverUrl: (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url,+ serverName: metadata.serverName,+ clientInfo: metadata.clientInfo,+ },+ this.serverConfig.oauth,+ );+ };+ }++ /** Sets up OAuth event handlers for the connection */+ protected handleOAuthEvents(connection: MCPConnection): void {+ connection.on('oauthRequired', async (data) => {+ logger.info(`${this.logPrefix} oauthRequired event received`);++ // If we just want to initiate OAuth and return, handle it differently+ if (this.returnOnOAuth) {+ try {+ const config = this.serverConfig;+ const { authorizationUrl, flowId, flowMetadata } =+ await MCPOAuthHandler.initiateOAuthFlow(+ this.serverName,+ data.serverUrl || '',+ this.userId!,+ config?.oauth,+ );++ // Create the flow state so the OAuth callback can find it+ // We spawn this in the background without waiting for it+ this.flowManager!.createFlow(flowId, 'mcp_oauth', flowMetadata).catch(() => {+ // The OAuth callback will resolve this flow, so we expect it to timeout here+ // which is fine - we just need the flow state to exist+ });++ if (this.oauthStart) {+ logger.info(`${this.logPrefix} OAuth flow started, issuing authorization URL`);+ await this.oauthStart(authorizationUrl);+ }++ // Emit oauthFailed to signal that connection should not proceed+ // but OAuth was successfully initiated+ connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));+ return;+ } catch (error) {+ logger.error(`${this.logPrefix} Failed to initiate OAuth flow`, error);+ connection.emit('oauthFailed', new Error('OAuth initiation failed'));+ return;+ }+ }++ // Normal OAuth handling - wait for completion+ const result = await this.handleOAuthRequired();++ if (result?.tokens && this.tokenMethods?.createToken) {+ try {+ connection.setOAuthTokens(result.tokens);+ await MCPTokenStorage.storeTokens({+ userId: this.userId!,+ serverName: this.serverName,+ tokens: result.tokens,+ createToken: this.tokenMethods.createToken,+ updateToken: this.tokenMethods.updateToken,+ findToken: this.tokenMethods.findToken,+ clientInfo: result.clientInfo,+ });+ logger.info(`${this.logPrefix} OAuth tokens saved to storage`);+ } catch (error) {+ logger.error(`${this.logPrefix} Failed to save OAuth tokens to storage`, error);+ }+ }++ // Only emit oauthHandled if we actually got tokens (OAuth succeeded)+ if (result?.tokens) {+ connection.emit('oauthHandled');+ } else {+ // OAuth failed, emit oauthFailed to properly reject the promise+ logger.warn(`${this.logPrefix} OAuth failed, emitting oauthFailed event`);+ connection.emit('oauthFailed', new Error('OAuth authentication failed'));+ }+ });+ }++ /** Attempts to establish connection with timeout handling */+ protected async attemptToConnect(connection: MCPConnection): Promise<void> {+ const connectTimeout = this.serverConfig.initTimeout ?? 30000;+ const connectionTimeout = new Promise<void>((_, reject) =>+ setTimeout(+ () => reject(new Error(`Connection timeout after ${connectTimeout}ms`)),+ connectTimeout,+ ),+ );+ const connectionAttempt = this.connectTo(connection);+ await Promise.race([connectionAttempt, connectionTimeout]);++ if (await connection.isConnected()) return;+ logger.error(`${this.logPrefix} Failed to establish connection.`);+ }++ // Handles connection attempts with retry logic and OAuth error handling+ private async connectTo(connection: MCPConnection): Promise<void> {+ const maxAttempts = 3;+ let attempts = 0;+ let oauthHandled = false;++ while (attempts < maxAttempts) {+ try {+ await connection.connect();+ if (await connection.isConnected()) {+ return;+ }+ throw new Error('Connection attempt succeeded but status is not connected');+ } catch (error) {+ attempts++;++ if (this.useOAuth && this.isOAuthError(error)) {+ // Only handle OAuth if this is a user connection (has oauthStart handler)+ if (this.oauthStart && !oauthHandled) {+ const errorWithFlag = error as (Error & { isOAuthError?: boolean }) | undefined;+ if (errorWithFlag?.isOAuthError) {+ oauthHandled = true;+ logger.info(`${this.logPrefix} Handling OAuth`);+ await this.handleOAuthRequired();+ }+ }+ // Don't retry on OAuth errors - just throw+ logger.info(`${this.logPrefix} OAuth required, stopping connection attempts`);+ throw error;+ }++ if (attempts === maxAttempts) {+ logger.error(`${this.logPrefix} Failed to connect after ${maxAttempts} attempts`, error);+ throw error;+ }+ await new Promise((resolve) => setTimeout(resolve, 2000 * attempts));+ }+ }+ }++ // Determines if an error indicates OAuth authentication is required+ private isOAuthError(error: unknown): boolean {+ if (!error || typeof error !== 'object') {+ return false;+ }++ // Check for SSE error with 401 status+ if ('message' in error && typeof error.message === 'string') {+ return error.message.includes('401') || error.message.includes('Non-200 status code (401)');+ }++ // Check for error code+ if ('code' in error) {+ const code = (error as { code?: number }).code;+ return code === 401 || code === 403;+ }++ return false;+ }++ /** Manages OAuth flow initiation and completion */+ protected async handleOAuthRequired(): Promise<{+ tokens: MCPOAuthTokens | null;+ clientInfo?: OAuthClientInformation;+ } | null> {+ const serverUrl = (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url;+ logger.debug(`${this.logPrefix} \`handleOAuthRequired\` called with serverUrl: ${serverUrl}`);++ if (!this.flowManager || !serverUrl) {+ logger.error(+ `${this.logPrefix} OAuth required but flow manager not available or server URL missing for ${this.serverName}`,+ );+ logger.warn(`${this.logPrefix} Please configure OAuth credentials for ${this.serverName}`);+ return null;+ }++ try {+ logger.debug(`${this.logPrefix} Checking for existing OAuth flow for ${this.serverName}...`);++ /** Flow ID to check if a flow already exists */+ const flowId = MCPOAuthHandler.generateFlowId(this.userId!, this.serverName);++ /** Check if there's already an ongoing OAuth flow for this flowId */+ const existingFlow = await this.flowManager.getFlowState(flowId, 'mcp_oauth');+ if (existingFlow && existingFlow.status === 'PENDING') {+ logger.debug(+ `${this.logPrefix} OAuth flow already exists for ${flowId}, waiting for completion`,+ );+ /** Tokens from existing flow to complete */+ const tokens = await this.flowManager.createFlow(flowId, 'mcp_oauth');+ if (typeof this.oauthEnd === 'function') {+ await this.oauthEnd();+ }+ logger.info(+ `${this.logPrefix} OAuth flow completed, tokens received for ${this.serverName}`,+ );++ /** Client information from the existing flow metadata */+ const existingMetadata = existingFlow.metadata as unknown as MCPOAuthFlowMetadata;+ const clientInfo = existingMetadata?.clientInfo;++ return { tokens, clientInfo };+ }++ logger.debug(`${this.logPrefix} Initiating new OAuth flow for ${this.serverName}...`);+ const {+ authorizationUrl,+ flowId: newFlowId,+ flowMetadata,+ } = await MCPOAuthHandler.initiateOAuthFlow(+ this.serverName,+ serverUrl,+ this.userId!,+ this.serverConfig.oauth,+ );++ if (typeof this.oauthStart === 'function') {+ logger.info(`${this.logPrefix} OAuth flow started, issued authorization URL to user`);+ await this.oauthStart(authorizationUrl);+ } else {+ logger.info(`+═══════════════════════════════════════════════════════════════════════+Please visit the following URL to authenticate:++${authorizationUrl}++${this.logPrefix} Flow ID: ${newFlowId}+═══════════════════════════════════════════════════════════════════════+`);+ }++ /** Tokens from the new flow */+ const tokens = await this.flowManager.createFlow(+ newFlowId,+ 'mcp_oauth',+ flowMetadata as FlowMetadata,+ );+ if (typeof this.oauthEnd === 'function') {+ await this.oauthEnd();+ }+ logger.info(`${this.logPrefix} OAuth flow completed, tokens received for ${this.serverName}`);++ /** Client information from the flow metadata */+ const clientInfo = flowMetadata?.clientInfo;++ return { tokens, clientInfo };+ } catch (error) {+ logger.error(`${this.logPrefix} Failed to complete OAuth flow for ${this.serverName}`, error);+ return null;+ }+ }+}diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.tsnew file mode 100644index 0000000000..9173ec58a9--- /dev/null+++ b/packages/api/src/mcp/MCPManager.ts@@ -0,0 +1,263 @@+import { CallToolResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';+import { logger } from '@librechat/data-schemas';+import pick from 'lodash/pick';+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';+import type { TokenMethods } from '@librechat/data-schemas';+import type { TUser } from 'librechat-data-provider';+import type { FlowStateManager } from '~/flow/manager';+import type { MCPOAuthTokens } from '~/mcp/oauth';+import { UserConnectionManager } from '~/mcp/UserConnectionManager';+import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';+import { formatToolContent } from './parsers';+import { MCPConnection } from './connection';+import { CONSTANTS } from './enum';+import type * as t from './types';++/**+ * Centralized manager for MCP server connections and tool execution.+ * Extends UserConnectionManager to handle both app-level and user-specific connections.+ */+export class MCPManager extends UserConnectionManager {+ private static instance: MCPManager | null;+ // Connections shared by all users.+ private appConnections: ConnectionsRepository | null = null;++ /** Creates and initializes the singleton MCPManager instance */+ public static async createInstance(configs: t.MCPServers): Promise<MCPManager> {+ if (MCPManager.instance) throw new Error('MCPManager has already been initialized.');+ MCPManager.instance = new MCPManager(configs);+ await MCPManager.instance.initialize();+ return MCPManager.instance;+ }++ /** Returns the singleton MCPManager instance */+ public static getInstance(): MCPManager {+ if (!MCPManager.instance) throw new Error('MCPManager has not been initialized.');+ return MCPManager.instance;+ }++ /** Initializes the MCPManager by setting up server registry and app connections */+ public async initialize() {+ await this.serversRegistry.initialize();+ this.appConnections = new ConnectionsRepository(this.serversRegistry.appServerConfigs!);+ }++ /** Returns all app-level connections */+ public async getAllConnections(): Promise<Map<string, MCPConnection>> {+ return this.appConnections!.getAll();+ }++ /** Get servers that require OAuth */+ public getOAuthServers(): Set<string> {+ return this.serversRegistry.oauthServers!;+ }++ /** Returns all available tool functions from app-level connections */+ public getAppToolFunctions(): t.LCAvailableTools {+ return this.serversRegistry.toolFunctions!;+ }++ /**+ * Get instructions for MCP servers+ * @param serverNames Optional array of server names. If not provided or empty, returns all servers.+ * @returns Object mapping server names to their instructions+ */+ public getInstructions(serverNames?: string[]): Record<string, string> {+ const instructions = this.serversRegistry.serverInstructions!;+ if (!serverNames) return instructions;+ return pick(instructions, serverNames);+ }++ /**+ * Format MCP server instructions for injection into context+ * @param serverNames Optional array of server names to include. If not provided, includes all servers.+ * @returns Formatted instructions string ready for context injection+ */+ public formatInstructionsForContext(serverNames?: string[]): string {+ /** Instructions for specified servers or all stored instructions */+ const instructionsToInclude = this.getInstructions(serverNames);++ if (Object.keys(instructionsToInclude).length === 0) {+ return '';+ }++ // Format instructions for context injection+ const formattedInstructions = Object.entries(instructionsToInclude)+ .map(([serverName, instructions]) => {+ return `## ${serverName} MCP Server Instructions++${instructions}`;+ })+ .join('\n\n');++ return `# MCP Server Instructions++The following MCP servers are available with their specific instructions:++${formattedInstructions}++Please follow these instructions when using tools from the respective MCP servers.`;+ }++ /** Loads tools from all app-level connections into the manifest. */+ public async loadManifestTools({+ serverToolsCallback,+ getServerTools,+ }: {+ flowManager: FlowStateManager<MCPOAuthTokens | null>;+ serverToolsCallback?: (serverName: string, tools: t.LCManifestTool[]) => Promise<void>;+ getServerTools?: (serverName: string) => Promise<t.LCManifestTool[] | undefined>;+ }): Promise<t.LCToolManifest> {+ const mcpTools: t.LCManifestTool[] = [];+ const connections = await this.appConnections!.getAll();+ for (const [serverName, connection] of connections.entries()) {+ try {+ if (!(await connection.isConnected())) {+ logger.warn(+ `[MCP][${serverName}] Connection not available for ${serverName} manifest tools.`,+ );+ if (typeof getServerTools !== 'function') {+ logger.warn(+ `[MCP][${serverName}] No \`getServerTools\` function provided, skipping tool loading.`,+ );+ continue;+ }+ const serverTools = await getServerTools(serverName);+ if (serverTools && serverTools.length > 0) {+ logger.info(`[MCP][${serverName}] Loaded tools from cache for manifest`);+ mcpTools.push(...serverTools);+ }+ continue;+ }++ const tools = await connection.fetchTools();+ const serverTools: t.LCManifestTool[] = [];+ for (const tool of tools) {+ const pluginKey = `${tool.name}${CONSTANTS.mcp_delimiter}${serverName}`;++ const config = this.serversRegistry.parsedConfigs[serverName];+ const manifestTool: t.LCManifestTool = {+ name: tool.name,+ pluginKey,+ description: tool.description ?? '',+ icon: connection.iconPath,+ authConfig: config?.customUserVars+ ? Object.entries(config.customUserVars).map(([key, value]) => ({+ authField: key,+ label: value.title || key,+ description: value.description || '',+ }))+ : undefined,+ };+ if (config?.chatMenu === false) {+ manifestTool.chatMenu = false;+ }+ mcpTools.push(manifestTool);+ serverTools.push(manifestTool);+ }+ if (typeof serverToolsCallback === 'function') {+ await serverToolsCallback(serverName, serverTools);+ }+ } catch (error) {+ logger.error(`[MCP][${serverName}] Error fetching tools for manifest:`, error);+ }+ }++ return mcpTools;+ }++ /**+ * Calls a tool on an MCP server, using either a user-specific connection+ * (if userId is provided) or an app-level connection. Updates the last activity timestamp+ * for user-specific connections upon successful call initiation.+ */+ async callTool({+ user,+ serverName,+ toolName,+ provider,+ toolArguments,+ options,+ tokenMethods,+ flowManager,+ oauthStart,+ oauthEnd,+ customUserVars,+ }: {+ user?: TUser;+ serverName: string;+ toolName: string;+ provider: t.Provider;+ toolArguments?: Record<string, unknown>;+ options?: RequestOptions;+ tokenMethods?: TokenMethods;+ customUserVars?: Record<string, string>;+ flowManager: FlowStateManager<MCPOAuthTokens | null>;+ oauthStart?: (authURL: string) => Promise<void>;+ oauthEnd?: () => Promise<void>;+ }): Promise<t.FormattedToolResponse> {+ /** User-specific connection */+ let connection: MCPConnection | undefined;+ const userId = user?.id;+ const logPrefix = userId ? `[MCP][User: ${userId}][${serverName}]` : `[MCP][${serverName}]`;++ try {+ if (!this.appConnections?.has(serverName) && userId && user) {+ this.updateUserLastActivity(userId);+ /** Get or create user-specific connection */+ connection = await this.getUserConnection({+ user,+ serverName,+ flowManager,+ tokenMethods,+ oauthStart,+ oauthEnd,+ signal: options?.signal,+ customUserVars,+ });+ } else {+ /** App-level connection */+ connection = await this.appConnections!.get(serverName);+ if (!connection) {+ throw new McpError(+ ErrorCode.InvalidRequest,+ `${logPrefix} No app-level connection found. Cannot execute tool ${toolName}.`,+ );+ }+ }++ if (!(await connection.isConnected())) {+ /** May happen if getUserConnection failed silently or app connection dropped */+ throw new McpError(+ ErrorCode.InternalError, // Use InternalError for connection issues+ `${logPrefix} Connection is not active. Cannot execute tool ${toolName}.`,+ );+ }++ const result = await connection.client.request(+ {+ method: 'tools/call',+ params: {+ name: toolName,+ arguments: toolArguments,+ },+ },+ CallToolResultSchema,+ {+ timeout: connection.timeout,+ ...options,+ },+ );+ if (userId) {+ this.updateUserLastActivity(userId);+ }+ this.checkIdleConnections();+ return formatToolContent(result as t.MCPToolCallResponse, provider);+ } catch (error) {+ // Log with context and re-throw or handle as needed+ logger.error(`${logPrefix}[${toolName}] Tool call failed`, error);+ // Rethrowing allows the caller (createMCPTool) to handle the final user message+ throw error;+ }+ }+}diff --git a/packages/api/src/mcp/MCPServersRegistry.ts b/packages/api/src/mcp/MCPServersRegistry.tsnew file mode 100644index 0000000000..b2ce2ed0ad--- /dev/null+++ b/packages/api/src/mcp/MCPServersRegistry.ts@@ -0,0 +1,200 @@+import { logger } from '@librechat/data-schemas';+import mapValues from 'lodash/mapValues';+import pickBy from 'lodash/pickBy';+import pick from 'lodash/pick';+import type { JsonSchemaType } from '~/types';+import type * as t from '~/mcp/types';+import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';+import { detectOAuthRequirement } from '~/mcp/oauth';+import { type MCPConnection } from './connection';+import { processMCPEnv } from '~/utils';+import { CONSTANTS } from '~/mcp/enum';++type ParsedServerConfig = t.MCPOptions & {+ url?: string;+ requiresOAuth?: boolean;+ oauthMetadata?: Record<string, unknown> | null;+ capabilities?: string;+ tools?: string;+};++/**+ * Manages MCP server configurations and metadata discovery.+ * Fetches server capabilities, OAuth requirements, and tool definitions for registry.+ * Determines which servers are for app-level connections.+ * Has its own connections repository. All connections are disconnected after initialization.+ */+export class MCPServersRegistry {+ private initialized: boolean = false;+ private connections: ConnectionsRepository;++ public readonly rawConfigs: t.MCPServers;+ public readonly parsedConfigs: Record<string, ParsedServerConfig>;++ public oauthServers: Set<string> | null = null;+ public serverInstructions: Record<string, string> | null = null;+ public toolFunctions: t.LCAvailableTools | null = null;+ public appServerConfigs: t.MCPServers | null = null;++ constructor(configs: t.MCPServers) {+ this.rawConfigs = configs;+ this.parsedConfigs = mapValues(configs, (con) => processMCPEnv(con));+ this.connections = new ConnectionsRepository(configs);+ }++ /** Initializes all startup-enabled servers by gathering their metadata asynchronously */+ public async initialize() {+ if (this.initialized) return;+ this.initialized = true;++ const serverNames = Object.keys(this.parsedConfigs);++ await Promise.allSettled(serverNames.map((serverName) => this.gatherServerInfo(serverName)));++ this.setOAuthServers();+ this.setServerInstructions();+ this.setAppServerConfigs();+ await this.setAppToolFunctions();++ this.connections.disconnectAll();+ }++ // Fetches all metadata for a single server in parallel+ private async gatherServerInfo(serverName: string) {+ try {+ await Promise.allSettled([+ this.fetchOAuthRequirement(serverName).catch((error) =>+ logger.error(`${this.prefix(serverName)} Failed to fetch OAuth requirement:`, error),+ ),+ this.fetchServerInstructions(serverName).catch((error) =>+ logger.error(`${this.prefix(serverName)} Failed to fetch server instructions:`, error),+ ),+ this.fetchServerCapabilities(serverName).catch((error) =>+ logger.error(`${this.prefix(serverName)} Failed to fetch server capabilities:`, error),+ ),+ ]);++ this.logUpdatedConfig(serverName);+ } catch (error) {+ logger.error(`${this.prefix(serverName)} Failed to initialize server:`, error);+ }+ }++ // Sets app-level server configs (startup enabled, non-OAuth servers)+ private setAppServerConfigs() {+ const appServers = Object.keys(+ pickBy(+ this.parsedConfigs,+ (config) => config.startup !== false && config.requiresOAuth === false,+ ),+ );+ this.appServerConfigs = pick(this.rawConfigs, appServers);+ }++ // Creates set of server names that require OAuth authentication+ private setOAuthServers() {+ if (this.oauthServers) return this.oauthServers;+ this.oauthServers = new Set(+ Object.keys(pickBy(this.parsedConfigs, (config) => config.requiresOAuth)),+ );+ return this.oauthServers;+ }++ // Collects server instructions from all configured servers+ private setServerInstructions() {+ this.serverInstructions = mapValues(+ pickBy(this.parsedConfigs, (config) => config.serverInstructions),+ (config) => config.serverInstructions as string,+ );+ }++ // Builds registry of all available tool functions from loaded connections+ private async setAppToolFunctions() {+ const connections = (await this.connections.getLoaded()).entries();+ const allToolFunctions: t.LCAvailableTools = {};+ for (const [serverName, conn] of connections) {+ try {+ const toolFunctions = await this.getToolFunctions(serverName, conn);+ Object.assign(allToolFunctions, toolFunctions);+ } catch (error) {+ logger.error(`${this.prefix(serverName)} Error fetching tool functions:`, error);+ }+ }+ this.toolFunctions = allToolFunctions;+ }++ // Converts server tools to LibreChat-compatible tool functions format+ private async getToolFunctions(+ serverName: string,+ conn: MCPConnection,+ ): Promise<t.LCAvailableTools> {+ const { tools } = await conn.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;+ }++ // Determines if server requires OAuth if not already specified in the config+ private async fetchOAuthRequirement(serverName: string) {+ const config = this.parsedConfigs[serverName];+ if (config.requiresOAuth != null) return;+ if (config.url == null) return (config.requiresOAuth = false);++ const result = await detectOAuthRequirement(config.url);+ config.requiresOAuth = result.requiresOAuth;+ config.oauthMetadata = result.metadata;+ }++ // Retrieves server instructions from MCP server if enabled in the config+ private async fetchServerInstructions(serverName: string) {+ const config = this.parsedConfigs[serverName];+ if (!config.serverInstructions) return;+ if (typeof config.serverInstructions === 'string') return;++ const conn = await this.connections.get(serverName);+ config.serverInstructions = conn.client.getInstructions();+ if (!config.serverInstructions) {+ logger.warn(`${this.prefix(serverName)} No server instructions available`);+ }+ }++ // Fetches server capabilities and available tools list+ private async fetchServerCapabilities(serverName: string) {+ const config = this.parsedConfigs[serverName];+ const conn = await this.connections.get(serverName);+ const capabilities = conn.client.getServerCapabilities();+ if (!capabilities) return;+ config.capabilities = JSON.stringify(capabilities);+ if (!capabilities.tools) return;+ const tools = await conn.client.listTools();+ config.tools = tools.tools.map((tool) => tool.name).join(', ');+ }++ // Logs server configuration summary after initialization+ private logUpdatedConfig(serverName: string) {+ const prefix = this.prefix(serverName);+ const config = this.parsedConfigs[serverName];+ logger.info(`${prefix} URL: ${config.url ?? 'N/A'}`);+ logger.info(`${prefix} OAuth Required: ${config.requiresOAuth}`);+ logger.info(`${prefix} Capabilities: ${config.capabilities}`);+ logger.info(`${prefix} Tools: ${config.tools}`);+ logger.info(`${prefix} Server Instructions: ${config.serverInstructions ?? 'None'}`);+ }++ // Returns formatted log prefix for server messages+ private prefix(serverName: string): string {+ return `[MCP][${serverName}]`;+ }+}diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsnew file mode 100644index 0000000000..0590c8211f--- /dev/null+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -0,0 +1,236 @@+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';+import { logger } from '@librechat/data-schemas';+import type { TokenMethods } from '@librechat/data-schemas';+import type { TUser } from 'librechat-data-provider';+import type { FlowStateManager } from '~/flow/manager';+import type { MCPOAuthTokens } from '~/mcp/oauth';+import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';+import { MCPServersRegistry } from '~/mcp/MCPServersRegistry';+import { MCPConnection } from './connection';+import type * as t from './types';++/**+ * Abstract base class for managing user-specific MCP connections with lifecycle management.+ * Only meant to be extended by MCPManager.+ * Much of the logic was move here from the old MCPManager to make it more manageable.+ * User connections will soon be ephemeral and not cached anymore:+ * https://github.com/danny-avila/LibreChat/discussions/8790+ */+export abstract class UserConnectionManager {+ protected readonly serversRegistry: MCPServersRegistry;+ protected userConnections: Map<string, Map<string, MCPConnection>> = new Map();+ /** Last activity timestamp for users (not per server) */+ protected userLastActivity: Map<string, number> = new Map();+ protected readonly USER_CONNECTION_IDLE_TIMEOUT = 15 * 60 * 1000; // 15 minutes (TODO: make configurable)++ constructor(serverConfigs: t.MCPServers) {+ this.serversRegistry = new MCPServersRegistry(serverConfigs);+ }++ /** fetches am MCP Server config from the registry */+ public getRawConfig(serverName: string): t.MCPOptions | undefined {+ return this.serversRegistry.rawConfigs[serverName];+ }++ /** Updates the last activity timestamp for a user */+ protected updateUserLastActivity(userId: string): void {+ const now = Date.now();+ this.userLastActivity.set(userId, now);+ logger.debug(+ `[MCP][User: ${userId}] Updated last activity timestamp: ${new Date(now).toISOString()}`,+ );+ }++ /** Gets or creates a connection for a specific user */+ public async getUserConnection({+ user,+ serverName,+ flowManager,+ customUserVars,+ tokenMethods,+ oauthStart,+ oauthEnd,+ signal,+ returnOnOAuth = false,+ }: {+ user: TUser;+ serverName: string;+ flowManager: FlowStateManager<MCPOAuthTokens | null>;+ customUserVars?: Record<string, string>;+ tokenMethods?: TokenMethods;+ oauthStart?: (authURL: string) => Promise<void>;+ oauthEnd?: () => Promise<void>;+ signal?: AbortSignal;+ returnOnOAuth?: boolean;+ }): Promise<MCPConnection> {+ const userId = user.id;+ if (!userId) {+ throw new McpError(ErrorCode.InvalidRequest, `[MCP] User object missing id property`);+ }++ const userServerMap = this.userConnections.get(userId);+ let connection = userServerMap?.get(serverName);+ const now = Date.now();++ // Check if user is idle+ const lastActivity = this.userLastActivity.get(userId);+ if (lastActivity && now - lastActivity > this.USER_CONNECTION_IDLE_TIMEOUT) {+ logger.info(`[MCP][User: ${userId}] User idle for too long. Disconnecting all connections.`);+ // Disconnect all user connections+ try {+ await this.disconnectUserConnections(userId);+ } catch (err) {+ logger.error(`[MCP][User: ${userId}] Error disconnecting idle connections:`, err);+ }+ connection = undefined; // Force creation of a new connection+ } else if (connection) {+ if (await connection.isConnected()) {+ logger.debug(`[MCP][User: ${userId}][${serverName}] Reusing active connection`);+ this.updateUserLastActivity(userId);+ return connection;+ } else {+ // Connection exists but is not connected, attempt to remove potentially stale entry+ logger.warn(+ `[MCP][User: ${userId}][${serverName}] Found existing but disconnected connection object. Cleaning up.`,+ );+ this.removeUserConnection(userId, serverName); // Clean up maps+ connection = undefined;+ }+ }++ // If no valid connection exists, create a new one+ if (!connection) {+ logger.info(`[MCP][User: ${userId}][${serverName}] Establishing new connection`);+ }++ const config = this.serversRegistry.parsedConfigs[serverName];+ if (!config) {+ throw new McpError(+ ErrorCode.InvalidRequest,+ `[MCP][User: ${userId}] Configuration for server "${serverName}" not found.`,+ );+ }++ try {+ connection = await MCPConnectionFactory.create(+ {+ serverName: serverName,+ serverConfig: config,+ },+ {+ useOAuth: true,+ user: user,+ customUserVars: customUserVars,+ flowManager: flowManager,+ tokenMethods: tokenMethods,+ signal: signal,+ oauthStart: oauthStart,+ oauthEnd: oauthEnd,+ returnOnOAuth: returnOnOAuth,+ },+ );++ if (!(await connection?.isConnected())) {+ throw new Error('Failed to establish connection after initialization attempt.');+ }++ if (!this.userConnections.has(userId)) {+ this.userConnections.set(userId, new Map());+ }+ this.userConnections.get(userId)?.set(serverName, connection);++ logger.info(`[MCP][User: ${userId}][${serverName}] Connection successfully established`);+ // Update timestamp on creation+ this.updateUserLastActivity(userId);+ return connection;+ } catch (error) {+ logger.error(`[MCP][User: ${userId}][${serverName}] Failed to establish connection`, error);+ // Ensure partial connection state is cleaned up if initialization fails+ await connection?.disconnect().catch((disconnectError) => {+ logger.error(+ `[MCP][User: ${userId}][${serverName}] Error during cleanup after failed connection`,+ disconnectError,+ );+ });+ // Ensure cleanup even if connection attempt fails+ this.removeUserConnection(userId, serverName);+ throw error; // Re-throw the error to the caller+ }+ }++ /** Returns all connections for a specific user */+ public getUserConnections(userId: string) {+ return this.userConnections.get(userId);+ }++ /** Removes a specific user connection entry */+ protected removeUserConnection(userId: string, serverName: string): void {+ const userMap = this.userConnections.get(userId);+ if (userMap) {+ userMap.delete(serverName);+ if (userMap.size === 0) {+ this.userConnections.delete(userId);+ // Only remove user activity timestamp if all connections are gone+ this.userLastActivity.delete(userId);+ }+ }++ logger.debug(`[MCP][User: ${userId}][${serverName}] Removed connection entry.`);+ }++ /** Disconnects and removes a specific user connection */+ public async disconnectUserConnection(userId: string, serverName: string): Promise<void> {+ const userMap = this.userConnections.get(userId);+ const connection = userMap?.get(serverName);+ if (connection) {+ logger.info(`[MCP][User: ${userId}][${serverName}] Disconnecting...`);+ await connection.disconnect();+ this.removeUserConnection(userId, serverName);+ }+ }++ /** Disconnects and removes all connections for a specific user */+ public async disconnectUserConnections(userId: string): Promise<void> {+ const userMap = this.userConnections.get(userId);+ const disconnectPromises: Promise<void>[] = [];+ if (userMap) {+ logger.info(`[MCP][User: ${userId}] Disconnecting all servers...`);+ const userServers = Array.from(userMap.keys());+ for (const serverName of userServers) {+ disconnectPromises.push(+ this.disconnectUserConnection(userId, serverName).catch((error) => {+ logger.error(+ `[MCP][User: ${userId}][${serverName}] Error during disconnection:`,+ error,+ );+ }),+ );+ }+ await Promise.allSettled(disconnectPromises);+ // Ensure user activity timestamp is removed+ this.userLastActivity.delete(userId);+ logger.info(`[MCP][User: ${userId}] All connections processed for disconnection.`);+ }+ }++ /** Check for and disconnect idle connections */+ protected checkIdleConnections(currentUserId?: string): void {+ const now = Date.now();++ // Iterate through all users to check for idle ones+ for (const [userId, lastActivity] of this.userLastActivity.entries()) {+ if (currentUserId && currentUserId === userId) {+ continue;+ }+ if (now - lastActivity > this.USER_CONNECTION_IDLE_TIMEOUT) {+ logger.info(+ `[MCP][User: ${userId}] User idle for too long. Disconnecting all connections...`,+ );+ // Disconnect all user connections asynchronously (fire and forget)+ this.disconnectUserConnections(userId).catch((err) =>+ logger.error(`[MCP][User: ${userId}] Error disconnecting idle connections:`, err),+ );+ }+ }+ }+}diff --git a/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts b/packages/api/src/mcp/__tests__/ConnectionsRepository.test.tsnew file mode 100644index 0000000000..dd71466e9b--- /dev/null+++ b/packages/api/src/mcp/__tests__/ConnectionsRepository.test.ts@@ -0,0 +1,212 @@+import { logger } from '@librechat/data-schemas';+import { ConnectionsRepository } from '../ConnectionsRepository';+import { MCPConnectionFactory } from '../MCPConnectionFactory';+import { MCPConnection } from '../connection';+import type * as t from '../types';++// Mock external dependencies+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ error: jest.fn(),+ },+}));++jest.mock('../MCPConnectionFactory', () => ({+ MCPConnectionFactory: {+ create: jest.fn(),+ },+}));++jest.mock('../connection');++const mockLogger = logger as jest.Mocked<typeof logger>;++describe('ConnectionsRepository', () => {+ let repository: ConnectionsRepository;+ let mockServerConfigs: t.MCPServers;+ let mockConnection: jest.Mocked<MCPConnection>;++ beforeEach(() => {+ mockServerConfigs = {+ server1: { url: 'http://localhost:3001' },+ server2: { command: 'test-command', args: ['--test'] },+ server3: { url: 'ws://localhost:8080', type: 'websocket' },+ };++ mockConnection = {+ isConnected: jest.fn().mockResolvedValue(true),+ disconnect: jest.fn().mockResolvedValue(undefined),+ } as unknown as jest.Mocked<MCPConnection>;++ (MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);++ repository = new ConnectionsRepository(mockServerConfigs);++ jest.clearAllMocks();+ });++ afterEach(() => {+ jest.clearAllMocks();+ });++ describe('has', () => {+ it('should return true for existing server', () => {+ expect(repository.has('server1')).toBe(true);+ });++ it('should return false for non-existing server', () => {+ expect(repository.has('nonexistent')).toBe(false);+ });+ });++ describe('get', () => {+ it('should return existing connected connection', async () => {+ mockConnection.isConnected.mockResolvedValue(true);+ repository['connections'].set('server1', mockConnection);++ const result = await repository.get('server1');++ expect(result).toBe(mockConnection);+ expect(MCPConnectionFactory.create).not.toHaveBeenCalled();+ });++ it('should create new connection if none exists', async () => {+ const result = await repository.get('server1');++ expect(result).toBe(mockConnection);+ expect(MCPConnectionFactory.create).toHaveBeenCalledWith(+ {+ serverName: 'server1',+ serverConfig: mockServerConfigs.server1,+ },+ undefined,+ );+ expect(repository['connections'].get('server1')).toBe(mockConnection);+ });++ it('should create new connection if existing connection is not connected', async () => {+ const oldConnection = {+ isConnected: jest.fn().mockResolvedValue(false),+ disconnect: jest.fn().mockResolvedValue(undefined),+ } as unknown as jest.Mocked<MCPConnection>;+ repository['connections'].set('server1', oldConnection);++ const result = await repository.get('server1');++ expect(result).toBe(mockConnection);+ expect(oldConnection.disconnect).toHaveBeenCalled();+ expect(MCPConnectionFactory.create).toHaveBeenCalledWith(+ {+ serverName: 'server1',+ serverConfig: mockServerConfigs.server1,+ },+ undefined,+ );+ });++ it('should throw error for non-existent server configuration', async () => {+ await expect(repository.get('nonexistent')).rejects.toThrow(+ '[MCP][nonexistent] Server not found in configuration',+ );+ });++ it('should handle MCPConnectionFactory.create errors', async () => {+ const createError = new Error('Connection creation failed');+ (MCPConnectionFactory.create as jest.Mock).mockRejectedValue(createError);++ await expect(repository.get('server1')).rejects.toThrow('Connection creation failed');+ });+ });++ describe('getMany', () => {+ it('should return connections for multiple servers', async () => {+ const result = await repository.getMany(['server1', 'server3']);++ expect(result).toBeInstanceOf(Map);+ expect(result.size).toBe(2);+ expect(result.get('server1')).toBe(mockConnection);+ expect(result.get('server3')).toBe(mockConnection);+ });+ });++ describe('getLoaded', () => {+ it('should return connections for loaded servers only', async () => {+ // Load one connection+ await repository.get('server1');++ const result = await repository.getLoaded();++ expect(result).toBeInstanceOf(Map);+ expect(result.size).toBe(1);+ expect(result.get('server1')).toBe(mockConnection);+ });++ it('should return empty map when no connections are loaded', async () => {+ const result = await repository.getLoaded();++ expect(result).toBeInstanceOf(Map);+ expect(result.size).toBe(0);+ });+ });++ describe('getAll', () => {+ it('should return connections for all configured servers', async () => {+ const result = await repository.getAll();++ expect(result).toBeInstanceOf(Map);+ expect(result.size).toBe(3);+ expect(result.get('server1')).toBe(mockConnection);+ expect(result.get('server2')).toBe(mockConnection);+ expect(result.get('server3')).toBe(mockConnection);+ });+ });++ describe('disconnect', () => {+ it('should disconnect and remove existing connection', async () => {+ repository['connections'].set('server1', mockConnection);++ await repository.disconnect('server1');++ expect(mockConnection.disconnect).toHaveBeenCalled();+ expect(repository['connections'].has('server1')).toBe(false);+ });++ it('should handle disconnect error gracefully', async () => {+ const disconnectError = new Error('Disconnect failed');+ mockConnection.disconnect.mockRejectedValue(disconnectError);+ repository['connections'].set('server1', mockConnection);++ await repository.disconnect('server1');++ expect(mockConnection.disconnect).toHaveBeenCalled();+ expect(repository['connections'].has('server1')).toBe(false);+ expect(mockLogger.error).toHaveBeenCalledWith(+ '[MCP][server1] Error disconnecting',+ disconnectError,+ );+ });+ });++ describe('disconnectAll', () => {+ it('should disconnect all active connections', () => {+ const mockConnection1 = {+ disconnect: jest.fn().mockResolvedValue(undefined),+ } as unknown as jest.Mocked<MCPConnection>;+ const mockConnection2 = {+ disconnect: jest.fn().mockResolvedValue(undefined),+ } as unknown as jest.Mocked<MCPConnection>;+ const mockConnection3 = {+ disconnect: jest.fn().mockResolvedValue(undefined),+ } as unknown as jest.Mocked<MCPConnection>;++ repository['connections'].set('server1', mockConnection1);+ repository['connections'].set('server2', mockConnection2);+ repository['connections'].set('server3', mockConnection3);++ const promises = repository.disconnectAll();++ expect(promises).toHaveLength(3);+ expect(Array.isArray(promises)).toBe(true);+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.tsnew file mode 100644index 0000000000..9ca447f92c--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts@@ -0,0 +1,347 @@+import { logger } from '@librechat/data-schemas';+import type { TUser } from 'librechat-data-provider';+import type { FlowStateManager } from '~/flow/manager';+import type { MCPOAuthTokens } from '~/mcp/oauth';+import { MCPConnectionFactory } from '../MCPConnectionFactory';+import { MCPOAuthHandler } from '~/mcp/oauth';+import { MCPConnection } from '../connection';+import { processMCPEnv } from '~/utils';+import type * as t from '../types';++jest.mock('../connection');+jest.mock('~/mcp/oauth');+jest.mock('~/utils');+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+}));++const mockLogger = logger as jest.Mocked<typeof logger>;+const mockProcessMCPEnv = processMCPEnv as jest.MockedFunction<typeof processMCPEnv>;+const mockMCPConnection = MCPConnection as jest.MockedClass<typeof MCPConnection>;+const mockMCPOAuthHandler = MCPOAuthHandler as jest.Mocked<typeof MCPOAuthHandler>;++describe('MCPConnectionFactory', () => {+ let mockUser: TUser;+ let mockServerConfig: t.MCPOptions;+ let mockFlowManager: jest.Mocked<FlowStateManager<MCPOAuthTokens | null>>;+ let mockConnectionInstance: jest.Mocked<MCPConnection>;++ beforeEach(() => {+ jest.clearAllMocks();+ mockUser = {+ id: 'user123',+ email: '[email protected]',+ } as TUser;++ mockServerConfig = {+ command: 'node',+ args: ['server.js'],+ initTimeout: 5000,+ } as t.MCPOptions;++ mockFlowManager = {+ createFlow: jest.fn(),+ createFlowWithHandler: jest.fn(),+ getFlowState: jest.fn(),+ } as unknown as jest.Mocked<FlowStateManager<MCPOAuthTokens | null>>;++ mockConnectionInstance = {+ connect: jest.fn(),+ isConnected: jest.fn(),+ setOAuthTokens: jest.fn(),+ on: jest.fn().mockReturnValue(mockConnectionInstance),+ emit: jest.fn(),+ } as unknown as jest.Mocked<MCPConnection>;++ mockMCPConnection.mockImplementation(() => mockConnectionInstance);+ mockProcessMCPEnv.mockReturnValue(mockServerConfig);+ });++ describe('static create method', () => {+ it('should create a basic connection without OAuth', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ mockConnectionInstance.isConnected.mockResolvedValue(true);++ const connection = await MCPConnectionFactory.create(basicOptions);++ expect(connection).toBe(mockConnectionInstance);+ expect(mockProcessMCPEnv).toHaveBeenCalledWith(mockServerConfig, undefined, undefined);+ expect(mockMCPConnection).toHaveBeenCalledWith({+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ userId: undefined,+ oauthTokens: null,+ });+ expect(mockConnectionInstance.connect).toHaveBeenCalled();+ });++ it('should create a connection with OAuth', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ const mockTokens: MCPOAuthTokens = {+ access_token: 'access123',+ refresh_token: 'refresh123',+ token_type: 'Bearer',+ obtained_at: Date.now(),+ };++ mockFlowManager.createFlowWithHandler.mockResolvedValue(mockTokens);+ mockConnectionInstance.isConnected.mockResolvedValue(true);++ const connection = await MCPConnectionFactory.create(basicOptions, oauthOptions);++ expect(connection).toBe(mockConnectionInstance);+ expect(mockProcessMCPEnv).toHaveBeenCalledWith(mockServerConfig, mockUser, undefined);+ expect(mockMCPConnection).toHaveBeenCalledWith({+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ userId: 'user123',+ oauthTokens: mockTokens,+ });+ });+ });++ describe('OAuth token handling', () => {+ it('should return null when no findToken method is provided', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: undefined as unknown as () => Promise<any>,+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ mockConnectionInstance.isConnected.mockResolvedValue(true);++ await MCPConnectionFactory.create(basicOptions, oauthOptions);++ expect(mockFlowManager.createFlowWithHandler).not.toHaveBeenCalled();+ });++ it('should handle token retrieval errors gracefully', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ mockFlowManager.createFlowWithHandler.mockRejectedValue(new Error('Token fetch failed'));+ mockConnectionInstance.isConnected.mockResolvedValue(true);++ const connection = await MCPConnectionFactory.create(basicOptions, oauthOptions);++ expect(connection).toBe(mockConnectionInstance);+ expect(mockMCPConnection).toHaveBeenCalledWith({+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ userId: 'user123',+ oauthTokens: null,+ });+ expect(mockLogger.debug).toHaveBeenCalledWith(+ expect.stringContaining('No existing tokens found or error loading tokens'),+ expect.any(Error),+ );+ });+ });++ describe('OAuth event handling', () => {+ it('should handle oauthRequired event for returnOnOAuth scenario', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: {+ ...mockServerConfig,+ url: 'https://api.example.com',+ type: 'sse' as const,+ } as t.SSEOptions,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ returnOnOAuth: true,+ oauthStart: jest.fn(),+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ const mockFlowData = {+ authorizationUrl: 'https://auth.example.com',+ flowId: 'flow123',+ flowMetadata: {+ serverName: 'test-server',+ userId: 'user123',+ serverUrl: 'https://api.example.com',+ state: 'random-state',+ clientInfo: { client_id: 'client123' },+ },+ };++ mockMCPOAuthHandler.initiateOAuthFlow.mockResolvedValue(mockFlowData);+ mockFlowManager.createFlow.mockRejectedValue(new Error('Timeout expected'));+ mockConnectionInstance.isConnected.mockResolvedValue(false);++ let oauthRequiredHandler: (data: Record<string, unknown>) => Promise<void>;+ mockConnectionInstance.on.mockImplementation((event, handler) => {+ if (event === 'oauthRequired') {+ oauthRequiredHandler = handler as (data: Record<string, unknown>) => Promise<void>;+ }+ return mockConnectionInstance;+ });++ try {+ await MCPConnectionFactory.create(basicOptions, oauthOptions);+ } catch {+ // Expected to fail due to connection not established+ }++ expect(oauthRequiredHandler!).toBeDefined();++ await oauthRequiredHandler!({ serverUrl: 'https://api.example.com' });++ expect(mockMCPOAuthHandler.initiateOAuthFlow).toHaveBeenCalledWith(+ 'test-server',+ 'https://api.example.com',+ 'user123',+ undefined,+ );+ expect(oauthOptions.oauthStart).toHaveBeenCalledWith('https://auth.example.com');+ expect(mockConnectionInstance.emit).toHaveBeenCalledWith(+ 'oauthFailed',+ expect.objectContaining({+ message: 'OAuth flow initiated - return early',+ }),+ );+ });+ });++ describe('connection retry logic', () => {+ it('should establish connection successfully', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig, // Use default 5000ms timeout+ };++ mockConnectionInstance.connect.mockResolvedValue(undefined);+ mockConnectionInstance.isConnected.mockResolvedValue(true);++ const connection = await MCPConnectionFactory.create(basicOptions);++ expect(connection).toBe(mockConnectionInstance);+ expect(mockConnectionInstance.connect).toHaveBeenCalledTimes(1);+ });++ it('should handle OAuth errors during connection attempts', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ oauthStart: jest.fn(),+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ const oauthError = new Error('Non-200 status code (401)');+ (oauthError as unknown as Record<string, unknown>).isOAuthError = true;++ mockConnectionInstance.connect.mockRejectedValue(oauthError);+ mockConnectionInstance.isConnected.mockResolvedValue(false);++ await expect(MCPConnectionFactory.create(basicOptions, oauthOptions)).rejects.toThrow(+ 'Non-200 status code (401)',+ );++ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining('OAuth required, stopping connection attempts'),+ );+ });+ });++ describe('isOAuthError method', () => {+ it('should identify OAuth errors by message content', async () => {+ const basicOptions = {+ serverName: 'test-server',+ serverConfig: mockServerConfig,+ };++ const oauthOptions = {+ useOAuth: true as const,+ user: mockUser,+ flowManager: mockFlowManager,+ tokenMethods: {+ findToken: jest.fn(),+ createToken: jest.fn(),+ updateToken: jest.fn(),+ deleteTokens: jest.fn(),+ },+ };++ const error401 = new Error('401 Unauthorized');++ mockConnectionInstance.connect.mockRejectedValue(error401);+ mockConnectionInstance.isConnected.mockResolvedValue(false);++ await expect(MCPConnectionFactory.create(basicOptions, oauthOptions)).rejects.toThrow('401');+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining('OAuth required, stopping connection attempts'),+ );+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPServersRegistry.test.ts b/packages/api/src/mcp/__tests__/MCPServersRegistry.test.tsnew file mode 100644index 0000000000..63fdc72ffb--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPServersRegistry.test.ts@@ -0,0 +1,287 @@+import { readFileSync } from 'fs';+import { join } from 'path';+import { logger } from '@librechat/data-schemas';+import { load as yamlLoad } from 'js-yaml';+import { ConnectionsRepository } from '../ConnectionsRepository';+import { MCPServersRegistry } from '../MCPServersRegistry';+import { detectOAuthRequirement } from '~/mcp/oauth';+import { MCPConnection } from '../connection';+import type * as t from '../types';++// Mock external dependencies+jest.mock('../oauth/detectOAuth');+jest.mock('../ConnectionsRepository');+jest.mock('../connection');+jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+}));++// Mock processMCPEnv to verify it's called and adds a processed marker+jest.mock('~/utils', () => ({+ ...jest.requireActual('~/utils'),+ processMCPEnv: jest.fn((config) => ({+ ...config,+ _processed: true, // Simple marker to verify processing occurred+ })),+}));++const mockDetectOAuthRequirement = detectOAuthRequirement as jest.MockedFunction<+ typeof detectOAuthRequirement+>;+const mockLogger = logger as jest.Mocked<typeof logger>;++describe('MCPServersRegistry - Initialize Function', () => {+ let rawConfigs: t.MCPServers;+ let expectedParsedConfigs: Record<string, any>;+ let mockConnectionsRepo: jest.Mocked<ConnectionsRepository>;+ let mockConnections: Map<string, jest.Mocked<MCPConnection>>;++ beforeEach(() => {+ // Load fixtures+ const rawConfigsPath = join(__dirname, 'fixtures', 'MCPServersRegistry.rawConfigs.yml');+ const parsedConfigsPath = join(__dirname, 'fixtures', 'MCPServersRegistry.parsedConfigs.yml');++ rawConfigs = yamlLoad(readFileSync(rawConfigsPath, 'utf8')) as t.MCPServers;+ expectedParsedConfigs = yamlLoad(readFileSync(parsedConfigsPath, 'utf8')) as Record<+ string,+ any+ >;++ // Setup mock connections+ mockConnections = new Map();+ const serverNames = Object.keys(rawConfigs);++ serverNames.forEach((serverName) => {+ const mockConnection = {+ client: {+ listTools: jest.fn(),+ getInstructions: jest.fn(),+ getServerCapabilities: jest.fn(),+ },+ } as unknown as jest.Mocked<MCPConnection>;++ // Setup mock responses based on expected configs+ const expectedConfig = expectedParsedConfigs[serverName];++ // Mock listTools response+ if (expectedConfig.tools) {+ const toolNames = expectedConfig.tools.split(', ');+ const tools = toolNames.map((name: string) => ({+ name,+ description: `Description for ${name}`,+ inputSchema: {+ type: 'object',+ properties: {+ input: { type: 'string' },+ },+ },+ }));+ mockConnection.client.listTools.mockResolvedValue({ tools });+ } else {+ mockConnection.client.listTools.mockResolvedValue({ tools: [] });+ }++ // Mock getInstructions response+ if (expectedConfig.serverInstructions) {+ mockConnection.client.getInstructions.mockReturnValue(expectedConfig.serverInstructions);+ } else {+ mockConnection.client.getInstructions.mockReturnValue(null);+ }++ // Mock getServerCapabilities response+ if (expectedConfig.capabilities) {+ const capabilities = JSON.parse(expectedConfig.capabilities);+ mockConnection.client.getServerCapabilities.mockReturnValue(capabilities);+ } else {+ mockConnection.client.getServerCapabilities.mockReturnValue(null);+ }++ mockConnections.set(serverName, mockConnection);+ });++ // Setup ConnectionsRepository mock+ mockConnectionsRepo = {+ get: jest.fn(),+ getLoaded: jest.fn(),+ disconnectAll: jest.fn(),+ } as unknown as jest.Mocked<ConnectionsRepository>;++ mockConnectionsRepo.get.mockImplementation((serverName: string) =>+ Promise.resolve(mockConnections.get(serverName)!),+ );++ mockConnectionsRepo.getLoaded.mockResolvedValue(mockConnections);++ (ConnectionsRepository as jest.Mock).mockImplementation(() => mockConnectionsRepo);++ // Setup OAuth detection mock with deterministic results+ mockDetectOAuthRequirement.mockImplementation((url: string) => {+ const oauthResults: Record<string, any> = {+ 'https://api.github.com/mcp': {+ requiresOAuth: true,+ metadata: {+ authorization_url: 'https://github.com/login/oauth/authorize',+ token_url: 'https://github.com/login/oauth/access_token',+ },+ },+ 'https://api.disabled.com/mcp': {+ requiresOAuth: false,+ metadata: null,+ },+ 'https://api.public.com/mcp': {+ requiresOAuth: false,+ metadata: null,+ },+ };++ return Promise.resolve(oauthResults[url] || { requiresOAuth: false, metadata: null });+ });++ // Clear all mocks+ jest.clearAllMocks();+ });++ afterEach(() => {+ jest.clearAllMocks();+ });++ describe('initialize() method', () => {+ it('should only run initialization once', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ await registry.initialize();+ await registry.initialize(); // Second call should not re-run++ // Verify that connections are only requested for servers that need them+ // (servers with serverInstructions=true or all servers for capabilities)+ expect(mockConnectionsRepo.get).toHaveBeenCalled();+ });++ it('should set all public properties correctly after initialization', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ // Verify initial state+ expect(registry.oauthServers).toBeNull();+ expect(registry.serverInstructions).toBeNull();+ expect(registry.toolFunctions).toBeNull();+ expect(registry.appServerConfigs).toBeNull();++ await registry.initialize();++ // Test oauthServers Set+ expect(registry.oauthServers).toBeInstanceOf(Set);+ expect(registry.oauthServers).toEqual(+ new Set(['oauth_server', 'oauth_predefined', 'oauth_startup_enabled']),+ );++ // Test serverInstructions+ expect(registry.serverInstructions).toEqual({+ oauth_server: 'GitHub MCP server instructions',+ stdio_server: 'Follow these instructions for stdio server',+ non_oauth_server: 'Public API instructions',+ });++ // Test appServerConfigs (startup enabled, non-OAuth servers only)+ expect(registry.appServerConfigs).toEqual({+ stdio_server: rawConfigs.stdio_server,+ websocket_server: rawConfigs.websocket_server,+ non_oauth_server: rawConfigs.non_oauth_server,+ });++ // Test toolFunctions (only 2 servers have tools: oauth_server has 1, stdio_server has 2)+ const expectedToolFunctions = {+ get_repository_mcp_oauth_server: {+ type: 'function',+ function: {+ name: 'get_repository_mcp_oauth_server',+ description: 'Description for get_repository',+ parameters: { type: 'object', properties: { input: { type: 'string' } } },+ },+ },+ file_read_mcp_stdio_server: {+ type: 'function',+ function: {+ name: 'file_read_mcp_stdio_server',+ description: 'Description for file_read',+ parameters: { type: 'object', properties: { input: { type: 'string' } } },+ },+ },+ file_write_mcp_stdio_server: {+ type: 'function',+ function: {+ name: 'file_write_mcp_stdio_server',+ description: 'Description for file_write',+ parameters: { type: 'object', properties: { input: { type: 'string' } } },+ },+ },+ };+ expect(registry.toolFunctions).toEqual(expectedToolFunctions);+ });++ it('should handle errors gracefully and continue initialization', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ // Make one server throw an error+ mockDetectOAuthRequirement.mockRejectedValueOnce(new Error('OAuth detection failed'));++ await registry.initialize();++ // Should still initialize successfully+ expect(registry.oauthServers).toBeInstanceOf(Set);+ expect(registry.toolFunctions).toBeDefined();++ // Error should be logged+ expect(mockLogger.error).toHaveBeenCalledWith(+ expect.stringContaining('[MCP][oauth_server] Failed to fetch OAuth requirement:'),+ expect.any(Error),+ );+ });++ it('should disconnect all connections after initialization', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ await registry.initialize();++ expect(mockConnectionsRepo.disconnectAll).toHaveBeenCalledTimes(1);+ });++ it('should log configuration updates for each server', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ await registry.initialize();++ const serverNames = Object.keys(rawConfigs);+ serverNames.forEach((serverName) => {+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining(`[MCP][${serverName}] URL:`),+ );+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining(`[MCP][${serverName}] OAuth Required:`),+ );+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining(`[MCP][${serverName}] Capabilities:`),+ );+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining(`[MCP][${serverName}] Tools:`),+ );+ expect(mockLogger.info).toHaveBeenCalledWith(+ expect.stringContaining(`[MCP][${serverName}] Server Instructions:`),+ );+ });+ });++ it('should have parsedConfigs matching the expected fixture after initialization', async () => {+ const registry = new MCPServersRegistry(rawConfigs);++ await registry.initialize();++ // Compare the actual parsedConfigs against the expected fixture+ expect(registry.parsedConfigs).toEqual(expectedParsedConfigs);+ });+ });+});diff --git a/packages/api/src/mcp/auth.test.ts b/packages/api/src/mcp/__tests__/auth.test.tssimilarity index 99%rename from packages/api/src/mcp/auth.test.tsrename to packages/api/src/mcp/__tests__/auth.test.tsindex 7bfb40ae93..5d3793cfb2 100644--- a/packages/api/src/mcp/auth.test.ts+++ b/packages/api/src/mcp/__tests__/auth.test.ts@@ -1,7 +1,7 @@import type { PluginAuthMethods } from '@librechat/data-schemas';import type { GenericTool } from '@librechat/agents';import { getPluginAuthMap } from '~/agents/auth';-import { getUserMCPAuthMap } from './auth';+import { getUserMCPAuthMap } from '../auth';jest.mock('~/agents/auth', () => ({getPluginAuthMap: jest.fn(),diff --git a/packages/api/src/mcp/__tests__/detectOAuth.integration.dev.ts b/packages/api/src/mcp/__tests__/detectOAuth.integration.dev.tsnew file mode 100644index 0000000000..7881b9bd65--- /dev/null+++ b/packages/api/src/mcp/__tests__/detectOAuth.integration.dev.ts@@ -0,0 +1,76 @@+// Integration tests for OAuth detection against real public MCP servers+// These tests verify the actual behavior against live endpoints+//+// DEVELOPMENT ONLY: This file is excluded from the test suite (.dev.ts extension)+// Use this for development and debugging OAuth detection behavior+//+// To run manually from packages/api directory:+// npx jest --testMatch="**/detectOAuth.integration.dev.ts"++import { detectOAuthRequirement } from '~/mcp/oauth';++describe('OAuth Detection Integration Tests', () => {+ const NETWORK_TIMEOUT = 10000;++ interface TestServer {+ name: string;+ url: string;+ expectedOAuth: boolean;+ expectedMethod: string;+ withMeta: boolean;+ }++ const testServers: TestServer[] = [+ {+ name: 'GitHub Copilot MCP Server',+ url: 'https://api.githubcopilot.com/mcp',+ expectedOAuth: true,+ expectedMethod: '401-challenge-metadata',+ withMeta: true,+ },+ {+ name: 'GitHub API (401 without metadata)',+ url: 'https://api.github.com/user',+ expectedOAuth: true,+ expectedMethod: 'no-metadata-found',+ withMeta: false,+ },+ {+ name: 'Stytch Todo MCP Server',+ url: 'https://mcp-stytch-consumer-todo-list.maxwell-gerber42.workers.dev',+ expectedOAuth: true,+ expectedMethod: 'protected-resource-metadata',+ withMeta: true,+ },+ {+ name: 'HTTPBin (Non-OAuth)',+ url: 'https://httpbin.org',+ expectedOAuth: false,+ expectedMethod: 'no-metadata-found',+ withMeta: false,+ },+ {+ name: 'Unreachable Server',+ url: 'https://definitely-not-a-real-server-12345.com',+ expectedOAuth: false,+ expectedMethod: 'no-metadata-found',+ withMeta: false,+ },+ ];++ describe('detectOAuthRequirement integration', () => {+ testServers.forEach((server) => {+ it(+ `should handle ${server.name}`,+ async () => {+ const result = await detectOAuthRequirement(server.url);++ expect(result.requiresOAuth).toBe(server.expectedOAuth);+ expect(result.method).toBe(server.expectedMethod);+ expect(result.metadata == null).toBe(!server.withMeta);+ },+ NETWORK_TIMEOUT,+ );+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.parsedConfigs.yml b/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.parsedConfigs.ymlnew file mode 100644index 0000000000..55ddbf4ed5--- /dev/null+++ b/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.parsedConfigs.yml@@ -0,0 +1,74 @@+# Expected parsed MCP server configurations after running initialize()+# These represent the expected state of parsedConfigs after all fetch functions complete++oauth_server:+ _processed: true+ type: "streamable-http"+ url: "https://api.github.com/mcp"+ headers:+ Authorization: "Bearer {{GITHUB_TOKEN}}"+ serverInstructions: "GitHub MCP server instructions"+ requiresOAuth: true+ oauthMetadata:+ authorization_url: "https://github.com/login/oauth/authorize"+ token_url: "https://github.com/login/oauth/access_token"+ capabilities: '{"tools":{"listChanged":true},"resources":{},"prompts":{}}'+ tools: "get_repository"++oauth_predefined:+ _processed: true+ type: "sse"+ url: "https://api.example.com/sse"+ requiresOAuth: true+ oauthMetadata:+ authorization_url: "https://example.com/oauth/authorize"+ token_url: "https://example.com/oauth/token"+ capabilities: '{"tools":{},"resources":{},"prompts":{}}'+ tools: ""++stdio_server:+ _processed: true+ command: "node"+ args: ["server.js"]+ env:+ API_KEY: "${TEST_API_KEY}"+ startup: true+ serverInstructions: "Follow these instructions for stdio server"+ requiresOAuth: false+ capabilities: '{"tools":{"listChanged":true},"resources":{"listChanged":true},"prompts":{}}'+ tools: "file_read, file_write"++websocket_server:+ _processed: true+ type: "websocket"+ url: "ws://localhost:3001/mcp"+ startup: true+ requiresOAuth: false+ oauthMetadata: null+ capabilities: '{"tools":{},"resources":{},"prompts":{}}'+ tools: ""++disabled_server:+ _processed: true+ type: "streamable-http"+ url: "https://api.disabled.com/mcp"+ startup: false+ requiresOAuth: false+ oauthMetadata: null++non_oauth_server:+ _processed: true+ type: "streamable-http"+ url: "https://api.public.com/mcp"+ requiresOAuth: false+ serverInstructions: "Public API instructions"+ capabilities: '{"tools":{},"resources":{},"prompts":{}}'+ tools: ""++oauth_startup_enabled:+ _processed: true+ type: "sse"+ url: "https://api.oauth-startup.com/sse"+ requiresOAuth: true+ capabilities: '{"tools":{},"resources":{},"prompts":{}}'+ tools: ""\ No newline at end of filediff --git a/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.rawConfigs.yml b/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.rawConfigs.ymlnew file mode 100644index 0000000000..907dfaa96b--- /dev/null+++ b/packages/api/src/mcp/__tests__/fixtures/MCPServersRegistry.rawConfigs.yml@@ -0,0 +1,53 @@+# Raw MCP server configurations used as input to MCPServersRegistry constructor+# These configs test different code paths in the initialization process++# Test OAuth detection with URL - should trigger fetchOAuthRequirement+oauth_server:+ type: "streamable-http"+ url: "https://api.github.com/mcp"+ headers:+ Authorization: "Bearer {{GITHUB_TOKEN}}"+ serverInstructions: true++# Test OAuth already specified - should skip OAuth detection+oauth_predefined:+ type: "sse"+ url: "https://api.example.com/sse"+ requiresOAuth: true+ oauthMetadata:+ authorization_url: "https://example.com/oauth/authorize"+ token_url: "https://example.com/oauth/token"++# Test stdio server without URL - should set requiresOAuth to false+stdio_server:+ command: "node"+ args: ["server.js"]+ env:+ API_KEY: "${TEST_API_KEY}"+ startup: true+ serverInstructions: "Follow these instructions for stdio server"++# Test websocket server with capabilities but no tools+websocket_server:+ type: "websocket"+ url: "ws://localhost:3001/mcp"+ startup: true++# Test server with startup disabled - should not be included in appServerConfigs+disabled_server:+ type: "streamable-http"+ url: "https://api.disabled.com/mcp"+ startup: false++# Test non-OAuth server - should be included in appServerConfigs+non_oauth_server:+ type: "streamable-http"+ url: "https://api.public.com/mcp"+ requiresOAuth: false+ serverInstructions: true++# Test server with OAuth but startup enabled - should not be in appServerConfigs+oauth_startup_enabled:+ type: "sse"+ url: "https://api.oauth-startup.com/sse"+ requiresOAuth: true\ No newline at end of filediff --git a/packages/api/src/mcp/oauth/handler.test.ts b/packages/api/src/mcp/__tests__/handler.test.tssimilarity index 99%rename from packages/api/src/mcp/oauth/handler.test.tsrename to packages/api/src/mcp/__tests__/handler.test.tsindex c65ffc151b..e4a4075aaf 100644--- a/packages/api/src/mcp/oauth/handler.test.ts+++ b/packages/api/src/mcp/__tests__/handler.test.ts@@ -1,5 +1,5 @@-import { MCPOAuthHandler } from './handler';import type { MCPOptions } from 'librechat-data-provider';+import { MCPOAuthHandler } from '~/mcp/oauth';jest.mock('@librechat/data-schemas', () => ({logger: {diff --git a/packages/api/src/mcp/mcp.spec.ts b/packages/api/src/mcp/__tests__/mcp.spec.tssimilarity index 100%rename from packages/api/src/mcp/mcp.spec.tsrename to packages/api/src/mcp/__tests__/mcp.spec.tsdiff --git a/packages/api/src/mcp/utils.test.ts b/packages/api/src/mcp/__tests__/utils.test.tssimilarity index 95%rename from packages/api/src/mcp/utils.test.tsrename to packages/api/src/mcp/__tests__/utils.test.tsindex bc5d0ba7d4..716a230ebe 100644--- a/packages/api/src/mcp/utils.test.ts+++ b/packages/api/src/mcp/__tests__/utils.test.ts@@ -1,4 +1,4 @@-import { normalizeServerName } from './utils';+import { normalizeServerName } from '../utils';describe('normalizeServerName', () => {it('should not modify server names that already match the pattern', () => {diff --git a/packages/api/src/mcp/zod.spec.ts b/packages/api/src/mcp/__tests__/zod.spec.tssimilarity index 99%rename from packages/api/src/mcp/zod.spec.tsrename to packages/api/src/mcp/__tests__/zod.spec.tsindex 7eb9c162a5..fbc72b7e68 100644--- a/packages/api/src/mcp/zod.spec.ts+++ b/packages/api/src/mcp/__tests__/zod.spec.ts@@ -2,7 +2,7 @@// zod.spec.tsimport { z } from 'zod';import type { JsonSchemaType } from '~/types';-import { resolveJsonSchemaRefs, convertJsonSchemaToZod, convertWithResolvedRefs } from './zod';+import { resolveJsonSchemaRefs, convertJsonSchemaToZod, convertWithResolvedRefs } from '../zod';describe('convertJsonSchemaToZod', () => {describe('primitive types', () => {diff --git a/packages/api/src/mcp/connection.ts b/packages/api/src/mcp/connection.tsindex 52189e2edc..7099205e6b 100644--- a/packages/api/src/mcp/connection.ts+++ b/packages/api/src/mcp/connection.ts@@ -1,17 +1,18 @@import { EventEmitter } from 'events';-import { logger } from '@librechat/data-schemas';-import { Client } from '@modelcontextprotocol/sdk/client/index.js';-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';import {StdioClientTransport,getDefaultEnvironment,} from '@modelcontextprotocol/sdk/client/stdio.js';-import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';-import { ResourceListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';+import { ResourceListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';+import { WebSocketClientTransport } from '@modelcontextprotocol/sdk/client/websocket.js';+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';+import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import { logger } from '@librechat/data-schemas';import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';import type { MCPOAuthTokens } from './oauth/types';+import { mcpConfig } from './mcpConfig';import type * as t from './types';function isStdioOptions(options: t.MCPOptions): options is t.StdioOptions {@@ -56,9 +57,17 @@ function isStreamableHTTPOptions(options: t.MCPOptions): options is t.Streamable}const FIVE_MINUTES = 5 * 60 * 1000;++interface MCPConnectionParams {+ serverName: string;+ serverConfig: t.MCPOptions;+ userId?: string;+ oauthTokens?: MCPOAuthTokens | null;+}+export class MCPConnection extends EventEmitter {- private static instance: MCPConnection | null = null;public client: Client;+ private options: t.MCPOptions;private transport: Transport | null = null; // Make this nullableprivate connectionState: t.ConnectionState = 'disconnected';private connectPromise: Promise<void> | null = null;@@ -70,26 +79,23 @@ export class MCPConnection extends EventEmitter {private reconnectAttempts = 0;private readonly userId?: string;private lastPingTime: number;+ private lastConnectionCheckAt: number = 0;private oauthTokens?: MCPOAuthTokens | null;private oauthRequired = false;iconPath?: string;timeout?: number;url?: string;- constructor(- serverName: string,- private readonly options: t.MCPOptions,- userId?: string,- oauthTokens?: MCPOAuthTokens | null,- ) {+ constructor(params: MCPConnectionParams) {super();- this.serverName = serverName;- this.userId = userId;- this.iconPath = options.iconPath;- this.timeout = options.timeout;+ this.options = params.serverConfig;+ this.serverName = params.serverName;+ this.userId = params.userId;+ this.iconPath = params.serverConfig.iconPath;+ this.timeout = params.serverConfig.timeout;this.lastPingTime = Date.now();- if (oauthTokens) {- this.oauthTokens = oauthTokens;+ if (params.oauthTokens) {+ this.oauthTokens = params.oauthTokens;}this.client = new Client({@@ -110,28 +116,6 @@ export class MCPConnection extends EventEmitter {return `[MCP]${userPart}[${this.serverName}]`;}- public static getInstance(- serverName: string,- options: t.MCPOptions,- userId?: string,- ): MCPConnection {- if (!MCPConnection.instance) {- MCPConnection.instance = new MCPConnection(serverName, options, userId);- }- return MCPConnection.instance;- }-- public static getExistingInstance(): MCPConnection | null {- return MCPConnection.instance;- }-- public static async destroyInstance(): Promise<void> {- if (MCPConnection.instance) {- await MCPConnection.instance.disconnect();- MCPConnection.instance = null;- }- }-private emitError(error: unknown, errorContext: string): void {const errorMessage = error instanceof Error ? error.message : String(error);logger.error(`${this.getLogPrefix()} ${errorContext}: ${errorMessage}`);@@ -589,6 +573,13 @@ export class MCPConnection extends EventEmitter {return false;}+ // If we recently checked, skip expensive verification+ const now = Date.now();+ if (now - this.lastConnectionCheckAt < mcpConfig.CONNECTION_CHECK_TTL) {+ return true;+ }+ this.lastConnectionCheckAt = now;+try {// Try ping first as it's the lightest checkawait this.client.ping();diff --git a/packages/api/src/mcp/manager.ts b/packages/api/src/mcp/manager.tsdeleted file mode 100644index 6db52ec9ec..0000000000--- a/packages/api/src/mcp/manager.ts+++ /dev/null@@ -1,1143 +0,0 @@-import { logger } from '@librechat/data-schemas';-import { CallToolResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';-import type { OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';-import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';-import type { TokenMethods } from '@librechat/data-schemas';-import type { TUser } from 'librechat-data-provider';-import type { MCPOAuthTokens, MCPOAuthFlowMetadata } from './oauth/types';-import type { FlowStateManager } from '~/flow/manager';-import type { JsonSchemaType } from '~/types/zod';-import type { FlowMetadata } from '~/flow/types';-import type * as t from './types';-import { CONSTANTS, isSystemUserId } from './enum';-import { MCPOAuthHandler } from './oauth/handler';-import { MCPTokenStorage } from './oauth/tokens';-import { formatToolContent } from './parsers';-import { MCPConnection } from './connection';-import { processMCPEnv } from '~/utils/env';--export class MCPManager {- private static instance: MCPManager | null = null;- /** App-level connections initialized at startup */- private connections: Map<string, MCPConnection> = new Map();- /** User-specific connections initialized on demand */- private userConnections: Map<string, Map<string, MCPConnection>> = new Map();- /** Last activity timestamp for users (not per server) */- private userLastActivity: Map<string, number> = new Map();- private readonly USER_CONNECTION_IDLE_TIMEOUT = 15 * 60 * 1000; // 15 minutes (TODO: make configurable)- private mcpConfigs: t.MCPServers = {};- /** Store MCP server instructions */- private serverInstructions: Map<string, string> = new Map();- /** Track servers that required OAuth at startup */- private oauthServers: Set<string> = new Set();-- public static getInstance(): MCPManager {- if (!MCPManager.instance) {- MCPManager.instance = new MCPManager();- }- // Check for idle connections when getInstance is called- MCPManager.instance.checkIdleConnections();- return MCPManager.instance;- }-- /** Stores configs and initializes app-level connections */- public async initializeMCPs({- mcpServers,- flowManager,- tokenMethods,- }: {- mcpServers: t.MCPServers;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- tokenMethods?: TokenMethods;- }): Promise<void> {- this.mcpConfigs = mcpServers;-- if (!flowManager) {- logger.info('[MCP] No flow manager provided, OAuth will not be available');- }-- if (!tokenMethods) {- logger.info('[MCP] No token methods provided, token persistence will not be available');- }- const entries = Object.entries(mcpServers);- const initializedServers = new Set();- const connectionResults = await Promise.allSettled(- entries.map(async ([serverName, config], i) => {- try {- await this.initializeMCP({- serverName,- config,- flowManager,- tokenMethods,- });- initializedServers.add(i);- } catch (error) {- logger.error(`[MCP][${serverName}] Initialization failed`, error);- }- }),- );-- const failedConnections = connectionResults.filter(- (result): result is PromiseRejectedResult => result.status === 'rejected',- );-- logger.info(- `[MCP] Initialized ${initializedServers.size}/${entries.length} app-level server(s)`,- );-- if (failedConnections.length > 0) {- logger.warn(- `[MCP] ${failedConnections.length}/${entries.length} app-level server(s) failed to initialize`,- );- }-- entries.forEach(([serverName], index) => {- if (initializedServers.has(index)) {- logger.info(`[MCP][${serverName}] ✓ Initialized`);- } else {- logger.info(`[MCP][${serverName}] ✗ Failed`);- }- });-- if (initializedServers.size === entries.length) {- logger.info('[MCP] All app-level servers initialized successfully');- } else if (initializedServers.size === 0) {- logger.warn('[MCP] No app-level servers initialized');- }- }-- /** Initializes a single MCP server connection (app-level) */- public async initializeMCP({- serverName,- config,- flowManager,- tokenMethods,- }: {- serverName: string;- config: t.MCPOptions;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- tokenMethods?: TokenMethods;- }): Promise<void> {- const processedConfig = processMCPEnv(config);- let tokens: MCPOAuthTokens | null = null;- if (tokenMethods?.findToken) {- try {- /** Refresh function for app-level connections */- const refreshTokensFunction = async (- refreshToken: string,- metadata: {- userId: string;- serverName: string;- identifier: string;- clientInfo?: OAuthClientInformation;- },- ) => {- const serverUrl = (processedConfig as t.SSEOptions | t.StreamableHTTPOptions).url;- return await MCPOAuthHandler.refreshOAuthTokens(- refreshToken,- {- serverName: metadata.serverName,- serverUrl,- clientInfo: metadata.clientInfo,- },- processedConfig.oauth,- );- };-- /** Flow state to prevent concurrent token operations */- const tokenFlowId = `tokens:${CONSTANTS.SYSTEM_USER_ID}:${serverName}`;- tokens = await flowManager.createFlowWithHandler(- tokenFlowId,- 'mcp_get_tokens',- async () => {- return await MCPTokenStorage.getTokens({- userId: CONSTANTS.SYSTEM_USER_ID,- serverName,- findToken: tokenMethods.findToken,- refreshTokens: refreshTokensFunction,- createToken: tokenMethods.createToken,- updateToken: tokenMethods.updateToken,- });- },- );- } catch {- logger.debug(`[MCP][${serverName}] No existing tokens found`);- }- }- if (tokens) {- logger.info(`[MCP][${serverName}] Loaded OAuth tokens`);- }- const connection = new MCPConnection(serverName, processedConfig, undefined, tokens);- logger.info(`[MCP][${serverName}] Setting up OAuth event listener`);- connection.on('oauthRequired', async () => {- logger.debug(`[MCP][${serverName}] oauthRequired event received`);-- this.oauthServers.add(serverName);-- // Skip OAuth at startup - let connection fail gracefully- logger.info(`[MCP][${serverName}] OAuth required, skipping at startup`);- connection.emit('oauthFailed', new Error('OAuth authentication skipped at startup'));- });- try {- const connectTimeout = processedConfig.initTimeout ?? 30000;- const connectionTimeout = new Promise<void>((_, reject) =>- setTimeout(- () => reject(new Error(`Connection timeout after ${connectTimeout}ms`)),- connectTimeout,- ),- );- const connectionAttempt = this.initializeServer({- connection,- logPrefix: `[MCP][${serverName}]`,- flowManager,- handleOAuth: false,- });- await Promise.race([connectionAttempt, connectionTimeout]);- if (await connection.isConnected()) {- this.connections.set(serverName, connection);-- /** Unified `serverInstructions` configuration */- const configInstructions = processedConfig.serverInstructions;- if (configInstructions !== undefined) {- if (typeof configInstructions === 'string') {- this.serverInstructions.set(serverName, configInstructions);- logger.info(- `[MCP][${serverName}] Custom instructions stored for context inclusion: ${configInstructions}`,- );- } else if (configInstructions === true) {- /** Server-provided instructions */- const serverInstructions = connection.client.getInstructions();-- if (serverInstructions) {- this.serverInstructions.set(serverName, serverInstructions);- logger.info(- `[MCP][${serverName}] Server instructions stored for context inclusion: ${serverInstructions}`,- );- } else {- logger.info(- `[MCP][${serverName}] serverInstructions=true but no server instructions available`,- );- }- } else {- logger.info(- `[MCP][${serverName}] Instructions explicitly disabled (serverInstructions=false)`,- );- }- } else {- logger.info(- `[MCP][${serverName}] Instructions not included (serverInstructions not configured)`,- );- }-- const serverCapabilities = connection.client.getServerCapabilities();- logger.info(`[MCP][${serverName}] Capabilities: ${JSON.stringify(serverCapabilities)}`);-- if (serverCapabilities?.tools) {- const tools = await connection.client.listTools();- if (tools.tools.length) {- logger.info(- `[MCP][${serverName}] Available tools: ${tools.tools- .map((tool) => tool.name)- .join(', ')}`,- );- }- }- logger.info(`[MCP][${serverName}] ✓ Initialized`);- } else {- logger.info(`[MCP][${serverName}] ✗ Failed`);- }- } catch (error) {- logger.error(`[MCP][${serverName}] Initialization failed`, error);- throw error;- }- }-- /** Generic server initialization logic */- private async initializeServer({- connection,- logPrefix,- flowManager,- handleOAuth = true,- }: {- connection: MCPConnection;- logPrefix: string;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- handleOAuth?: boolean;- }): Promise<void> {- const maxAttempts = 3;- let attempts = 0;- /** Whether OAuth has been handled by the connection */- let oauthHandled = false;-- while (attempts < maxAttempts) {- try {- await connection.connect();- if (await connection.isConnected()) {- return;- }- throw new Error('Connection attempt succeeded but status is not connected');- } catch (error) {- attempts++;-- if (this.isOAuthError(error)) {- // Only handle OAuth if requested (not already handled by event listener)- if (handleOAuth) {- /** Check if OAuth was already handled by the connection */- const errorWithFlag = error as (Error & { isOAuthError?: boolean }) | undefined;- if (!oauthHandled && errorWithFlag?.isOAuthError) {- oauthHandled = true;- logger.info(`${logPrefix} Handling OAuth`);- const serverUrl = connection.url;- if (serverUrl) {- await this.handleOAuthRequired({- serverName: connection.serverName,- serverUrl,- flowManager,- });- }- } else {- logger.info(`${logPrefix} OAuth already handled by connection`);- }- }- // Don't retry on OAuth errors - just throw- logger.info(`${logPrefix} OAuth required, stopping connection attempts`);- throw error;- }-- if (attempts === maxAttempts) {- logger.error(`${logPrefix} Failed to connect after ${maxAttempts} attempts`, error);- throw error; // Re-throw the last error- }- await new Promise((resolve) => setTimeout(resolve, 2000 * attempts));- }- }- }-- private isOAuthError(error: unknown): boolean {- if (!error || typeof error !== 'object') {- return false;- }-- // Check for SSE error with 401 status- if ('message' in error && typeof error.message === 'string') {- return error.message.includes('401') || error.message.includes('Non-200 status code (401)');- }-- // Check for error code- if ('code' in error) {- const code = (error as { code?: number }).code;- return code === 401 || code === 403;- }-- return false;- }-- /** Check for and disconnect idle connections */- private checkIdleConnections(currentUserId?: string): void {- const now = Date.now();-- // Iterate through all users to check for idle ones- for (const [userId, lastActivity] of this.userLastActivity.entries()) {- if (currentUserId && currentUserId === userId) {- continue;- }- if (now - lastActivity > this.USER_CONNECTION_IDLE_TIMEOUT) {- logger.info(- `[MCP][User: ${userId}] User idle for too long. Disconnecting all connections...`,- );- // Disconnect all user connections asynchronously (fire and forget)- this.disconnectUserConnections(userId).catch((err) =>- logger.error(`[MCP][User: ${userId}] Error disconnecting idle connections:`, err),- );- }- }- }-- /** Updates the last activity timestamp for a user */- private updateUserLastActivity(userId: string): void {- const now = Date.now();- this.userLastActivity.set(userId, now);- logger.debug(- `[MCP][User: ${userId}] Updated last activity timestamp: ${new Date(now).toISOString()}`,- );- }-- /** Gets or creates a connection for a specific user */- public async getUserConnection({- user,- serverName,- flowManager,- customUserVars,- tokenMethods,- oauthStart,- oauthEnd,- signal,- returnOnOAuth = false,- }: {- user: TUser;- serverName: string;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- customUserVars?: Record<string, string>;- tokenMethods?: TokenMethods;- oauthStart?: (authURL: string) => Promise<void>;- oauthEnd?: () => Promise<void>;- signal?: AbortSignal;- returnOnOAuth?: boolean;- }): Promise<MCPConnection> {- const userId = user.id;- if (!userId) {- throw new McpError(ErrorCode.InvalidRequest, `[MCP] User object missing id property`);- }-- const userServerMap = this.userConnections.get(userId);- let connection = userServerMap?.get(serverName);- const now = Date.now();-- // Check if user is idle- const lastActivity = this.userLastActivity.get(userId);- if (lastActivity && now - lastActivity > this.USER_CONNECTION_IDLE_TIMEOUT) {- logger.info(`[MCP][User: ${userId}] User idle for too long. Disconnecting all connections.`);- // Disconnect all user connections- try {- await this.disconnectUserConnections(userId);- } catch (err) {- logger.error(`[MCP][User: ${userId}] Error disconnecting idle connections:`, err);- }- connection = undefined; // Force creation of a new connection- } else if (connection) {- if (await connection.isConnected()) {- logger.debug(`[MCP][User: ${userId}][${serverName}] Reusing active connection`);- this.updateUserLastActivity(userId);- return connection;- } else {- // Connection exists but is not connected, attempt to remove potentially stale entry- logger.warn(- `[MCP][User: ${userId}][${serverName}] Found existing but disconnected connection object. Cleaning up.`,- );- this.removeUserConnection(userId, serverName); // Clean up maps- connection = undefined;- }- }-- // If no valid connection exists, create a new one- if (!connection) {- logger.info(`[MCP][User: ${userId}][${serverName}] Establishing new connection`);- }-- let config = this.mcpConfigs[serverName];- if (!config) {- throw new McpError(- ErrorCode.InvalidRequest,- `[MCP][User: ${userId}] Configuration for server "${serverName}" not found.`,- );- }-- config = { ...(processMCPEnv(config, user, customUserVars) ?? {}) };- /** If no in-memory tokens, tokens from persistent storage */- let tokens: MCPOAuthTokens | null = null;- if (tokenMethods?.findToken) {- try {- /** Refresh function for user-specific connections */- const refreshTokensFunction = async (- refreshToken: string,- metadata: {- userId: string;- serverName: string;- identifier: string;- clientInfo?: OAuthClientInformation;- },- ) => {- /** URL from config since connection doesn't exist yet */- const serverUrl = (config as t.SSEOptions | t.StreamableHTTPOptions).url;- return await MCPOAuthHandler.refreshOAuthTokens(- refreshToken,- {- serverName: metadata.serverName,- serverUrl,- clientInfo: metadata.clientInfo,- },- config.oauth,- );- };-- /** Flow state to prevent concurrent token operations */- const tokenFlowId = `tokens:${userId}:${serverName}`;- tokens = await flowManager.createFlowWithHandler(- tokenFlowId,- 'mcp_get_tokens',- async () => {- return await MCPTokenStorage.getTokens({- userId,- serverName,- findToken: tokenMethods.findToken,- refreshTokens: refreshTokensFunction,- createToken: tokenMethods.createToken,- updateToken: tokenMethods.updateToken,- });- },- signal,- );- } catch (error) {- logger.error(- `[MCP][User: ${userId}][${serverName}] Error loading OAuth tokens from storage`,- error,- );- }- }-- if (tokens) {- logger.info(`[MCP][User: ${userId}][${serverName}] Loaded OAuth tokens`);- }-- connection = new MCPConnection(serverName, config, userId, tokens);-- connection.on('oauthRequired', async (data) => {- logger.info(`[MCP][User: ${userId}][${serverName}] oauthRequired event received`);-- // If we just want to initiate OAuth and return, handle it differently- if (returnOnOAuth) {- try {- const config = this.mcpConfigs[serverName];- const { authorizationUrl, flowId, flowMetadata } =- await MCPOAuthHandler.initiateOAuthFlow(- serverName,- data.serverUrl || '',- userId,- config?.oauth,- );-- // Create the flow state so the OAuth callback can find it- // We spawn this in the background without waiting for it- flowManager.createFlow(flowId, 'mcp_oauth', flowMetadata).catch(() => {- // The OAuth callback will resolve this flow, so we expect it to timeout here- // which is fine - we just need the flow state to exist- });-- if (oauthStart) {- logger.info(- `[MCP][User: ${userId}][${serverName}] OAuth flow started, issuing authorization URL`,- );- await oauthStart(authorizationUrl);- }-- // Emit oauthFailed to signal that connection should not proceed- // but OAuth was successfully initiated- connection?.emit('oauthFailed', new Error('OAuth flow initiated - return early'));- return;- } catch (error) {- logger.error(- `[MCP][User: ${userId}][${serverName}] Failed to initiate OAuth flow`,- error,- );- connection?.emit('oauthFailed', new Error('OAuth initiation failed'));- return;- }- }-- // Normal OAuth handling - wait for completion- const result = await this.handleOAuthRequired({- ...data,- flowManager,- oauthStart,- oauthEnd,- });-- if (result?.tokens && tokenMethods?.createToken) {- try {- connection?.setOAuthTokens(result.tokens);- await MCPTokenStorage.storeTokens({- userId,- serverName,- tokens: result.tokens,- createToken: tokenMethods.createToken,- updateToken: tokenMethods.updateToken,- findToken: tokenMethods.findToken,- clientInfo: result.clientInfo,- });- logger.info(`[MCP][User: ${userId}][${serverName}] OAuth tokens saved to storage`);- } catch (error) {- logger.error(- `[MCP][User: ${userId}][${serverName}] Failed to save OAuth tokens to storage`,- error,- );- }- }-- // Only emit oauthHandled if we actually got tokens (OAuth succeeded)- if (result?.tokens) {- connection?.emit('oauthHandled');- } else {- // OAuth failed, emit oauthFailed to properly reject the promise- logger.warn(- `[MCP][User: ${userId}][${serverName}] OAuth failed, emitting oauthFailed event`,- );- connection?.emit('oauthFailed', new Error('OAuth authentication failed'));- }- });-- try {- const connectTimeout = config.initTimeout ?? 30000;- const connectionTimeout = new Promise<void>((_, reject) =>- setTimeout(- () => reject(new Error(`Connection timeout after ${connectTimeout}ms`)),- connectTimeout,- ),- );- const connectionAttempt = this.initializeServer({- connection,- logPrefix: `[MCP][User: ${userId}][${serverName}]`,- flowManager,- });- await Promise.race([connectionAttempt, connectionTimeout]);-- if (!(await connection?.isConnected())) {- throw new Error('Failed to establish connection after initialization attempt.');- }-- if (!this.userConnections.has(userId)) {- this.userConnections.set(userId, new Map());- }- this.userConnections.get(userId)?.set(serverName, connection);-- logger.info(`[MCP][User: ${userId}][${serverName}] Connection successfully established`);- // Update timestamp on creation- this.updateUserLastActivity(userId);- return connection;- } catch (error) {- logger.error(`[MCP][User: ${userId}][${serverName}] Failed to establish connection`, error);- // Ensure partial connection state is cleaned up if initialization fails- await connection?.disconnect().catch((disconnectError) => {- logger.error(- `[MCP][User: ${userId}][${serverName}] Error during cleanup after failed connection`,- disconnectError,- );- });- // Ensure cleanup even if connection attempt fails- this.removeUserConnection(userId, serverName);- throw error; // Re-throw the error to the caller- }- }-- /** Removes a specific user connection entry */- private removeUserConnection(userId: string, serverName: string): void {- const userMap = this.userConnections.get(userId);- if (userMap) {- userMap.delete(serverName);- if (userMap.size === 0) {- this.userConnections.delete(userId);- // Only remove user activity timestamp if all connections are gone- this.userLastActivity.delete(userId);- }- }-- logger.debug(`[MCP][User: ${userId}][${serverName}] Removed connection entry.`);- }-- /** Disconnects and removes a specific user connection */- public async disconnectUserConnection(userId: string, serverName: string): Promise<void> {- const userMap = this.userConnections.get(userId);- const connection = userMap?.get(serverName);- if (connection) {- logger.info(`[MCP][User: ${userId}][${serverName}] Disconnecting...`);- await connection.disconnect();- this.removeUserConnection(userId, serverName);- }- }-- /** Disconnects and removes all connections for a specific user */- public async disconnectUserConnections(userId: string): Promise<void> {- const userMap = this.userConnections.get(userId);- const disconnectPromises: Promise<void>[] = [];- if (userMap) {- logger.info(`[MCP][User: ${userId}] Disconnecting all servers...`);- const userServers = Array.from(userMap.keys());- for (const serverName of userServers) {- disconnectPromises.push(- this.disconnectUserConnection(userId, serverName).catch((error) => {- logger.error(- `[MCP][User: ${userId}][${serverName}] Error during disconnection:`,- error,- );- }),- );- }- await Promise.allSettled(disconnectPromises);- // Ensure user activity timestamp is removed- this.userLastActivity.delete(userId);- logger.info(`[MCP][User: ${userId}] All connections processed for disconnection.`);- }- }-- /** Returns the app-level connection (used for mapping tools, etc.) */- public getConnection(serverName: string): MCPConnection | undefined {- return this.connections.get(serverName);- }-- /** Returns all app-level connections */- public getAllConnections(): Map<string, MCPConnection> {- return this.connections;- }-- /** Attempts to reconnect an app-level connection if it's disconnected */- private async isConnectionActive({- serverName,- connection,- flowManager,- skipReconnect = false,- }: {- serverName: string;- connection: MCPConnection;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- skipReconnect?: boolean;- }): Promise<boolean> {- if (await connection.isConnected()) {- return true;- }-- if (skipReconnect) {- logger.warn(- `[MCP][${serverName}] App-level connection is disconnected, skipping reconnection attempt`,- );- return false;- }-- logger.warn(- `[MCP][${serverName}] App-level connection disconnected, attempting to reconnect...`,- );-- try {- const config = this.mcpConfigs[serverName];- if (!config) {- logger.error(`[MCP][${serverName}] Configuration not found for reconnection`);- return false;- }-- await this.initializeServer({- connection,- logPrefix: `[MCP][${serverName}]`,- flowManager,- });-- if (await connection.isConnected()) {- logger.info(`[MCP][${serverName}] App-level connection successfully reconnected`);- return true;- } else {- logger.warn(`[MCP][${serverName}] App-level connection reconnection failed`);- return false;- }- } catch (error) {- logger.error(`[MCP][${serverName}] Error during app-level connection reconnection:`, error);- return false;- }- }-- /**- * Maps available tools from all app-level connections into the provided object.- * The object is modified in place.- */- public async mapAvailableTools(- availableTools: t.LCAvailableTools,- flowManager: FlowStateManager<MCPOAuthTokens | null>,- ): Promise<void> {- for (const [serverName, connection] of this.connections.entries()) {- try {- /** Attempt to ensure connection is active, with reconnection if needed */- const isActive = await this.isConnectionActive({ serverName, connection, flowManager });- if (!isActive) {- logger.warn(`[MCP][${serverName}] Connection not available. Skipping tool mapping.`);- continue;- }-- const tools = await connection.fetchTools();- for (const tool of tools) {- const name = `${tool.name}${CONSTANTS.mcp_delimiter}${serverName}`;- availableTools[name] = {- type: 'function',- ['function']: {- name,- description: tool.description,- parameters: tool.inputSchema as JsonSchemaType,- },- };- }- } catch (error) {- logger.warn(`[MCP][${serverName}] Error fetching tools`, error);- }- }- }-- /**- * Loads tools from all app-level connections into the manifest.- */- public async loadManifestTools({- flowManager,- serverToolsCallback,- getServerTools,- }: {- flowManager: FlowStateManager<MCPOAuthTokens | null>;- serverToolsCallback?: (serverName: string, tools: t.LCManifestTool[]) => Promise<void>;- getServerTools?: (serverName: string) => Promise<t.LCManifestTool[] | undefined>;- }): Promise<t.LCToolManifest> {- const mcpTools: t.LCManifestTool[] = [];- for (const [serverName, connection] of this.connections.entries()) {- try {- /** Attempt to ensure connection is active, with reconnection if needed */- const isActive = await this.isConnectionActive({- serverName,- connection,- flowManager,- skipReconnect: true,- });- if (!isActive) {- logger.warn(- `[MCP][${serverName}] Connection not available for ${serverName} manifest tools.`,- );- if (typeof getServerTools !== 'function') {- logger.warn(- `[MCP][${serverName}] No \`getServerTools\` function provided, skipping tool loading.`,- );- continue;- }- const serverTools = await getServerTools(serverName);- if (serverTools && serverTools.length > 0) {- logger.info(`[MCP][${serverName}] Loaded tools from cache for manifest`);- mcpTools.push(...serverTools);- }- continue;- }-- const tools = await connection.fetchTools();- const serverTools: t.LCManifestTool[] = [];- for (const tool of tools) {- const pluginKey = `${tool.name}${CONSTANTS.mcp_delimiter}${serverName}`;-- const config = this.mcpConfigs[serverName];- const manifestTool: t.LCManifestTool = {- name: tool.name,- pluginKey,- description: tool.description ?? '',- icon: connection.iconPath,- authConfig: config?.customUserVars- ? Object.entries(config.customUserVars).map(([key, value]) => ({- authField: key,- label: value.title || key,- description: value.description || '',- }))- : undefined,- };- if (config?.chatMenu === false) {- manifestTool.chatMenu = false;- }- mcpTools.push(manifestTool);- serverTools.push(manifestTool);- }- if (typeof serverToolsCallback === 'function') {- await serverToolsCallback(serverName, serverTools);- }- } catch (error) {- logger.error(`[MCP][${serverName}] Error fetching tools for manifest:`, error);- }- }-- return mcpTools;- }-- /**- * Calls a tool on an MCP server, using either a user-specific connection- * (if userId is provided) or an app-level connection. Updates the last activity timestamp- * for user-specific connections upon successful call initiation.- */- async callTool({- user,- serverName,- toolName,- provider,- toolArguments,- options,- tokenMethods,- flowManager,- oauthStart,- oauthEnd,- customUserVars,- }: {- user?: TUser;- serverName: string;- toolName: string;- provider: t.Provider;- toolArguments?: Record<string, unknown>;- options?: RequestOptions;- tokenMethods?: TokenMethods;- customUserVars?: Record<string, string>;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- oauthStart?: (authURL: string) => Promise<void>;- oauthEnd?: () => Promise<void>;- }): Promise<t.FormattedToolResponse> {- /** User-specific connection */- let connection: MCPConnection | undefined;- const userId = user?.id;- const logPrefix = userId ? `[MCP][User: ${userId}][${serverName}]` : `[MCP][${serverName}]`;-- try {- if (userId && user) {- this.updateUserLastActivity(userId);- /** Get or create user-specific connection */- connection = await this.getUserConnection({- user,- serverName,- flowManager,- tokenMethods,- oauthStart,- oauthEnd,- signal: options?.signal,- customUserVars,- });- } else {- /** App-level connection */- connection = this.connections.get(serverName);- if (!connection) {- throw new McpError(- ErrorCode.InvalidRequest,- `${logPrefix} No app-level connection found. Cannot execute tool ${toolName}.`,- );- }- }-- if (!(await connection.isConnected())) {- /** May happen if getUserConnection failed silently or app connection dropped */- throw new McpError(- ErrorCode.InternalError, // Use InternalError for connection issues- `${logPrefix} Connection is not active. Cannot execute tool ${toolName}.`,- );- }-- const result = await connection.client.request(- {- method: 'tools/call',- params: {- name: toolName,- arguments: toolArguments,- },- },- CallToolResultSchema,- {- timeout: connection.timeout,- ...options,- },- );- if (userId) {- this.updateUserLastActivity(userId);- }- this.checkIdleConnections();- return formatToolContent(result as t.MCPToolCallResponse, provider);- } catch (error) {- // Log with context and re-throw or handle as needed- logger.error(`${logPrefix}[${toolName}] Tool call failed`, error);- // Rethrowing allows the caller (createMCPTool) to handle the final user message- throw error;- }- }-- /** Disconnects a specific app-level server */- public async disconnectServer(serverName: string): Promise<void> {- const connection = this.connections.get(serverName);- if (connection) {- logger.info(`[MCP][${serverName}] Disconnecting...`);- await connection.disconnect();- this.connections.delete(serverName);- }- }-- /** Disconnects all app-level and user-level connections */- public async disconnectAll(): Promise<void> {- logger.info('[MCP] Disconnecting all app-level and user-level connections...');-- const userDisconnectPromises = Array.from(this.userConnections.keys()).map((userId) =>- this.disconnectUserConnections(userId),- );- await Promise.allSettled(userDisconnectPromises);- this.userLastActivity.clear();-- // Disconnect all app-level connections- const appDisconnectPromises = Array.from(this.connections.values()).map((connection) =>- connection.disconnect().catch((error) => {- logger.error(`[MCP][${connection.serverName}] Error during disconnectAll:`, error);- }),- );- await Promise.allSettled(appDisconnectPromises);- this.connections.clear();-- logger.info('[MCP] All connections processed for disconnection.');- }-- /** Destroys the singleton instance and disconnects all connections */- public static async destroyInstance(): Promise<void> {- if (MCPManager.instance) {- await MCPManager.instance.disconnectAll();- MCPManager.instance = null;- logger.info('[MCP] Manager instance destroyed.');- }- }-- /**- * Get instructions for MCP servers- * @param serverNames Optional array of server names. If not provided or empty, returns all servers.- * @returns Object mapping server names to their instructions- */- public getInstructions(serverNames?: string[]): Record<string, string> {- const instructions: Record<string, string> = {};-- if (!serverNames || serverNames.length === 0) {- // Return all instructions if no specific servers requested- for (const [serverName, serverInstructions] of this.serverInstructions.entries()) {- instructions[serverName] = serverInstructions;- }- } else {- // Return instructions for specific servers- for (const serverName of serverNames) {- const serverInstructions = this.serverInstructions.get(serverName);- if (serverInstructions) {- instructions[serverName] = serverInstructions;- }- }- }-- return instructions;- }-- /**- * Format MCP server instructions for injection into context- * @param serverNames Optional array of server names to include. If not provided, includes all servers.- * @returns Formatted instructions string ready for context injection- */- public formatInstructionsForContext(serverNames?: string[]): string {- /** Instructions for specified servers or all stored instructions */- const instructionsToInclude = this.getInstructions(serverNames);-- if (Object.keys(instructionsToInclude).length === 0) {- return '';- }-- // Format instructions for context injection- const formattedInstructions = Object.entries(instructionsToInclude)- .map(([serverName, instructions]) => {- return `## ${serverName} MCP Server Instructions--${instructions}`;- })- .join('\n\n');-- return `# MCP Server Instructions--The following MCP servers are available with their specific instructions:--${formattedInstructions}--Please follow these instructions when using tools from the respective MCP servers.`;- }-- /** Handles OAuth authentication requirements */- private async handleOAuthRequired({- serverName,- serverUrl,- flowManager,- userId = CONSTANTS.SYSTEM_USER_ID,- oauthStart,- oauthEnd,- }: {- serverName: string;- flowManager: FlowStateManager<MCPOAuthTokens | null>;- userId?: string;- serverUrl?: string;- oauthStart?: (authURL: string) => Promise<void>;- oauthEnd?: () => Promise<void>;- }): Promise<{ tokens: MCPOAuthTokens | null; clientInfo?: OAuthClientInformation } | null> {- const userPart = isSystemUserId(userId) ? '' : `[User: ${userId}]`;- const logPrefix = `[MCP]${userPart}[${serverName}]`;- logger.debug(`${logPrefix} \`handleOAuthRequired\` called with serverUrl: ${serverUrl}`);-- if (!flowManager || !serverUrl) {- logger.error(- `${logPrefix} OAuth required but flow manager not available or server URL missing for ${serverName}`,- );- logger.warn(`${logPrefix} Please configure OAuth credentials for ${serverName}`);- return null;- }-- try {- const config = this.mcpConfigs[serverName];- logger.debug(`${logPrefix} Checking for existing OAuth flow for ${serverName}...`);-- /** Flow ID to check if a flow already exists */- const flowId = MCPOAuthHandler.generateFlowId(userId, serverName);-- /** Check if there's already an ongoing OAuth flow for this flowId */- const existingFlow = await flowManager.getFlowState(flowId, 'mcp_oauth');- if (existingFlow && existingFlow.status === 'PENDING') {- logger.debug(- `${logPrefix} OAuth flow already exists for ${flowId}, waiting for completion`,- );- /** Tokens from existing flow to complete */- const tokens = await flowManager.createFlow(flowId, 'mcp_oauth');- if (typeof oauthEnd === 'function') {- await oauthEnd();- }- logger.info(`${logPrefix} OAuth flow completed, tokens received for ${serverName}`);-- /** Client information from the existing flow metadata */- const existingMetadata = existingFlow.metadata as unknown as MCPOAuthFlowMetadata;- const clientInfo = existingMetadata?.clientInfo;-- return { tokens, clientInfo };- }-- logger.debug(`${logPrefix} Initiating new OAuth flow for ${serverName}...`);- const {- authorizationUrl,- flowId: newFlowId,- flowMetadata,- } = await MCPOAuthHandler.initiateOAuthFlow(serverName, serverUrl, userId, config?.oauth);-- if (typeof oauthStart === 'function') {- logger.info(`${logPrefix} OAuth flow started, issued authorization URL to user`);- await oauthStart(authorizationUrl);- } else {- logger.info(`-═══════════════════════════════════════════════════════════════════════-Please visit the following URL to authenticate:--${authorizationUrl}--${logPrefix} Flow ID: ${newFlowId}-═══════════════════════════════════════════════════════════════════════-`);- }-- /** Tokens from the new flow */- const tokens = await flowManager.createFlow(- newFlowId,- 'mcp_oauth',- flowMetadata as FlowMetadata,- );- if (typeof oauthEnd === 'function') {- await oauthEnd();- }- logger.info(`${logPrefix} OAuth flow completed, tokens received for ${serverName}`);-- /** Client information from the flow metadata */- const clientInfo = flowMetadata?.clientInfo;-- return { tokens, clientInfo };- } catch (error) {- logger.error(`${logPrefix} Failed to complete OAuth flow for ${serverName}`, error);- return null;- }- }- public getUserConnections(userId: string) {- return this.userConnections.get(userId);- }-- /** Get servers that require OAuth */- public getOAuthServers(): Set<string> {- return this.oauthServers;- }-}diff --git a/packages/api/src/mcp/mcpConfig.ts b/packages/api/src/mcp/mcpConfig.tsnew file mode 100644index 0000000000..4d0f2b8ca7--- /dev/null+++ b/packages/api/src/mcp/mcpConfig.ts@@ -0,0 +1,11 @@+import { math, isEnabled } from '~/utils';++/**+ * Centralized configuration for MCP-related environment variables.+ * Provides typed access to MCP settings with default values.+ */+export const mcpConfig = {+ OAUTH_ON_AUTH_ERROR: isEnabled(process.env.MCP_OAUTH_ON_AUTH_ERROR ?? true),+ OAUTH_DETECTION_TIMEOUT: math(process.env.MCP_OAUTH_DETECTION_TIMEOUT ?? 5000),+ CONNECTION_CHECK_TTL: math(process.env.MCP_CONNECTION_CHECK_TTL ?? 60000),+};diff --git a/packages/api/src/mcp/oauth/detectOAuth.ts b/packages/api/src/mcp/oauth/detectOAuth.tsnew file mode 100644index 0000000000..f22f5e4cd2--- /dev/null+++ b/packages/api/src/mcp/oauth/detectOAuth.ts@@ -0,0 +1,120 @@+// ATTENTION: If you modify OAuth detection logic in this file, run the integration tests to verify:+// npx jest --testMatch="**/detectOAuth.integration.dev.ts" (from packages/api directory)+//+// These tests are excluded from CI because they make live HTTP requests to external services,+// which could cause flaky builds due to network issues or changes in third-party endpoints.+// Manual testing ensures the OAuth detection still works against real MCP servers.++import { discoverOAuthProtectedResourceMetadata } from '@modelcontextprotocol/sdk/client/auth.js';+import { mcpConfig } from '../mcpConfig';++export interface OAuthDetectionResult {+ requiresOAuth: boolean;+ method: 'protected-resource-metadata' | '401-challenge-metadata' | 'no-metadata-found';+ metadata?: Record<string, unknown> | null;+}++/**+ * Detects if an MCP server requires OAuth authentication using proactive discovery methods.+ *+ * This function implements a comprehensive OAuth detection strategy:+ * 1. Standard Protected Resource Metadata (RFC 9728) - checks /.well-known/oauth-protected-resource+ * 2. 401 Challenge Method - checks WWW-Authenticate header for resource_metadata URL+ * 3. Optional fallback: treat any 401/403 response as OAuth requirement (if MCP_OAUTH_ON_AUTH_ERROR=true)+ *+ * @param serverUrl - The MCP server URL to check for OAuth requirements+ * @returns Promise<OAuthDetectionResult> - OAuth requirement details+ */+export async function detectOAuthRequirement(serverUrl: string): Promise<OAuthDetectionResult> {+ const protectedResourceResult = await checkProtectedResourceMetadata(serverUrl);+ if (protectedResourceResult) return protectedResourceResult;++ const challengeResult = await check401ChallengeMetadata(serverUrl);+ if (challengeResult) return challengeResult;++ const fallbackResult = await checkAuthErrorFallback(serverUrl);+ if (fallbackResult) return fallbackResult;++ // No OAuth detected+ return {+ requiresOAuth: false,+ method: 'no-metadata-found',+ metadata: null,+ };+}++////////////////////////////////////////////////////////////////////////////////////////////////////+// ------------------------ Private helper functions for OAuth detection -------------------------//+////////////////////////////////////////////////////////////////////////////////////////////////////++// Checks for OAuth using standard protected resource metadata (RFC 9728)+async function checkProtectedResourceMetadata(+ serverUrl: string,+): Promise<OAuthDetectionResult | null> {+ try {+ const resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl);++ if (!resourceMetadata?.authorization_servers?.length) return null;++ return {+ requiresOAuth: true,+ method: 'protected-resource-metadata',+ metadata: resourceMetadata,+ };+ } catch {+ return null;+ }+}++// Checks for OAuth using 401 challenge with resource metadata URL+async function check401ChallengeMetadata(serverUrl: string): Promise<OAuthDetectionResult | null> {+ try {+ const response = await fetch(serverUrl, {+ method: 'HEAD',+ signal: AbortSignal.timeout(mcpConfig.OAUTH_DETECTION_TIMEOUT),+ });++ if (response.status !== 401) return null;++ const wwwAuth = response.headers.get('www-authenticate');+ const metadataUrl = wwwAuth?.match(/resource_metadata="([^"]+)"/)?.[1];+ if (!metadataUrl) return null;++ const metadataResponse = await fetch(metadataUrl, {+ signal: AbortSignal.timeout(mcpConfig.OAUTH_DETECTION_TIMEOUT),+ });+ const metadata = await metadataResponse.json();++ if (!metadata?.authorization_servers?.length) return null;++ return {+ requiresOAuth: true,+ method: '401-challenge-metadata',+ metadata,+ };+ } catch {+ return null;+ }+}++// Fallback method: treats any auth error as OAuth requirement if configured+async function checkAuthErrorFallback(serverUrl: string): Promise<OAuthDetectionResult | null> {+ try {+ if (!mcpConfig.OAUTH_ON_AUTH_ERROR) return null;++ const response = await fetch(serverUrl, {+ method: 'HEAD',+ signal: AbortSignal.timeout(mcpConfig.OAUTH_DETECTION_TIMEOUT),+ });++ if (response.status !== 401 && response.status !== 403) return null;++ return {+ requiresOAuth: true,+ method: 'no-metadata-found',+ metadata: null,+ };+ } catch {+ return null;+ }+}diff --git a/packages/api/src/mcp/oauth/index.ts b/packages/api/src/mcp/oauth/index.tsindex ff82bd92f7..d9c75071e0 100644--- a/packages/api/src/mcp/oauth/index.ts+++ b/packages/api/src/mcp/oauth/index.ts@@ -1,3 +1,4 @@export * from './types';export * from './handler';export * from './tokens';+export * from './detectOAuth';diff --git a/packages/data-provider/src/mcp.ts b/packages/data-provider/src/mcp.tsindex b244f7fe5f..e908d9f90a 100644--- a/packages/data-provider/src/mcp.ts+++ b/packages/data-provider/src/mcp.ts@@ -3,6 +3,13 @@ import { TokenExchangeMethodEnum } from './types/agents';import { extractEnvVariable } from './utils';const BaseOptionsSchema = z.object({+ /**+ * Controls whether the MCP server is initialized during application startup.+ * - true (default): Server is initialized during app startup and included in app-level connections+ * - false: Skips initialization at startup and excludes from app-level connections - useful for servers+ * requiring manual authentication (e.g., GitHub PAT tokens) that need to be configured through the UI after startup+ */+ startup: z.boolean().optional(),iconPath: z.string().optional(),timeout: z.number().optional(),initTimeout: z.number().optional(),@@ -15,6 +22,11 @@ const BaseOptionsSchema = z.object({* - string: Use custom instructions (overrides server-provided)*/serverInstructions: z.union([z.boolean(), z.string()]).optional(),+ /**+ * Whether this server requires OAuth authentication+ * If not specified, will be auto-detected during construction+ */+ requiresOAuth: z.boolean().optional(),/*** OAuth configuration for SSE and Streamable HTTP transports* - Optional: OAuth can be auto-discovered on 401 responses