README

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.

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:

Path	Purpose
`config/project-mcp.php`	Package configuration
`database/migrations/*_create_project_mcp_tool_calls_table.php`	Optional audit log table
`app/MCP/Tools`	Custom project tools
`app/MCP/Tools/Generated`	Generated tool extension point
`app/MCP/Workflows`	Project workflow definitions
`app/MCP/Policies`	Project MCP policy extension point

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:

Setting	Default
Web MCP path	`mcp/project`
Local MCP handle	`project-mcp`
MCP middleware	`[]`

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	Group	Purpose
`business_overview`	`business`	Summarizes detected modules, model-backed entities, counts, status totals, and recent activity
`business_metric_summary`	`business`	Returns dynamic entity totals, created-today counts, failed counts, and open counts
`business_module_health`	`business`	Reports detected/configured business module availability
`business_entity_lookup`	`entities`	Searches safe text columns across configured or detected entities
`project_capabilities`	`agent_context`	Explains registered tools, risk flags, Boost integration, and discovered app context
`app_health_plus`	`diagnostics_plus`	Summarizes queue health and detected entity status health
`error_impact_summary`	`diagnostics_plus`	Summarizes failed jobs and failed/error-like entity statuses
`export_status`	`exports`	Reports export table status when export tables are configured or detected
`user_access_summary`	`permissions`	Summarizes role/permission assignments when permission tables are configured
`workflow_dry_run`	`workflows`	Validates configured workflows without executing them

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:

Custom tools from app/MCP/Tools
Generated tools from app/MCP/Tools/Generated
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:

Risk	Default	Description
Read	Allowed	Safe inspection tools
Write	Blocked	Tools that modify application data
Destructive	Blocked	Tools that delete, reset, or irreversibly change data
System	Blocked	Tools that execute commands or access system resources

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:

Push packages/laravel-project-mcp to a public Git repository.
Ensure composer validate --strict passes.
Create a release tag, for example v0.1.0.
Submit the repository URL at packagist.org/packages/submit.
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.

hasanhawary / laravel-project-mcp

Maintainers

Package info

Statistics

Security

README

Contents

Features

Requirements

Installation

Configuration

Usage

MCP Server

Available Tools

Custom Tools

Security

Testing

Publishing

Changelog

Contributing

Credits

License