README

Type-safe PHP DTOs for the Model Context Protocol (MCP) specification.

This package provides comprehensive Data Transfer Objects and Enums that ensure full compliance with the official MCP schema, enabling robust server and client implementations with complete type safety.

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

Installation

composer require php-mcp/schema

Requirements: PHP 8.1+ • No dependencies

Quick Start

use PhpMcp\Schema\Tool;
use PhpMcp\Schema\Resource;
use PhpMcp\Schema\Request\CallToolRequest;

// Create a tool definition
$tool = Tool::make(
    name: 'calculator',
    inputSchema: [
        'type' => 'object',
        'properties' => [
            'operation' => ['type' => 'string'],
            'a' => ['type' => 'number'],
            'b' => ['type' => 'number']
        ],
        'required' => ['operation', 'a', 'b']
    ],
    description: 'Performs basic arithmetic operations'
);

// Serialize to JSON
$json = json_encode($tool);

// Deserialize from array
$tool = Tool::fromArray($decodedData);

Core Features

🏗️ Complete Schema Coverage

Every MCP protocol type is represented with full validation and type safety.

🔒 Immutable Design

All DTOs use readonly properties to prevent accidental mutations.

🚀 Developer Experience

• Factory Methods: Convenient make() methods for fluent object creation
• Array Conversion: Seamless toArray() and fromArray() methods
• JSON Ready: Built-in JsonSerializable interface support
• Validation: Comprehensive input validation with clear error messages

📦 Schema Components

Usage Patterns

Creating Protocol Messages

// Initialize request
$request = InitializeRequest::make(
    protocolVersion: '2025-03-26',
    capabilities: ClientCapabilities::make(),
    clientInfo: Implementation::make('MyClient', '1.0.0')
);

// Call tool request  
$callRequest = CallToolRequest::make(
    name: 'calculator',
    arguments: ['operation' => 'add', 'a' => 5, 'b' => 3]
);

Working with Resources

// Static resource
$resource = Resource::make(
    uri: '/data/users.json',
    name: 'User Database',
    description: 'Complete user registry'
);

// Resource template
$template = ResourceTemplate::make(
    uriTemplate: '/users/{id}',
    name: 'User Profile',
    description: 'Individual user data'
);

Content Handling

// Text content
$text = TextContent::make('Hello, world!');

// Image content
$image = ImageContent::make(
    data: base64_encode($imageData),
    mimeType: 'image/png'
);

Package Structure

src/
├── Content/         # Content types (Text, Image, Audio, Blob, etc.)
├── Enum/           # Protocol enums (LoggingLevel, Role)
├── JsonRpc/        # JSON-RPC 2.0 implementation
├── Notification/   # Event notification types
├── Request/        # Protocol request messages
├── Result/         # Protocol response messages
├── Tool.php        # Tool definitions
├── Resource.php    # Resource representations
├── Prompt.php      # Prompt definitions
└── ...            # Core protocol types

Why Use This Package?

• ✅ 100% MCP Compliance - Matches official specification exactly
• ✅ Type Safety - Catch errors at development time, not runtime
• ✅ Zero Dependencies - Lightweight and self-contained
• ✅ Production Ready - Immutable, validated, and thoroughly tested
• ✅ Future Proof - Updated with latest MCP specification versions

License

MIT License. See LICENSE for details.

Part of the PHP MCP ecosystem • Build type-safe MCP applications with confidence