PHP MCP SDK

Developers declare MCP capabilities (tools, resources, prompts) using PHP attributes (#[McpTool], #[McpResource], #[McpPrompt]) on class methods. The SDK's Discoverer and SchemaGenerator components automatically parse DocBlocks and method signatures using phpdocumentor/reflection-docblock to generate JSON Schema definitions for each capability, eliminating manual schema maintenance. This approach integrates with the Builder pattern to accumulate and register capabilities during server initialization.

The Server\Builder class (src/Server/Builder.php) implements a fluent builder pattern that accumulates MCP server configuration through method chaining. Developers call methods like ->addTool(), ->addResource(), ->addPrompt() to register capabilities, then ->build() constructs the complete Server instance with all dependencies wired. The builder manages capability loaders (ArrayLoader, Discoverer), transport configuration, session stores, and request handlers, providing a single assembly point that enforces initialization order and dependency injection.

The SDK implements comprehensive error handling that catches exceptions during capability execution and converts them to MCP-compliant error responses with proper error codes and messages. The error handling pipeline includes validation errors (argument schema mismatches), execution errors (capability handler exceptions), and protocol errors (malformed requests). Each error type is mapped to an appropriate MCP error code (e.g., -32600 for invalid request, -32603 for internal error), with detailed error messages for debugging.

The Server class implements the core MCP protocol message routing logic, handling JSON-RPC 2.0 serialization and deserialization of all MCP requests and responses. The protocol layer routes incoming requests (tools/call, resources/read, prompts/get, etc.) to appropriate request handlers, manages request/response correlation via JSON-RPC IDs, and handles notifications (one-way messages without response). The transport layer abstracts the underlying communication mechanism (STDIO, HTTP), while the protocol layer remains transport-agnostic.

The SDK includes a CompletionProvider capability that allows MCP servers to provide completion suggestions to AI clients, enhancing LLM context with dynamic suggestions based on partial input. Completion providers receive partial text and return a list of completion options with descriptions. This capability is useful for exposing autocomplete functionality, command suggestions, or context-aware recommendations to AI clients. Completion providers are defined similarly to tools and resources, with a handler that generates completions based on input.

The SDK includes built-in testing infrastructure with conformance tests that validate MCP protocol compliance and inspector-based testing that captures and validates server behavior. The Inspector component intercepts all MCP messages (requests, responses, notifications) and records them for analysis. Conformance tests verify that the server correctly implements MCP specification requirements (e.g., proper error codes, valid response formats). This enables developers to validate their MCP servers against the specification without manual testing.

The SDK abstracts communication transport through a Transport interface with concrete implementations for STDIO (StdioTransport) and HTTP (StreamableHttpTransport). The Server class routes all MCP protocol messages through the selected transport, handling JSON-RPC 2.0 serialization, message framing, and bidirectional communication. This abstraction allows the same server logic to run in CLI environments (STDIO) or as HTTP endpoints without code changes, with the transport layer managing session lifecycle and connection state.

The Capability\Registry stores all registered tools, resources, and prompts, populated by pluggable loaders (ArrayLoader for manual registration, Discoverer for attribute-based auto-discovery). The registry implements a lookup interface that the Server uses to resolve capability requests by name. Loaders can be chained or composed, allowing hybrid approaches where some capabilities are manually defined and others are auto-discovered from class attributes, with the registry merging results into a unified capability namespace.

The SDK's request processing pipeline routes incoming MCP requests (tools/call, resources/read, prompts/get) through specialized request handlers that resolve capability references, execute them with validated arguments, and format results. The ReferenceHandler resolves tool/resource/prompt names to actual capability objects, the execution layer invokes the capability with type-coerced arguments, and ResultFormatters convert execution results into MCP-compliant response objects. This pipeline includes error handling that catches exceptions and converts them to MCP error responses with proper error codes.

The SDK implements session management through the Session interface with a PSR-16StoreSession implementation that persists session state to any PSR-16 compatible cache store (Redis, Memcached, file-based). Sessions are identified by UUIDs (via symfony/uid) and store client metadata, request history, and protocol state. The session store is pluggable, allowing developers to use their existing cache infrastructure (Laravel Cache, Symfony Cache) without additional dependencies. Session lifecycle is managed by the Server, with automatic cleanup and timeout handling.

Tools are MCP capabilities that represent executable functions exposed to AI clients. The Tool class encapsulates a name, description, JSON Schema for arguments, and an executable handler (callable or class method). When a client calls tools/call, the request handler validates arguments against the schema using opis/json-schema, coerces types to match PHP signatures, invokes the handler, and returns the result. Tools support both synchronous execution and can be defined via attributes (#[McpTool]) with automatic schema generation from method signatures and DocBlocks.

Resources are MCP capabilities that represent data sources with static or dynamic URIs. The Resource class encapsulates a URI template, description, MIME type, and a handler that reads or lists resource content. Resources support URI templates with variables (e.g., 'file://{path}') that are resolved at runtime. The ResourceTemplate class enables parameterized resource definitions where clients can request resources with specific parameters. When a client calls resources/read or resources/list, the handler resolves the URI, fetches content, and returns it with the specified MIME type.

Prompts are MCP capabilities that represent template-based prompt generators with arguments. The Prompt class encapsulates a name, description, arguments schema, and a handler that generates prompt text based on provided arguments. Prompts support parameterized templates where clients can request prompt generation with specific argument values. When a client calls prompts/get, the handler receives the arguments, generates the prompt text, and returns it as content. Prompts can be defined via attributes (#[McpPrompt]) with automatic schema generation from method signatures.

The SDK uses opis/json-schema for validating MCP request arguments against capability schemas, and phpdocumentor/reflection-docblock for generating schemas from PHP method signatures and DocBlocks. The SchemaGenerator component parses type hints (scalar, class, union types) and PHPDoc annotations to produce JSON Schema objects that describe tool/resource/prompt arguments. This enables automatic schema generation from attributes without manual schema writing, with support for complex types like arrays, objects, and nullable types.