Php Mcp Schema Laravel Package

Technical Evaluation

Architecture fit

• v0.2.0 is a dependency-free schema runtime for two pinned MCP protocol revisions (2025-11-25, 2026-07-28). It is framework-agnostic PHP — there is no Laravel service provider, facade, or config file. In a Laravel app it sits in the library layer, called from the controllers/jobs that implement MCP transport and tool dispatch.
• The Schemas::create()->forVersion($revision) entry point forces explicit revision selection, which maps well onto a JSON-RPC middleware that resolves the negotiated revision per request. Immutable records with fromArray() / fromValue() / fromJson() are a clean fit for request-payload hydration.
• Split namespaces (Record for protocol objects, Contract for unions, Value for enum-like constants) give an obvious mapping to our own domain boundaries and make the anti-corruption layer thin.
• Validation is always on with no flag to disable it. That is good for correctness and auditability, but removes the usual escape hatch for hot paths.

Integration feasibility

• Composer-installable, pure PHP; binding a memoized Schema instance per revision in a service provider is a few lines of code. No adapter layer required.
• Input helpers align with Laravel idioms: fromArray() takes validated request arrays, fromJson() takes raw Http client bodies, fromValue() handles scalar unions.
• Every runtime exception extends \InvalidArgumentException. Laravel's default handler renders that as a 500, so exception-to-JSON-RPC error code mapping (parse error, invalid params, method not found) must be written by us — it is not provided.

Technical risk

• High, one-time. v0.2.0 deletes the entire v0.1.x generated DTO API — Client/Common/Server namespaces, DTO constructors and factories, class-based enums, validation flags, and toArray() variants — with no compatibility aliases. Any existing call site is a rewrite, not a bump.
• Forward compatibility is vendor-gated: unknown revision identifiers throw UnsupportedRevisionException. Client/version drift becomes a runtime error path we must design for, not an edge case.
• Outbound serialization lost its toArray() variants; the replacement path is not stated in the notes, so ad-hoc serializers are a real divergence risk.
• Pre-1.0 (0.2.0) — treat each minor as potentially breaking until a 1.0 commitment exists.

Key questions

• Do we own the Laravel wrapper (service provider, config, revision cache), and is that scoped?
• Which revisions must we support at launch, and what is the policy for an unlisted revision — reject, downgrade, or translate?
• Is the exception subclass hierarchy documented well enough to map deterministically to JSON-RPC error codes?
• Do we have a complete call-site inventory for the removed Client/Common/Server namespaces?
• What replaces toArray() for outbound payload construction?
• What is the performance profile at realistic 1–50 KB payloads, as opposed to the 8 MiB memory benchmark?

Integration Approach

Stack fit

• Installs into Laravel 10/11/12 with no framework coupling. Recommended shape: a singleton Schema per supported revision, memoized behind a small McpSchemaManager exposing forVersion().
• Sits beneath a JSON-RPC controller or middleware that parses the envelope, selects the negotiated revision, then hydrates via fromArray() / fromJson().

Migration path

• v0.1.x → v0.2.0 is a namespace-wide rewrite: every constructor, factory, class-based enum reference, and toArray() call must change. Budget it as a feature-sized task, not a dependency bump.
• No aliases means old and new APIs cannot coexist in one codebase. If a staged rollout is required, first introduce our own interface around all schema usage on v0.1.3, then swap the implementation behind it.
• Read the migration guide before writing code; it is the only authoritative mapping from old namespaces to Record/Contract/Value.

Compatibility

• Exact-per-revision validation plus only two supported revisions means clients on older drafts will fail hard. Negotiation and a clear error surface are prerequisites, not follow-ups.
• Stricter programmatic input (NUL-prefixed key rejection, aligned nesting limits, native-range numeric checks) will reject payloads previously accepted. Existing test fixtures need regeneration against real client traffic.
• Fractional number handling widened on both revisions (ElicitResult.content, JSONValue on 2026-07-28, NumberSchema bounds on 2025-11-25). Confirm downstream consumers tolerate floats where they previously saw only ints.

Sequencing

1. Pin the exact version in composer.json and enable dependabot-style review, not auto-merge, for this package.
2. Land exception → JSON-RPC error mapping before or alongside the upgrade, so failures are well-formed from day one.
3. Regenerate fixtures from captured real client payloads and add contract tests per supported revision.
4. Only then remove any legacy abstraction layer.

Operational Impact

Maintenance

• Dependency-free and small surface area makes it cheap to vendor and audit; the cost is API churn. Assume a breaking release at each minor and reserve a recurring upgrade slot rather than treating this as a one-off.
• Removal of the skill/ reference scripts and @since protocol-history annotations moves discovery burden onto us: internal documentation for revision semantics and namespace layout becomes our responsibility.
• Supporting two revisions today implies an N-revision matrix over time; plan the support policy before the third revision lands.

Support

• Unmapped \InvalidArgumentException produces 500s for what are client-caused malformed payloads. Fixing this early avoids a long tail of indistinguishable support tickets.
• Log UnsupportedRevisionException as a distinct, tagged metric — it is the primary signal of client/version drift and should not be buried in generic error rates.

Scaling

• The memory fix is the meaningful operational gain: an 8 MiB validated payload completes within a 128 MiB limit, so default PHP limits are viable. Still set memory_limit deliberately and alert on headroom rather than relying on defaults.
• Immutable records imply copy-on-write on every mutation; for high-QPS tool dispatch, cache the per-revision Schema instance and profile allocation churn.
• Linear raw-JSON numeric scanning removes a prior pathological case for dense numeric documents — relevant if we carry telemetry-like MCP payloads.

Failure modes

• Revision mismatch → hard throw. Must degrade to a well-formed JSON-RPC error, never a stack trace or 500.
• Over-strict validation (NUL keys, overflowing floats, nesting depth) rejects traffic previously accepted; expect a small tail of new errors immediately post-deploy and watch error rates by code.
• Overlapping object unions hydrate the record declaring the most input keys, canonical order as tie-breaker. Deterministic, but a payload can land in a different record than the caller expects — assert union resolution in tests.
• Loss of toArray() variants invites hand-rolled serializers that drift from the schema; standardize one outbound path.

Ramp-up

• Any PHP developer can use fromArray() / fromJson() within a day; the real curve is revision semantics and union-resolution rules, not the API surface.
• Before onboarding the wider team, publish one worked example per supported revision in our own repo plus a short internal note on the exception hierarchy.