Laravel Agent Kit Laravel Package

Getting Started

This release is about hardening an existing surface rather than adding new API, so the fastest path is still: composer require the package, publish its config, and point it at one model you already understand.

1. Publish and read the config first. The security defaults (policy requirement, field exposure, audit sink) are decided there, not in your tool classes. Read it before generating anything.
2. Register the MCP server in the place the package documents (typically a route file or a dedicated server class), then confirm the endpoint responds to a handshake from the MCP inspector or your client.
3. Generate one tool against a single, read-only model — a Ticket or Article. The generated class is real code that serialises through laravel/mcp, so it is a working starting point, not a stub you have to wire up.
4. Write the policy immediately. A model without a policy throws by design. Doing this second (not last) turns the fail-closed behaviour into a guide rather than a wall of 500s.

First real use case: a read-only "look up my ticket by ID" tool. It exercises the whole chain — policy get, payload shaping, the denied-vs-missing rule — in about twenty lines, and every later tool is a variation on it.

Version floor: Laravel 13 requires PHP 8.3. If your app is on 8.2 you stay on Laravel 12 and this release changes nothing for you; the constraint widened rather than moved.

Implementation Patterns

Policy-per-model, explicitly. Treat the policy as the only authorisation boundary. Don't also filter in the tool body — two places to check means one gets out of sync. Define the abilities the package asks for and let denials propagate.

Shape payloads with an allowlist, never toArray(). The release notes assert internal_notes is absent from the payload and that no field value reaches the audit record. That only stays true if every tool returns an explicit array of named fields. Make "never return a model or a ->toArray()" a review rule.

Expose relations deliberately. A relation cannot reach a model nobody exposed, which means nested data is opt-in twice: once for the parent, once for the child. Model this as an explicit graph in config or policy rather than relying on $with, and you get predictable payloads for free.

Audit as identifiers, not values. Log tool name, actor, model class, record ID, and outcome. The moment you log the request payload you have recreated the leak the package is built to prevent.

Test the properties, not the prose. The 58-test suite asserts absences — that Bob's ticket is not in Alice's list, that a denied get is indistinguishable from a missing one. Copy that style: assert assertJsonMissingPath('internal_notes'), assert a 404-equivalent for the denied case, assert the audit table has no field values. Property-style assertions survive refactors; assertSee('Alice') does not.

Keep generated tools in version control and edit them in place. Regeneration is for new tools, not for refreshing existing ones — you will lose your allowlist.

Gotchas and Tips

• Fail-closed means loud. A model without a policy throws. In a shared dev environment that surfaces as a 500 mid-demo. Add the policy in the same commit as the tool.
• Don't "fix" the denied-vs-missing behaviour. A denied get returning a distinct 403 tells an attacker the record exists. The indistinguishable response is the feature; resist the pull request that adds a friendlier error.
• $hidden and $visible are not the exposure mechanism. They govern Eloquent serialisation, not what this package will emit. Two systems with similar names and different jobs — keep the allowlist authoritative and consider not returning models at all.
• Eager loading can route around your graph. ->with('customer.contracts') may pull in a model you never exposed. If a payload grows unexpectedly, check with() before you check the policy.
• Audit records are a serialisation surface. If the audit driver accepts a model or an array of attributes, someone will eventually pass one. Constrain the type.
• CI matrix: the release tests Laravel 12 and 13 across PHP 8.2–8.4, with 8.2 rows pinned to Laravel 12. Mirror that shape or you will chase a phantom failure on the 8.2 job.
• Extension points worth knowing early: custom tool classes (the generated ones are examples, not the only shape), policy resolution if you use a non-standard guard, and the audit sink if you need to ship records somewhere other than the default.
• Debugging: log the tool name and arguments before the policy check, with values redacted. When a call denies, you want to distinguish "wrong ability" from "wrong record" without printing the record.

Assessment: v0.5.0 is a compatibility and confidence release, not a breaking one. Laravel 12 support is unchanged and the constraint widened rather than moved, so upgrading is low-risk on any PHP 8.2+ app. The substantive signal is the test suite: a package whose tests assert that data is absent is telling you where its design attention went, and the day-to-day leverage follows from leaning on that — explicit policies, explicit field allowlists, identifiers-only audit trails — rather than fighting it.