diff --git a/README.md b/README.md index 08548b6..2db4011 100644 --- a/README.md +++ b/README.md @@ -323,7 +323,7 @@ The `AgentToolkitConfig` object accepts: ### Operations -- `buildOperation(schema, fieldName, options?)` -- Generate a GraphQL operation string with variables +- `buildOperation(schema, fieldName, options?)` -- Generate a GraphQL operation string with variables. Set `options.operationType` to `query` or `mutation` to select the root explicitly when both use the same field name. ### MCP diff --git a/src/adapters/crewai.ts b/src/adapters/crewai.ts index 6b2fe4c..c8c9346 100644 --- a/src/adapters/crewai.ts +++ b/src/adapters/crewai.ts @@ -41,7 +41,7 @@ const namedTypeToJsonSchema = ( const required: string[] = []; for (const field of namedType.inputFields) { properties[field.name] = convertType(field.type, schema); - if (field.type.kind === 'NON_NULL') { + if (field.type.kind === 'NON_NULL' && field.defaultValue === null) { required.push(field.name); } } @@ -118,7 +118,7 @@ const buildArgumentsSchema = ( for (const argument of field.args) { properties[argument.name] = typeReferenceToJsonSchema(argument.type, schema); - if (argument.type.kind === 'NON_NULL') { + if (argument.type.kind === 'NON_NULL' && argument.defaultValue === null) { required.push(argument.name); } } @@ -156,7 +156,7 @@ export const createCrewAITools = ( args_schema: argumentsSchema, description, func: async (parameters: Record): Promise => { - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType: 'query' }); return executor.execute(op.operation, parameters); }, name: toolName, @@ -176,7 +176,7 @@ export const createCrewAITools = ( args_schema: argumentsSchema, description, func: async (parameters: Record): Promise => { - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType: 'mutation' }); return executor.execute(op.operation, parameters); }, name: toolName, diff --git a/src/adapters/langchain.ts b/src/adapters/langchain.ts index 0d55821..e3567a6 100644 --- a/src/adapters/langchain.ts +++ b/src/adapters/langchain.ts @@ -1,6 +1,6 @@ import { z } from 'zod'; import { buildOperation } from '../operations/index.js'; -import { typeReferenceToZod } from '../zod.js'; +import { argumentToZod } from '../zod.js'; import { unwrapType } from '../operations/variables.js'; import type { ParsedSchema, @@ -50,7 +50,7 @@ const namedTypeToJsonSchema = ( const required: string[] = []; for (const field of namedType.inputFields) { properties[field.name] = convertType(field.type, schema); - if (field.type.kind === 'NON_NULL') { + if (field.type.kind === 'NON_NULL' && field.defaultValue === null) { required.push(field.name); } } @@ -124,7 +124,7 @@ const buildJsonSchema = (field: SchemaField, schema: ParsedSchema): Record = {}; for (const argument of field.args) { - shape[argument.name] = typeReferenceToZod(argument.type, schema); + shape[argument.name] = argumentToZod(argument, schema); } return z.object(shape); @@ -204,7 +204,7 @@ export const createLangChainTools = ( description, func: async (input: string): Promise => { const variables = input ? JSON.parse(input) : {}; - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType }); return executor.execute(op.operation, variables); }, name: toolName, @@ -234,7 +234,7 @@ export const createStructuredTools = ( return { description, func: async (input: Record): Promise => { - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType }); return executor.execute(op.operation, input); }, name: toolName, diff --git a/src/adapters/vercel-ai.ts b/src/adapters/vercel-ai.ts index 635a621..2122b7d 100644 --- a/src/adapters/vercel-ai.ts +++ b/src/adapters/vercel-ai.ts @@ -1,6 +1,6 @@ import { z } from 'zod'; import { buildOperation } from '../operations/index.js'; -import { typeReferenceToZod } from '../zod.js'; +import { argumentToZod } from '../zod.js'; import type { ParsedSchema, SchemaField } from '../types/index.js'; import type { GraphQLExecutor } from '../mcp/executor.js'; @@ -24,7 +24,7 @@ const buildParametersSchema = ( const shape: Record = {}; for (const argument of field.args) { - shape[argument.name] = typeReferenceToZod(argument.type, schema); + shape[argument.name] = argumentToZod(argument, schema); } return z.object(shape); @@ -52,7 +52,7 @@ export const createVercelAITools = ( tools[toolName] = { description, execute: async (input: Record): Promise => { - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType: 'query' }); return executor.execute(op.operation, input); }, parameters, @@ -71,7 +71,7 @@ export const createVercelAITools = ( tools[toolName] = { description, execute: async (input: Record): Promise => { - const op = buildOperation(schema, field.name, { maxDepth }); + const op = buildOperation(schema, field.name, { maxDepth, operationType: 'mutation' }); return executor.execute(op.operation, input); }, parameters, diff --git a/src/mcp/tool-factory.ts b/src/mcp/tool-factory.ts index d3c273b..067dab4 100644 --- a/src/mcp/tool-factory.ts +++ b/src/mcp/tool-factory.ts @@ -1,5 +1,5 @@ import { buildOperation } from '../operations/index.js'; -import { typeReferenceToZod } from '../zod.js'; +import { argumentToZod } from '../zod.js'; import type { z } from 'zod'; import type { ParsedSchema, SchemaField } from '../types/index.js'; import type { GraphQLExecutor } from './executor.js'; @@ -23,7 +23,7 @@ const buildInputSchema = (field: SchemaField, schema: ParsedSchema): Record = {}; for (const argument of field.args) { - shape[argument.name] = typeReferenceToZod(argument.type, schema); + shape[argument.name] = argumentToZod(argument, schema); } return shape; @@ -56,7 +56,11 @@ export const createToolsFromSchema = ( tools.push({ description, execute: async (parameters: Record) => { - const op = buildOperation(schema, field.name, { includeDeprecated, maxDepth }); + const op = buildOperation(schema, field.name, { + includeDeprecated, + maxDepth, + operationType: 'query', + }); return executor.execute(op.operation, parameters); }, inputSchema, @@ -81,7 +85,11 @@ export const createToolsFromSchema = ( tools.push({ description, execute: async (parameters: Record) => { - const op = buildOperation(schema, field.name, { includeDeprecated, maxDepth }); + const op = buildOperation(schema, field.name, { + includeDeprecated, + maxDepth, + operationType: 'mutation', + }); return executor.execute(op.operation, parameters); }, inputSchema, diff --git a/src/operations/builder.ts b/src/operations/builder.ts index 37c8b89..782a7b8 100644 --- a/src/operations/builder.ts +++ b/src/operations/builder.ts @@ -17,6 +17,7 @@ export interface GeneratedOperation { export interface BuildOperationOptions { maxDepth?: number; + operationType?: 'query' | 'mutation'; includeDeprecated?: boolean; } @@ -65,6 +66,11 @@ const buildSelectionSet = (typeName: string, context: SelectionContext): string // Only include scalar fields to break the cycle const scalarFields = type.fields .filter((field) => !field.isDeprecated || isDeprecatedIncluded) + .filter((field) => + field.args.every( + (argument) => !isRequired(argument.type) || argument.defaultValue !== null, + ), + ) .filter((f) => isScalarLike(schema, f)); if (scalarFields.length === 0) { @@ -77,7 +83,11 @@ const buildSelectionSet = (typeName: string, context: SelectionContext): string visited.add(typeName); - const fields = type.fields.filter((field) => !field.isDeprecated || isDeprecatedIncluded); + const fields = type.fields + .filter((field) => !field.isDeprecated || isDeprecatedIncluded) + .filter((field) => + field.args.every((argument) => !isRequired(argument.type) || argument.defaultValue !== null), + ); const lines: string[] = []; for (const field of fields) { @@ -109,6 +119,26 @@ const buildSelectionSet = (typeName: string, context: SelectionContext): string const capitalize = (input: string): string => input.charAt(0).toUpperCase() + input.slice(1); +const resolveRootField = ( + schema: ParsedSchema, + name: string, + preferredType?: 'query' | 'mutation', +): { rootField: SchemaField; operationType: 'query' | 'mutation' } => { + const operationTypes: ('query' | 'mutation')[] = preferredType + ? [preferredType] + : ['query', 'mutation']; + for (const operationType of operationTypes) { + const rootName = operationType === 'query' ? schema.queryType : schema.mutationType; + const rootField = rootName + ? schema.types.get(rootName)?.fields.find((field) => field.name === name) + : undefined; + if (rootField) { + return { operationType, rootField }; + } + } + throw new Error(`Field "${name}" not found in schema query or mutation types`); +}; + export const buildOperation = ( schema: ParsedSchema, rootFieldName: string, @@ -117,28 +147,11 @@ export const buildOperation = ( const maxDepth = options?.maxDepth ?? 2; const isDeprecatedIncluded = options?.includeDeprecated ?? false; - // Look up the field in query type first, then mutation type - let operationType: 'query' | 'mutation' = 'query'; - let rootField: SchemaField | undefined; - - const queryType = schema.types.get(schema.queryType); - if (queryType) { - rootField = queryType.fields.find((f) => f.name === rootFieldName); - } - - if (!rootField && schema.mutationType) { - const mutationType = schema.types.get(schema.mutationType); - if (mutationType) { - rootField = mutationType.fields.find((f) => f.name === rootFieldName); - if (rootField) { - operationType = 'mutation'; - } - } - } - - if (!rootField) { - throw new Error(`Field "${rootFieldName}" not found in schema query or mutation types`); - } + const { rootField, operationType } = resolveRootField( + schema, + rootFieldName, + options?.operationType, + ); const operationName = `${capitalize(rootFieldName)}${capitalize(operationType)}`; @@ -146,13 +159,17 @@ export const buildOperation = ( const variables: VariableDefinition[] = rootField.args.map((argument) => ({ description: argument.description, name: argument.name, - required: isRequired(argument.type), + required: isRequired(argument.type) && argument.defaultValue === null, type: typeReferenceToString(argument.type), })); // Build the variable definitions string for the operation const variableDefinitions = variables - .map((variable) => `$${variable.name}: ${variable.type}`) + .map((variable, index) => { + const defaultValue = rootField.args[index]?.defaultValue; + const suffix = typeof defaultValue === 'string' ? ` = ${defaultValue}` : ''; + return `$${variable.name}: ${variable.type}${suffix}`; + }) .join(', '); const variableDefs = variables.length > 0 ? `(${variableDefinitions})` : ''; @@ -175,7 +192,9 @@ export const buildOperation = ( visited: new Set(), }) : ''; - const selectionSet = nestedSelection ? ` ${nestedSelection}` : ''; + const selectionSet = isScalarLike(schema, rootField) + ? '' + : ` ${nestedSelection || '{ __typename }'}`; const operation = `${operationType} ${operationName}${variableDefs} {\n ${rootFieldName}${argumentsPassing}${selectionSet}\n}`; diff --git a/src/summarizer/summarizer.ts b/src/summarizer/summarizer.ts index 74904e5..77ad00f 100644 --- a/src/summarizer/summarizer.ts +++ b/src/summarizer/summarizer.ts @@ -27,7 +27,7 @@ export const summarizeResponse = ( config?: Partial, ): { summary: unknown; metadata: SummaryMetadata } => { const resolvedConfig = { ...DEFAULT_CONFIG, ...config }; - const originalSize = JSON.stringify(data).length; + const originalSize = JSON.stringify(data)?.length ?? 0; let isTruncated = false; const countItems = (value: unknown): number => { diff --git a/src/zod.ts b/src/zod.ts index 7df9cf2..910d7c3 100644 --- a/src/zod.ts +++ b/src/zod.ts @@ -1,29 +1,30 @@ import { z } from 'zod'; import { unwrapType } from './operations/variables.js'; -import type { ParsedSchema, TypeRef as TypeReference } from './types/index.js'; +import type { ParsedSchema, SchemaArgument, TypeRef as TypeReference } from './types/index.js'; const withGraphQLNullability = (zodType: z.ZodType, isNullable: boolean): z.ZodType => isNullable ? zodType.nullish() : zodType; -/** - * Maps a GraphQL TypeRef to a Zod schema while preserving GraphQL nullability. - * Nullable GraphQL values accept null or omission. NON_NULL values reject both. - */ -export const typeReferenceToZod = ( +interface ConversionContext { + inputObjects: Map; + isNullable: boolean; +} + +const convertTypeReference = ( typeReference: TypeReference, schema: ParsedSchema, - isNullable = true, + { inputObjects, isNullable }: ConversionContext, ): z.ZodType => { if (typeReference.kind === 'NON_NULL') { if (!typeReference.ofType) { return z.unknown(); } - return typeReferenceToZod(typeReference.ofType, schema, false); + return convertTypeReference(typeReference.ofType, schema, { inputObjects, isNullable: false }); } if (typeReference.kind === 'LIST') { const itemSchema = typeReference.ofType - ? typeReferenceToZod(typeReference.ofType, schema) + ? convertTypeReference(typeReference.ofType, schema, { inputObjects, isNullable: true }) : z.unknown(); return withGraphQLNullability(z.array(itemSchema), isNullable); } @@ -39,11 +40,24 @@ export const typeReferenceToZod = ( } if (namedType && namedType.kind === 'INPUT_OBJECT') { - const shape: Record = {}; - for (const field of namedType.inputFields) { - shape[field.name] = typeReferenceToZod(field.type, schema); + const cached = inputObjects.get(typeName); + if (cached) { + return withGraphQLNullability(cached, isNullable); } - return withGraphQLNullability(z.object(shape), isNullable); + // Reuse the same lazy identity so JSON Schema exporters can emit refs. + const inputObject = z.lazy(() => { + const shape: Record = {}; + for (const field of namedType.inputFields) { + const fieldSchema = convertTypeReference(field.type, schema, { + inputObjects, + isNullable: true, + }); + shape[field.name] = field.defaultValue === null ? fieldSchema : fieldSchema.optional(); + } + return z.object(shape); + }); + inputObjects.set(typeName, inputObject); + return withGraphQLNullability(inputObject, isNullable); } } @@ -53,7 +67,10 @@ export const typeReferenceToZod = ( return withGraphQLNullability(z.string(), isNullable); } case 'Int': { - return withGraphQLNullability(z.number().int(), isNullable); + return withGraphQLNullability( + z.number().int().min(-2_147_483_648).max(2_147_483_647), + isNullable, + ); } case 'Float': { return withGraphQLNullability(z.number(), isNullable); @@ -66,3 +83,21 @@ export const typeReferenceToZod = ( } } }; + +/** +Preserve GraphQL nullability while sharing recursive input object schemas. +*/ +export const typeReferenceToZod = ( + typeReference: TypeReference, + schema: ParsedSchema, + isNullable = true, +): z.ZodType => + convertTypeReference(typeReference, schema, { inputObjects: new Map(), isNullable }); + +/** +A non-null argument with a default may be omitted, but may not be null. +*/ +export const argumentToZod = (argument: SchemaArgument, schema: ParsedSchema): z.ZodType => { + const converted = typeReferenceToZod(argument.type, schema); + return argument.defaultValue === null ? converted : converted.optional(); +}; diff --git a/tests/nov1-regression.test.ts b/tests/nov1-regression.test.ts new file mode 100644 index 0000000..df110f6 --- /dev/null +++ b/tests/nov1-regression.test.ts @@ -0,0 +1,120 @@ +import assert from 'node:assert/strict'; +import { expect, it, vi } from 'vitest'; +import { z } from 'zod'; +import { buildSchema, introspectionFromSchema, parse, validate, graphqlSync } from 'graphql'; +import { parseSchema } from '../src/introspection/parser.js'; +import { buildOperation } from '../src/operations/builder.js'; +import { createToolsFromSchema } from '../src/mcp/tool-factory.js'; +import { createStructuredTools, createLangChainTools } from '../src/adapters/langchain.js'; +import { createCrewAITools } from '../src/adapters/crewai.js'; +import { createVercelAITools } from '../src/adapters/vercel-ai.js'; +import { summarizeResponse, formatForLLM } from '../src/summarizer/summarizer.js'; +import type { GraphQLExecutor } from '../src/mcp/executor.js'; + +const parsed = (sdl: string) => parseSchema(introspectionFromSchema(buildSchema(sdl))); +const executor = () => ({ execute: vi.fn().mockResolvedValue('{}') }) as unknown as GraphQLExecutor; + +it('omits nested fields whose required arguments cannot be supplied', () => { + const source = buildSchema( + 'type Query { user: User } type User { id: ID display(locale:String!):String related(id:ID!):User }', + ); + const op = buildOperation(parseSchema(introspectionFromSchema(source)), 'user'); + expect(validate(source, parse(op.operation))).toEqual([]); + expect(op.operation).not.toContain('display'); + expect(op.operation).not.toContain('related'); +}); +it.each(['result', 'user'])( + 'keeps composite root %s outputs valid even without selectable fields', + (name) => { + const source = buildSchema( + 'type Query { result: Search user: User } union Search = User type User { id: ID }', + ); + const op = buildOperation(parseSchema(introspectionFromSchema(source)), name, { maxDepth: 0 }); + expect(validate(source, parse(op.operation))).toEqual([]); + expect(op.operation).toContain('__typename'); + }, +); +it('mutation tools select mutations when a query uses the same field name', async () => { + const schema = parsed('type Query { item: String } type Mutation { item: Int }'); + const ex = executor(); + const mcp = createToolsFromSchema(schema, ex).find((tool) => tool.name === 'mutate_item'); + const structured = createStructuredTools(schema, ex).find((tool) => tool.name === 'mutate_item'); + const langchain = createLangChainTools(schema, ex).find((tool) => tool.name === 'mutate_item'); + const crew = createCrewAITools(schema, ex).find((tool) => tool.name === 'mutate_item'); + assert.ok(mcp); + assert.ok(structured); + assert.ok(langchain); + assert.ok(crew); + await mcp.execute({}); + await structured.func({}); + await langchain.func('{}'); + await crew.func({}); + await createVercelAITools(schema, ex).mutate_item.execute({}); + for (const [operation] of vi.mocked(ex.execute).mock.calls) { + expect(parse(operation).definitions[0]).toMatchObject({ operation: 'mutation' }); + } +}); +it('preserves argument defaults in generated operations and tool schemas', () => { + const source = buildSchema( + 'type Query { greet(name:String!="friend", options:Options):String } input Options { limit:Int! = 5 }', + ); + const schema = parseSchema(introspectionFromSchema(source)); + const op = buildOperation(schema, 'greet'); + const result = graphqlSync({ + rootValue: { greet: () => 'ok' }, + schema: source, + source: op.operation, + variableValues: {}, + }); + expect(result.errors).toBeUndefined(); + const nameVariable = op.variables.find((variable) => variable.name === 'name'); + assert.ok(nameVariable); + expect(nameVariable.required).toBe(false); + const ex = executor(); + const input = z.object(createToolsFromSchema(schema, ex)[0].inputSchema); + expect(input.safeParse({ options: {} }).success).toBe(true); + expect(input.safeParse({ name: null }).success).toBe(false); + expect(createStructuredTools(schema, ex)[0].schema.safeParse({ options: {} }).success).toBe(true); + expect( + createVercelAITools(schema, ex).query_greet.parameters.safeParse({ options: {} }).success, + ).toBe(true); + expect(createLangChainTools(schema, ex)[0].schema.required ?? []).not.toContain('name'); + expect(createCrewAITools(schema, ex)[0].args_schema.required ?? []).not.toContain('name'); +}); +it('builds recursive input schemas lazily for Zod-backed tools', () => { + const schema = parsed( + 'type Query { search(filter:Filter):String } input Filter { term:String and:[Filter!] }', + ); + const ex = executor(); + const input = { filter: { and: [{ term: 'name' }] } }; + expect(z.object(createToolsFromSchema(schema, ex)[0].inputSchema).safeParse(input).success).toBe( + true, + ); + expect(createStructuredTools(schema, ex)[0].schema.safeParse(input).success).toBe(true); + expect(createVercelAITools(schema, ex).query_search.parameters.safeParse(input).success).toBe( + true, + ); +}); +it('rejects GraphQL Int values outside the signed 32-bit range', () => { + const schema = parsed('type Query { find(limit:Int):String }'); + const input = z.object(createToolsFromSchema(schema, executor())[0].inputSchema); + expect(input.safeParse({ limit: 2_147_483_648 }).success).toBe(false); + expect(input.safeParse({ limit: -2_147_483_649 }).success).toBe(false); + expect(input.safeParse({ limit: 2_147_483_647 }).success).toBe(true); + expect(input.safeParse({ limit: -2_147_483_648 }).success).toBe(true); +}); +it('summarizes undefined input using the renderer null representation', () => { + const { summary, metadata } = summarizeResponse(undefined); + expect(summary).toBeUndefined(); + expect(metadata).toEqual({ originalSize: 0, totalItems: 0, truncated: false }); + expect(formatForLLM(undefined)).toBe('null'); +}); + +it('exports recursive Zod tool inputs as finite JSON Schema references', () => { + const schema = parsed( + 'type Query { search(filter:Filter):String } input Filter { term:String and:[Filter!] }', + ); + const input = z.object(createToolsFromSchema(schema, executor())[0].inputSchema); + const jsonSchema = z.toJSONSchema(input); + expect(JSON.stringify(jsonSchema)).toContain('$ref'); +});