Php Mcp Schema Laravel Package

Product Decisions This Supports

• MCP roadmap alignment: The package now targets exact MCP schema revisions 2025-11-25 and 2026-07-28. This supports a deliberate decision about which protocol revision(s) your Laravel/PHP product supports, rather than implicitly following a generated DTO surface.
• Build vs. buy for protocol correctness: Adopting this runtime replaces hand-rolled validation/hydration for MCP payloads with revision-exact, always-on validation. That is usually a buy decision: protocol schemas are broad, edge-case-heavy, and expensive to maintain internally.
• Breaking-change budget: v0.2.0 removes the generated DTO API with no compatibility aliases. This is a product-planning item, not just an engineering one: any roadmap work depending on the old Client, Common, Server namespaces, DTO constructors/factories, class enums, validation flags, or toArray() variants must be scheduled for migration before upgrading.
• Upgrade gating: Because unknown revisions throw UnsupportedRevisionException and validation is always on, the package enforces explicit revision support. Product should treat MCP revision support as a versioned capability, with release notes and migration guides as customer-facing upgrade artifacts.
• Use cases: Best suited to Laravel/PHP services that need to validate, hydrate, and inspect MCP payloads for server or client implementations, especially where payload sizes may be large. The memory improvement for an 8 MiB payload under a 128 MiB limit supports decisions to handle larger MCP messages inline rather than introducing external validation services.
• Risk management: Pre-1.0 breaking releases and removed per-class @since annotations increase upgrade overhead. Product should avoid exposing the package’s internal object model as a public contract and should version its own MCP-facing APIs independently.

When to Consider This Package

Consider adoption when:

• You are building an MCP server or client in PHP/Laravel and need protocol-exact validation against 2025-11-25 or 2026-07-28.
• You want a dependency-free runtime with immutable records and JSON/array/value hydration rather than maintaining generated DTOs or custom schema validators.
• You need predictable handling of object unions, scalar unions, allOf refinements of Error, and strict rejection of malformed input.
• You want to handle large validated payloads within constrained PHP memory limits.
• You can absorb a breaking migration now and can pin to exact package versions while the API stabilizes.

Look elsewhere or defer when:

• You need support for MCP revisions outside the two exact revisions listed; unsupported identifiers throw.
• You depend on the removed generated DTO API, class-based enums, validation flags, or compatibility aliases.
• Your product requires a stable public object model from a pre-1.0 dependency, or cannot schedule the migration described in the v0.2.0 migration guide.
• You need a Laravel-native integration layer with framework conventions; this package is a dependency-free schema runtime, not a Laravel bundle.
• You are not yet committed to MCP as a protocol surface, or you only need loose JSON shape checks.

How to Pitch It (Stakeholders)

For executives: This package gives our PHP/Laravel MCP work revision-exact schema validation without us building and maintaining a protocol validator. The trade-off is that v0.2.0 is a breaking release: the old generated DTO API is gone, so upgrading requires planned migration work. We should treat MCP revision support as a product capability, pin versions, and avoid exposing the package’s internal objects as our own API.

For engineering: v0.2.0 replaces the generated DTO API with a dependency-free runtime for exact MCP revisions 2025-11-25 and 2026-07-28. Construction moves to Schemas::create()->forVersion($revision) with immutable Record objects via fromArray(), fromValue(), or fromJson(). Validation is always on, unsupported revisions throw, and there are no compatibility aliases. The release also improves numeric handling, union hydration, input rejection, and memory use for large payloads. Read and schedule the migration guide before upgrading.