Laravel Project MCP

Laravel Project MCP adds project-aware Model Context Protocol tools to Laravel applications. It discovers the installed application's Eloquent models, configured business entities, and schema so AI agents can understand the project domain without hardcoded, app-specific assumptions.

Use Laravel Boost for framework documentation, raw schema, routes, logs, and config. Use Laravel Project MCP for live business context, model-backed entity discovery, operational summaries, workflow dry-runs, and custom project tools.

Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
• MCP Server
• Available Tools
• Custom Tools
• Security
• Testing
• Publishing
• Changelog
• Credits
• License

Features

• Auto-discovered Laravel package service provider.
• Dynamic Eloquent model discovery from configurable model paths.
• Configurable business entities, modules, status columns, sensitive columns, export tables, and permission tables.
• Optional Laravel MCP web and local server registration.
• Business overview, metrics, entity lookup, app health, error impact, exports, permissions, workflows, and agent context tools.
• Read/write/destructive/system risk profiles.
• Safe-by-default behavior with write, destructive, and system tools disabled unless explicitly enabled.
• Sensitive value masking for arguments, tool output, errors, and audit logs.
• Output limiting to protect MCP clients from oversized responses.
• Optional database audit logging for tool calls.
• Custom project tools under app/MCP/Tools.
• Generated tool extension point under app/MCP/Tools/Generated.

Requirements

• PHP 8.1, 8.2, 8.3, 8.4, or 8.5
• Laravel 13.x components
• Optional laravel/mcp to expose web/local MCP servers
• Optional laravel/boost for complementary Laravel agent tools

Installation

Install the package via Composer:

composer require hasanhawary/laravel-project-mcp

Publish the package configuration and migration:

php artisan project-mcp:install

Run migrations:

php artisan migrate

Check the installation:

php artisan project-mcp:doctor

The install command publishes or prepares:

You may also publish files manually:

php artisan vendor:publish --tag=project-mcp-config
php artisan vendor:publish --tag=project-mcp-migrations

Configuration

The package is configured in config/project-mcp.php.

Common environment variables:

PROJECT_MCP_ENABLED=true
PROJECT_MCP_PROFILE=developer
PROJECT_MCP_FULL_ACCESS=false
PROJECT_MCP_ALLOW_WRITE=false
PROJECT_MCP_ALLOW_DESTRUCTIVE=false
PROJECT_MCP_ALLOW_SYSTEM=false
PROJECT_MCP_HTTP_ENABLED=false
PROJECT_MCP_SERVER_ENABLED=true
PROJECT_MCP_WEB_PATH=mcp/project
PROJECT_MCP_LOCAL_HANDLE=project-mcp

By default, business entities are discovered from Eloquent models in app/Models:

'business_model_paths' => [
    app_path('Models'),
],

If your application keeps models in modules or packages, add those paths:

'business_model_paths' => [
    app_path('Models'),
    base_path('modules/Billing/Models'),
    base_path('modules/CRM/Models'),
],

You can override entity discovery explicitly:

'searchable_business_entities' => [
    'customers' => 'customers',
    'invoices' => ['table' => 'billing_invoices'],
],

You can tune discovery and safety rules:

'business_entity_excluded_tables' => [
    'migrations',
    'jobs',
    'sessions',
    'personal_access_tokens',
],

'business_entity_search_columns' => [
    'name',
    'title',
    'email',
    'slug',
    'code',
    'status',
    'state',
    'type',
    'description',
],

'business_entity_sensitive_columns' => [
    'password',
    'remember_token',
    'token',
    'api_token',
    'secret',
    'private_key',
    'otp',
],

Usage

List registered tools:

php artisan project-mcp:list-tools

Run a tool from the command line:

php artisan project-mcp:test-tool business_overview

Run a tool with JSON arguments:

php artisan project-mcp:test-tool business_entity_lookup '{"query":"acme","limit":5}'

Generate and inspect the project map:

php artisan project-mcp:scan

Show current package capabilities:

php artisan project-mcp:capabilities

Review audited tool calls:

php artisan project-mcp:audit

MCP Server

If laravel/mcp is installed, Laravel Project MCP can register both web and local MCP servers.

Default server settings:

Inspect the web server:

php artisan mcp:inspector mcp/project

Inspect the local server:

php artisan mcp:inspector project-mcp

If you expose the web MCP server publicly, protect it with middleware:

'mcp_middleware' => ['auth:sanctum'],

Available Tools

Tool definitions include input schemas, risk levels, groups, source, and Laravel Boost overlap metadata.

Custom Tools

Create a custom tool:

php artisan project-mcp:make-tool CustomerRiskTool

Custom tools are written to app/MCP/Tools and extend LaravelProjectMcp\Tools\AbstractProjectMcpTool:

<?php

namespace App\MCP\Tools;

use LaravelProjectMcp\Core\ToolContext;
use LaravelProjectMcp\Core\ToolResult;
use LaravelProjectMcp\Tools\AbstractProjectMcpTool;

class CustomerRiskTool extends AbstractProjectMcpTool
{
    public function name(): string
    {
        return 'customer_risk';
    }

    public function description(): string
    {
        return 'Summarize customer risk signals.';
    }

    public function group(): string
    {
        return 'business';
    }

    /**
     * @param  array<string, mixed>  $arguments
     */
    public function handle(array $arguments, ToolContext $context): ToolResult
    {
        return ToolResult::success([
            'risk' => 'low',
        ], 'Customer risk generated.');
    }
}

Tool priority:

1. Custom tools from app/MCP/Tools
2. Generated tools from app/MCP/Tools/Generated
3. Package default tools

If a custom tool uses the same name() as a package tool, the custom tool wins.

Security

Laravel Project MCP is read-only by default. Write, destructive, and system tools are blocked unless explicitly enabled.

PROJECT_MCP_ALLOW_WRITE=false
PROJECT_MCP_ALLOW_DESTRUCTIVE=false
PROJECT_MCP_ALLOW_SYSTEM=false

Risk profile controls:

Additional safety features:

• Sensitive values are masked by default.
• Tool output is limited by output_limit.
• Audit logging is available through project_mcp_tool_calls.
• Paths can be restricted with allowed_paths and blocked_paths.
• Artisan and shell commands have allowlists and denylists.

Before enabling write, destructive, or system tools, review your config carefully and protect MCP endpoints with authentication.

Testing

Run the focused package tests from a host Laravel application:

php artisan test --compact tests/Feature/ProjectMcp/ProjectMcpPackageTest.php

Validate package metadata:

composer validate --strict

Format code:

vendor/bin/pint --dirty --format agent

Publishing

To publish this package on Packagist:

1. Push packages/laravel-project-mcp to a public Git repository.
2. Ensure composer validate --strict passes.
3. Create a release tag, for example v0.1.0.
4. Submit the repository URL at packagist.org/packages/submit.
5. Enable the GitHub/Packagist hook so future tags sync automatically.

Recommended release command:

git tag v0.1.0
git push origin v0.1.0

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Pull requests are welcome. Please keep the package generic and avoid adding tools that assume one specific application's tables, models, modules, or business domain.

Credits

• Hasan Hawary

License

The MIT License (MIT). Please see License File for more information.