🪐 feat: MCP OAuth 2.0 Discovery Support (#7924)

* chore: Update @modelcontextprotocol/sdk to version 1.12.3 in package.json and package-lock.json

- Bump version of @modelcontextprotocol/sdk to 1.12.3 to incorporate recent updates.
- Update dependencies for ajv and cross-spawn to their latest versions.
- Add ajv as a new dependency in the sdk module.
- Include json-schema-traverse as a new dependency in the sdk module.

* feat: @librechat/auth

* feat: Add crypto module exports to auth package

- Introduced a new crypto module by creating index.ts in the crypto directory.
- Updated the main index.ts of the auth package to export from the new crypto module.

* feat: Update package dependencies and build scripts for auth package

- Added @librechat/auth as a dependency in package.json and package-lock.json.
- Updated build scripts to include the auth package in both frontend and bun build processes.
- Removed unused mongoose and openid-client dependencies from package-lock.json for cleaner dependency management.

* refactor: Migrate crypto utility functions to @librechat/auth

- Replaced local crypto utility imports with the new @librechat/auth package across multiple files.
- Removed the obsolete crypto.js file and its exports.
- Updated relevant services and models to utilize the new encryption and decryption methods from @librechat/auth.

* feat: Enhance OAuth token handling and update dependencies in auth package

* chore: Remove Token model and TokenService due to restructuring of OAuth handling

- Deleted the Token.js model and TokenService.js, which were responsible for managing OAuth tokens.
- This change is part of a broader refactor to streamline OAuth token management and improve code organization.

* refactor: imports from '@librechat/auth' to '@librechat/api' and add OAuth token handling functionality

* refactor: Simplify logger usage in MCP and FlowStateManager classes

* chore: fix imports

* feat: Add OAuth configuration schema to MCP with token exchange method support

* feat: FIRST PASS Implement MCP OAuth flow with token management and error handling

- Added a new route for handling OAuth callbacks and token retrieval.
- Integrated OAuth token storage and retrieval mechanisms.
- Enhanced MCP connection to support automatic OAuth flow initiation on 401 errors.
- Implemented dynamic client registration and metadata discovery for OAuth.
- Updated MCPManager to manage OAuth tokens and handle authentication requirements.
- Introduced comprehensive logging for OAuth processes and error handling.

* refactor: Update MCPConnection and MCPManager to utilize new URL handling

- Added a `url` property to MCPConnection for better URL management.
- Refactored MCPManager to use the new `url` property instead of a deprecated method for OAuth handling.
- Changed logging from info to debug level for flow manager and token methods initialization.
- Improved comments for clarity on existing tokens and OAuth event listener setup.

* refactor: Improve connection timeout error messages in MCPConnection and MCPManager and use initTimeout for connection

- Updated the connection timeout error messages to include the duration of the timeout.
- Introduced a configurable `connectTimeout` variable in both MCPConnection and MCPManager for better flexibility.

* chore: cleanup MCP OAuth Token exchange handling; fix: erroneous use of flowsCache and remove verbose logs

* refactor: Update MCPManager and MCPTokenStorage to use TokenMethods for token management

- Removed direct token storage handling in MCPManager and replaced it with TokenMethods for better abstraction.
- Refactored MCPTokenStorage methods to accept parameters for token operations, enhancing flexibility and readability.
- Improved logging messages related to token persistence and retrieval processes.

* refactor: Update MCP OAuth handling to use static methods and improve flow management

- Refactored MCPOAuthHandler to utilize static methods for initiating and completing OAuth flows, enhancing clarity and reducing instance dependencies.
- Updated MCPManager to pass flowManager explicitly to OAuth handling methods, improving flexibility in flow state management.
- Enhanced comments and logging for better understanding of OAuth processes and flow state retrieval.

* refactor: Integrate token methods into createMCPTool for enhanced token management

* refactor: Change logging from info to debug level in MCPOAuthHandler for improved log management

* chore: clean up logging

* feat: first pass, auth URL from MCP OAuth flow

* chore: Improve logging format for OAuth authentication URL display

* chore: cleanup mcp manager comments

* feat: add connection reconnection logic in MCPManager

* refactor: reorganize token storage handling in MCP

- Moved token storage logic from MCPManager to a new MCPTokenStorage class for better separation of concerns.
- Updated imports to reflect the new token storage structure.
- Enhanced methods for storing, retrieving, updating, and deleting OAuth tokens, improving overall token management.

* chore: update comment for SYSTEM_USER_ID in MCPManager for clarity

* feat: implement refresh token functionality in MCP

- Added refresh token handling in MCPManager to support token renewal for both app-level and user-specific connections.
- Introduced a refreshTokens function to facilitate token refresh logic.
- Enhanced MCPTokenStorage to manage client information and refresh token processes.
- Updated logging for better traceability during token operations.

* chore: cleanup @librechat/auth

* feat: implement MCP server initialization in a separate service

- Added a new service to handle the initialization of MCP servers, improving code organization and readability.
- Refactored the server startup logic to utilize the new initializeMCP function.
- Removed redundant MCP initialization code from the main server file.

* fix: don't log auth url for user connections

* feat: enhance OAuth flow with success and error handling components

- Updated OAuth callback routes to redirect to new success and error pages instead of sending status messages.
- Introduced `OAuthSuccess` and `OAuthError` components to provide user feedback during authentication.
- Added localization support for success and error messages in the translation files.
- Implemented countdown functionality in the success component for a better user experience.

* fix: refresh token handling for user connections, add missing URL and methods

- add standard enum for system user id and helper for determining app-lvel vs. user-level connections

* refactor: update token handling in MCPManager and MCPTokenStorage

* fix: improve error logging in OAuth authentication handler

* fix: concurrency issues for both login url emission and concurrency of oauth flows for shared flows (same user, same server, multiple calls for same server)

* fix: properly fail shared flows for concurrent server calls and prevent duplication of tokens

* chore: remove unused auth package directory from update configuration

* ci: fix mocks in samlStrategy tests

* ci: add mcpConfig to AppService test setup

* chore: remove obsolete MCP OAuth implementation documentation

* fix: update build script for API to use correct command

* chore: bump version of @librechat/api to 1.2.4

* fix: update abort signal handling in createMCPTool function

* fix: add optional clientInfo parameter to refreshTokensFunction metadata

* refactor: replace app.locals.availableTools with getCachedTools in multiple services and controllers for improved tool management

* fix: concurrent refresh token handling issue

* refactor: add signal parameter to getUserConnection method for improved abort handling

* chore: JSDoc typing for `loadEphemeralAgent`

* refactor: update isConnectionActive method to use destructured parameters for improved readability

* feat: implement caching for MCP tools to handle app-level disconnects for loading list of tools

* ci: fix agent test
This commit is contained in:
Danny Avila 2025-06-17 13:50:33 -04:00 committed by GitHub
parent b412455e9d
commit ec7370dfe9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
60 changed files with 3399 additions and 764 deletions

View file

@ -1,4 +1,5 @@
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 {
@ -10,7 +11,7 @@ import { ResourceListChangedNotificationSchema } from '@modelcontextprotocol/sdk
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
import type { Logger } from 'winston';
import type { MCPOAuthTokens } from './oauth/types';
import type * as t from './types';
function isStdioOptions(options: t.MCPOptions): options is t.StdioOptions {
@ -67,24 +68,29 @@ export class MCPConnection extends EventEmitter {
private isReconnecting = false;
private isInitializing = false;
private reconnectAttempts = 0;
iconPath?: string;
timeout?: number;
private readonly userId?: string;
private lastPingTime: number;
private oauthTokens?: MCPOAuthTokens | null;
private oauthRequired = false;
iconPath?: string;
timeout?: number;
url?: string;
constructor(
serverName: string,
private readonly options: t.MCPOptions,
private logger?: Logger,
userId?: string,
oauthTokens?: MCPOAuthTokens | null,
) {
super();
this.serverName = serverName;
this.logger = logger;
this.userId = userId;
this.iconPath = options.iconPath;
this.timeout = options.timeout;
this.lastPingTime = Date.now();
if (oauthTokens) {
this.oauthTokens = oauthTokens;
}
this.client = new Client(
{
name: '@librechat/api-client',
@ -107,11 +113,10 @@ export class MCPConnection extends EventEmitter {
public static getInstance(
serverName: string,
options: t.MCPOptions,
logger?: Logger,
userId?: string,
): MCPConnection {
if (!MCPConnection.instance) {
MCPConnection.instance = new MCPConnection(serverName, options, logger, userId);
MCPConnection.instance = new MCPConnection(serverName, options, userId);
}
return MCPConnection.instance;
}
@ -129,7 +134,7 @@ export class MCPConnection extends EventEmitter {
private emitError(error: unknown, errorContext: string): void {
const errorMessage = error instanceof Error ? error.message : String(error);
this.logger?.error(`${this.getLogPrefix()} ${errorContext}: ${errorMessage}`);
logger.error(`${this.getLogPrefix()} ${errorContext}: ${errorMessage}`);
this.emit('error', new Error(`${errorContext}: ${errorMessage}`));
}
@ -167,45 +172,52 @@ export class MCPConnection extends EventEmitter {
if (!isWebSocketOptions(options)) {
throw new Error('Invalid options for websocket transport.');
}
this.url = options.url;
return new WebSocketClientTransport(new URL(options.url));
case 'sse': {
if (!isSSEOptions(options)) {
throw new Error('Invalid options for sse transport.');
}
this.url = options.url;
const url = new URL(options.url);
this.logger?.info(`${this.getLogPrefix()} Creating SSE transport: ${url.toString()}`);
logger.info(`${this.getLogPrefix()} Creating SSE transport: ${url.toString()}`);
const abortController = new AbortController();
/** Add OAuth token to headers if available */
const headers = { ...options.headers };
if (this.oauthTokens?.access_token) {
headers['Authorization'] = `Bearer ${this.oauthTokens.access_token}`;
}
const transport = new SSEClientTransport(url, {
requestInit: {
headers: options.headers,
headers,
signal: abortController.signal,
},
eventSourceInit: {
fetch: (url, init) => {
const headers = new Headers(Object.assign({}, init?.headers, options.headers));
const fetchHeaders = new Headers(Object.assign({}, init?.headers, headers));
return fetch(url, {
...init,
headers,
headers: fetchHeaders,
});
},
},
});
transport.onclose = () => {
this.logger?.info(`${this.getLogPrefix()} SSE transport closed`);
logger.info(`${this.getLogPrefix()} SSE transport closed`);
this.emit('connectionChange', 'disconnected');
};
transport.onerror = (error) => {
this.logger?.error(`${this.getLogPrefix()} SSE transport error:`, error);
logger.error(`${this.getLogPrefix()} SSE transport error:`, error);
this.emitError(error, 'SSE transport error:');
};
transport.onmessage = (message) => {
this.logger?.info(
`${this.getLogPrefix()} Message received: ${JSON.stringify(message)}`,
);
logger.info(`${this.getLogPrefix()} Message received: ${JSON.stringify(message)}`);
};
this.setupTransportErrorHandlers(transport);
@ -216,33 +228,38 @@ export class MCPConnection extends EventEmitter {
if (!isStreamableHTTPOptions(options)) {
throw new Error('Invalid options for streamable-http transport.');
}
this.url = options.url;
const url = new URL(options.url);
this.logger?.info(
logger.info(
`${this.getLogPrefix()} Creating streamable-http transport: ${url.toString()}`,
);
const abortController = new AbortController();
// Add OAuth token to headers if available
const headers = { ...options.headers };
if (this.oauthTokens?.access_token) {
headers['Authorization'] = `Bearer ${this.oauthTokens.access_token}`;
}
const transport = new StreamableHTTPClientTransport(url, {
requestInit: {
headers: options.headers,
headers,
signal: abortController.signal,
},
});
transport.onclose = () => {
this.logger?.info(`${this.getLogPrefix()} Streamable-http transport closed`);
logger.info(`${this.getLogPrefix()} Streamable-http transport closed`);
this.emit('connectionChange', 'disconnected');
};
transport.onerror = (error: Error | unknown) => {
this.logger?.error(`${this.getLogPrefix()} Streamable-http transport error:`, error);
logger.error(`${this.getLogPrefix()} Streamable-http transport error:`, error);
this.emitError(error, 'Streamable-http transport error:');
};
transport.onmessage = (message: JSONRPCMessage) => {
this.logger?.info(
`${this.getLogPrefix()} Message received: ${JSON.stringify(message)}`,
);
logger.info(`${this.getLogPrefix()} Message received: ${JSON.stringify(message)}`);
};
this.setupTransportErrorHandlers(transport);
@ -271,17 +288,17 @@ export class MCPConnection extends EventEmitter {
/**
* // FOR DEBUGGING
* // this.client.setRequestHandler(PingRequestSchema, async (request, extra) => {
* // this.logger?.info(`[MCP][${this.serverName}] PingRequest: ${JSON.stringify(request)}`);
* // logger.info(`[MCP][${this.serverName}] PingRequest: ${JSON.stringify(request)}`);
* // if (getEventListeners && extra.signal) {
* // const listenerCount = getEventListeners(extra.signal, 'abort').length;
* // this.logger?.debug(`Signal has ${listenerCount} abort listeners`);
* // logger.debug(`Signal has ${listenerCount} abort listeners`);
* // }
* // return {};
* // });
*/
} else if (state === 'error' && !this.isReconnecting && !this.isInitializing) {
this.handleReconnection().catch((error) => {
this.logger?.error(`${this.getLogPrefix()} Reconnection handler failed:`, error);
logger.error(`${this.getLogPrefix()} Reconnection handler failed:`, error);
});
}
});
@ -290,7 +307,15 @@ export class MCPConnection extends EventEmitter {
}
private async handleReconnection(): Promise<void> {
if (this.isReconnecting || this.shouldStopReconnecting || this.isInitializing) {
if (
this.isReconnecting ||
this.shouldStopReconnecting ||
this.isInitializing ||
this.oauthRequired
) {
if (this.oauthRequired) {
logger.info(`${this.getLogPrefix()} OAuth required, skipping reconnection attempts`);
}
return;
}
@ -305,7 +330,7 @@ export class MCPConnection extends EventEmitter {
this.reconnectAttempts++;
const delay = backoffDelay(this.reconnectAttempts);
this.logger?.info(
logger.info(
`${this.getLogPrefix()} Reconnecting ${this.reconnectAttempts}/${this.MAX_RECONNECT_ATTEMPTS} (delay: ${delay}ms)`,
);
@ -316,13 +341,13 @@ export class MCPConnection extends EventEmitter {
this.reconnectAttempts = 0;
return;
} catch (error) {
this.logger?.error(`${this.getLogPrefix()} Reconnection attempt failed:`, error);
logger.error(`${this.getLogPrefix()} Reconnection attempt failed:`, error);
if (
this.reconnectAttempts === this.MAX_RECONNECT_ATTEMPTS ||
(this.shouldStopReconnecting as boolean)
) {
this.logger?.error(`${this.getLogPrefix()} Stopping reconnection attempts`);
logger.error(`${this.getLogPrefix()} Stopping reconnection attempts`);
return;
}
}
@ -366,18 +391,21 @@ export class MCPConnection extends EventEmitter {
await this.client.close();
this.transport = null;
} catch (error) {
this.logger?.warn(`${this.getLogPrefix()} Error closing connection:`, error);
logger.warn(`${this.getLogPrefix()} Error closing connection:`, error);
}
}
this.transport = this.constructTransport(this.options);
this.setupTransportDebugHandlers();
const connectTimeout = this.options.initTimeout ?? 10000;
const connectTimeout = this.options.initTimeout ?? 120000;
await Promise.race([
this.client.connect(this.transport),
new Promise((_resolve, reject) =>
setTimeout(() => reject(new Error('Connection timeout')), connectTimeout),
setTimeout(
() => reject(new Error(`Connection timeout after ${connectTimeout}ms`)),
connectTimeout,
),
),
]);
@ -385,9 +413,85 @@ export class MCPConnection extends EventEmitter {
this.emit('connectionChange', 'connected');
this.reconnectAttempts = 0;
} catch (error) {
// Check if it's an OAuth authentication error
if (this.isOAuthError(error)) {
logger.warn(`${this.getLogPrefix()} OAuth authentication required`);
this.oauthRequired = true;
const serverUrl = this.url;
logger.debug(`${this.getLogPrefix()} Server URL for OAuth: ${serverUrl}`);
const oauthTimeout = this.options.initTimeout ?? 60000;
/** Promise that will resolve when OAuth is handled */
const oauthHandledPromise = new Promise<void>((resolve, reject) => {
let timeoutId: NodeJS.Timeout | null = null;
let oauthHandledListener: (() => void) | null = null;
let oauthFailedListener: ((error: Error) => void) | null = null;
/** Cleanup function to remove listeners and clear timeout */
const cleanup = () => {
if (timeoutId) {
clearTimeout(timeoutId);
}
if (oauthHandledListener) {
this.off('oauthHandled', oauthHandledListener);
}
if (oauthFailedListener) {
this.off('oauthFailed', oauthFailedListener);
}
};
// Success handler
oauthHandledListener = () => {
cleanup();
resolve();
};
// Failure handler
oauthFailedListener = (error: Error) => {
cleanup();
reject(error);
};
// Timeout handler
timeoutId = setTimeout(() => {
cleanup();
reject(new Error(`OAuth handling timeout after ${oauthTimeout}ms`));
}, oauthTimeout);
// Listen for both success and failure events
this.once('oauthHandled', oauthHandledListener);
this.once('oauthFailed', oauthFailedListener);
});
// Emit the event
this.emit('oauthRequired', {
serverName: this.serverName,
error,
serverUrl,
userId: this.userId,
});
try {
// Wait for OAuth to be handled
await oauthHandledPromise;
// Reset the oauthRequired flag
this.oauthRequired = false;
// Don't throw the error - just return so connection can be retried
logger.info(
`${this.getLogPrefix()} OAuth handled successfully, connection will be retried`,
);
return;
} catch (oauthError) {
// OAuth failed or timed out
this.oauthRequired = false;
logger.error(`${this.getLogPrefix()} OAuth handling failed:`, oauthError);
// Re-throw the original authentication error
throw error;
}
}
this.connectionState = 'error';
this.emit('connectionChange', 'error');
this.lastError = error instanceof Error ? error : new Error(String(error));
throw error;
} finally {
this.connectPromise = null;
@ -403,7 +507,7 @@ export class MCPConnection extends EventEmitter {
}
this.transport.onmessage = (msg) => {
this.logger?.debug(`${this.getLogPrefix()} Transport received: ${JSON.stringify(msg)}`);
logger.debug(`${this.getLogPrefix()} Transport received: ${JSON.stringify(msg)}`);
};
const originalSend = this.transport.send.bind(this.transport);
@ -414,7 +518,7 @@ export class MCPConnection extends EventEmitter {
}
this.lastPingTime = Date.now();
}
this.logger?.debug(`${this.getLogPrefix()} Transport sending: ${JSON.stringify(msg)}`);
logger.debug(`${this.getLogPrefix()} Transport sending: ${JSON.stringify(msg)}`);
return originalSend(msg);
};
}
@ -427,14 +531,24 @@ export class MCPConnection extends EventEmitter {
throw new Error('Connection not established');
}
} catch (error) {
this.logger?.error(`${this.getLogPrefix()} Connection failed:`, error);
logger.error(`${this.getLogPrefix()} Connection failed:`, error);
throw error;
}
}
private setupTransportErrorHandlers(transport: Transport): void {
transport.onerror = (error) => {
this.logger?.error(`${this.getLogPrefix()} Transport error:`, error);
logger.error(`${this.getLogPrefix()} Transport error:`, error);
// Check if it's an OAuth authentication error
if (error && typeof error === 'object' && 'code' in error) {
const errorCode = (error as unknown as { code?: number }).code;
if (errorCode === 401 || errorCode === 403) {
logger.warn(`${this.getLogPrefix()} OAuth authentication error detected`);
this.emit('oauthError', error);
}
}
this.emit('connectionChange', 'error');
};
}
@ -562,22 +676,36 @@ export class MCPConnection extends EventEmitter {
// }
// }
// Public getters for state information
public getConnectionState(): t.ConnectionState {
return this.connectionState;
}
public async isConnected(): Promise<boolean> {
try {
await this.client.ping();
return this.connectionState === 'connected';
} catch (error) {
this.logger?.error(`${this.getLogPrefix()} Ping failed:`, error);
logger.error(`${this.getLogPrefix()} Ping failed:`, error);
return false;
}
}
public getLastError(): Error | null {
return this.lastError;
public setOAuthTokens(tokens: MCPOAuthTokens): void {
this.oauthTokens = tokens;
}
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;
}
}