MCP Schema Enhancement - Automatic JSON Schema Generation from Laravel

[binaryk]

✨ What's New

This release significantly enhances the Model Context Protocol (MCP)
integration by introducing automatic JSON Schema generation from Laravel
validation rules. This allows AI assistants to understand and validate Action
and Getter parameters more effectively.

🚀 Key Features

1. Automatic JSON Schema Generation

• New JsonSchemaFromRulesAction class that converts Laravel validation rules
  to JSON Schema
• Supports 60+ Laravel validation rules including:
  • String validations (email, url, uuid, ip, json, etc.)
  • Numeric validations (integer, numeric, min, max, between, etc.)
  • Date validations (date, before, after, before_or_equal, after_or_equal)
  • Array validations (array, in, not_in, distinct, etc.)
  • File validations (file, image, mimes, mimetypes, dimensions)
  • Custom rule objects (Email, Password, File, etc.)
• Comprehensive schema attributes with 2,800+ lines of validation-to-schema
  mappings

2. Enhanced Actions

• Added description() method to provide context for MCP tools
• Added rules() method for validation
• Added toolSchema() method that automatically generates JSON Schema from
  validation rules
• New HasSchemaResolver concern for schema generation

3. Enhanced Getters

• Added description property and description() method
• Added rules() method for validation
• Added toolSchema() method with automatic schema generation
• Parity with Actions functionality

4. Improved MCP Tool Schema Generation

• ActionTool now uses custom descriptions and auto-generated schemas
• GetterTool now uses custom descriptions and auto-generated schemas
• Better parameter documentation for AI assistants
• Consistent schema structure across all MCP tools

5. Field Schema Detection Improvements

• Enhanced FieldMcpSchemaDetection with better type inference
• Improved field validation schema generation
• Better support for nested fields and arrays

📝 Examples

Before:
class MyAction extends Action
{
public function handle(ActionRequest $request)
{
// action logic
}
}

After:
class MyAction extends Action
{
public string $description = 'Archive selected posts and notify authors';

  public function rules(): array
  {
      return [
          'reason' => ['required', 'string', 'max:255'],
          'notify' => ['boolean'],
          'scheduled_at' => ['nullable', 'date', 'after:now'],
      ];
  }

  public function handle(ActionRequest $request)
  {
      // action logic
  }

}

The MCP server will automatically generate a JSON Schema with:

• reason: string (required, max 255 characters)
• notify: boolean
• scheduled_at: string/date (nullable, must be after current time)

🔧 Technical Changes

• New Files:
  • src/MCP/Actions/JsonSchemaFromRulesAction.php - Core schema conversion
    logic
  • src/MCP/Actions/SchemaAttributes.php - Comprehensive validation rule
    handlers
  • src/Actions/Concerns/HasSchemaResolver.php - Schema resolution trait
  • tests/MCP/JsonSchemaFromRulesActionTest.php - Test coverage
• Enhanced Files:
  • src/Actions/Action.php - Added schema methods
  • src/Getters/Getter.php - Added schema methods and description support
  • src/MCP/Tools/Operations/ActionTool.php - Improved schema generation
  • src/MCP/Tools/Operations/GetterTool.php - Improved schema generation
  • src/MCP/RestifyServer.php - Enhanced pagination settings

🧪 Testing

• Added comprehensive tests for JSON Schema generation
• Added tests for field schema validation
• Improved MCP integration tests

📦 Migration Guide

No breaking changes. Existing Actions and Getters will continue to work
without modification. To leverage the new features:

1. Add a description property/method to your Actions or Getters
2. Implement the rules() method to define validation rules
3. The toolSchema() method will automatically generate JSON Schema from your
   rules

🎯 Benefits

• Better AI Integration: AI assistants get precise parameter documentation
• Type Safety: Automatic validation schema generation from your existing
  rules
• Consistency: Same validation rules used for both runtime validation and MCP
  schema
• Developer Experience: Less boilerplate, more functionality out of the box