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

🧩 fix: `additionalProperties` Handling and Ref Resolution in Zod Schemas (#8381)

Danny Avila4bbdc4c402c3
diff --git a/api/server/services/MCP.js b/api/server/services/MCP.js
index 527fe2d514..a058117fbb 100644
--- a/api/server/services/MCP.js
+++ b/api/server/services/MCP.js
@@ -2,16 +2,17 @@ const { z } = require('zod');
const { tool } = require('@langchain/core/tools');
const { logger } = require('@librechat/data-schemas');
const { Time, CacheKeys, StepTypes } = require('librechat-data-provider');
-const { sendEvent, normalizeServerName, MCPOAuthHandler } = require('@librechat/api');
const { Constants: AgentConstants, Providers, GraphEvents } = require('@librechat/agents');
+const { Constants, ContentTypes, isAssistantsEndpoint } = require('librechat-data-provider');
const {
- Constants,
- ContentTypes,
- isAssistantsEndpoint,
+ sendEvent,
+ MCPOAuthHandler,
+ normalizeServerName,
+ resolveJsonSchemaRefs,
convertJsonSchemaToZod,
-} = require('librechat-data-provider');
-const { getMCPManager, getFlowStateManager } = require('~/config');
+} = require('@librechat/api');
const { findToken, createToken, updateToken } = require('~/models');
+const { getMCPManager, getFlowStateManager } = require('~/config');
const { getCachedTools } = require('./Config');
const { getLogStores } = require('~/cache');
@@ -113,7 +114,8 @@ async function createMCPTool({ req, res, toolKey, provider: _provider }) {
/** @type {LCTool} */
const { description, parameters } = toolDefinition;
const isGoogle = _provider === Providers.VERTEXAI || _provider === Providers.GOOGLE;
- let schema = convertJsonSchemaToZod(parameters, {
+ const resolvedJsonSchema = resolveJsonSchemaRefs(parameters);
+ let schema = convertJsonSchemaToZod(resolvedJsonSchema, {
allowEmptyObject: !isGoogle,
transformOneOfAnyOf: true,
});
diff --git a/api/typedefs.js b/api/typedefs.js
index c0e0dd5f46..3ad7366242 100644
--- a/api/typedefs.js
+++ b/api/typedefs.js
@@ -1074,7 +1074,7 @@
/**
* @exports JsonSchemaType
- * @typedef {import('librechat-data-provider').JsonSchemaType} JsonSchemaType
+ * @typedef {import('@librechat/api').JsonSchemaType} JsonSchemaType
* @memberof typedefs
*/
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index 0b00293240..afdd2141c7 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -2,6 +2,7 @@
export * from './mcp/manager';
export * from './mcp/oauth';
export * from './mcp/auth';
+export * from './mcp/zod';
/* Utilities */
export * from './mcp/utils';
export * from './utils';
diff --git a/packages/api/src/mcp/manager.ts b/packages/api/src/mcp/manager.ts
index 8b51b3cf8a..b4a6a71a1f 100644
--- a/packages/api/src/mcp/manager.ts
+++ b/packages/api/src/mcp/manager.ts
@@ -1,11 +1,12 @@
import { logger } from '@librechat/data-schemas';
import { CallToolResultSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
import type { OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';
-import type { JsonSchemaType, TUser } from 'librechat-data-provider';
+import type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
import type { TokenMethods } from '@librechat/data-schemas';
-import type { FlowStateManager } from '~/flow/manager';
+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';
@@ -892,7 +893,7 @@ export class MCPManager {
this.updateUserLastActivity(userId);
}
this.checkIdleConnections();
- return formatToolContent(result, provider);
+ 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);
diff --git a/packages/api/src/mcp/types/index.ts b/packages/api/src/mcp/types/index.ts
index d95251eecc..7fc72e18c2 100644
--- a/packages/api/src/mcp/types/index.ts
+++ b/packages/api/src/mcp/types/index.ts
@@ -7,8 +7,9 @@ import {
WebSocketOptionsSchema,
StreamableHTTPOptionsSchema,
} from 'librechat-data-provider';
-import type { JsonSchemaType, TPlugin } from 'librechat-data-provider';
import type * as t from '@modelcontextprotocol/sdk/types.js';
+import type { TPlugin } from 'librechat-data-provider';
+import type { JsonSchemaType } from '~/types/zod';
export type StdioOptions = z.infer<typeof StdioOptionsSchema>;
export type WebSocketOptions = z.infer<typeof WebSocketOptionsSchema>;
diff --git a/packages/data-provider/src/zod.spec.ts b/packages/api/src/mcp/zod.spec.ts
similarity index 74%
rename from packages/data-provider/src/zod.spec.ts
rename to packages/api/src/mcp/zod.spec.ts
index 6da3a4f241..28199646cb 100644
--- a/packages/data-provider/src/zod.spec.ts
+++ b/packages/api/src/mcp/zod.spec.ts
@@ -1,8 +1,8 @@
/* eslint-disable @typescript-eslint/no-explicit-any */
// zod.spec.ts
import { z } from 'zod';
-import { convertJsonSchemaToZod } from './zod';
-import type { JsonSchemaType } from './zod';
+import type { JsonSchemaType } from '~/types';
+import { resolveJsonSchemaRefs, convertJsonSchemaToZod } from './zod';
describe('convertJsonSchemaToZod', () => {
describe('primitive types', () => {
@@ -1083,4 +1083,403 @@ describe('convertJsonSchemaToZod', () => {
expect(() => zodSchema?.parse(true)).toThrow();
});
});
+
+ describe('additionalProperties with anyOf/oneOf and allowEmptyObject', () => {
+ it('should handle anyOf with object containing only additionalProperties when allowEmptyObject is false', () => {
+ const schema: JsonSchemaType & { anyOf?: any } = {
+ type: 'object',
+ properties: {
+ filter: {
+ description: 'Filter field',
+ anyOf: [
+ {
+ type: 'object',
+ additionalProperties: {
+ type: 'object',
+ properties: {
+ _icontains: { type: 'string' },
+ },
+ },
+ },
+ {
+ type: 'null',
+ },
+ ],
+ } as JsonSchemaType & { anyOf?: any },
+ },
+ };
+
+ const zodSchema = convertJsonSchemaToZod(schema, {
+ allowEmptyObject: false,
+ transformOneOfAnyOf: true,
+ });
+
+ expect(zodSchema).toBeDefined();
+
+ const testData = {
+ filter: {
+ title: {
+ _icontains: 'Pirate',
+ },
+ },
+ };
+
+ const result = zodSchema?.parse(testData);
+ expect(result).toEqual(testData);
+ expect(result?.filter).toBeDefined();
+ expect(result?.filter?.title?._icontains).toBe('Pirate');
+ });
+
+ it('should not treat objects with additionalProperties as empty', () => {
+ const schema: JsonSchemaType = {
+ type: 'object',
+ additionalProperties: {
+ type: 'string',
+ },
+ };
+
+ const zodSchemaWithoutAllow = convertJsonSchemaToZod(schema, {
+ allowEmptyObject: false,
+ });
+
+ // Should not return undefined because it has additionalProperties
+ expect(zodSchemaWithoutAllow).toBeDefined();
+
+ const testData = {
+ customField: 'value',
+ };
+
+ expect(zodSchemaWithoutAllow?.parse(testData)).toEqual(testData);
+ });
+
+ it('should handle oneOf with object containing only additionalProperties', () => {
+ const schema: JsonSchemaType & { oneOf?: any } = {
+ type: 'object',
+ properties: {},
+ oneOf: [
+ {
+ type: 'object',
+ additionalProperties: true,
+ },
+ {
+ type: 'object',
+ properties: {
+ specificField: { type: 'string' },
+ },
+ },
+ ],
+ };
+
+ const zodSchema = convertJsonSchemaToZod(schema, {
+ allowEmptyObject: false,
+ transformOneOfAnyOf: true,
+ });
+
+ expect(zodSchema).toBeDefined();
+
+ // Test with additional properties
+ const testData1 = {
+ randomField: 'value',
+ anotherField: 123,
+ };
+
+ expect(zodSchema?.parse(testData1)).toEqual(testData1);
+
+ // Test with specific field
+ const testData2 = {
+ specificField: 'test',
+ };
+
+ expect(zodSchema?.parse(testData2)).toEqual(testData2);
+ });
+
+ it('should handle complex nested schema with $ref-like structure', () => {
+ const schema: JsonSchemaType & { anyOf?: any } = {
+ type: 'object',
+ properties: {
+ query: {
+ type: 'object',
+ properties: {
+ filter: {
+ description: 'Filter conditions',
+ anyOf: [
+ {
+ // This simulates a resolved $ref
+ anyOf: [
+ {
+ type: 'object',
+ properties: {
+ _or: {
+ type: 'array',
+ items: { type: 'object' },
+ },
+ },
+ required: ['_or'],
+ },
+ {
+ type: 'object',
+ additionalProperties: {
+ anyOf: [
+ {
+ type: 'object',
+ properties: {
+ _icontains: { type: 'string' },
+ _eq: { type: 'string' },
+ },
+ },
+ ],
+ },
+ },
+ ],
+ },
+ {
+ type: 'null',
+ },
+ ],
+ } as JsonSchemaType & { anyOf?: any },
+ },
+ },
+ },
+ };
+
+ const zodSchema = convertJsonSchemaToZod(schema, {
+ allowEmptyObject: false,
+ transformOneOfAnyOf: true,
+ });
+
+ expect(zodSchema).toBeDefined();
+
+ const testData = {
+ query: {
+ filter: {
+ title: {
+ _icontains: 'Pirate',
+ },
+ },
+ },
+ };
+
+ const result = zodSchema?.parse(testData);
+ expect(result).toEqual(testData);
+ expect(result?.query?.filter?.title?._icontains).toBe('Pirate');
+ });
+ });
+
+ describe('$ref resolution with resolveJsonSchemaRefs', () => {
+ it('should handle schemas with $ref references when resolved', () => {
+ const schemaWithRefs = {
+ type: 'object' as const,
+ properties: {
+ collection: {
+ type: 'string' as const,
+ },
+ query: {
+ type: 'object' as const,
+ properties: {
+ filter: {
+ anyOf: [{ $ref: '#/$defs/__schema0' }, { type: 'null' as const }],
+ },
+ },
+ },
+ },
+ required: ['collection', 'query'],
+ $defs: {
+ __schema0: {
+ anyOf: [
+ {
+ type: 'object' as const,
+ properties: {
+ _or: {
+ type: 'array' as const,
+ items: { $ref: '#/$defs/__schema0' },
+ },
+ },
+ required: ['_or'],
+ },
+ {
+ type: 'object' as const,
+ additionalProperties: {
+ anyOf: [
+ {
+ type: 'object' as const,
+ properties: {
+ _eq: {
+ anyOf: [
+ { type: 'string' as const },
+ { type: 'number' as const },
+ { type: 'null' as const },
+ ],
+ },
+ },
+ },
+ ],
+ },
+ },
+ ],
+ },
+ },
+ };
+
+ // First test without resolving refs - should not work properly
+ const zodSchemaUnresolved = convertJsonSchemaToZod(schemaWithRefs as any, {
+ allowEmptyObject: true,
+ transformOneOfAnyOf: true,
+ });
+
+ const testData = {
+ collection: 'posts',
+ query: {
+ filter: {
+ status: {
+ _eq: 'draft',
+ },
+ },
+ },
+ };
+
+ // Without resolving refs, the filter field won't work correctly
+ const resultUnresolved = zodSchemaUnresolved?.parse(testData);
+ expect(resultUnresolved?.query?.filter).toEqual({});
+
+ // Now resolve refs first
+ const resolvedSchema = resolveJsonSchemaRefs(schemaWithRefs);
+
+ // Verify refs were resolved
+ expect(resolvedSchema.properties?.query?.properties?.filter?.anyOf?.[0]).not.toHaveProperty(
+ '$ref',
+ );
+ expect(resolvedSchema.properties?.query?.properties?.filter?.anyOf?.[0]).toHaveProperty(
+ 'anyOf',
+ );
+
+ const zodSchemaResolved = convertJsonSchemaToZod(resolvedSchema as any, {
+ allowEmptyObject: true,
+ transformOneOfAnyOf: true,
+ });
+
+ // With resolved refs, it should work correctly
+ const resultResolved = zodSchemaResolved?.parse(testData);
+ expect(resultResolved).toEqual(testData);
+ expect(resultResolved?.query?.filter?.status?._eq).toBe('draft');
+ });
+
+ it('should handle circular $ref references without infinite loops', () => {
+ const schemaWithCircularRefs = {
+ type: 'object' as const,
+ properties: {
+ node: { $ref: '#/$defs/TreeNode' },
+ },
+ $defs: {
+ TreeNode: {
+ type: 'object' as const,
+ properties: {
+ value: { type: 'string' as const },
+ children: {
+ type: 'array' as const,
+ items: { $ref: '#/$defs/TreeNode' },
+ },
+ },
+ },
+ },
+ };
+
+ // Should not throw or hang
+ const resolved = resolveJsonSchemaRefs(schemaWithCircularRefs);
+ expect(resolved).toBeDefined();
+
+ // The circular reference should be broken with a simple object schema
+ const zodSchema = convertJsonSchemaToZod(resolved as any, {
+ allowEmptyObject: true,
+ transformOneOfAnyOf: true,
+ });
+
+ expect(zodSchema).toBeDefined();
+
+ const testData = {
+ node: {
+ value: 'root',
+ children: [
+ {
+ value: 'child1',
+ children: [],
+ },
+ ],
+ },
+ };
+
+ expect(() => zodSchema?.parse(testData)).not.toThrow();
+ });
+
+ it('should handle various edge cases safely', () => {
+ // Test with null/undefined
+ expect(resolveJsonSchemaRefs(null as any)).toBeNull();
+ expect(resolveJsonSchemaRefs(undefined as any)).toBeUndefined();
+
+ // Test with non-object primitives
+ expect(resolveJsonSchemaRefs('string' as any)).toBe('string');
+ expect(resolveJsonSchemaRefs(42 as any)).toBe(42);
+ expect(resolveJsonSchemaRefs(true as any)).toBe(true);
+
+ // Test with arrays
+ const arrayInput = [{ type: 'string' }, { $ref: '#/def' }];
+ const arrayResult = resolveJsonSchemaRefs(arrayInput as any);
+ expect(Array.isArray(arrayResult)).toBe(true);
+ expect(arrayResult).toHaveLength(2);
+
+ // Test with schema that has no refs
+ const noRefSchema = {
+ type: 'object' as const,
+ properties: {
+ name: { type: 'string' as const },
+ nested: {
+ type: 'object' as const,
+ properties: {
+ value: { type: 'number' as const },
+ },
+ },
+ },
+ };
+
+ const resolvedNoRef = resolveJsonSchemaRefs(noRefSchema);
+ expect(resolvedNoRef).toEqual(noRefSchema);
+
+ // Test with invalid ref (non-existent)
+ const invalidRefSchema = {
+ type: 'object' as const,
+ properties: {
+ item: { $ref: '#/$defs/nonExistent' },
+ },
+ $defs: {
+ other: { type: 'string' as const },
+ },
+ };
+
+ const resolvedInvalid = resolveJsonSchemaRefs(invalidRefSchema);
+ // Invalid refs should be preserved as-is
+ expect(resolvedInvalid.properties?.item?.$ref).toBe('#/$defs/nonExistent');
+
+ // Test with empty object
+ expect(resolveJsonSchemaRefs({})).toEqual({});
+
+ // Test with schema containing special JSON Schema keywords
+ const schemaWithKeywords = {
+ type: 'object' as const,
+ properties: {
+ value: {
+ type: 'string' as const,
+ minLength: 5,
+ maxLength: 10,
+ pattern: '^[A-Z]',
+ },
+ },
+ additionalProperties: false,
+ minProperties: 1,
+ };
+
+ const resolvedKeywords = resolveJsonSchemaRefs(schemaWithKeywords);
+ expect(resolvedKeywords).toEqual(schemaWithKeywords);
+ expect(resolvedKeywords.properties?.value?.minLength).toBe(5);
+ expect(resolvedKeywords.additionalProperties).toBe(false);
+ });
+ });
});
diff --git a/packages/data-provider/src/zod.ts b/packages/api/src/mcp/zod.ts
similarity index 82%
rename from packages/data-provider/src/zod.ts
rename to packages/api/src/mcp/zod.ts
index bffc693b4a..6a3e3194b2 100644
--- a/packages/data-provider/src/zod.ts
+++ b/packages/api/src/mcp/zod.ts
@@ -1,30 +1,16 @@
import { z } from 'zod';
-
-export type JsonSchemaType = {
- type: 'string' | 'number' | 'boolean' | 'array' | 'object';
- enum?: string[];
- items?: JsonSchemaType;
- properties?: Record<string, JsonSchemaType>;
- required?: string[];
- description?: string;
- additionalProperties?: boolean | JsonSchemaType;
-};
+import type { JsonSchemaType, ConvertJsonSchemaToZodOptions } from '~/types';
function isEmptyObjectSchema(jsonSchema?: JsonSchemaType): boolean {
return (
jsonSchema != null &&
typeof jsonSchema === 'object' &&
jsonSchema.type === 'object' &&
- (jsonSchema.properties == null || Object.keys(jsonSchema.properties).length === 0)
+ (jsonSchema.properties == null || Object.keys(jsonSchema.properties).length === 0) &&
+ !jsonSchema.additionalProperties // Don't treat objects with additionalProperties as empty
);
}
-type ConvertJsonSchemaToZodOptions = {
- allowEmptyObject?: boolean;
- dropFields?: string[];
- transformOneOfAnyOf?: boolean;
-};
-
function dropSchemaFields(
schema: JsonSchemaType | undefined,
fields: string[],
@@ -98,6 +84,10 @@ function convertToZodUnion(
return convertJsonSchemaToZod(objSchema, options);
}
+ return convertJsonSchemaToZod(objSchema, options);
+ } else if (!subSchema.type && subSchema.additionalProperties) {
+ // It's likely an object schema with additionalProperties
+ const objSchema = { ...subSchema, type: 'object' } as JsonSchemaType;
return convertJsonSchemaToZod(objSchema, options);
} else if (!subSchema.type && subSchema.items) {
// It's likely an array schema
@@ -182,6 +172,82 @@ function convertToZodUnion(
return zodSchemas[0];
}
+/**
+ * Helper function to resolve $ref references
+ * @param schema - The schema to resolve
+ * @param definitions - The definitions to use
+ * @param visited - The set of visited references
+ * @returns The resolved schema
+ */
+export function resolveJsonSchemaRefs<T extends Record<string, unknown>>(
+ schema: T,
+ definitions?: Record<string, unknown>,
+ visited = new Set<string>(),
+): T {
+ // Handle null, undefined, or non-object values first
+ if (!schema || typeof schema !== 'object') {
+ return schema;
+ }
+
+ // If no definitions provided, try to extract from schema.$defs or schema.definitions
+ if (!definitions) {
+ definitions = (schema.$defs || schema.definitions) as Record<string, unknown>;
+ }
+
+ // Handle arrays
+ if (Array.isArray(schema)) {
+ return schema.map((item) => resolveJsonSchemaRefs(item, definitions, visited)) as unknown as T;
+ }
+
+ // Handle objects
+ const result: Record<string, unknown> = {};
+
+ for (const [key, value] of Object.entries(schema)) {
+ // Skip $defs/definitions at root level to avoid infinite recursion
+ if ((key === '$defs' || key === 'definitions') && !visited.size) {
+ result[key] = value;
+ continue;
+ }
+
+ // Handle $ref
+ if (key === '$ref' && typeof value === 'string') {
+ // Prevent circular references
+ if (visited.has(value)) {
+ // Return a simple schema to break the cycle
+ return { type: 'object' } as unknown as T;
+ }
+
+ // Extract the reference path
+ const refPath = value.replace(/^#\/(\$defs|definitions)\//, '');
+ const resolved = definitions?.[refPath];
+
+ if (resolved) {
+ visited.add(value);
+ const resolvedSchema = resolveJsonSchemaRefs(
+ resolved as Record<string, unknown>,
+ definitions,
+ visited,
+ );
+ visited.delete(value);
+
+ // Merge the resolved schema into the result
+ Object.assign(result, resolvedSchema);
+ } else {
+ // If we can't resolve the reference, keep it as is
+ result[key] = value;
+ }
+ } else if (value && typeof value === 'object') {
+ // Recursively resolve nested objects/arrays
+ result[key] = resolveJsonSchemaRefs(value as Record<string, unknown>, definitions, visited);
+ } else {
+ // Copy primitive values as is
+ result[key] = value;
+ }
+ }
+
+ return result as T;
+}
+
export function convertJsonSchemaToZod(
schema: JsonSchemaType & Record<string, unknown>,
options: ConvertJsonSchemaToZodOptions = {},
diff --git a/packages/api/src/types/index.ts b/packages/api/src/types/index.ts
index 6db727529a..75ee614ff1 100644
--- a/packages/api/src/types/index.ts
+++ b/packages/api/src/types/index.ts
@@ -4,3 +4,4 @@ export * from './google';
export * from './mistral';
export * from './openai';
export * from './run';
+export * from './zod';
diff --git a/packages/api/src/types/zod.ts b/packages/api/src/types/zod.ts
new file mode 100644
index 0000000000..e8b3c9327d
--- /dev/null
+++ b/packages/api/src/types/zod.ts
@@ -0,0 +1,15 @@
+export type JsonSchemaType = {
+ type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+ enum?: string[];
+ items?: JsonSchemaType;
+ properties?: Record<string, JsonSchemaType>;
+ required?: string[];
+ description?: string;
+ additionalProperties?: boolean | JsonSchemaType;
+};
+
+export type ConvertJsonSchemaToZodOptions = {
+ allowEmptyObject?: boolean;
+ dropFields?: string[];
+ transformOneOfAnyOf?: boolean;
+};
diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts
index 9869029adf..d80861acfe 100644
--- a/packages/data-provider/src/index.ts
+++ b/packages/data-provider/src/index.ts
@@ -8,7 +8,6 @@ export * from './artifacts';
/* schema helpers */
export * from './parsers';
export * from './ocr';
-export * from './zod';
/* custom/dynamic configurations */
export * from './generate';
export * from './models';