[bug]: Failed to validate tool mcp_devantler-tec_ksail_cluster_read: Error: tool parameters array type must have items. Please open an issue for the MCP server or extension which provides this tool

[devantler]

Expected Behavior

MCP Server should work

Actual Behavior

MCP Server does not work

Steps to Replicate

Try to add the MCP Server to VSCode, and notice that it fails during validation when you send off a prompt:

"github-agentic-workflows": {
  "command": "gh",
  "args": [
    "aw",
    "mcp-server"
  ],
},

[github-actions]

🎉 Yo ho ho! Agentic Triage found the treasure and completed successfully! ⚓💰

[botantler]

🎯 Agentic Issue Triage

This is a valid bug in the MCP tool generation code. The issue occurs when consolidated tools (like cluster_read or cluster_write) contain flags with array types.

📋 Issue Analysis

Problem: The MCP server validation fails with error: tool parameters array type must have items

Root Cause: In /pkg/ai/toolgen/generator.go, the addFlagProperties function (lines 706-744) does not add the items field when setting array-type properties for consolidated tools. This violates the JSON Schema specification which requires array types to define their item structure.

Affected Code:

• Location: pkg/ai/toolgen/generator.go:712-714
• Current behavior: Only sets "type": flagDef.Type for all flag types
• Expected behavior: For array types, should also set "items" field similar to how buildStandardProperty does it (lines 232-236)

🔍 Reproduction Steps

1. Add the KSail MCP server to VSCode's mcp.json:

   {
     "servers": {
       "github-agentic-workflows": {
         "command": "gh",
         "args": ["aw", "mcp-server"]
       }
     }
   }

2. Attempt to use the MCP server by sending a prompt in VSCode

3. The validation will fail for tools like ksail_cluster_read that have array-type flags (e.g., stringSlice, intSlice)

🛠️ Debugging Strategy

1. Identify array-typed flags: Check which cluster subcommands have array-type flags (stringSlice, stringArray, intSlice)
2. Verify the schema: Run the MCP server and inspect the tool schemas being generated
3. Compare implementations: Note that buildStandardProperty() correctly handles array types but addFlagProperties() doesn't

✅ Proposed Fix

In pkg/ai/toolgen/generator.go, modify the addFlagProperties function to add items field for array types:

func addFlagProperties(
	properties map[string]any,
	allFlags map[string]*FlagDef,
	totalSubcommands int,
) {
	for flagName, flagDef := range allFlags {
		prop := map[string]any{
			"type": flagDef.Type,
		}
		
		// Add items field for array types
		if flagDef.Type == jsonSchemaTypeArray {
			// Determine item type based on flag name or default to string
			// For now, default to string items (can be enhanced later)
			prop["items"] = map[string]any{"type": jsonSchemaTypeString}
		}

		// ... rest of the function
	}
}

Note: The fix should ideally preserve the specific item type (string vs integer) from the original flag definition. This may require enhancing FlagDef to include item type information, or inferring it from the flag type name.

📚 Relevant Resources

• JSON Schema Array Specification - Explains why items is required for array types
• MCP SDK Tool Validation - The Go MCP SDK documentation
• Related code:
  • pkg/ai/toolgen/generator.go:232-236 - Correct implementation in buildStandardProperty
  • pkg/ai/toolgen/generator.go:712-714 - Buggy implementation in addFlagProperties
  • pkg/cli/cmd/cluster/cluster.go:22 - Where consolidate annotation is set

✨ Implementation Checklist

• Enhance FlagDef struct to include ItemType field for array flags
• Update extractFlags() to capture item type information from array flags
• Modify addFlagProperties() to add items field when Type == jsonSchemaTypeArray
• Add unit tests for consolidated tools with array-type flags
• Test the fix with VSCode MCP client integration
• Verify no regression in non-consolidated tools

AI generated by Agentic Triage