Skip to content

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

19.4 KB
Raw Blame
import { nanoid } from 'nanoid';
import {
  ResourceType,
  PrincipalType,
  PermissionBits,
  normalizeServerName,
} from 'librechat-data-provider';
import type { Model, RootFilterQuery, Types } from 'mongoose';
import type { MCPOptions } from 'librechat-data-provider';
import type { MCPServerDocument } from '../types';
import { permissionBitSupersets } from './aclEntry';
import logger from '~/config/winston';

const NORMALIZED_LIMIT_DEFAULT = 20;
const MAX_CREATE_RETRIES = 5;
const RETRY_BASE_DELAY_MS = 25;

/**
 * Helper to check if an error is a MongoDB duplicate key error.
 * Both MCPServer unique indexes represent raw or normalized server-name collisions,
 * so retrying name allocation is safe for either E11000 source.
 */
function isDuplicateKeyError(error: unknown): boolean {
  if (error && typeof error === 'object' && 'code' in error) {
    const mongoError = error as { code: number };
    return mongoError.code === 11000;
  }
  return false;
}

/**
 * Escapes special regex characters in a string so they are treated literally.
 */
function escapeRegex(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

/**
 * Generates a URL-friendly server name from a title.
 * Converts to lowercase, replaces spaces with hyphens, removes special characters.
 */
function generateServerNameFromTitle(title: string): string {
  const slug = title
    .toLowerCase()
    .trim()
    .replace(/[^a-z0-9\s-]/g, '') // Remove special chars except spaces and hyphens
    .replace(/\s+/g, '-') // Replace spaces with hyphens
    .replace(/-+/g, '-') // Remove consecutive hyphens
    .replace(/^-|-$/g, ''); // Trim leading/trailing hyphens

  return slug || 'mcp-server'; // Fallback if empty
}

export interface MCPServerDeps {
  /** Returns resource IDs solely owned by the given user. From createAclEntryMethods. */
  getSoleOwnedResourceIds: (
    userObjectId: Types.ObjectId,
    resourceTypes: string | string[],
  ) => Promise<Types.ObjectId[]>;
}

/** An MCP server removed with its owner's account. */
export interface MCPServerViewerEntry {
  principalType: string;
  principalId?: string;
}

/** A view-ACL principal as stored or as already read by a caller. */
export interface MCPServerViewerPrincipal {
  principalType: string;
  principalId?: { toString(): string } | string | null;
}

const OBJECT_ID_PATTERN = /^[a-f\d]{24}$/i;

export interface ErasableMCPServer {
  id: string;
  serverName: string;
}

export function createMCPServerMethods(
  mongoose: typeof import('mongoose'),
  deps: MCPServerDeps,
): {
  createMCPServer: (data: {
    config: MCPOptions;
    author: string | Types.ObjectId;
    reservedServerNames?: Iterable<string>;
  }) => Promise<MCPServerDocument>;
  findMCPServerByServerName: (serverName: string) => Promise<MCPServerDocument | null>;
  findMCPServerByObjectId: (_id: string | Types.ObjectId) => Promise<MCPServerDocument | null>;
  getListMCPServersByIds: ({
    ids,
    otherParams,
    limit,
    after,
  }: {
    ids?: Types.ObjectId[];
    otherParams?: RootFilterQuery<MCPServerDocument>;
    limit?: number | null;
    after?: string | null;
  }) => Promise<{
    data: MCPServerDocument[];
    has_more: boolean;
    after: string | null;
  }>;
  getListMCPServersByNames: ({ names }: { names: string[] }) => Promise<{
    data: MCPServerDocument[];
  }>;
  updateMCPServer: (
    serverName: string,
    updateData: { config?: MCPOptions },
  ) => Promise<MCPServerDocument | null>;
  deleteMCPServer: (serverName: string) => Promise<MCPServerDocument | null>;
  findUserErasableMCPServers: (userId: string) => Promise<ErasableMCPServer[]>;
  deleteMCPServersWithAcl: (ids: string[]) => Promise<number>;
  findMCPServerOAuthTokenUserIds: (serverName: string, tenantId?: string) => Promise<string[]>;
  findMCPServerViewerEntries: (serverId: string) => Promise<MCPServerViewerEntry[]>;
  findMCPServerViewerUserIds: (entries: MCPServerViewerPrincipal[]) => Promise<string[]>;
} {
  /**
   * Finds the next available server name by checking DB and reserved-name collisions.
   * If baseName is taken or reserved, returns baseName-2, baseName-3, etc.
   */
  async function findNextAvailableServerName(
    baseName: string,
    reservedServerNames: Set<string> = new Set(),
  ): Promise<string> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;

    // Find all servers with matching base name pattern (baseName or baseName-N)
    const escapedBaseName = escapeRegex(baseName);
    const matchingNamePattern = new RegExp(`^${escapedBaseName}(-\\d+)?$`);
    const existing = await MCPServer.find({
      serverName: { $regex: matchingNamePattern },
    })
      .select('serverName')
      .lean<Array<{ serverName: string }>>();

    const existingNames = new Set([
      ...existing.map((server) => server.serverName),
      ...Array.from(reservedServerNames).filter((serverName) =>
        matchingNamePattern.test(serverName),
      ),
    ]);

    if (existingNames.size === 0) {
      return baseName;
    }

    // Extract numbers from existing names
    const numbers = Array.from(existingNames).map((serverName) => {
      const match = serverName.match(/-(\d+)$/);
      return match ? parseInt(match[1], 10) : 1;
    });

    const maxNumber = Math.max(...numbers);
    return `${baseName}-${maxNumber + 1}`;
  }

  /**
   * Create a new MCP server with retry logic for handling race conditions.
   * When multiple requests try to create servers with the same title simultaneously,
   * they may get the same serverName from findNextAvailableServerName() before any
   * creates the record (TOCTOU race condition). This is handled by retrying with
   * exponential backoff when a duplicate key error occurs.
   * @param data - Object containing config (with title, description, url, etc.) and author
   * @returns The created MCP server document
   */
  async function createMCPServer(data: {
    config: MCPOptions;
    author: string | Types.ObjectId;
    reservedServerNames?: Iterable<string>;
  }): Promise<MCPServerDocument> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    let lastError: unknown;
    const reservedServerNames = new Set(data.reservedServerNames ?? []);

    for (let attempt = 0; attempt < MAX_CREATE_RETRIES; attempt++) {
      try {
        // Generate serverName from title, with fallback to nanoid if no title
        // Important: regenerate on each attempt to get fresh available name
        let serverName: string;
        if (data.config.title) {
          const baseSlug = generateServerNameFromTitle(data.config.title);
          serverName = await findNextAvailableServerName(baseSlug, reservedServerNames);
        } else {
          serverName = `mcp-${nanoid(16)}`;
        }

        const newServer = await MCPServer.create({
          serverName,
          normalizedServerName: normalizeServerName(serverName),
          config: data.config,
          author: data.author,
        });

        return newServer.toObject() as MCPServerDocument;
      } catch (error) {
        lastError = error;

        // Only retry on duplicate key errors (serverName collision)
        if (isDuplicateKeyError(error) && attempt < MAX_CREATE_RETRIES - 1) {
          // Exponential backoff: 10ms, 20ms, 40ms
          const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
          logger.debug(
            `[createMCPServer] Duplicate serverName detected, retrying (attempt ${attempt + 2}/${MAX_CREATE_RETRIES}) after ${delay}ms`,
          );
          await new Promise((resolve) => setTimeout(resolve, delay));
          continue;
        }

        // Not a duplicate key error or out of retries - throw immediately
        throw error;
      }
    }

    // Should not reach here, but TypeScript requires a return
    throw lastError;
  }

  /**
   * Find an MCP server by serverName
   * @param serverName - The unique server name identifier
   * @returns The MCP server document or null
   */
  async function findMCPServerByServerName(serverName: string): Promise<MCPServerDocument | null> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    return await MCPServer.findOne({ serverName }).lean<MCPServerDocument>();
  }

  /**
   * Find an MCP server by MongoDB ObjectId
   * @param _id - The MongoDB ObjectId
   * @returns The MCP server document or null
   */
  async function findMCPServerByObjectId(
    _id: string | Types.ObjectId,
  ): Promise<MCPServerDocument | null> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    return await MCPServer.findById(_id).lean<MCPServerDocument>();
  }

  /**
   * Get a paginated list of MCP servers by IDs with filtering and search
   * @param ids - Array of ObjectIds to include
   * @param otherParams - Additional filter parameters (e.g., search)
   * @param limit - Page size limit (null for no pagination)
   * @param after - Cursor for pagination
   * @returns Paginated list of MCP servers
   */
  async function getListMCPServersByIds({
    ids = [],
    otherParams = {},
    limit = null,
    after = null,
  }: {
    ids?: Types.ObjectId[];
    otherParams?: RootFilterQuery<MCPServerDocument>;
    limit?: number | null;
    after?: string | null;
  }): Promise<{
    data: MCPServerDocument[];
    has_more: boolean;
    after: string | null;
  }> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    const isPaginated = limit !== null && limit !== undefined;
    const normalizedLimit = isPaginated
      ? Math.min(Math.max(1, parseInt(String(limit)) || NORMALIZED_LIMIT_DEFAULT), 100)
      : null;

    // Build base query combining accessible servers with other filters
    const baseQuery: RootFilterQuery<MCPServerDocument> = { ...otherParams, _id: { $in: ids } };

    // Add cursor condition
    if (after) {
      try {
        const cursor = JSON.parse(Buffer.from(after, 'base64').toString('utf8'));
        const { updatedAt, _id } = cursor;

        const cursorCondition = {
          $or: [
            { updatedAt: { $lt: new Date(updatedAt) } },
            { updatedAt: new Date(updatedAt), _id: { $gt: new mongoose.Types.ObjectId(_id) } },
          ],
        };

        // Merge cursor condition with base query
        if (Object.keys(baseQuery).length > 0) {
          baseQuery.$and = [{ ...baseQuery }, cursorCondition];
          // Remove the original conditions from baseQuery to avoid duplication
          Object.keys(baseQuery).forEach((key) => {
            if (key !== '$and') {
              delete baseQuery[key];
            }
          });
        }
      } catch (error) {
        // Invalid cursor, ignore
        logger.warn('[getListMCPServersByIds] Invalid cursor provided', error);
      }
    }

    if (normalizedLimit === null) {
      // No pagination - return all matching servers
      const servers = await MCPServer.find(baseQuery)
        .sort({ updatedAt: -1, _id: 1 })
        .lean<MCPServerDocument[]>();

      return {
        data: servers,
        has_more: false,
        after: null,
      };
    }

    // Paginated query - assign to const to help TypeScript
    const servers = await MCPServer.find(baseQuery)
      .sort({ updatedAt: -1, _id: 1 })
      .limit(normalizedLimit + 1)
      .lean<MCPServerDocument[]>();

    const hasMore = servers.length > normalizedLimit;
    const data = hasMore ? servers.slice(0, normalizedLimit) : servers;

    let nextCursor = null;
    if (hasMore && data.length > 0) {
      const lastItem = data[data.length - 1];
      nextCursor = Buffer.from(
        JSON.stringify({
          updatedAt: lastItem.updatedAt,
          _id: lastItem._id,
        }),
      ).toString('base64');
    }

    return {
      data,
      has_more: hasMore,
      after: nextCursor,
    };
  }

  /**
   * Update an MCP server
   * @param serverName - The MCP server ID
   * @param updateData - Object containing config to update
   * @returns The updated MCP server document or null
   */
  async function updateMCPServer(
    serverName: string,
    updateData: { config?: MCPOptions },
  ): Promise<MCPServerDocument | null> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    return await MCPServer.findOneAndUpdate(
      { serverName },
      { $set: updateData },
      { new: true, runValidators: true },
    ).lean<MCPServerDocument>();
  }

  /**
   * Delete an MCP server
   * @param serverName - The MCP server ID
   * @returns The deleted MCP server document or null
   */
  async function deleteMCPServer(serverName: string): Promise<MCPServerDocument | null> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    return await MCPServer.findOneAndDelete({ serverName }).lean<MCPServerDocument>();
  }

  /**
   * Get MCP servers by their serverName strings
   * @param names - Array of serverName strings to fetch
   * @returns Object containing array of MCP server documents
   */
  async function getListMCPServersByNames({ names = [] }: { names: string[] }): Promise<{
    data: MCPServerDocument[];
  }> {
    if (names.length === 0) {
      return { data: [] };
    }
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    const servers = await MCPServer.find({ serverName: { $in: names } }).lean<
      MCPServerDocument[]
    >();
    return { data: servers };
  }

  /**
   * Account erasure: servers solely owned by the user, plus legacy (pre-ACL) servers that only
   * carry the author field. Servers shared with another owner are not returned.
   */
  async function findUserErasableMCPServers(userId: string): Promise<ErasableMCPServer[]> {
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument> | undefined;
    const AclEntry = mongoose.models.AclEntry;
    if (!MCPServer || !AclEntry) {
      return [];
    }

    const userObjectId = new mongoose.Types.ObjectId(userId);
    const soleOwnedIds = await deps.getSoleOwnedResourceIds(userObjectId, ResourceType.MCPSERVER);
    const authoredServers = await MCPServer.find({ author: userObjectId })
      .select('_id serverName')
      .lean<Array<{ _id: Types.ObjectId; serverName: string }>>();
    const migratedEntries =
      authoredServers.length > 0
        ? await AclEntry.find({
            resourceType: ResourceType.MCPSERVER,
            resourceId: { $in: authoredServers.map((s) => s._id) },
          })
            .select('resourceId')
            .lean<Array<{ resourceId: Types.ObjectId }>>()
        : [];
    const migratedIds = new Set(migratedEntries.map((e) => e.resourceId.toString()));
    const legacyServers = authoredServers.filter((s) => !migratedIds.has(s._id.toString()));
    const aclOwnedServers =
      soleOwnedIds.length > 0
        ? await MCPServer.find({ _id: { $in: soleOwnedIds } })
            .select('_id serverName')
            .lean<Array<{ _id: Types.ObjectId; serverName: string }>>()
        : [];
    const found = new Set(aclOwnedServers.map((s) => s._id.toString()));
    /** Sole-owned ids whose server is already gone keep an empty name so the ACLs still get cleaned. */
    const residual = soleOwnedIds
      .filter((id) => !found.has(id.toString()))
      .map((id) => ({ id: id.toString(), serverName: '' }));
    return [
      ...[...aclOwnedServers, ...legacyServers].map((s) => ({
        id: s._id.toString(),
        serverName: s.serverName,
      })),
      ...residual,
    ];
  }

  /** Users holding an OAuth credential record for the server, used to fence them on removal. */
  async function findMCPServerOAuthTokenUserIds(
    serverName: string,
    tenantId?: string,
  ): Promise<string[]> {
    const Token = mongoose.models.Token;
    if (!Token) {
      return [];
    }
    const identifier = `mcp:${serverName}`;
    /** Server names are unique per tenant, so a tenantless owner only matches tenantless tokens. */
    const userIds = await Token.distinct('userId', {
      tenantId: tenantId ?? null,
      identifier: { $in: [identifier, `${identifier}:client`, `${identifier}:refresh`] },
    });
    return userIds.map(String);
  }

  /** Principals holding view access on the server, used to find users it was shared with. */
  async function findMCPServerViewerEntries(serverId: string): Promise<MCPServerViewerEntry[]> {
    const entries = await mongoose.models.AclEntry.find({
      resourceType: ResourceType.MCPSERVER,
      resourceId: new mongoose.Types.ObjectId(serverId),
      permBits: { $in: permissionBitSupersets(PermissionBits.VIEW) },
    })
      .select('principalType principalId')
      .lean<Array<{ principalType: string; principalId?: Types.ObjectId | string }>>();
    return entries.map((entry) => ({
      principalType: entry.principalType,
      principalId: entry.principalId?.toString(),
    }));
  }

  /**
   * Users a server's view ACL names directly or through a group, so its removal can fence viewers
   * who hold no OAuth credential. Role and public principals are not enumerated.
   */
  async function findMCPServerViewerUserIds(
    entries: MCPServerViewerPrincipal[],
  ): Promise<string[]> {
    const userIds = new Set<string>();
    const groupIds = new Set<string>();
    for (const entry of entries) {
      const principalId = entry.principalId?.toString();
      if (!principalId) {
        continue;
      }
      if (entry.principalType === PrincipalType.USER) {
        userIds.add(principalId);
      } else if (
        entry.principalType === PrincipalType.GROUP &&
        OBJECT_ID_PATTERN.test(principalId)
      ) {
        groupIds.add(principalId);
      }
    }
    if (groupIds.size === 0) {
      return [...userIds];
    }
    const groups = await mongoose.models.Group.find({
      _id: { $in: [...groupIds].map((id) => new mongoose.Types.ObjectId(id)) },
    })
      .select('memberIds')
      .lean<Array<{ memberIds?: string[] }>>();
    /** `memberIds` holds `idOnTheSource` for external users and the user id otherwise. */
    const memberIds = [...new Set(groups.flatMap((group) => group.memberIds ?? []))];
    if (memberIds.length === 0) {
      return [...userIds];
    }
    const objectIds = memberIds
      .filter((id) => OBJECT_ID_PATTERN.test(id))
      .map((id) => new mongoose.Types.ObjectId(id));
    const members = await mongoose.models.User.find({
      $or: [
        { idOnTheSource: { $in: memberIds } },
        ...(objectIds.length > 0 ? [{ _id: { $in: objectIds } }] : []),
      ],
    })
      .select('_id')
      .lean<Array<{ _id: Types.ObjectId }>>();
    for (const member of members) {
      userIds.add(member._id.toString());
    }
    return [...userIds];
  }

  /** Deletes MCP servers by id together with every ACL entry on them. */
  async function deleteMCPServersWithAcl(ids: string[]): Promise<number> {
    if (ids.length === 0) {
      return 0;
    }
    const MCPServer = mongoose.models.MCPServer as Model<MCPServerDocument>;
    const objectIds = ids.map((id) => new mongoose.Types.ObjectId(id));
    const result = await MCPServer.deleteMany({ _id: { $in: objectIds } });
    /** ACL entries are the retry discovery key for sole-owned servers, so they go last. */
    await mongoose.models.AclEntry.deleteMany({
      resourceType: ResourceType.MCPSERVER,
      resourceId: { $in: objectIds },
    });
    return result.deletedCount ?? 0;
  }

  return {
    findUserErasableMCPServers,
    deleteMCPServersWithAcl,
    findMCPServerOAuthTokenUserIds,
    findMCPServerViewerEntries,
    findMCPServerViewerUserIds,
    createMCPServer,
    findMCPServerByServerName,
    findMCPServerByObjectId,
    getListMCPServersByIds,
    getListMCPServersByNames,
    updateMCPServer,
    deleteMCPServer,
  };
}

export type MCPServerMethods = ReturnType<typeof createMCPServerMethods>;