PHPackages                             visualbuilder/eloquent-schema - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. visualbuilder/eloquent-schema

ActiveLibrary[Database & ORM](/categories/database)

visualbuilder/eloquent-schema
=============================

Eloquent model schema discovery service with MCP tools for Laravel applications

v1.0.3(3mo ago)3201MITPHPPHP ^8.2CI failing

Since Jan 27Pushed 3mo agoCompare

[ Source](https://github.com/visualbuilder/eloquent-schema)[ Packagist](https://packagist.org/packages/visualbuilder/eloquent-schema)[ RSS](/packages/visualbuilder-eloquent-schema/feed)WikiDiscussions 1.x Synced 1mo ago

READMEChangelogDependencies (5)Versions (6)Used By (0)

Eloquent Schema
===============

[](#eloquent-schema)

[![run-tests](https://github.com/visualbuilder/eloquent-schema/actions/workflows/run-tests.yml/badge.svg)](https://github.com/visualbuilder/eloquent-schema/actions/workflows/run-tests.yml)

Adds new MCP tools to [Laravel Boost](https://github.com/bootstrapguru/laravel-boost) for Eloquent model introspection. Designed for AI assistants and development tools that need to understand your application's data structure.

Provides complete model schemas, relationships and accessors so AI assistants can generate more accurate Eloquent queries and code without needing to read through multiple model files. This reduces token usage, speeds up responses, and eliminates guesswork about your database structure.

Features
--------

[](#features)

- **MCP Tools** - Expose model schemas to AI assistants via Laravel MCP
- **Model Discovery** - Automatically discover models in your app and configured vendor packages
- **Schema Introspection** - Extract columns, relationships, and accessors from models
- **Caching** - Built-in caching for performance
- **Vendor Support** - Include models from packages like Spatie Permission, Media Library, etc.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11 or 12
- Laravel MCP package (optional, for MCP tools)

Installation
------------

[](#installation)

```
composer require visualbuilder/eloquent-schema
```

Publish the configuration file:

```
php artisan vendor:publish --tag=eloquent-schema-config
```

Configuration
-------------

[](#configuration)

```
// config/eloquent-schema.php

return [
    // Cache TTL in seconds (0 to disable)
    'cache_ttl' => env('ELOQUENT_SCHEMA_CACHE_TTL', 3600),

    // Additional model paths to scan
    'model_paths' => [
        // app_path('Domain/Models'),
    ],

    // Explicitly include specific models
    'additional_models' => [
        // \App\Models\SomeModel::class,
    ],

    // Exclude specific models from discovery
    'excluded_models' => [
        // \App\Models\ExcludedModel::class,
    ],

    // Vendor packages to include (use composer package names)
    'included_packages' => [
        // 'spatie/laravel-permission',
        // 'spatie/laravel-medialibrary',
    ],

    // MCP tools configuration
    'mcp' => [
        'enabled' => true,
    ],
];
```

MCP Tools
---------

[](#mcp-tools)

This package provides three MCP tools for AI assistants:

### list-models

[](#list-models)

List all discoverable Eloquent models in the application.

**Parameters:**

- `filter` (string, optional) - Filter models by name (case-insensitive partial match)
- `include_vendor` (boolean, default: false) - Include models from vendor packages

**Example Response:**

```
{
  "count": 5,
  "namespace": "App\\Models",
  "models": ["User", "Order", "Product"],
  "vendor_models": ["Spatie\\Permission\\Models\\Role", "Spatie\\Permission\\Models\\Permission"]
}
```

Note: Combine `namespace` + model name for the full class (e.g., `App\Models\User`). Vendor models include their full namespace. The `vendor_models` key is only present when vendor models exist.

### model-schema

[](#model-schema)

Get the complete schema for an Eloquent model including columns, relationships, and accessors.

**Parameters:**

- `model` (string, required) - Fully qualified model class name
- `max_depth` (integer, default: 2, max: 3) - Depth for relationship exploration

**Example Response:**

```
{
  "model": "App\\Models\\Order",
  "table": "orders",
  "columns": {
    "id": "bigint",
    "user_id": "bigint",
    "status": {
      "type": "enum:pending|processing|shipped|delivered",
      "enum_class": "App\\Enums\\OrderStatus"
    },
    "total": "decimal",
    "created_at": "datetime",
    "updated_at": "datetime"
  },
  "accessors": {
    "formatted_total": "string"
  },
  "relationships": {
    "user": {
      "type": "BelongsTo",
      "model": "User"
    },
    "lineItems": {
      "type": "HasMany",
      "model": "OrderLineItem"
    }
  }
}
```

### model-fields

[](#model-fields)

Get a compact list of model columns and relationship names. Useful for building queries.

**Parameters:**

- `model` (string, required) - Fully qualified model class name

**Example Response:**

```
{
  "model": "App\\Models\\Order",
  "table": "orders",
  "columns": ["id", "user_id", "status", "total", "created_at", "updated_at"],
  "accessors": ["formatted_total"],
  "relationships": ["user", "lineItems", "payments"]
}
```

Artisan Commands
----------------

[](#artisan-commands)

### List Models

[](#list-models-1)

```
# List all app models
php artisan eloquent-schema:list

# Include vendor models
php artisan eloquent-schema:list --vendor

# Filter by name
php artisan eloquent-schema:list --filter=User

# Show count only
php artisan eloquent-schema:list --count
```

### Discover Vendor Packages

[](#discover-vendor-packages)

Interactively discover and select vendor packages with Eloquent models:

```
# Interactive selection
php artisan eloquent-schema:discover

# List available packages without selection
php artisan eloquent-schema:discover --list
```

### Cache Management

[](#cache-management)

```
# Warm the cache (discovers models and preloads schemas)
php artisan eloquent-schema:cache

# Skip schema preloading
php artisan eloquent-schema:cache --no-schema

# Set relationship depth for schema caching (warning: depth 2+ uses significant memory)
php artisan eloquent-schema:cache --max-depth=2

# Clear the cache
php artisan eloquent-schema:clear

# Clear including individual schema caches
php artisan eloquent-schema:clear --schema
```

### Testing MCP Tools from CLI

[](#testing-mcp-tools-from-cli)

Test the eloquent-schema MCP tools directly from the command line:

```
# Test list-models
php artisan eloquent-schema:mcp list-models
php artisan eloquent-schema:mcp list-models --vendor --filter=User

# Test model-schema
php artisan eloquent-schema:mcp model-schema --model='App\Models\Order'
php artisan eloquent-schema:mcp model-schema --model='App\Models\Order' --max-depth=2

# Test model-fields
php artisan eloquent-schema:mcp model-fields --model='App\Models\Order'
```

### Generic MCP Tools Command

[](#generic-mcp-tools-command)

List and call any registered MCP tool (works with Laravel Boost and custom tools):

```
# List all available MCP tools
php artisan mcp:tools --list

# Describe a tool's parameters
php artisan mcp:tools ModelSchema --describe

# Call any MCP tool with arguments
php artisan mcp:tools GetConfig --args='{"key":"app.name"}'
php artisan mcp:tools ListModels
php artisan mcp:tools DatabaseSchema --args='{"filter":"users"}'
php artisan mcp:tools ModelSchema --args='{"model":"App\\Models\\Order","max_depth":1}'
```

Vendor Model Discovery
----------------------

[](#vendor-model-discovery)

To include models from vendor packages:

1. Run the discovery command to find packages with models:

    ```
    php artisan eloquent-schema:discover
    ```
2. Select the packages you want to include
3. Add the suggested configuration to `config/eloquent-schema.php`:

    ```
    'included_packages' => [
        'spatie/laravel-permission',
        'spatie/laravel-medialibrary',
    ],
    ```
4. Warm the cache:

    ```
    php artisan eloquent-schema:cache
    ```

### Deduplication

[](#deduplication)

When your app extends a vendor model, the package intelligently prefers your app model:

- `App\Models\User` extends `Spatie\Permission\Models\User` → Only `App\Models\User` is included
- Models with the same basename prefer the App version

Using with Laravel Boost
------------------------

[](#using-with-laravel-boost)

Add the tools to your `config/boost.php`:

```
'mcp' => [
    'tools' => [
        'include' => [
            \Visualbuilder\EloquentSchema\Mcp\Tools\ListModels::class,
            \Visualbuilder\EloquentSchema\Mcp\Tools\ModelSchema::class,
            \Visualbuilder\EloquentSchema\Mcp\Tools\ModelFields::class,
        ],
        'exclude' => [],
    ],
],
```

Using with Custom MCP Server
----------------------------

[](#using-with-custom-mcp-server)

If using a custom MCP server, register the tools in your server class:

```
use Visualbuilder\EloquentSchema\Mcp\Tools\ListModels;
use Visualbuilder\EloquentSchema\Mcp\Tools\ModelSchema;
use Visualbuilder\EloquentSchema\Mcp\Tools\ModelFields;

class YourServer extends Server
{
    protected array $tools = [
        ListModels::class,
        ModelSchema::class,
        ModelFields::class,
    ];
}
```

Programmatic Usage
------------------

[](#programmatic-usage)

You can also use the services directly:

```
use Visualbuilder\EloquentSchema\Services\ModelDiscoveryService;
use Visualbuilder\EloquentSchema\Services\ModelSchemaService;

// Discover models
$discovery = app(ModelDiscoveryService::class);
$models = $discovery->getModels(includeVendor: true);

// Get schema for a model
$schema = app(ModelSchemaService::class);
$orderSchema = $schema->getSchema(Order::class, maxDepth: 2);

// Get flat field list
$fields = $schema->getFlatFieldList(Order::class);
```

Caching
-------

[](#caching)

Caching improves performance when frequently querying model schemas:

```
# Warm the cache (recommended after model changes)
php artisan eloquent-schema:cache

# Clear the cache when models change
php artisan eloquent-schema:clear --schema
```

Set cache TTL via environment variable:

```
ELOQUENT_SCHEMA_CACHE_TTL=3600

```

Set to `0` to disable caching during active development.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance79

Regular maintenance activity

Popularity13

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 83.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

110d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/133e7275d57b3053e870a66332b987ae0be489e1c61938f22196d42cf19d2be9?d=identicon)[ekoukltd](/maintainers/ekoukltd)

---

Top Contributors

[![leeoptima](https://avatars.githubusercontent.com/u/202847690?v=4)](https://github.com/leeoptima "leeoptima (5 commits)")[![cannycookie](https://avatars.githubusercontent.com/u/500822?v=4)](https://github.com/cannycookie "cannycookie (1 commits)")

---

Tags

laravelschemamcpmodeleloquentintrospection

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/visualbuilder-eloquent-schema/health.svg)

```
[![Health](https://phpackages.com/badges/visualbuilder-eloquent-schema/health.svg)](https://phpackages.com/packages/visualbuilder-eloquent-schema)
```

###  Alternatives

[mongodb/laravel-mongodb

A MongoDB based Eloquent model and Query builder for Laravel

7.1k7.2M71](/packages/mongodb-laravel-mongodb)[tucker-eric/eloquentfilter

An Eloquent way to filter Eloquent Models

1.8k4.8M26](/packages/tucker-eric-eloquentfilter)[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[spiritix/lada-cache

A Redis based, automated and scalable database caching layer for Laravel

591444.8k2](/packages/spiritix-lada-cache)[pdphilip/elasticsearch

An Elasticsearch implementation of Laravel's Eloquent ORM

145360.2k4](/packages/pdphilip-elasticsearch)[sebastiaanluca/laravel-boolean-dates

Automatically convert Eloquent model boolean attributes to dates (and back).

40111.7k1](/packages/sebastiaanluca-laravel-boolean-dates)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)