Add TypeScript generator for MCP PHP DTOs

[galatanovidiu]

What

This PR establishes a complete PHP Composer package (wordpress/php-mcp-schema) with a TypeScript-based code generator that creates PHP 7.4 DTOs from the official Model Context Protocol TypeScript schema.

Package Structure:

• src/ - Auto-generated PHP DTOs (distributed via Packagist)
• generator/ - TypeScript generator (excluded from distribution via .gitattributes)

Generator Pipeline:

schema.ts → fetcher → parser → extractors → generators → writers → PHP files

Generated Artifacts:

• DTOs with constructors, fromArray(), toArray() (auto-hydration/serialization)
• Class-based enums (PHP 7.4 compatible)
• Union marker interfaces with discriminator-based factories
• True PHP class inheritance mirroring TypeScript extends
• Domain organization (Server, Client, Common) based on @category JSDoc tags

Why

1. TypeScript AST over JSON Schema: The generator parses TypeScript directly using ts-morph because:

   • TypeScript is the authoritative MCP schema; JSON Schema is derived and loses information
   • Preserves extends relationships (JSON Schema flattens into allOf)
   • Preserves @category JSDoc tags for domain classification
   • Distinguishes string literal unions (enums) from object unions (polymorphic types)

2. PHP 7.4 Compatibility: Ensures broad adoption across PHP ecosystems, using class-based enums instead of native PHP 8.1 enums, PHPDoc annotations instead of union types.

3. Generator Approach: Keeps PHP code synchronized with the evolving MCP specification. The generator supports multiple schema versions (2024-11-05 through 2025-11-25) and tracks version history for changelog annotations.

4. True Inheritance: PHP DTOs mirror TypeScript inheritance chains (InitializeRequest extends JSONRPCRequest extends Request) instead of flattening, enabling instanceof checks and eliminating code duplication.

Key Files

Component	Path	Purpose
Main orchestrator	generator/src/index.ts	8-step generation pipeline
DTO generator	generator/src/generators/dto.ts	PHP class generation with inheritance
Type mapper	generator/src/generators/type-mapper.ts	TS→PHP type conversion
Domain classifier	generator/src/generators/domain-classifier.ts	@category → namespace mapping
Synthetic extractor	generator/src/extractors/synthetic-dto.ts	Inline object → DTO conversion
CLI	generator/src/cli/index.ts	Commander.js interface

Usage

# Generate PHP from latest schema
cd generator && npm install && npm run build
npx mcp-php-generator generate -c config/2025-11-25.json

# Validate with PHPStan
npm run generate:check -- -c config/2025-11-25.json

Test Plan

• Run npm run build in generator/ - compiles without errors
• Run npx mcp-php-generator generate -c config/2025-11-25.json - generates PHP files
• Run composer analyse - PHPStan level 8 passes
• Verify generated DTOs have proper inheritance chains
• Verify union factories route correctly based on discriminators