Add TypeScript generator for MCP PHP DTOs

.gitattributes

@@ -0,0 +1,7 @@
+# Exclude generator and dev files from Packagist distribution
+/generator              export-ignore
+/.claude                export-ignore
+/.idea                  export-ignore
+/.gitattributes         export-ignore
+/phpstan.neon           export-ignore
+*.DS_Store              export-ignore

.gitignore

@@ -1,6 +1,9 @@
 # Dependencies
-/vendor/
-/node_modules/
+vendor/
+node_modules/
+
+# Build output
+dist/
 
 # IDE
 .idea/
@@ -13,21 +16,21 @@
 .DS_Store
 Thumbs.db
 
-# Claude Code
-.claude/settings.local.json
+# Logs
+*.log
+npm-debug.log*
+
+# Test coverage
+coverage/
 
-# PHP
-*.phar
-phpunit.xml
-.phpunit.result.cache
-.phpunit.cache/
+# Cache
+.cache/
+.npm/
 
 # Environment
 .env
 .env.local
-.env.*.local
 
-# Build artifacts
-/build/
-/dist/
-/.cache/
+# Temporary files
+tmp/
+temp/

CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+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.
+
+## Commands
+
+### PHP Package (root)
+
+```bash
+composer analyse          # Run PHPStan static analysis (level 8)
+composer phpstan          # Alias for analyse
+```
+
+### Generator (generator/)
+
+```bash
+cd generator
+npm install               # Install dependencies
+npm run build             # Compile TypeScript
+npm run generate          # Generate PHP schema to ../src
+npm run lint              # ESLint
+npm run format            # Prettier
+```
+
+### Generate with specific version
+
+```bash
+cd generator
+npx mcp-php-generator generate -c config/2025-11-25.json
+npm run generate:check -- -c config/2025-11-25.json  # Generate + PHPStan validation
+```
+
+## Architecture
+
+### Repository Structure
+
+- `src/` - Generated PHP DTOs (the Composer package distributed via Packagist)
+- `generator/` - TypeScript generator (excluded from Packagist via `.gitattributes`)
+
+### PHP Schema (`src/`)
+
+**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.
+
+Organized by MCP domain with PSR-4 autoloading (`WP\McpSchema\` → `src/`):
+
+- `Common/` - Shared base classes, traits, JSON-RPC, protocol types
+- `Server/` - Server-side types (Tools, Resources, Prompts, Logging)
+- `Client/` - Client-side types (Sampling, Elicitation, Roots, Tasks)
+
+### Generator Pipeline (`generator/src/`)
+
+```
+schema.ts → parser/ → extractors/ → generators/ → writers/ → PHP files
+```
+
+- `fetcher/` - Downloads schema from GitHub with caching
+- `parser/` - ts-morph AST parsing
+- `extractors/` - Extract type info, @category tags, inheritance
+- `generators/` - PHP code generation (DTO, Enum, Union, Factory)
+- `writers/` - File output organized by domain/subdomain
+- `cli/` - Command-line interface
+
+### Key Design Decisions
+
+- PHP 7.4 compatibility (class-based enums, typed properties)
+- Uses `@category` JSDoc tags for domain classification
+- Generator outputs to `../src` relative to `generator/` directory
+- PHPStan level 8 for strict static analysis

README.md

@@ -1 +1,72 @@
 # PHP MCP Schema
+
+A PHP representation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) schema types.
+
+This package provides Data Transfer Objects (DTOs), Enums, and Unions that mirror the official MCP TypeScript schema.
+It is **not** an SDK, client, or server implementation;
+just the type definitions for building your own MCP-compatible applications in PHP.
+
+## Installation
+
+```bash
+composer require wordpress/php-mcp-schema
+```
+
+Requires PHP 7.4 or higher.
+
+## Usage
+
+```php
+use WP\McpSchema\Server\Tools\Tool;
+use WP\McpSchema\Server\Tools\CallToolRequest;
+use WP\McpSchema\Common\Content\TextContent;
+
+// Create a tool definition
+$tool = Tool::fromArray([
+    'name' => 'get_weather',
+    'description' => 'Get current weather for a location',
+    'inputSchema' => [
+        'type' => 'object',
+        'properties' => [
+            'location' => ['type' => 'string', 'description' => 'City name'],
+        ],
+        'required' => ['location'],
+    ],
+]);
+```
+
+## Available Types
+
+### Server Types (`WP\McpSchema\Server\`)
+
+- **Tools** - `Tool`, `CallToolRequest`, `CallToolResult`, `ListToolsRequest`, `ListToolsResult`
+- **Resources** - `Resource`, `ResourceTemplate`, `ReadResourceRequest`, `ReadResourceResult`
+- **Prompts** - `Prompt`, `PromptMessage`, `GetPromptRequest`, `GetPromptResult`
+- **Logging** - `LoggingMessageNotification`, `SetLevelRequest`
+
+### Client Types (`WP\McpSchema\Client\`)
+
+- **Sampling** - `CreateMessageRequest`, `CreateMessageResult`, `SamplingMessage`
+- **Elicitation** - `ElicitRequest`, `ElicitResult`
+- **Roots** - `ListRootsRequest`, `ListRootsResult`, `Root`
+
+### Common Types (`WP\McpSchema\Common\`)
+
+- **Protocol** - `InitializeRequest`, `InitializeResult`, `PingRequest`
+- **Content** - `TextContent`, `ImageContent`, `AudioContent`
+- **JSON-RPC** - `JSONRPCRequest`, `JSONRPCNotification`, `JSONRPCResultResponse`, `JSONRPCErrorResponse`
+
+## Generator
+
+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.
+
+See [generator/README.md](generator/README.md) for setup and usage instructions.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
+- [MCP GitHub Repository](https://github.com/modelcontextprotocol/modelcontextprotocol)

composer.json

@@ -0,0 +1,38 @@
+{
+    "name": "wordpress/php-mcp-schema",
+    "description": "PHP DTOs for the Model Context Protocol (MCP) specification",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "dto",
+        "schema",
+        "php"
+    ],
+    "homepage": "https://github.com/WordPress/php-mcp-schema",
+    "authors": [
+        {
+            "name": "WordPress",
+            "homepage": "https://wordpress.org"
+        }
+    ],
+    "require": {
+        "php": ">=7.4"
+    },
+    "require-dev": {
+        "phpstan/phpstan": "^1.10"
+    },
+    "autoload": {
+        "psr-4": {
+            "WP\\McpSchema\\": "src/"
+        }
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "scripts": {
+        "analyse": "phpstan analyse",
+        "phpstan": "@analyse"
+    }
+}

generator/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

generator/README.md

@@ -0,0 +1,60 @@
+# MCP PHP Schema Generator
+
+TypeScript generator that creates PHP DTOs from the official MCP TypeScript schema.
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+## Running the Generator
+
+The generator requires a configuration file that specifies the schema version. Config files are located in `config/`.
+
+**Available versions:**
+- `2024-11-05.json` - Initial MCP release
+- `2025-03-26.json`
+- `2025-06-18.json`
+- `2025-11-25.json` - Latest
+
+**Generate PHP schema:**
+
+```bash
+npx mcp-php-generator generate -c config/2025-11-25.json
+```
+
+**Generate and run PHPStan validation:**
+
+```bash
+npm run generate:check -- -c config/2025-11-25.json
+```
+
+## CLI Options
+
+```bash
+npx mcp-php-generator generate --help
+
+Options:
+  -c, --config <file>      Configuration file (required)
+  -o, --output <dir>       Output directory (overrides config)
+  -n, --namespace <ns>     PHP namespace (overrides config)
+  -p, --php-version <ver>  PHP version (overrides config)
+  --builders               Generate builder classes
+  --no-factories           Disable factory generation
+  --dry-run                Show what would be generated without writing files
+  --fresh                  Force fresh fetch from GitHub (ignore cache)
+  --verbose                Enable verbose output
+```
+
+## Other Commands
+
+```bash
+npm run build                        # Compile TypeScript
+npm run lint                         # Run ESLint
+npm run format                       # Run Prettier
+npx mcp-php-generator info           # Show generator info
+npx mcp-php-generator configs        # List available config files
+npx mcp-php-generator clear-cache    # Clear schema cache
+```

generator/config/2024-11-05.json

@@ -0,0 +1,8 @@
+{
+  "schema": {
+    "version": "2024-11-05"
+  },
+  "output": {
+    "generateBuilders": false
+  }
+}