# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## IMPORTANT: Generated Code

**NEVER manually edit files in `src/`.** All PHP code in `src/` is auto-generated by the TypeScript generator in `generator/`.

To fix PHP issues (PHPStan errors, bugs, etc.):

1. Modify the generator code in `generator/src/`
2. Regenerate with `npm run generate` (from `generator/` directory)
3. Validate with `composer analyse` (from root)

## 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 max)
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/`)

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 max for strictest static analysis
