[bug]: Too many tools in MCP server

[devantler]

Expected Behavior

Completion command tools is excluded

Actual Behavior

Steps to Replicate

Check ksail tools in VSCode tools viewer

[github-actions]

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

[botantler]

🎯 Agentic Issue Triage

Summary

The MCP server is exposing shell completion commands (bash, fish, powershell, zsh) as tools in VSCode's MCP tools viewer. These should be excluded since they're shell completion utilities, not operational tools for AI interaction.

📋 Issue Analysis

Root Cause: The completion command is auto-added by Cobra and includes subcommands for various shells. While "ksail completion" is in the exclusion list in toolgen.DefaultOptions(), Cobra's completion implementation creates a parent command with runnable subcommands (bash, fish, powershell, zsh), and these subcommands are not being filtered out.

Current Exclusion List (in pkg/ai/toolgen/options.go):

ExcludeCommands: []string{
    "ksail chat",       // Chat interface, not a tool
    "ksail mcp",        // MCP server itself, not a tool
    "ksail completion", // Shell completion generator
    "ksail help",       // Help command, not a tool
    "ksail",            // Root command, not a tool
},

Problem: The exclusion only matches the parent "ksail completion" command, but the tool generator still processes its subcommands because:

1. The exclusion check in shouldExclude() only checks the exact command path
2. Child commands like "ksail completion bash" don't match "ksail completion" exactly
3. The hasExcludeAnnotation() check would catch this, but completion commands lack the annotation since they're auto-generated by Cobra

🔍 Debugging Strategy

1. Verify the completion subcommands are the issue:

   • Run ksail --help and check if completion subcommands appear
   • Inspect the generated MCP tools to confirm which completion-related tools are exposed

2. Test the exclusion logic:

   • Add all completion subcommands explicitly to the exclusion list:

     "ksail completion bash",
     "ksail completion fish",
     "ksail completion powershell",
     "ksail completion zsh",

   • Or improve the exclusion logic to handle parent-child relationships

3. Validate the fix:

   • Build the MCP server
   • Connect it to VSCode
   • Verify completion tools are no longer visible in the tools viewer

💡 Proposed Solutions

Option 1: Explicit Subcommand Exclusions (Quick Fix)

Add each completion subcommand to the exclusion list in pkg/ai/toolgen/options.go:

ExcludeCommands: []string{
    // Meta commands - not useful as tools
    "ksail chat",       
    "ksail mcp",        
    "ksail completion", 
    "ksail completion bash",
    "ksail completion fish",
    "ksail completion powershell",
    "ksail completion zsh",
    "ksail help",       
    "ksail",            
},

Pros: Simple, immediate fix
Cons: Must update if Cobra adds new completion shells

Option 2: Hierarchical Exclusion Logic (Robust)

Modify shouldExclude() in pkg/ai/toolgen/generator.go to exclude children of excluded commands:

func shouldExclude(cmd *cobra.Command, opts ToolOptions) bool {
    // Check hidden commands
    if cmd.Hidden && !opts.IncludeHidden {
        return true
    }

    // Check exclusion list for exact match or parent match
    cmdPath := cmd.CommandPath()
    for _, excluded := range opts.ExcludeCommands {
        // Exact match or child of excluded parent
        if cmdPath == excluded || strings.HasPrefix(cmdPath, excluded+" ") {
            return true
        }
    }

    return false
}

Pros: Automatically handles all current and future subcommands
Cons: Slightly more complex logic

Option 3: Disable Cobra's Completion Command (Cleanest)

Disable the auto-generated completion command entirely in pkg/cli/cmd/root.go:

func NewRootCmd(version, commit, date string) *cobra.Command {
    // ... existing code ...
    
    cmd.CompletionOptions.DisableDefaultCmd = true
    
    return cmd
}

Pros: Eliminates the problem at the source, no manual shell completion management needed
Cons: Removes built-in shell completion feature (may want to keep this for users)

Recommendation

Use Option 2 (Hierarchical Exclusion Logic) as it's the most robust solution that maintains the completion feature for CLI users while properly excluding it from AI tool generation. This also protects against similar issues with other command hierarchies in the future.

🔗 Related Context

• Related Issue: [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 #1976 - MCP Server validation failures (also MCP-related)
• Original Feature: [feature]: Add MCP Server #1948 - Add MCP Server (completed)
• Code Locations:
  • pkg/ai/toolgen/options.go - Default exclusion list
  • pkg/ai/toolgen/generator.go - Tool generation and exclusion logic
  • pkg/svc/mcp/server.go - MCP server implementation
  • pkg/cli/cmd/root.go - Root command where completion is auto-added

📚 Learning Resources

• Cobra Command Line Library - Understanding auto-generated commands
• [MCP Protocol Documentation]((redacted) - MCP tool specification
• MCP Go SDK - SDK used by KSail
• Cobra Completion Guide - How Cobra's completion works

AI generated by Agentic Triage