Laravel Model Inspector Mcp Laravel Package

Getting Started

1. Install into the Laravel app you want inspected (not globally):

   composer require skylence/laravel-model-inspector-mcp --dev
   php artisan vendor:publish --tag=model-inspector-config
   

   Keep it in require-dev — it is a developer tool, not runtime infrastructure.

2. Register the MCP server with your client (Claude Desktop, Claude Code, Cursor, etc.). The package ships an Artisan entrypoint (typically php artisan mcp:serve or a dedicated model-inspector:* command — confirm the exact name in the README/src/Console). A stdio registration looks like:

   {
     "mcpServers": {
       "laravel-models": {
         "command": "php",
         "args": ["artisan", "mcp:serve"],
         "cwd": "/absolute/path/to/project"
       }
     }
   }
   

   Absolute cwd matters: the server boots the app from that directory.

3. Look here first, in this order:

   • config/model-inspector.php (published) — model discovery paths, exclusions, which tools are enabled.
   • src/Servers / src/Tools — the actual tool list and their input schemas. This is the contract the LLM sees.
   • README examples — copy one prompt verbatim, then iterate.

4. First use case: ask the assistant a question you would otherwise answer by opening five files — "List the relationships, casts, and fillable attributes of App\Models\Invoice, and tell me which of them are belongsTo vs hasMany." If that works, the server is wired correctly. The second prompt to try is "Which models reference App\Models\Team and how?" — that is where the package earns its keep over grep.

Implementation Patterns

Schema-grounded code generation. The highest-value pattern is to make the inspector the first tool call in any generation task: "inspect Order and OrderItem, then write a Filament resource / policy / factory that matches the actual schema." This removes the most common LLM failure mode in Laravel work — hallucinated column names and invented relationship methods.

Relationship graph traversal before refactors. Before renaming a column or splitting a model, ask for inbound references ("what points at users.id?"). Use this as a cheap pre-flight check alongside grep, not as a replacement for static analysis or a real migration plan.

Drift detection between models and migrations. Prompt: "compare the $fillable/$casts on Invoice against database/migrations/*invoice* and list mismatches." This catches the classic forgotten-migration or stale-$fillable bug faster than reading diffs.

Scoped exposure for large codebases. On anything past ~50 models, whitelist rather than blacklist. Point discovery at app/Models with explicit except entries for vendor-ish or legacy models. Fewer, sharper tools produce better LLM output than a firehose of 200 model summaries.

Multi-step workflows with a DB tool. The inspector tells you the shape; pair it with a read-only query tool (or php artisan tinker manually) when you need values. Keep those as separate servers so you can disable DB access in shared/remote contexts.

Team distribution. Commit the config file and a short "MCP setup" section in the repo README with the client JSON snippet. Per-project (.mcp.json in the repo root) beats per-developer global config — everyone gets identical tool behaviour and the config is code-reviewed.

Filament-heavy stacks. Given the package's origin, expect the most polish around relationship/enum/column introspection — exactly the inputs needed to scaffold Filament resources, form schemas, and table columns. Use it as a schema oracle when generating resources by hand.

Extension points. If the shipped tools don't cover your case (computed attributes, custom casts, tenant-scoped models), register your own tool class in the server's tool list rather than forking. The inspection logic is usually a thin wrapper over Schema::getColumns() / reflection — cheap to reuse.

Gotchas and Tips

• Zero stars, zero dependents. Treat this as an unaudited dependency: read src/ before installing, pin an exact version ("1.0.*"), and never let it into require. There is no community signal to lean on if it breaks or goes unmaintained.
• stdio protocol poisoning. Any dump(), dd(), echo, or Laravel log written to stdout corrupts the MCP stream and produces opaque "server disconnected" errors. Route logs to stderr or files; if the assistant suddenly stops responding, suspect a stray ray()/dump() in a model's boot().
• Boot-time side effects. Inspecting a model triggers its service provider/observer/trait bootstrapping. Models that query the DB, resolve tenancy, or call external APIs in boot() or booted() will slow down or break inspection. Exclude them, or guard those calls.
• Multi-tenancy and non-default connections. Introspection against a tenant-scoped connection can either fail or silently return the wrong schema. Prefer model/reflection-based inspection over live DB introspection, and test with DB_CONNECTION pointed at a scratch database.
• Cache staleness. If model metadata is cached, php artisan config:clear / the package's cache-clear command after every migrate — otherwise the assistant confidently describes a schema from three commits ago.
• Data leakage. A model-inspection server in a shared or hosted client means your schema (table names, columns, sometimes sample values) leaves the machine. Restrict to local stdio transport, whitelist models, and audit any tool that returns row data.
• Context bloat. Dumping all models into one prompt blows the context window and degrades answer quality. Ask for one model or one relationship question at a time; the package's value is precision, not breadth.
• Laravel/PHP version constraints. Verify composer.json requirements against your app — early-stage packages frequently lag on Laravel major bumps, and a broken composer update in a dev-only package is an annoying afternoon.
• Verify the tool contract, not the README. The README drifts fastest. Have the assistant list its available tools on first connect ("what tools do you have for Laravel?") — the model's own tool listing is the ground truth for what this version actually exposes.