Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (55 loc) · 2.57 KB

CLAUDE.md

File metadata and controls

80 lines (55 loc) · 2.57 KB

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)

composer analyse          # Run PHPStan static analysis (level max)
composer phpstan          # Alias for analyse

Generator (generator/)

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

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