Skip to content

Commit 6b81c60

Browse files
ovidiu-galatanovidiu-galatan
committed
Add TypeScript generator for MCP PHP DTOs
Implement a complete pipeline to generate PHP Data Transfer Objects from the official MCP TypeScript schema specification. The generator handles enums, unions, inheritance hierarchies, and domain-based file organization. This enables automatic PHP schema updates when new MCP spec versions are released, ensuring the Composer package stays in sync with the protocol specification.
1 parent 351bc7c commit 6b81c60

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+10746
-14
lines changed

‎.gitattributes‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Exclude generator and dev files from Packagist distribution
2+
/generator export-ignore
3+
/.claude export-ignore
4+
/.idea export-ignore
5+
/.gitattributes export-ignore
6+
/phpstan.neon export-ignore
7+
*.DS_Store export-ignore

‎.gitignore‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Dependencies
2-
/vendor/
3-
/node_modules/
2+
vendor/
3+
node_modules/
4+
5+
# Build output
6+
dist/
47

58
# IDE
69
.idea/
@@ -13,21 +16,21 @@
1316
.DS_Store
1417
Thumbs.db
1518

16-
# Claude Code
17-
.claude/settings.local.json
19+
# Logs
20+
*.log
21+
npm-debug.log*
22+
23+
# Test coverage
24+
coverage/
1825

19-
# PHP
20-
*.phar
21-
phpunit.xml
22-
.phpunit.result.cache
23-
.phpunit.cache/
26+
# Cache
27+
.cache/
28+
.npm/
2429

2530
# Environment
2631
.env
2732
.env.local
28-
.env.*.local
2933

30-
# Build artifacts
31-
/build/
32-
/dist/
33-
/.cache/
34+
# Temporary files
35+
tmp/
36+
temp/

‎CLAUDE.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This repository contains PHP DTOs for the Model Context Protocol (MCP) specification, distributed as a Composer package. It also includes a TypeScript generator (in `generator/`) that creates PHP code from the official MCP TypeScript schema.
8+
9+
## Commands
10+
11+
### PHP Package (root)
12+
13+
```bash
14+
composer analyse # Run PHPStan static analysis (level 8)
15+
composer phpstan # Alias for analyse
16+
```
17+
18+
### Generator (generator/)
19+
20+
```bash
21+
cd generator
22+
npm install # Install dependencies
23+
npm run build # Compile TypeScript
24+
npm run generate # Generate PHP schema to ../src
25+
npm run lint # ESLint
26+
npm run format # Prettier
27+
```
28+
29+
### Generate with specific version
30+
31+
```bash
32+
cd generator
33+
npx mcp-php-generator generate -c config/2025-11-25.json
34+
npm run generate:check -- -c config/2025-11-25.json # Generate + PHPStan validation
35+
```
36+
37+
## Architecture
38+
39+
### Repository Structure
40+
41+
- `src/` - Generated PHP DTOs (the Composer package distributed via Packagist)
42+
- `generator/` - TypeScript generator (excluded from Packagist via `.gitattributes`)
43+
44+
### PHP Schema (`src/`)
45+
46+
**Do not manually edit files in `src/`.** All PHP code is auto-generated by the TypeScript generator. To make changes, modify the generator and regenerate.
47+
48+
Organized by MCP domain with PSR-4 autoloading (`WP\McpSchema\` → `src/`):
49+
50+
- `Common/` - Shared base classes, traits, JSON-RPC, protocol types
51+
- `Server/` - Server-side types (Tools, Resources, Prompts, Logging)
52+
- `Client/` - Client-side types (Sampling, Elicitation, Roots, Tasks)
53+
54+
### Generator Pipeline (`generator/src/`)
55+
56+
```
57+
schema.ts → parser/ → extractors/ → generators/ → writers/ → PHP files
58+
```
59+
60+
- `fetcher/` - Downloads schema from GitHub with caching
61+
- `parser/` - ts-morph AST parsing
62+
- `extractors/` - Extract type info, @category tags, inheritance
63+
- `generators/` - PHP code generation (DTO, Enum, Union, Factory)
64+
- `writers/` - File output organized by domain/subdomain
65+
- `cli/` - Command-line interface
66+
67+
### Key Design Decisions
68+
69+
- PHP 7.4 compatibility (class-based enums, typed properties)
70+
- Uses `@category` JSDoc tags for domain classification
71+
- Generator outputs to `../src` relative to `generator/` directory
72+
- PHPStan level 8 for strict static analysis

‎README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,72 @@
11
# PHP MCP Schema
2+
3+
A PHP representation of the [Model Context Protocol (MCP)](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+
```php
20+
use WP\McpSchema\Server\Tools\Tool;
21+
use WP\McpSchema\Server\Tools\CallToolRequest;
22+
use WP\McpSchema\Common\Content\TextContent;
23+
24+
// Create a tool definition
25+
$tool = Tool::fromArray([
26+
'name' => 'get_weather',
27+
'description' => 'Get current weather for a location',
28+
'inputSchema' => [
29+
'type' => 'object',
30+
'properties' => [
31+
'location' => ['type' => 'string', 'description' => 'City name'],
32+
],
33+
'required' => ['location'],
34+
],
35+
]);
36+
```
37+
38+
## Available Types
39+
40+
### Server Types (`WP\McpSchema\Server\`)
41+
42+
- **Tools** - `Tool`, `CallToolRequest`, `CallToolResult`, `ListToolsRequest`, `ListToolsResult`
43+
- **Resources** - `Resource`, `ResourceTemplate`, `ReadResourceRequest`, `ReadResourceResult`
44+
- **Prompts** - `Prompt`, `PromptMessage`, `GetPromptRequest`, `GetPromptResult`
45+
- **Logging** - `LoggingMessageNotification`, `SetLevelRequest`
46+
47+
### Client Types (`WP\McpSchema\Client\`)
48+
49+
- **Sampling** - `CreateMessageRequest`, `CreateMessageResult`, `SamplingMessage`
50+
- **Elicitation** - `ElicitRequest`, `ElicitResult`
51+
- **Roots** - `ListRootsRequest`, `ListRootsResult`, `Root`
52+
53+
### Common Types (`WP\McpSchema\Common\`)
54+
55+
- **Protocol** - `InitializeRequest`, `InitializeResult`, `PingRequest`
56+
- **Content** - `TextContent`, `ImageContent`, `AudioContent`
57+
- **JSON-RPC** - `JSONRPCRequest`, `JSONRPCNotification`, `JSONRPCResultResponse`, `JSONRPCErrorResponse`
58+
59+
## Generator
60+
61+
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.
62+
63+
See [generator/README.md](generator/README.md) for setup and usage instructions.
64+
65+
## License
66+
67+
MIT License - see [LICENSE](LICENSE) for details.
68+
69+
## Links
70+
71+
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
72+
- [MCP GitHub Repository](https://github.com/modelcontextprotocol/modelcontextprotocol)

‎composer.json‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
{
2+
"name": "wordpress/php-mcp-schema",
3+
"description": "PHP DTOs for the Model Context Protocol (MCP) specification",
4+
"type": "library",
5+
"license": "MIT",
6+
"keywords": [
7+
"mcp",
8+
"model-context-protocol",
9+
"dto",
10+
"schema",
11+
"php"
12+
],
13+
"homepage": "https://github.com/WordPress/php-mcp-schema",
14+
"authors": [
15+
{
16+
"name": "WordPress",
17+
"homepage": "https://wordpress.org"
18+
}
19+
],
20+
"require": {
21+
"php": ">=7.4"
22+
},
23+
"require-dev": {
24+
"phpstan/phpstan": "^1.10"
25+
},
26+
"autoload": {
27+
"psr-4": {
28+
"WP\\McpSchema\\": "src/"
29+
}
30+
},
31+
"config": {
32+
"sort-packages": true
33+
},
34+
"scripts": {
35+
"analyse": "phpstan analyse",
36+
"phpstan": "@analyse"
37+
}
38+
}

‎composer.lock‎

Lines changed: 74 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎generator/.prettierrc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"semi": true,
3+
"singleQuote": true,
4+
"tabWidth": 2,
5+
"trailingComma": "es5",
6+
"printWidth": 100,
7+
"bracketSpacing": true,
8+
"arrowParens": "always",
9+
"endOfLine": "lf"
10+
}

‎generator/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# MCP PHP Schema Generator
2+
3+
TypeScript generator that creates PHP DTOs from the official MCP TypeScript schema.
4+
5+
## Setup
6+
7+
```bash
8+
npm install
9+
npm run build
10+
```
11+
12+
## Running the Generator
13+
14+
The generator requires a configuration file that specifies the schema version. Config files are located in `config/`.
15+
16+
**Available versions:**
17+
- `2024-11-05.json` - Initial MCP release
18+
- `2025-03-26.json`
19+
- `2025-06-18.json`
20+
- `2025-11-25.json` - Latest
21+
22+
**Generate PHP schema:**
23+
24+
```bash
25+
npx mcp-php-generator generate -c config/2025-11-25.json
26+
```
27+
28+
**Generate and run PHPStan validation:**
29+
30+
```bash
31+
npm run generate:check -- -c config/2025-11-25.json
32+
```
33+
34+
## CLI Options
35+
36+
```bash
37+
npx mcp-php-generator generate --help
38+
39+
Options:
40+
-c, --config <file> Configuration file (required)
41+
-o, --output <dir> Output directory (overrides config)
42+
-n, --namespace <ns> PHP namespace (overrides config)
43+
-p, --php-version <ver> PHP version (overrides config)
44+
--builders Generate builder classes
45+
--no-factories Disable factory generation
46+
--dry-run Show what would be generated without writing files
47+
--fresh Force fresh fetch from GitHub (ignore cache)
48+
--verbose Enable verbose output
49+
```
50+
51+
## Other Commands
52+
53+
```bash
54+
npm run build # Compile TypeScript
55+
npm run lint # Run ESLint
56+
npm run format # Run Prettier
57+
npx mcp-php-generator info # Show generator info
58+
npx mcp-php-generator configs # List available config files
59+
npx mcp-php-generator clear-cache # Clear schema cache
60+
```

‎generator/config/2024-11-05.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"schema": {
3+
"version": "2024-11-05"
4+
},
5+
"output": {
6+
"generateBuilders": false
7+
}
8+
}

0 commit comments

Comments
 (0)