feat: add type-safe array items helper functions

• Add ItemsString(), ItemsNumber(), ItemsBoolean() for type-safe array schema construction
• Add ItemsStringEnum() for string enum arrays with cleaner API
• Improve Items() documentation with examples and usage guidance
• Add comprehensive compatibility tests ensuring new APIs generate identical schemas

Description

This PR introduces type-safe helper functions for configuring array items in MCP tool schemas. The original Items() function accepts any type, which can lead to runtime errors when developers accidentally pass incompatible types. These new helper functions provide compile-time type safety for common array element types while maintaining full backward compatibility.

The new functions include:

• ItemsString(opts ...PropertyOption) - for string arrays with optional constraints
• ItemsNumber(opts ...PropertyOption) - for number arrays with optional constraints
• ItemsBoolean(opts ...PropertyOption) - for boolean arrays with optional constraints
• ItemsStringEnum(values []string) - for string enum arrays with predefined values

All functions generate identical JSON schemas to their manual Items() equivalents, ensuring seamless migration and compatibility.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update
• Tests only (no functional changes)

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• I have updated the documentation accordingly

Additional Information

Implementation Scope and Design Decisions

This implementation focuses on simple array types (string, number, boolean) which cover the majority of common use cases. The design maintains the existing functional options pattern for consistency with the broader API.

API Consistency Analysis

During implementation, we identified an interesting API consistency gap: while top-level object properties enjoy full type-safe API support (WithString, WithNumber, etc.), complex object arrays still require manual map[string]any construction.

For example:

// Top-level: Clean, type-safe API ✅
WithString("name", Required(), Description("User name"))

// Array items: Still requires manual construction
Items(map[string]any{
    "type": "object", 
    "properties": map[string]any{...}  // Manual approach
})

Current Solution Sufficiency

Important: The existing manual construction approach using Items(map[string]any{...}) remains fully functional and sufficient for all complex scenarios. It provides complete flexibility for any JSON Schema construct without additional learning overhead.

Future Enhancement Proposal

Based on the API consistency analysis, I would like to respectfully propose considering a future enhancement to introduce an ItemsObject API that could provide type-safe construction for complex object arrays.

The approach I have in mind would use a Property constructor pattern:

// Potential future API
WithArray("products",
    ItemsObject(
        Property("id", WithString(Required(), Description("Product ID"))),
        Property("name", WithString(Required(), Description("Product name"))),
        Property("category", WithString(Enum("electronics", "books"))),
    ))

This would help maintain API consistency between top-level and array item definitions while leveraging existing WithString, WithNumber functions for reusability.

However, I fully understand this would introduce additional API complexity, and I want to be mindful of the project's goals for simplicity and maintainability.

Question for maintainers:

Would this direction be worth exploring in a future proposal, or would you prefer to keep the current manual construction approach as the primary solution for complex object arrays?

I'm very open to feedback and happy to discuss the trade-offs between API consistency and simplicity. If this isn't the right direction for the project, I completely understand and respect that decision.

Backward Compatibility

• All existing code continues to work without changes
• New functions are fully tested with compatibility tests verifying identical schema generation
• The manual Items() approach remains the recommended solution for complex object arrays
• Zero breaking changes to existing APIs

This implementation strikes a balance between improving developer experience for common cases while maintaining simplicity and full backward compatibility.

Summary by CodeRabbit

• New Features
  • Introduced specialized options for configuring array item types in schemas, including helpers for string, string enum, number, and boolean types.
• Documentation
  • Enhanced documentation with usage examples for new and existing array item configuration options.
• Tests
  • Added tests to ensure the new array item helpers produce schemas consistent with previous methods.