* 🔧 refactor: Simplify MCP selection logic in useMCPSelect hook
- Removed redundant useEffect for setting ephemeral agent when MCP values change.
- Integrated ephemeral agent update directly into the MCP value change handler, improving code clarity and reducing unnecessary re-renders.
- Updated dependencies in the effect hook to ensure proper state management.
Why Effect 2 Was Added (PR #9528)
PR #9528 was a refactor that migrated MCP state from useLocalStorage hooks to Jotai atomWithStorage. Before that PR, useLocalStorage
handled bidirectional sync between localStorage and Recoil in one abstraction. After the migration, the two useEffect hooks were
introduced to bridge Jotai ↔ Recoil:
- Effect 1 (Recoil → Jotai): When ephemeralAgent.mcp changes externally, update the Jotai atom (which drives the UI dropdown)
- Effect 2 (Jotai → Recoil): When mcpValues changes, push it back to ephemeralAgent.mcp (which is read at submission time)
Effect 2 was needed because in that PR's design, setMCPValues only wrote to Jotai — it never touched Recoil. Effect 2 was the bridge to
propagate user selections into the ephemeral agent.
Why Removing It Is Correct
All user-initiated MCP changes go through setMCPValues. The callers are in useMCPServerManager: toggleServerSelection,
batchToggleServers, OAuth success callbacks, and access revocation. Our change puts the Recoil write directly in that callback, so all
these paths are covered.
All external changes go through Recoil, handled by Effect 1 (kept). Model spec application (applyModelSpecEphemeralAgent), agent
template application after submission, and BadgeRowContext initialization all write directly to ephemeralAgentByConvoId. Effect 1
watches ephemeralAgent?.mcp and syncs those into the Jotai atom for the UI.
There is no code path where mcpValues changes without going through setMCPValues or Effect 1. The only other source is
atomWithStorage's getOnInit reading from localStorage on mount — that's just restoring persisted state and is harmless (overwritten by
Effect 1 if the ephemeral agent has values).
Additional Benefits
- Eliminates the race condition. Effect 2 fired on mount with Jotai's stale default ([]), overwriting ephemeralAgent.mcp that had been
set by a model spec. Our change prevents that because the imperative sync only fires on explicit user action.
- Eliminates infinite loop risk. The old bidirectional two-effect approach relied on isEqual/JSON.stringify checks to break cycles. The
new unidirectional-reactive (Effect 1) + imperative (setMCPValues) approach has no such risk.
- Effect 1's enhancements are preserved. The mcp_clear sentinel handling and configuredServers filtering (both added after PR #9528)
continue to work correctly.
* ✨ feat: Add artifacts support to model specifications and ephemeral agents
- Introduced `artifacts` property in the model specification and ephemeral agent types, allowing for string or boolean values.
- Updated `applyModelSpecEphemeralAgent` to handle artifacts, defaulting to 'default' if true or an empty string if not specified.
- Enhanced localStorage handling to store artifacts alongside other agent properties, improving state management for ephemeral agents.
* 🔧 refactor: Update BadgeRowContext to improve localStorage handling
- Modified the logic to only apply values from localStorage that were actually stored, preventing unnecessary overrides of the ephemeral agent.
- Simplified the setting of ephemeral agent values by directly using initialValues, enhancing code clarity and maintainability.
* 🔧 refactor: Enhance ephemeral agent handling in BadgeRowContext and model spec application
- Updated BadgeRowContext to apply localStorage values only for tools not already set in ephemeralAgent, improving state management.
- Modified useApplyModelSpecEffects to reset the ephemeral agent when no spec is provided but specs are configured, ensuring localStorage defaults are applied correctly.
- Streamlined the logic for applying model spec properties, enhancing clarity and maintainability.
* refactor: Isolate spec and non-spec tool/MCP state with environment-keyed storage
Spec tool state (badges, MCP) and non-spec user preferences previously shared
conversation-keyed localStorage, causing cross-pollination when switching between
spec and non-spec models. This introduces environment-keyed storage so each
context maintains independent persisted state.
Key changes:
- Spec active: no localStorage persistence — admin config always applied fresh
- Non-spec (with specs configured): tool/MCP state persisted to __defaults__ key
- No specs configured: zero behavior change (conversation-keyed storage)
- Per-conversation isolation preserved for existing conversations
- Dual-write on user interaction updates both conversation and environment keys
- Remove mcp_clear sentinel in favor of null ephemeral agent reset
* refactor: Enhance ephemeral agent initialization and MCP handling in BadgeRowContext and useMCPSelect
- Updated BadgeRowContext to clarify the handling of localStorage values for ephemeral agents, ensuring proper initialization based on conversation state.
- Improved useMCPSelect tests to accurately reflect behavior when setting empty MCP values, ensuring the visual selection clears as expected.
- Introduced environment-keyed storage logic to maintain independent state for spec and non-spec contexts, enhancing user experience during context switching.
* test: Add comprehensive tests for useToolToggle and applyModelSpecEphemeralAgent hooks
- Introduced unit tests for the useToolToggle hook, covering dual-write behavior in non-spec mode and per-conversation isolation.
- Added tests for applyModelSpecEphemeralAgent, ensuring correct application of model specifications and user overrides from localStorage.
- Enhanced test coverage for ephemeral agent state management during conversation transitions, validating expected behaviors for both new and existing conversations.
* feat: add groupIcon property to modelSpecs for custom group icons
Added the ability to define icons for custom model spec groups in the UI selector.
Changes:
- Added property to TModelSpec type and schema in data-provider
- Created GroupIcon component to render URL or built-in endpoint icons
- Updated CustomGroup component to display group icons
- Added documentation and examples in librechat.example.yaml
Usage:
The groupIcon can be:
- A built-in endpoint key (e.g., "openAI", "anthropic", "groq")
- A URL to a custom icon image
Only the first spec in a group needs groupIcon - all specs share the same icon.
* fix: address Copilot review comments for GroupIcon component
- Changed URL detection from includes('http') to checking if iconURL exists in icons map (more robust approach)
- Removed redundant !iconURL check since iconURL is always a string from props
---------
Co-authored-by: odrec <odrec@users.noreply.github.com>
Co-authored-by: Odrec <odrec@Odrecs-MacBook-Pro.local>
* refactor: remove `useChatContext` from `useSelectMention`, explicitly pass `conversation` object
* feat: ephemeral agents via model specs
* refactor: Sync Jotai state with ephemeral agent state, also when Ephemeral Agent has no MCP servers selected
* refactor: move `useUpdateEphemeralAgent` to store and clean up imports
* refactor: reorder imports and invalidate queries for mcpConnectionStatus in event handler
* refactor: replace useApplyModelSpecEffects with useApplyModelSpecAgents and update event handlers to use new agent template logic
* ci: update useMCPSelect test to verify mcpValues sync with empty ephemeralAgent.mcp
* feat: Add group field to modelSpecs for flexible grouping
* resolve lint issues
* fix test
* docs: enhance modelSpecs group field documentation for clarity
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* 🔧 refactor: Remove modelSpecs prop from ModelSelector and related components
* fix: Update submission.conversationId references in SSE hooks and data types as was incorrectly typed
* feat: Allow showing specific endpoints alongside model specs via `addedEndpoints` field
* feat: allowed agents providers via `agents.allowedProviders` field
* fix: bump dicebear/sharp dependencies to resolve CVE-2024-12905 and improve avatar gen logic
* fix: rename variable for clarity in loadDefaultInterface function
* fix: add keepAddedConvos option to newConversation calls for modular chat support
* fix: include model information in endpoint selection for improved context
* fix: update data-provider version to 0.7.78 and increment config version to 1.2.4
* 🐛 fix: default modelSpecs not being set
* feat: Add imageDetail parameter for OpenAI endpoints in tQueryParamsSchema
* feat: Implement processModelSpecs function to enhance model specs processing from configuration
* feat: Refactor configuration schemas and types for improved structure and clarity
* feat: Add append_current_datetime parameter to tQueryParamsSchema for enhanced endpoint functionality
* fix: Add endpointType to getSaveOptions and enhance endpoint handling in Settings component
* fix: Change endpointType to be nullable and optional in tConversationSchema for improved flexibility
* fix: allow save & submit for google endpoint
* WIP: first pass ModelSpecs
* refactor(onSelectEndpoint): use `getConvoSwitchLogic`
* feat: introduce iconURL, greeting, frontend fields for conversations/presets/messages
* feat: conversation.iconURL & greeting in Landing
* feat: conversation.iconURL & greeting in New Chat button
* feat: message.iconURL
* refactor: ConversationIcon -> ConvoIconURL
* WIP: add spec as a conversation field
* refactor: useAppStartup, set spec on initial load for new chat, allow undefined spec, add localStorage keys enum, additional type fields for spec
* feat: handle `showIconInMenu`, `showIconInHeader`, undefined `iconURL` and no specs on initial load
* chore: handle undefined or empty modelSpecs
* WIP: first pass, modelSpec schema for custom config
* refactor: move default filtered tools definition to ToolService
* feat: pass modelSpecs from backend via startupConfig
* refactor: modelSpecs config, return and define list
* fix: react error and include iconURL in responseMessage
* refactor: add iconURL to responseMessage only
* refactor: getIconEndpoint
* refactor: pass TSpecsConfig
* fix(assistants): differentiate compactAssistantSchema, correctly resets shared conversation state with other endpoints
* refactor: assistant id prefix localStorage key
* refactor: add more LocalStorageKeys and replace hardcoded values
* feat: prioritize spec on new chat behavior: last selected modelSpec behavior (localStorage)
* feat: first pass, interface config
* chore: WIP, todo: add warnings based on config.modelSpecs settings.
* feat: enforce modelSpecs if configured
* feat: show config file yaml errors
* chore: delete unused legacy Plugins component
* refactor: set tools to localStorage from recoil store
* chore: add stable recoil setter to useEffect deps
* refactor: save tools to conversation documents
* style(MultiSelectPop): dynamic height, remove unused import
* refactor(react-query): use localstorage keys and pass config to useAvailablePluginsQuery
* feat(utils): add mapPlugins
* refactor(Convo): use conversation.tools if defined, lastSelectedTools if not
* refactor: remove unused legacy code using `useSetOptions`, remove conditional flag `isMultiChat` for using legacy settings
* refactor(PluginStoreDialog): add exhaustive-deps which are stable react state setters
* fix(HeaderOptions): pass `popover` as true
* refactor(useSetStorage): use project enums
* refactor: use LocalStorageKeys enum
* fix: prevent setConversation from setting falsy values in lastSelectedTools
* refactor: use map for availableTools state and available Plugins query
* refactor(updateLastSelectedModel): organize logic better and add note on purpose
* fix(setAgentOption): prevent reseting last model to secondary model for gptPlugins
* refactor(buildDefaultConvo): use enum
* refactor: remove `useSetStorage` and consolidate areas where conversation state is saved to localStorage
* fix: conversations retain tools on refresh
* fix(gptPlugins): prevent nullish tools from being saved
* chore: delete useServerStream
* refactor: move initial plugins logic to useAppStartup
* refactor(MultiSelectDropDown): add more pass-in className props
* feat: use tools in presets
* chore: delete unused usePresetOptions
* refactor: new agentOptions default handling
* chore: note
* feat: add label and custom instructions to agents
* chore: remove 'disabled with tools' message
* style: move plugins to 2nd column in parameters
* fix: TPreset type for agentOptions
* fix: interface controls
* refactor: add interfaceConfig, use Separator within Switcher
* refactor: hide Assistants panel if interface.parameters are disabled
* fix(Header): only modelSpecs if list is greater than 0
* refactor: separate MessageIcon logic from useMessageHelpers for better react rule-following
* fix(AppService): don't use reserved keyword 'interface'
* feat: set existing Icon for custom endpoints through iconURL
* fix(ci): tests passing for App Service
* docs: refactor custom_config.md for readability and better organization, also include missing values
* docs: interface section and re-organize docs
* docs: update modelSpecs info
* chore: remove unused files
* chore: remove unused files
* chore: move useSetIndexOptions
* chore: remove unused file
* chore: move useConversation(s)
* chore: move useDefaultConvo
* chore: move useNavigateToConvo
* refactor: use plugin install hook so it can be used elsewhere
* chore: import order
* update docs
* refactor(OpenAI/Plugins): allow modelLabel as an initial value for chatGptLabel
* chore: remove unused EndpointOptionsPopover and hide 'Save as Preset' button if preset UI visibility disabled
* feat(loadDefaultInterface): issue warnings based on values
* feat: changelog for custom config file
* docs: add additional changelog note
* fix: prevent unavailable tool selection from preset and update availableTools on Plugin installations
* feat: add `filteredTools` option in custom config
* chore: changelog
* fix(MessageIcon): always overwrite conversation.iconURL in messageSettings
* fix(ModelSpecsMenu): icon edge cases
* fix(NewChat): dynamic icon
* fix(PluginsClient): always include endpoint in responseMessage
* fix: always include endpoint and iconURL in responseMessage across different response methods
* feat: interchangeable keys for modelSpec enforcing
