fix(core): Recursive schema parsing for array items with MCP transport (#286)

* fix(core): Recursive schema parsing for array items with MCP transport

* remove unused var

* Update test.protocol.ts

* fix cases

* fix tests

* lint

Author: twishabansal

packages/toolbox-core/src/toolbox_core/mcp/transportBase.ts

@@ -142,16 +142,35 @@ export abstract class McpHttpTransportBase implements ITransport {
 
   private _convertTypeSchema(schemaData: unknown): TypeSchema {
     const schema = schemaData as JsonSchema;
-    if (schema.type === 'array') {
+    const paramType = schema.type || 'string';
+
+    if (paramType === 'array') {
+      let itemsSchema: TypeSchema | undefined;
+
+      // MCP strictly requires standard JSON Schema formatting:
+      // https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool
+      // This dictates using `items` for array types (https://json-schema.org/understanding-json-schema/reference/array#items)
+      // and `additionalProperties` for maps (https://json-schema.org/understanding-json-schema/reference/object#additionalproperties).
+      if (schema.items !== undefined && schema.items !== null) {
+        // For third-party compatibility, skip strict typing if 'items' is a list (Draft 7 tuple validation).
+        // Missing 'items' keys default natively to generic lists (list[Any]).
+        if (typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+          itemsSchema = this._convertTypeSchema(schema.items);
+        }
+      }
+
       return {
         type: 'array',
-        items: this._convertTypeSchema(schema.items || {type: 'string'}),
+        ...(itemsSchema ? {items: itemsSchema} : {}),
       };
-    } else if (schema.type === 'object') {
+    } else if (paramType === 'object') {
       let additionalProperties: boolean | PrimitiveTypeSchema | undefined;
+
       if (
-        schema.additionalProperties &&
-        typeof schema.additionalProperties === 'object'
+        schema.additionalProperties !== undefined &&
+        schema.additionalProperties !== null &&
+        typeof schema.additionalProperties === 'object' &&
+        !Array.isArray(schema.additionalProperties)
       ) {
         additionalProperties = {
           type: schema.additionalProperties.type as
@@ -163,13 +182,14 @@ export abstract class McpHttpTransportBase implements ITransport {
       } else {
         additionalProperties = schema.additionalProperties !== false;
       }
+
       return {
         type: 'object',
         additionalProperties,
       };
     } else {
       return {
-        type: schema.type as
+        type: paramType as
           | 'string'
           | 'integer'
           | 'float'

packages/toolbox-core/src/toolbox_core/protocol.ts

@@ -55,7 +55,7 @@ export type PrimitiveTypeSchema =
 
 interface ArrayType {
   type: 'array';
-  items: TypeSchema; // Recursive
+  items?: TypeSchema; // Recursive
 }
 interface ObjectType {
   type: 'object';
@@ -91,7 +91,7 @@ const ZodTypeSchema: z.ZodType<TypeSchema> = z.lazy(() =>
     z.object({type: z.literal('integer')}),
     z.object({type: z.literal('float')}),
     z.object({type: z.literal('boolean')}),
-    z.object({type: z.literal('array'), items: ZodTypeSchema}),
+    z.object({type: z.literal('array'), items: ZodTypeSchema.optional()}),
     z.object({
       type: z.literal('object'),
       additionalProperties: z
@@ -140,6 +140,9 @@ function buildZodShapeFromTypeSchema(typeSchema: TypeSchema): ZodTypeAny {
     case 'boolean':
       return z.boolean();
     case 'array':
+      if (!typeSchema.items) {
+        return z.array(z.any());
+      }
       return z.array(buildZodShapeFromTypeSchema(typeSchema.items));
     case 'object':
       if (typeof typeSchema.additionalProperties === 'object') {

packages/toolbox-core/test/mcp/test.base.ts

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import {McpHttpTransportBase} from '../../src/toolbox_core/mcp/transportBase.js';
 import {Protocol, ZodManifest} from '../../src/toolbox_core/protocol.js';
 import axios, {AxiosInstance} from 'axios';
@@ -329,7 +330,7 @@ describe('McpHttpTransportBase', () => {
       expect(result.authRequired).toBeUndefined();
     });
 
-    it('should handle array without items (default to string)', () => {
+    it('should handle array without items (default to any)', () => {
       const toolData = {
         name: 'arrayDefault',
         inputSchema: {
@@ -343,9 +344,72 @@ describe('McpHttpTransportBase', () => {
       expect(result.parameters[0]).toEqual(
         expect.objectContaining({
           type: 'array',
-          items: {type: 'string'},
         }),
       );
+      expect((result.parameters[0] as any).items).toBeUndefined();
+    });
+
+    it('should convert schema with recursive types (nested arrays, arrays of maps)', () => {
+      const toolData = {
+        name: 'recursive_tool',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            // List[List[str]]
+            nested_array: {
+              type: 'array',
+              items: {
+                type: 'array',
+                items: {type: 'string'},
+              },
+            },
+            // List[Dict[str, int]]
+            array_of_maps: {
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: {type: 'integer'},
+              },
+            },
+            // Dict[str, List[int]]
+            map_of_arrays: {
+              type: 'object',
+              additionalProperties: {
+                type: 'array',
+                items: {type: 'integer'},
+              },
+            },
+          },
+        },
+      };
+
+      const result = transport.testConvertToolSchema(toolData);
+
+      // 1. Nested Array
+      const pNested: any = result.parameters.find(
+        p => p.name === 'nested_array',
+      );
+      expect(pNested.type).toBe('array');
+      expect(pNested.items).toBeDefined();
+      expect(pNested.items.type).toBe('array');
+      expect(pNested.items.items).toBeDefined();
+      expect(pNested.items.items.type).toBe('string');
+
+      // 2. Array of Maps
+      const pArrMap: any = result.parameters.find(
+        p => p.name === 'array_of_maps',
+      );
+      expect(pArrMap.type).toBe('array');
+      expect(pArrMap.items).toBeDefined();
+      expect(pArrMap.items.type).toBe('object');
+      expect(pArrMap.items.additionalProperties.type).toBe('integer');
+
+      // 3. Map of Arrays
+      const pMapArr: any = result.parameters.find(
+        p => p.name === 'map_of_arrays',
+      );
+      expect(pMapArr.type).toBe('object');
+      expect(pMapArr.additionalProperties.type).toBe('array');
     });
 
     it('should handle partial auth metadata', () => {

packages/toolbox-core/test/test.protocol.ts

@@ -199,13 +199,9 @@ describe('ZodParameterSchema', () => {
     });
   });
 
-  it('should invalidate an array parameter with missing items definition', () => {
+  it('should validate an array parameter with missing items definition (defaults to any)', () => {
     const data = {name: 'testArray', description: 'An array', type: 'array'};
-    expectParseFailure(ZodParameterSchema, data, errors => {
-      expect(errors).toEqual(
-        expect.arrayContaining([expect.stringMatching(/items: Required/i)]),
-      );
-    });
+    expectParseSuccess(ZodParameterSchema, data);
   });
 
   it('should invalidate if type is missing', () => {