🥫 fix: Normalize Legacy MCP Header Maps on Cached Reads (#16200)

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-22 07:46:17 -04:00 • committed by GitHub
parent 07e91ccdec
commit f192308f4c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 138 additions and 24 deletions

View file

@ -10,6 +10,7 @@ import {
CONFIG_CACHE_NAMESPACE,
} from './cache/ServerConfigsCacheFactory';
import { MCPInspectionFailedError, isMCPDomainNotAllowedError } from '~/mcp/errors';
import { normalizeLegacyHeaderMaps, normalizeLegacyHeaderMapsIn } from './compat';
import { canBackfillSharedServerInstructions, isUserSourced } from '~/mcp/utils';
import { ReadThroughAllCache } from './cache/ReadThroughAllCache';
import { isPluginSourced, MCP_PLUGIN_SOURCE } from '~/utils/env';
@ -29,11 +30,19 @@ export class MCPConfigInitializationCanceledError extends Error {}
/** Cached configs carry decrypted oauth/apiKey credentials, so the shared
* stores only ever see ciphertext; plaintext stays in process memory,
* exactly where it lived before these caches became shared. */
function encryptedStoreTransforms<T>(): ReadThroughTransforms<T> {
* exactly where it lived before these caches became shared.
*
* Decoding also normalizes legacy header maps, because a replica running older
* code fills these stores from its own database reads: without it, a rolling
* deployment would keep serving a config the runtime schemas reject, from a
* cache hit that never reaches the repository's own normalization. */
function serverMapStoreTransforms(): ReadThroughTransforms<Record<string, t.ParsedServerConfig>> {
return {
encode: async (value) => encryptV2(JSON.stringify(value)),
decode: async (raw) => JSON.parse(await decryptV2(raw)),
decode: async (raw) =>
normalizeLegacyHeaderMapsIn(
JSON.parse(await decryptV2(raw)) as Record<string, t.ParsedServerConfig>,
),
};
}
@ -46,7 +55,7 @@ function perServerStoreTransforms(): ReadThroughTransforms<t.ParsedServerConfig
const decoded = JSON.parse(await decryptV2(raw)) as {
config: t.ParsedServerConfig | null;
};
return decoded.config ?? undefined;
return decoded.config == null ? undefined : normalizeLegacyHeaderMaps(decoded.config);
},
};
}
@ -284,7 +293,7 @@ export class MCPServersRegistry {
this.readThroughCacheAll = new ReadThroughAllCache<Record<string, t.ParsedServerConfig>>(
'mcp-registry-read-through-all',
ttl,
encryptedStoreTransforms<Record<string, t.ParsedServerConfig>>(),
serverMapStoreTransforms(),
);
}

View file

@ -7,6 +7,7 @@ import {
MCPConfigInitializationCanceledError,
} from '~/mcp/registry/MCPServersRegistry';
import { ServerConfigsCacheInMemory } from '~/mcp/registry/cache/ServerConfigsCacheInMemory';
import { getMCPAppToolsPublicationGeneration } from '~/mcp/toolsChanged';
import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';
import { MCPInspectionFailedError } from '~/mcp/errors';
import { processMCPEnv } from '~/utils/env';
@ -1549,6 +1550,77 @@ describe('MCPServersRegistry', () => {
expect(cacheRepoGetAllSpy).toHaveBeenCalledTimes(3);
});
});
/** A replica running older code fills these stores from its own DB reads, so a
* cache hit has to carry the same normalization the repository applies. */
describe('configs stored by an older replica', () => {
const storedByOlderReplica = {
type: 'streamable-http',
url: 'https://example.com/mcp',
source: 'user',
dbId: 'db-legacy-1',
requiresOAuth: true,
headers: null,
requestHeaders: null,
} as unknown as t.ParsedServerConfig;
it('normalizes null header maps served from a per-server cache hit', async () => {
const dbGet = jest
.spyOn(registry['dbConfigsRepo'], 'get')
.mockResolvedValue(storedByOlderReplica);
await registry.getServerConfig('legacy_server', 'user-1');
expect(dbGet).toHaveBeenCalledTimes(1);
const cached = await registry.getServerConfig('legacy_server', 'user-1');
expect(dbGet).toHaveBeenCalledTimes(1);
expect(cached).toMatchObject({ dbId: 'db-legacy-1', source: 'user' });
expect(cached).not.toHaveProperty('headers');
expect(cached).not.toHaveProperty('requestHeaders');
expect(() => getMCPAppToolsPublicationGeneration(cached!)).not.toThrow();
});
it('normalizes null header maps served from an all-servers cache hit', async () => {
const dbGetAll = jest
.spyOn(registry['dbConfigsRepo'], 'getAll')
.mockResolvedValue({ legacy_server: storedByOlderReplica });
await registry.getAllServerConfigs('user-1');
expect(dbGetAll).toHaveBeenCalledTimes(1);
/** Drop this replica's process memo only; the shared entry stays as the
* older replica encoded it, which is what another pod would read. */
registry['readThroughCacheAll']['memo'].clear();
const cached = (await registry.getAllServerConfigs('user-1')).legacy_server;
expect(dbGetAll).toHaveBeenCalledTimes(1);
expect(cached).toMatchObject({ dbId: 'db-legacy-1', source: 'user' });
expect(cached).not.toHaveProperty('headers');
expect(cached).not.toHaveProperty('requestHeaders');
expect(() => getMCPAppToolsPublicationGeneration(cached)).not.toThrow();
});
it('preserves populated header maps across both cache hits', async () => {
const headers = { 'X-Shared': 'value' };
const requestHeaders = { 'X-Request': 'value' };
const config = { ...storedByOlderReplica, headers, requestHeaders };
jest.spyOn(registry['dbConfigsRepo'], 'get').mockResolvedValue(config);
jest
.spyOn(registry['dbConfigsRepo'], 'getAll')
.mockResolvedValue({ header_server: config });
await registry.getServerConfig('header_server', 'user-1');
await registry.getAllServerConfigs('user-1');
registry['readThroughCacheAll']['memo'].clear();
const single = await registry.getServerConfig('header_server', 'user-1');
const all = (await registry.getAllServerConfigs('user-1')).header_server;
for (const cached of [single, all]) {
expect(cached).toMatchObject({ headers, requestHeaders });
expect(() => getMCPAppToolsPublicationGeneration(cached!)).not.toThrow();
}
});
});
});
describe('admin-panel overrides for YAML-defined servers', () => {

View file

@ -0,0 +1,50 @@
import type { ParsedServerConfig } from '~/mcp/types';
/** Optional header maps a stored config may carry as an explicit null. */
type LegacyHeaderMaps = {
headers?: Record<string, string> | null;
requestHeaders?: Record<string, string> | null;
};
/**
* Drops `headers` and `requestHeaders` stored as null by a writer that
* serialized an absent map: BSON materializes an explicit undefined property as
* null, and both fields are optional objects in the MCP transport schemas, so a
* stored null fails the runtime validation every connection and catalog
* generation depends on.
*
* Every store a config is read back from is a compatibility boundary, because a
* replica running older code can write into it while this replica reads. The
* same value is returned when there is nothing to normalize, so the hot path
* allocates nothing.
*/
export function normalizeLegacyHeaderMaps(config: ParsedServerConfig): ParsedServerConfig {
const persistedConfig = config as ParsedServerConfig & LegacyHeaderMaps;
if (persistedConfig.headers !== null && persistedConfig.requestHeaders !== null) {
return config;
}
const { headers, requestHeaders, ...rest } = persistedConfig;
return {
...rest,
...(headers != null && { headers }),
...(requestHeaders != null && { requestHeaders }),
} as ParsedServerConfig;
}
/** The same normalization across a stored server map, reusing the input map when every entry is current. */
export function normalizeLegacyHeaderMapsIn<T extends Record<string, ParsedServerConfig>>(
configs: T,
): T {
let normalized: Record<string, ParsedServerConfig> | undefined;
for (const serverName of Object.keys(configs)) {
const config = configs[serverName];
const normalizedConfig = normalizeLegacyHeaderMaps(config);
if (normalizedConfig === config) {
continue;
}
normalized ??= { ...configs };
normalized[serverName] = normalizedConfig;
}
return (normalized as T) ?? configs;
}

View file

@ -11,6 +11,7 @@ import type { IServerConfigsRepositoryInterface } from '~/mcp/registry/ServerCon
import type { ParsedServerConfig, AddServerResult } from '~/mcp/types';
import type { ResolvedPrincipal } from '~/types/principal';
import { requireApiKeyReentryForRebinding } from '~/mcp/registry/binding';
import { normalizeLegacyHeaderMaps } from '~/mcp/registry/compat';
import { MCPOAuthSecretReentryRequiredError } from '~/mcp/errors';
import { AccessControlService } from '~/acl/accessControlService';
@ -118,24 +119,6 @@ function sanitizeUserManagedOAuthConfig(config: ParsedServerConfig): ParsedServe
};
}
/** Normalizes legacy values that predate the current runtime config schemas. */
function normalizePersistedConfig(config: ParsedServerConfig): ParsedServerConfig {
const persistedConfig = config as ParsedServerConfig & {
headers?: Record<string, string> | null;
requestHeaders?: Record<string, string> | null;
};
if (persistedConfig.headers !== null && persistedConfig.requestHeaders !== null) {
return config;
}
const { headers, requestHeaders, ...rest } = persistedConfig;
return {
...rest,
...(headers != null && { headers }),
...(requestHeaders != null && { requestHeaders }),
} as ParsedServerConfig;
}
function normalizeOAuthUrl(value?: string): string | undefined {
if (!value) {
return value;
@ -663,7 +646,7 @@ export class ServerConfigsDB implements IServerConfigsRepositoryInterface {
...(authorId ? { author: authorId } : {}),
};
return sanitizeUserManagedOAuthConfig(
await this.decryptConfig(normalizePersistedConfig(config)),
await this.decryptConfig(normalizeLegacyHeaderMaps(config)),
);
}