php-mcp/schema

🎉 Initial Stable Release

I'm excited to announce the first stable release of php-mcp/schema, a comprehensive PHP implementation of Data Transfer Objects (DTOs) and Enums for the Model Context Protocol (MCP).

📋 Overview

This package provides type-safe PHP representations of the complete MCP specification, enabling robust server and client implementations with full schema compliance.

MCP Schema Version Support: 2025-03-26 (Latest)

🚀 Key Features

Core DTOs and Schema Support

• Complete MCP Schema Coverage: Full implementation of all MCP protocol types
• Type Safety: Strongly-typed PHP classes with readonly properties for immutability
• JSON Serialization: Built-in JsonSerializable support for seamless API communication
• Validation: Comprehensive input validation with meaningful error messages

Protocol Components

🛠️ Tools & Resources

• Tool - Tool definitions with JSON Schema validation
• Resource - Static resource representations
• ResourceTemplate - Dynamic resource templates with URI patterns
• ToolAnnotations - Rich metadata for tool descriptions

📝 Content Types

• TextContent - Plain text content handling
• ImageContent - Image content with MIME type support
• AudioContent - Audio content representation
• BlobResourceContents - Binary resource handling
• EmbeddedResource - Embedded resource content

🔄 Communication Layer

• JSON-RPC 2.0: Complete implementation (Request, Response, Error, Notification)
• Batch Operations: Support for batch requests and responses
• Message Parsing: Robust JSON-RPC message parsing utilities

📨 Request & Response Types

• 15 Request Types: From InitializeRequest to CreateSamplingMessageRequest
• 12 Result Types: Corresponding response objects for all operations
• 9 Notification Types: Real-time event notifications

🎯 Prompts & Capabilities

• Prompt - Interactive prompt definitions
• PromptArgument - Structured prompt parameters
• ClientCapabilities & ServerCapabilities - Capability negotiation
• ModelPreferences - LLM model preference specifications

Developer Experience Features

🏭 Factory Methods

Every DTO includes convenient static factory methods:

$tool = Tool::make('calculator', $schema, 'A calculator tool');
$resource = Resource::make('/api/data', 'Dataset', 'Sample dataset');

🔄 Array Conversion

Seamless conversion between PHP objects and arrays:

// To array (for JSON encoding)
$toolArray = $tool->toArray();

// From array (from JSON decoding)  
$tool = Tool::fromArray($decodedData);

✅ Input Validation

Comprehensive validation with descriptive error messages:

• Required field validation
• Type checking
• Schema compliance verification
• JSON Schema validation for tool inputs

📦 Installation

composer require php-mcp/schema

Requirements:

• PHP 8.1 or higher
• No additional dependencies

🎯 Use Cases

• MCP Server Development: Build compliant MCP servers with type safety
• MCP Client Development: Create robust clients with validated schemas
• API Integration: Seamless JSON serialization for MCP communication
• Testing: Mock MCP protocol interactions with real schema objects
• Documentation: Self-documenting code with comprehensive type hints

🔧 Architecture Highlights

• Immutable Design: Readonly properties prevent accidental mutations
• PSR Compliance: Follows PHP standards and best practices
• Zero Dependencies: Lightweight with no external requirements
• Full Coverage: Every MCP protocol type is represented

📁 Package Structure

src/
├── Content/          # Content type DTOs (Text, Image, Audio, etc.)
├── Enum/            # Protocol enums (LoggingLevel, Role)
├── JsonRpc/         # JSON-RPC protocol implementation
├── Notification/    # Notification message types
├── Request/         # Request message types  
├── Result/          # Response result types
├── Tool.php         # Core tool definitions
├── Resource.php     # Resource representations
├── Prompt.php       # Prompt definitions
└── ...             # Additional core types

🛣️ What's Next

This stable release provides the foundation for the broader PHP MCP ecosystem:

• php-mcp/server: SDK for MCP server implementation
• php-mcp/client: SDK for MCP client implementation
• php-mcp/laravel: Laravel integration package

📖 Documentation

• Package README
• Model Context Protocol Specification
• MCP Schema Reference

🤝 Contributing

Contributions are welcome! This package aims to maintain 100% compatibility with the official MCP specification.

📄 License

MIT License - see LICENSE file for details.