src
1 month ago
CHANGELOG.md
1 month ago
LICENSE.md
1 month ago
README.md
1 month ago
composer.json
1 month ago
README.md
136 lines
| 1 | # PHP MCP Schema |
| 2 | |
| 3 | A PHP representation of the [](https://modelcontextprotocol.io/Model Context Protocol (MCP)](https://modelcontextprotocol.io/](https://modelcontextprotocol.io/) schema types. |
| 4 | |
| 5 | This package provides Data Transfer Objects (DTOs), Enums, and Unions that mirror the official MCP TypeScript schema. |
| 6 | It is **not** an SDK, client, or server implementation; |
| 7 | just the type definitions for building your own MCP-compatible applications in PHP. |
| 8 | |
| 9 | ## Installation |
| 10 | |
| 11 | ```bash |
| 12 | composer require wordpress/php-mcp-schema |
| 13 | ``` |
| 14 | |
| 15 | Requires PHP 7.4 or higher. |
| 16 | |
| 17 | ## Usage |
| 18 | |
| 19 | ### Creating a Tool Definition |
| 20 | |
| 21 | ```php |
| 22 | use WP\McpSchema\Server\Tools\DTO\Tool; |
| 23 | |
| 24 | $tool = Tool::fromArray([ |
| 25 | 'name' => 'get_weather', |
| 26 | 'description' => 'Get current weather for a location', |
| 27 | 'inputSchema' => [ |
| 28 | 'type' => 'object', |
| 29 | 'properties' => [ |
| 30 | 'location' => ['type' => 'string', 'description' => 'City name'], |
| 31 | ], |
| 32 | 'required' => ['location'], |
| 33 | ], |
| 34 | ]); |
| 35 | ``` |
| 36 | |
| 37 | ### Serialization (toArray) |
| 38 | |
| 39 | Convert a DTO to a plain array for JSON encoding: |
| 40 | |
| 41 | ```php |
| 42 | use WP\McpSchema\Server\Tools\DTO\Tool; |
| 43 | |
| 44 | $tool = Tool::fromArray([ |
| 45 | 'name' => 'get_weather', |
| 46 | 'description' => 'Get current weather for a location', |
| 47 | 'inputSchema' => ['type' => 'object', 'properties' => []], |
| 48 | ]); |
| 49 | |
| 50 | $array = $tool->toArray(); |
| 51 | $json = json_encode($array); // Ready to send over the wire |
| 52 | ``` |
| 53 | |
| 54 | ### Deserialization (fromArray) |
| 55 | |
| 56 | Decode incoming JSON into a fully typed DTO: |
| 57 | |
| 58 | ```php |
| 59 | use WP\McpSchema\Server\Tools\DTO\CallToolRequest; |
| 60 | |
| 61 | $json = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{"location":"Paris"}}}'; |
| 62 | $data = json_decode($json, true); |
| 63 | |
| 64 | $request = CallToolRequest::fromArray($data); |
| 65 | $tool_name = $request->getTypedParams()->getName(); // "get_weather" |
| 66 | $arguments = $request->getTypedParams()->getArguments(); // ['location' => 'Paris'] |
| 67 | ``` |
| 68 | |
| 69 | ### Factory / Union Types |
| 70 | |
| 71 | Use a factory to resolve polymorphic content blocks without knowing the concrete type up front: |
| 72 | |
| 73 | ```php |
| 74 | use WP\McpSchema\Common\Protocol\Factory\ContentBlockFactory; |
| 75 | use WP\McpSchema\Common\Content\DTO\TextContent; |
| 76 | |
| 77 | $block = ContentBlockFactory::fromArray(['type' => 'text', 'text' => 'Hello, world!']); |
| 78 | |
| 79 | // $block implements ContentBlockInterface; cast when you need the concrete API |
| 80 | if ($block instanceof TextContent) { |
| 81 | echo $block->getText(); // "Hello, world!" |
| 82 | } |
| 83 | ``` |
| 84 | |
| 85 | ### JSON-RPC Messages |
| 86 | |
| 87 | Construct a generic JSON-RPC request for any MCP method: |
| 88 | |
| 89 | ```php |
| 90 | use WP\McpSchema\Common\JsonRpc\DTO\JSONRPCRequest; |
| 91 | |
| 92 | $request = JSONRPCRequest::fromArray([ |
| 93 | 'jsonrpc' => '2.0', |
| 94 | 'id' => 1, |
| 95 | 'method' => 'tools/list', |
| 96 | ]); |
| 97 | |
| 98 | $json = json_encode($request->toArray()); |
| 99 | ``` |
| 100 | |
| 101 | ## Available Types |
| 102 | |
| 103 | ### Server Types (`WP\McpSchema\Server\`) |
| 104 | |
| 105 | - **Tools** - `Tool`, `CallToolRequest`, `CallToolResult`, `ListToolsRequest`, `ListToolsResult` |
| 106 | - **Resources** - `Resource`, `ResourceTemplate`, `ReadResourceRequest`, `ReadResourceResult` |
| 107 | - **Prompts** - `Prompt`, `PromptMessage`, `GetPromptRequest`, `GetPromptResult` |
| 108 | - **Logging** - `LoggingMessageNotification`, `SetLevelRequest` |
| 109 | |
| 110 | ### Client Types (`WP\McpSchema\Client\`) |
| 111 | |
| 112 | - **Sampling** - `CreateMessageRequest`, `CreateMessageResult`, `SamplingMessage` |
| 113 | - **Elicitation** - `ElicitRequest`, `ElicitResult` |
| 114 | - **Roots** - `ListRootsRequest`, `ListRootsResult`, `Root` |
| 115 | |
| 116 | ### Common Types (`WP\McpSchema\Common\`) |
| 117 | |
| 118 | - **Protocol** - `InitializeRequest`, `InitializeResult`, `PingRequest` |
| 119 | - **Content** - `TextContent`, `ImageContent`, `AudioContent` |
| 120 | - **JSON-RPC** - `JSONRPCRequest`, `JSONRPCNotification`, `JSONRPCResultResponse`, `JSONRPCErrorResponse` |
| 121 | |
| 122 | ## Generator |
| 123 | |
| 124 | The PHP code in `src/` is auto-generated from the official MCP TypeScript schema. The generator is located in the `generator/` directory and is not included in the Composer package. |
| 125 | |
| 126 | See [](generator/README.mdgenerator/README.md](generator/README.md](generator/README.md) for setup and usage instructions. |
| 127 | |
| 128 | ## License |
| 129 | |
| 130 | GPL-2.0-or-later - see [](LICENSE.mdLICENSE.md](LICENSE.md](LICENSE.md) for details. |
| 131 | |
| 132 | ## Links |
| 133 | |
| 134 | - [](https://spec.modelcontextprotocol.io/Model Context Protocol Specification](https://spec.modelcontextprotocol.io/](https://spec.modelcontextprotocol.io/) |
| 135 | - [](https://github.com/modelcontextprotocol/modelcontextprotocolMCP GitHub Repository](https://github.com/modelcontextprotocol/modelcontextprotocol](https://github.com/modelcontextprotocol/modelcontextprotocol) |
| 136 |