Laravel Model Mcp Laravel Package

Getting Started

• Upgrade with composer require <vendor>/<package>:^0.2.2 and read the changelog for 0.2.1 → 0.2.2 in one pass. The 0.2.x line is stabilising its dependency graph rather than changing behaviour, so expect no code changes on your side.
• Look first at the tool class you already own — the one extending AbstractModelTool. That base class is the seam everything flows through: validation rules, the model resolution, and the ValidationException handling that the v0.2.2 fix touches.
• First use case: build one read-only tool (e.g. "find model by ID", "search models with filters") before touching anything with side effects. It exercises the full path — auth gate → validation → model query — with a blast radius of zero.
• After upgrading, run composer why illuminate/validation and composer why illuminate/auth. Both should now report a direct requirement from this package. If either still shows only a transitive path, your lock file is stale — composer update <vendor>/<package> --with-dependencies.
• Sanity-check the tool end-to-end with a deliberately invalid payload and confirm you get structured validation errors back rather than a 500. That is exactly the path v0.2.2 hardened.

Implementation Patterns

One tool per intent, thin subclasses. Extend AbstractModelTool, declare the model and the validation rules, and keep handle() to a couple of lines. The base class owns validation and exception translation; duplicating that in your subclass means your error shape drifts from every other tool.

Treat validation rules as the public contract. Rules on a tool are consumed by an LLM or an API client, not just a form. Keep rule messages descriptive and explicit ('exists:users,id' rather than a bare required) — the failure text is often the only feedback the caller gets to self-correct.

Gate at the tool boundary, not inside handle(). Combine the package's auth integration with Laravel policies so each tool declares who may invoke it. Checking inside handle() means an unauthorised call still passes validation and burns a query.

Wrap mutating tools in transactions. A tool call is an untrusted, single-shot request. DB::transaction() around writes keeps a partially-validated multi-model operation from leaving debris, since validation failures surface as exceptions that will bubble.

Register tools centrally and keep the list explicit. Whether you register via a service provider, a config array, or an attribute, avoid auto-discovery over a directory — an accidentally exposed model tool is a data-leak vector. An explicit array is auditable in code review.

Test tools as units, not through the agent. Instantiate the tool, call it with a payload array, and assert on both the success path and the ValidationException path. This is fast, deterministic, and independent of whatever model or client sits in front of it.

Gotchas and Tips

• v0.2.2 is a supply-chain hygiene fix, not a bug fix. illuminate/validation was resolving only because something else in your tree pulled it in. Nothing broke — but on a leaner install, or after another package drops that dependency, AbstractModelTool would fatal on the missing ValidationException. The upgrade is cheap; take it.
• Watch for constraint conflicts if you pin illuminate/* components. Now that the package declares illuminate/validation and illuminate/auth explicitly, your own pinned versions must agree. Run composer update --dry-run before committing the lock file, especially on older Laravel majors.
• Transitive dependencies are load-bearing until proven otherwise. The 0.2.1 (auth) and 0.2.2 (validation) fixes are the same class of bug twice. When you write your own tool packages, declare every illuminate/* component you use — a use statement is a dependency, whether or not Composer knows it.
• Don't swallow ValidationException. The base class translates it into a caller-friendly error payload. Catching it in your subclass to return false or a custom array breaks that contract and silently drops field-level detail.
• Debugging a tool that "does nothing": check the auth gate first, then the validation rules, then the model query — in that order. A rule referencing a column you renamed fails as a validation error, not an exception, so it can look like the tool was never invoked.
• Extension point: if you need custom error shaping across every tool, override the base class's exception handling once in an intermediate abstract class rather than in each tool. Subclassing AbstractModelTool yourself keeps the upgrade path to 0.3.x a one-file change.
• Version your tool surface alongside the package. A model exposed as a tool is effectively a public API. Renaming a field or narrowing a rule is a breaking change for whatever prompts or clients call it — note it in your own changelog.