MCP Server Parameter Hints and Validation¶

This document describes the enhanced parameter hints and validation system for the Gira MCP server, designed to improve usability and reduce command errors.

Overview¶

The parameter hints system provides: - Enhanced Error Messages: Detailed error messages with examples and suggestions - Interactive Help: Context-aware help for all commands and parameters - Parameter Validation: Comprehensive validation with type hints and examples - Auto-Documentation: Automatically generated documentation with usage examples - Interactive Builder: Step-by-step parameter building with suggestions

Features¶

1. Enhanced Error Messages¶

Instead of generic validation errors, the system now provides detailed, actionable feedback:

Before:

ValidationError: Field required

After:

Error in 'create_ticket': Parameter validation failed for 'priority'

Parameter: priority
Expected: Priority
Received: str = "urgent"

Valid values:
  low, medium, high, critical

Examples:
  • high - High priority item
  • critical - Urgent issue requiring immediate attention

Tips:
  • Priority values are case-insensitive
  • Use 'critical' for urgent issues requiring immediate attention

2. Interactive Help System¶

Get comprehensive help for any command:

{
  "command": "help",
  "parameters": {
    "command": "create_ticket"
  }
}

Response:

{
  "help": "# create_ticket\n\nCreate a new ticket in the project\n\n## Parameters\n\n**title** (str)\n  Ticket title\n  ✅ Required\n  💡 Examples:\n    • Implement user authentication - Feature title\n    • Fix login bug with empty passwords - Bug fix title\n  💭 Tips:\n    • Keep titles concise but descriptive\n    • Use imperative mood (e.g., 'Fix bug' not 'Fixed bug')\n\n..."
}

3. Parameter Suggestions¶

Get context-aware suggestions for any parameter:

{
  "command": "get_parameter_suggestions",
  "parameters": {
    "command": "create_ticket",
    "parameter": "type",
    "current_value": "feat"
  }
}

Response:

{
  "command": "create_ticket",
  "parameter": "type",
  "available_values": ["feature", "bug", "task", "epic", "story", "improvement", "documentation"],
  "validation": {
    "valid": false,
    "errors": ["Invalid value 'feat'. Valid values: feature, bug, task, epic, story, improvement, documentation"],
    "suggestions": ["Did you mean 'feature'?"]
  },
  "examples": [
    {"value": "feature", "description": "New functionality"},
    {"value": "bug", "description": "Bug fix"}
  ]
}

4. Interactive Parameter Builder¶

Build command parameters step-by-step with guidance:

{
  "command": "build_parameters",
  "parameters": {
    "command": "create_ticket",
    "action": "start"
  }
}

Response:

{
  "command": "create_ticket",
  "action": "start",
  "parameters": {},
  "suggestions": [
    {
      "name": "title",
      "type": "str",
      "required": true,
      "description": "Ticket title",
      "examples": [
        {"value": "Implement user authentication", "description": "Feature title"},
        {"value": "Fix login bug", "description": "Bug fix title"}
      ]
    }
  ]
}

5. Command Examples¶

Get usage examples for any command:

{
  "command": "get_command_examples",
  "parameters": {
    "command": "create_ticket",
    "scenario": "basic"
  }
}

Response:

{
  "command": "create_ticket",
  "scenario": "basic",
  "examples": [
    {
      "parameters": {
        "title": "Implement user authentication",
        "description": "Add JWT-based authentication with login/logout endpoints",
        "type": "feature",
        "priority": "high",
        "labels": ["backend", "security"]
      },
      "description": "Example 1 for create_ticket",
      "use_case": "Creating a feature ticket with full details"
    }
  ]
}

Command Reference¶

Help Commands¶

`help`¶

Get comprehensive help information for MCP commands.

Parameters: - command (optional): Command name to get help for - format (optional): Output format (detailed, brief, json) - parameter (optional): Get help for specific parameter

Examples:

// List all commands
{"command": "help"}

// Get detailed help for a command
{"command": "help", "parameters": {"command": "create_ticket"}}

// Get help for specific parameter
{"command": "help", "parameters": {"command": "create_ticket", "parameter": "priority"}}

// Get help in JSON format
{"command": "help", "parameters": {"command": "create_ticket", "format": "json"}}

`get_parameter_suggestions`¶

Get suggestions and validation info for command parameters.

Parameters: - command (required): Command name - parameter (required): Parameter name - current_value (optional): Current parameter value to validate

`build_parameters`¶

Interactive parameter builder with validation.

Parameters: - command (required): Command name to build parameters for - action (required): Builder action (start, add, validate, complete) - parameter_name (optional): Parameter name (for add action) - parameter_value (optional): Parameter value (for add action) - current_params (optional): Current parameters being built

`get_command_examples`¶

Get usage examples for commands.

Parameters: - command (required): Command name - scenario (optional): Type of examples (basic, advanced, minimal, all)

`validate_command_parameters`¶

Validate parameters for a command before execution.

Parameters: - command (required): Command name - parameters (required): Parameters to validate - include_suggestions (optional): Include helpful suggestions

`search_commands`¶

Search for commands by name or functionality.

Parameters: - query (required): Search query - format (optional): Output format (brief, detailed)

Integration Guide¶

For MCP Clients¶

Error Handling: Parse enhanced error responses for user-friendly messages
Help Integration: Use the help system to provide contextual assistance
Parameter Building: Implement interactive parameter builders using the builder API
Validation: Validate parameters before sending commands

For Command Implementation¶

Use Enhanced Decorators: Apply @enhanced_mcp_tool to new commands
Define Pydantic Models: Create comprehensive parameter models with validation
Add Help Support: Ensure commands support --help and validate_only flags
Register Help Info: Register comprehensive help information for all commands

Example Enhanced Command¶

from gira.mcp.enhanced_tools import enhanced_mcp_tool
from gira.mcp.schema import TicketCreateParams

@enhanced_mcp_tool(
    name="create_ticket",
    description="Create a new ticket with enhanced validation and help",
    schema_model=TicketCreateParams,
    is_destructive=True
)
def create_ticket(
    title: str,
    description: Optional[str] = None,
    type: str = "task",
    priority: str = "medium",
    assignee: Optional[str] = None,
    epic_id: Optional[str] = None,
    labels: Optional[List[str]] = None,
    story_points: Optional[int] = None
) -> Dict[str, Any]:
    """Create a new ticket with comprehensive validation."""
    # Implementation here
    pass

Configuration¶

Help System Configuration¶

The help system is automatically initialized with built-in command information. To customize:

from gira.mcp.help_system import help_registry, CommandHelp, ParameterHint

# Register custom command help
custom_help = CommandHelp(
    name="my_command",
    description="My custom command",
    parameters=[
        ParameterHint(
            name="param1",
            type_name="str",
            description="First parameter",
            required=True,
            examples=[ParameterExample("value1", "Example value")]
        )
    ],
    usage_examples=[{"param1": "example"}],
    related_commands=["other_command"]
)

help_registry.register_command_help(custom_help)

Enhanced Validation Configuration¶

Enable enhanced validation for existing commands:

from gira.mcp.enhanced_tools import initialize_enhanced_features

# Initialize enhanced features during server startup
initialize_enhanced_features()

Best Practices¶

For Parameter Design¶

Use Descriptive Names: Choose clear, unambiguous parameter names
Provide Examples: Include realistic examples for complex parameters
Add Validation Rules: Define clear validation rules with helpful messages
Include Suggestions: Provide actionable suggestions for common mistakes

For Error Messages¶

Be Specific: Explain exactly what's wrong and why
Provide Examples: Show correct parameter formats
Suggest Solutions: Offer concrete steps to fix the issue
Include Context: Reference related parameters or commands

For Help Content¶

Write Clear Descriptions: Use plain language and avoid jargon
Include Common Workflows: Show how commands fit into larger processes
Provide Troubleshooting: Address common issues and solutions
Keep Examples Current: Ensure examples reflect actual usage patterns

Troubleshooting¶

Common Issues¶

Help not displaying for custom commands - Ensure command help is registered with help_registry.register_command_help() - Check that command names match exactly - Verify help initialization runs before command usage

Enhanced validation not working - Apply @enhanced_mcp_tool decorator or call initialize_enhanced_features() - Ensure Pydantic models are properly defined with field descriptions - Check that validation errors are properly handled

Parameter suggestions not appearing - Verify parameter hints are defined with examples and suggestions - Check that command help includes parameter information - Ensure parameter names match between schema and help definitions

Builder not providing suggestions - Register comprehensive parameter hints with examples - Include enum values for choice parameters - Add validation rules and common mistake patterns

Debugging¶

Enable debug logging to troubleshoot issues:

import logging
logging.getLogger('gira.mcp.help_system').setLevel(logging.DEBUG)
logging.getLogger('gira.mcp.enhanced_validation').setLevel(logging.DEBUG)

Check help registry contents:

from gira.mcp.help_system import help_registry
print("Registered commands:", help_registry.list_commands())

Validate parameter definitions:

from gira.mcp.enhanced_validation import EnhancedParameterValidator
validator = EnhancedParameterValidator("create_ticket")
result = validator.validate_parameters(params, TicketCreateParams)
print("Validation result:", result.to_dict())

Migration Guide¶

Upgrading Existing Commands¶

Add Enhanced Decorator: Replace @register_tool with @enhanced_mcp_tool
Create Pydantic Model: Define comprehensive parameter schema
Register Help Information: Add detailed help with examples
Update Error Handling: Use enhanced error types
Test Validation: Verify parameter validation works correctly

Updating Clients¶

Parse Enhanced Errors: Handle detailed error responses
Implement Help Integration: Use help commands for user assistance
Add Parameter Building: Implement interactive parameter builders
Update Error Display: Show enhanced error messages to users

This enhanced parameter hints system significantly improves the developer experience when working with MCP commands, reducing errors and providing comprehensive guidance for correct usage.

MCP Server Parameter Hints and Validation¶

Overview¶

Features¶

1. Enhanced Error Messages¶

2. Interactive Help System¶

3. Parameter Suggestions¶

4. Interactive Parameter Builder¶

5. Command Examples¶

Command Reference¶

Help Commands¶

help¶

get_parameter_suggestions¶

build_parameters¶

get_command_examples¶

validate_command_parameters¶

search_commands¶

Integration Guide¶

For MCP Clients¶

For Command Implementation¶

Example Enhanced Command¶

Configuration¶

Help System Configuration¶

Enhanced Validation Configuration¶

Best Practices¶

For Parameter Design¶

For Error Messages¶

For Help Content¶

Troubleshooting¶

Common Issues¶

Debugging¶

Migration Guide¶

Upgrading Existing Commands¶

Updating Clients¶

`help`¶

`get_parameter_suggestions`¶

`build_parameters`¶

`get_command_examples`¶

`validate_command_parameters`¶

`search_commands`¶