mcp-schema-php

MCP Schema PHP

PHP Data Transfer Objects (DTOs), Builders, and Factories for the Model Context Protocol (MCP).

Overview

This package provides typed PHP classes for the MCP protocol schema. Use it as a foundation for building MCP servers or clients in PHP.

What this is:

• DTOs with fromArray()/toArray() for JSON-RPC message handling
• Fluent Builders for constructing complex objects
• Factories for routing polymorphic union types

What this is NOT:

• Not an MCP SDK (no client/server implementation)
• Not a transport layer (STDIO, HTTP, SSE are your responsibility)

Installation

composer require automattic/mcp-schema

Requirements: PHP 7.4+

Quick Start

use Automattic\MCP\Schema\Server\Tools\Dto\CallToolRequest;
use Automattic\MCP\Schema\Server\Tools\Builder\ToolBuilder;
use Automattic\MCP\Schema\Common\Protocol\Factory\ClientRequestFactory;

// 1. Parse incoming JSON-RPC request
$data = json_decode($jsonRpc, true);
$request = ClientRequestFactory::create($data);

// 2. Handle based on request type
if ($request instanceof CallToolRequest) {
    $toolName = $request->getParams()->getName();
    $arguments = $request->getParams()->getArguments();
    // ... execute tool
}

// 3. Build response using DTOs
$result = (new CallToolResultBuilder())
    ->content([$textContent])
    ->build();

Schema Structure

Type	Count	Purpose
DTOs	179	Immutable data objects with validation
Builders	114	Fluent construction for complex DTOs
Factories	9	Polymorphic union type routing
Unions	15	Type-safe union interfaces
Enums	3	Class-based enums (PHP 7.4 compatible)

Namespace Pattern

Automattic\MCP\Schema\{Domain}\{Subdomain}\{Type}\{Class}

Examples:
  Server\Tools\Dto\Tool
  Server\Tools\Builder\ToolBuilder
  Common\Protocol\Factory\ClientRequestFactory

Domain Organization

Domain	Purpose	Contains
Server/	Handle client requests	Tools, Resources, Prompts, Logging
Client/	Handle server requests	Sampling, Elicitation, Roots
Common/	Shared types	Protocol, Lifecycle, Tasks, Content

Core Patterns

1. DTO (fromArray/toArray)

All DTOs support bidirectional array transformation:

use Automattic\MCP\Schema\Server\Tools\Dto\Tool;

// Deserialize from JSON-RPC data
$tool = Tool::fromArray($data);

// Access typed properties
$name = $tool->getName();
$description = $tool->getDescription();
$inputSchema = $tool->getInputSchema();

// Serialize back to array
$array = $tool->toArray();

2. Builder (Fluent Construction)

Builders provide fluent APIs for constructing DTOs with 2+ parameters:

use Automattic\MCP\Schema\Server\Tools\Builder\ToolBuilder;
use Automattic\MCP\Schema\Server\Tools\Builder\ToolInputSchemaBuilder;

$tool = (new ToolBuilder())
    ->name('calculator')
    ->description('Performs arithmetic operations')
    ->inputSchema(
        (new ToolInputSchemaBuilder())
            ->type('object')
            ->properties([
                'operation' => ['type' => 'string', 'enum' => ['add', 'subtract']],
                'a' => ['type' => 'number'],
                'b' => ['type' => 'number'],
            ])
            ->required(['operation', 'a', 'b'])
            ->build()
    )
    ->build();

3. Factory (Union Routing)

Factories instantiate the correct type from polymorphic union data:

use Automattic\MCP\Schema\Common\Protocol\Factory\ClientRequestFactory;
use Automattic\MCP\Schema\Server\Tools\Dto\ListToolsRequest;
use Automattic\MCP\Schema\Server\Tools\Dto\CallToolRequest;

$request = ClientRequestFactory::create($jsonRpcData);

// Route by type
match (get_class($request)) {
    ListToolsRequest::class => handleListTools($request),
    CallToolRequest::class => handleCallTool($request),
    default => methodNotFound(),
};

4. Response Building

use Automattic\MCP\Schema\Common\Protocol\Builder\JSONRPCResultResponseBuilder;
use Automattic\MCP\Schema\Server\Tools\Builder\ListToolsResultBuilder;

$result = (new ListToolsResultBuilder())
    ->tools([$tool1, $tool2])
    ->build();

$response = (new JSONRPCResultResponseBuilder())
    ->id($request->getId())
    ->result($result)
    ->build();

echo json_encode($response->toArray());

Key Classes by Capability

Server Capabilities

Capability	Key Classes
Tools	Tool, CallToolRequest, CallToolResult, ToolBuilder
Resources	Resource, ResourceTemplate, ReadResourceRequest, ResourceBuilder
Prompts	Prompt, PromptArgument, GetPromptRequest, PromptBuilder

Client Capabilities

Capability	Key Classes
Sampling	CreateMessageRequest, CreateMessageResult, SamplingMessage
Elicitation	ElicitRequest, ElicitResult, ElicitRequestParamsFactory
Roots	ListRootsRequest, ListRootsResult, Root

Common Types

Category	Key Classes
Protocol	JSONRPCRequest, JSONRPCResultResponse, JSONRPCErrorResponse
Factories	ClientRequestFactory, ServerRequestFactory, ContentBlockFactory
Lifecycle	InitializeRequest, InitializeResult, PingRequest

Important: MCP Naming Convention

MCP naming is counterintuitive. Names indicate who sends the message:

Term	Meaning	Handle In
ClientRequest	Request sent by client	Server code
ServerRequest	Request sent by server	Client code

Think: "ClientRequest" = "Request that the Client sends"

Claude Code Integration

This package includes a skill for Claude Code that provides contextual documentation when working with MCP in PHP.

composer run mcp-schema:install-claude-skill

This copies documentation to your project's .claude/ directory, enabling Claude to provide accurate, context-aware assistance when building MCP servers or clients.

Development

# Run tests
composer test

# Static analysis (PHPStan level 8)
composer analyse

License

GPL-2.0-or-later. See LICENSE for details.

Links

• MCP Specification
• GitHub Issues