Skip to content

Commit 15d5466

Browse files
CodeWithKyrianCodeWithKyrian
committed
docs: update README with more detailed info
1 parent c605dee commit 15d5466

File tree

1 file changed

+132
-19
lines changed

1 file changed

+132
-19
lines changed

‎README.md‎

Lines changed: 132 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,41 +4,154 @@
44
[![Total Downloads](https://img.shields.io/packagist/dt/php-mcp/schema.svg?style=flat-square)](https://packagist.org/packages/php-mcp/schema)
55
[![License](https://img.shields.io/packagist/l/php-mcp/schema.svg?style=flat-square)](LICENSE)
66

7-
This package provides PHP Data Transfer Objects (DTOs) and Enums for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) schema. It is intended to be used by PHP implementations of MCP servers and clients, ensuring type safety and consistency with the official specification.
7+
**Type-safe PHP DTOs for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) specification.**
88

9-
Current MCP Schema Version: [**2025-03-26**](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts)
9+
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.
10+
11+
> 🎯 **MCP Schema Version:** [2025-03-26](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts) (Latest)
1012
1113
## Installation
1214

1315
```bash
1416
composer require php-mcp/schema
1517
```
1618

17-
## Usage
19+
**Requirements:** PHP 8.1+ • No dependencies
20+
21+
## Quick Start
22+
23+
```php
24+
use PhpMcp\Schema\Tool;
25+
use PhpMcp\Schema\Resource;
26+
use PhpMcp\Schema\Request\CallToolRequest;
27+
28+
// Create a tool definition
29+
$tool = Tool::make(
30+
name: 'calculator',
31+
inputSchema: [
32+
'type' => 'object',
33+
'properties' => [
34+
'operation' => ['type' => 'string'],
35+
'a' => ['type' => 'number'],
36+
'b' => ['type' => 'number']
37+
],
38+
'required' => ['operation', 'a', 'b']
39+
],
40+
description: 'Performs basic arithmetic operations'
41+
);
42+
43+
// Serialize to JSON
44+
$json = json_encode($tool);
45+
46+
// Deserialize from array
47+
$tool = Tool::fromArray($decodedData);
48+
```
1849

19-
This package contains PHP classes and enums that directly correspond to the types defined in the official MCP TypeScript schema (linked above). These can be used for:
50+
## Core Features
51+
52+
### 🏗️ **Complete Schema Coverage**
53+
Every MCP protocol type is represented with full validation and type safety.
54+
55+
### 🔒 **Immutable Design**
56+
All DTOs use readonly properties to prevent accidental mutations.
57+
58+
### 🚀 **Developer Experience**
59+
- **Factory Methods:** Convenient `make()` methods for fluent object creation
60+
- **Array Conversion:** Seamless `toArray()` and `fromArray()` methods
61+
- **JSON Ready:** Built-in `JsonSerializable` interface support
62+
- **Validation:** Comprehensive input validation with clear error messages
63+
64+
### 📦 **Schema Components**
65+
66+
| Component | Description |
67+
|-----------|-------------|
68+
| **Tools** | Tool definitions with JSON Schema validation |
69+
| **Resources** | Static and template-based resource representations |
70+
| **Prompts** | Interactive prompt definitions with arguments |
71+
| **Content** | Text, image, audio, and blob content types |
72+
| **JSON-RPC** | Complete JSON-RPC 2.0 protocol implementation |
73+
| **Requests/Results** | All 15 request types and corresponding responses |
74+
| **Notifications** | Real-time event notification messages |
75+
| **Capabilities** | Client and server capability declarations |
76+
77+
## Usage Patterns
78+
79+
### Creating Protocol Messages
80+
81+
```php
82+
// Initialize request
83+
$request = InitializeRequest::make(
84+
protocolVersion: '2025-03-26',
85+
capabilities: ClientCapabilities::make(),
86+
clientInfo: Implementation::make('MyClient', '1.0.0')
87+
);
88+
89+
// Call tool request
90+
$callRequest = CallToolRequest::make(
91+
name: 'calculator',
92+
arguments: ['operation' => 'add', 'a' => 5, 'b' => 3]
93+
);
94+
```
95+
96+
### Working with Resources
97+
98+
```php
99+
// Static resource
100+
$resource = Resource::make(
101+
uri: '/data/users.json',
102+
name: 'User Database',
103+
description: 'Complete user registry'
104+
);
105+
106+
// Resource template
107+
$template = ResourceTemplate::make(
108+
uriTemplate: '/users/{id}',
109+
name: 'User Profile',
110+
description: 'Individual user data'
111+
);
112+
```
20113

21-
* Type-hinting in your MCP server or client application logic.
22-
* Serializing PHP objects into arrays that match the MCP JSON structure before sending them over a transport.
23-
* Deserializing associative arrays (from decoded JSON) received from an MCP transport into strongly-typed PHP objects.
114+
### Content Handling
24115

25-
### DTO Features
116+
```php
117+
// Text content
118+
$text = TextContent::make('Hello, world!');
26119

27-
Each Data Transfer Object (DTO) class typically provides:
120+
// Image content
121+
$image = ImageContent::make(
122+
data: base64_encode($imageData),
123+
mimeType: 'image/png'
124+
);
125+
```
28126

29-
* **Readonly Public Properties:** For immutability and direct access to data fields.
30-
* **Constructor:** For instantiating objects with all required properties and optional ones.
31-
* **Static `make(...): static` Method:** (For most DTOs) A convenient alternative factory method, often mirroring the constructor's signature, allowing for a fluent instantiation style.
32-
* **`toArray(): array` Method:** Converts the DTO instance into an associative array suitable for `json_encode()`. Optional properties with `null` values are typically omitted from the output array for cleaner JSON.
33-
* **Static `fromArray(array $data): static` Factory Method:** Constructs a DTO instance from an associative array (e.g., after `json_decode(..., true)`). This method usually includes validation for required fields.
34-
* **`JsonSerializable` Interface:** Most DTOs implement this, allowing them to be directly used with `json_encode()`.
127+
## Package Structure
35128

36-
See the `src/` directory for all available schema types, organized by their functional area within the Model Context Protocol.
129+
```
130+
src/
131+
├── Content/ # Content types (Text, Image, Audio, Blob, etc.)
132+
├── Enum/ # Protocol enums (LoggingLevel, Role)
133+
├── JsonRpc/ # JSON-RPC 2.0 implementation
134+
├── Notification/ # Event notification types
135+
├── Request/ # Protocol request messages
136+
├── Result/ # Protocol response messages
137+
├── Tool.php # Tool definitions
138+
├── Resource.php # Resource representations
139+
├── Prompt.php # Prompt definitions
140+
└── ... # Core protocol types
141+
```
37142

38-
## Contributing
143+
## Why Use This Package?
39144

40-
Contributions are welcome! Please refer to the contributing guidelines of the main `php-mcp` project.
145+
- ✅ **100% MCP Compliance** - Matches official specification exactly
146+
- ✅ **Type Safety** - Catch errors at development time, not runtime
147+
- ✅ **Zero Dependencies** - Lightweight and self-contained
148+
- ✅ **Production Ready** - Immutable, validated, and thoroughly tested
149+
- ✅ **Future Proof** - Updated with latest MCP specification versions
41150

42151
## License
43152

44-
MIT License. See [LICENSE](LICENSE) file.
153+
MIT License. See [LICENSE](LICENSE) for details.
154+
155+
---
156+
157+
**Part of the [PHP MCP](https://github.com/php-mcp) ecosystem** • Build type-safe MCP applications with confidence

0 commit comments

Comments
 (0)