mcp-php-schema

name	mcp-php-schema
schema_version	2025-11-25
description	PHP DTOs, Builders, and Factories for the Model Context Protocol (MCP). Use when building MCP servers or clients in PHP, implementing tools/resources/prompts handlers, parsing JSON-RPC messages, or working with MCP protocol types. Triggers: MCP, Model Context Protocol, tools, resources, prompts, sampling, elicitation, roots, factories, CallToolRequest, ToolBuilder, PHP MCP server, PHP MCP client.
globs	["Schema/**/*.php","examples/**/*.php"]

MCP PHP Schema

PHP 7.4+ DTOs for the Model Context Protocol (MCP). Build servers and clients using typed DTOs, fluent Builders, and routing Factories.

---

Quick Start Decision Tree

What are you building?

├─► MCP SERVER (receives client requests)
│   ├─► Define Tools? → ToolBuilder, CallToolRequest
│   ├─► Expose Resources? → ResourceBuilder, ReadResourceRequest
│   └─► Provide Prompts? → PromptBuilder, GetPromptRequest
│   📖 Read: guides/server-guide.md
│
├─► MCP CLIENT (receives server requests)
│   ├─► Handle Sampling? → CreateMessageRequest, CreateMessageResult
│   ├─► Handle Elicitation? → ElicitRequest, ElicitResult
│   └─► Provide Roots? → ListRootsRequest, ListRootsResult
│   📖 Read: guides/client-guide.md
│
└─► QUICK HELLO WORLD?
    📖 Read: guides/quickstart.md

---

Schema Overview

Property	Value
Schema Version	2025-11-25
Namespace Root	Automattic\Mcp\Schema\
DTOs	179
Builders	114
Factories	9
Unions	15
Enums	3

Namespace Pattern

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

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

Domain Structure

Domain	Purpose	Use In
Server/	Tools, Resources, Prompts, Logging	MCP Servers
Client/	Sampling, Elicitation, Roots	MCP Clients
Common/	Protocol, Lifecycle, Tasks, Content	Both

---

Critical Warning: MCP Naming Convention

MCP naming is counterintuitive:

Term	Meaning	Handle In
ClientRequest	Request BY client	Server code
ServerRequest	Request BY server	Client code
ClientNotification	Notification BY client	Server code
ServerNotification	Notification BY server	Client code

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

---

Core 4 Patterns

1. DTO (fromArray/toArray)

use Automattic\Mcp\Schema\Server\Tools\Dto\CallToolRequest;

$request = CallToolRequest::fromArray($jsonData);
$toolName = $request->getParams()->getName();
$array = $response->toArray();

2. Builder (Fluent Construction)

Only DTOs with 2+ parameters have builders.

use Automattic\Mcp\Schema\Server\Tools\Builder\ToolBuilder;

$tool = (new ToolBuilder())
    ->name('calculator')
    ->description('Math operations')
    ->inputSchema($schema)
    ->build();

3. Factory (Union Routing)

use Automattic\Mcp\Schema\Common\Protocol\Factory\ClientRequestFactory;

// Handler map: class name => handler function
$handlers = [
    ListToolsRequest::class => 'handleListTools',
    CallToolRequest::class  => 'handleCallTool',
];

$request = ClientRequestFactory::create($data);
$class = get_class($request);

$response = isset($handlers[$class])
    ? $handlers[$class]($request)
    : methodNotFound();

4. Response Building

use Automattic\Mcp\Schema\Common\Protocol\Builder\JSONRPCResultResponseBuilder;
use Automattic\Mcp\Schema\Common\Core\Dto\Result;

$response = (new JSONRPCResultResponseBuilder())
    ->id($request->getId())
    ->result(Result::fromArray($specificResult->toArray()))
    ->build();

---

"I Want To..." Quick Lookup

Server Operations

Goal	Read	Key Classes
Route incoming requests	reference/factories.md	ClientRequestFactory
Define a tool	domains/server/tools.md	ToolBuilder, ToolInputSchema
Handle tool calls	domains/server/tools.md	CallToolRequest, CallToolResult
Define a resource	domains/server/resources.md	ResourceBuilder, ResourceTemplate
Read resources	domains/server/resources.md	ReadResourceRequest, ReadResourceResult
Define a prompt	domains/server/prompts.md	PromptBuilder, PromptArgument
Get prompts	domains/server/prompts.md	GetPromptRequest, GetPromptResult
Build error response	guides/server-guide.md	JSONRPCErrorResponseBuilder

Client Operations

Goal	Read	Key Classes
Route server requests	reference/factories.md	ServerRequestFactory
Handle sampling	domains/client/sampling.md	CreateMessageRequest, CreateMessageResult
Handle elicitation	domains/client/elicitation.md	ElicitRequest, ElicitResult
Provide roots	domains/client/roots.md	ListRootsRequest, Root
Parse content blocks	reference/factories.md	ContentBlockFactory

Common Operations

Goal	Read	Key Classes
Initialize connection	guides/server-guide.md	InitializeRequest, InitializeResult
Async tasks	domains/client/tasks.md	TaskMetadata, TaskStatus
Pagination	reference/advanced.md	PaginatedRequest, cursor
Logging	reference/advanced.md	LoggingMessageNotification

---

Key Types by Capability

Tools (Server)

Dto: Tool, CallToolRequest, CallToolResult, ListToolsRequest, ListToolsResult
Builder: ToolBuilder, CallToolResultBuilder, ToolInputSchemaBuilder

Resources (Server)

Dto: Resource, ResourceTemplate, ReadResourceRequest, ReadResourceResult
Builder: ResourceBuilder, ReadResourceResultBuilder, TextResourceContentsBuilder

Prompts (Server)

Dto: Prompt, PromptArgument, GetPromptRequest, GetPromptResult
Builder: PromptBuilder, PromptArgumentBuilder, GetPromptResultBuilder

Sampling (Client)

Dto: CreateMessageRequest, CreateMessageResult, SamplingMessage
Builder: CreateMessageResultBuilder, SamplingMessageBuilder
Factory: SamplingMessageContentBlockFactory

Elicitation (Client)

Dto: ElicitRequest, ElicitResult, ElicitRequestFormParams
Builder: ElicitResultBuilder, StringSchemaBuilder, BooleanSchemaBuilder
Factory: ElicitRequestParamsFactory

Roots (Client)

Dto: ListRootsRequest, ListRootsResult, Root, RootsListChangedNotification
Builder: ListRootsResultBuilder, RootBuilder

Protocol (Common)

Dto: JSONRPCRequest, JSONRPCResultResponse, JSONRPCErrorResponse
Builder: JSONRPCResultResponseBuilder, JSONRPCErrorResponseBuilder
Factory: ClientRequestFactory, ServerRequestFactory

---

Navigation

Guides (Start Here)

Guide	Purpose
guides/quickstart.md	5-minute hello world
guides/server-guide.md	Build MCP servers
guides/client-guide.md	Build MCP clients

Domain Deep-Dives

Server Domains	Client Domains
domains/server/tools.md	domains/client/sampling.md
domains/server/resources.md	domains/client/elicitation.md
domains/server/prompts.md	domains/client/roots.md
	domains/client/tasks.md

Reference Documentation

Reference	Contents
reference/factories.md	All 9 factories with discriminators
reference/types-index.md	Complete type lookup table
reference/advanced.md	Pagination, metadata, errors

Copy-Paste Snippets

Server Snippets	Client Snippets
snippets/server/tool-handler.md	snippets/client/sampling-handler.md
snippets/server/resource-handler.md	snippets/client/elicitation-handler.md
snippets/server/prompt-handler.md	snippets/client/roots-handler.md

Working Examples

See examples/ for complete implementations:

• 01-tools-server/ - Tool definitions and handling
• 02-resources-server/ - Resource exposure
• 03-prompts-server/ - Prompt templates
• 04-full-server/ - Complete server
• 05-smart-client/ - Full client implementation

---

Important Notes

1. All DTOs are immutable - Use Builders for construction
2. Schema is protocol only - Transport (STDIO, HTTP) is your responsibility
3. Factories route by discriminator - method for requests, type for content
4. PHP 7.4 compatible - Uses AbstractEnum instead of native enums