Laravel Devtoolbox

DevToolbox exposes its scanners as MCP tools. Each scanner is mapped to a tool with the prefix devtoolbox-<name> (e.g., devtoolbox-routes, devtoolbox-sql-trace).

Tool Types

Tools are categorized into two types based on their side effects:

1. Active Scanners: These tools execute actual code or queries. They are not marked as read-only or idempotent.
   • Examples: sql-trace, sql-analysis, performance.
   • Warning: Never run devtoolbox-sql-trace in a production environment.
2. Read-Only Scanners: These are idempotent and safe for introspection. They are marked with #[IsReadOnly] and #[IsIdempotent].

Tool Discovery and Execution

• Naming: Tools use the scanner name as a slug (e.g., database-schema) and a human-readable title.
• Arguments: Each tool has a typed schema defined by getOptionSchema(). Arguments are validated before execution.
• Responses: Results are returned as structured JSON. If a response exceeds devtoolbox.mcp.max_response_bytes (default 262144), the ResponseTruncator will truncate large lists and add a _truncated metadata key to help you refine your query.

DevToolbox uses a tiered approach to determine the available options and their types for its scanners. This allows both modern scanners (with explicit schemas) and legacy scanners (with simple text descriptions) to work with the MCP server.

1. Explicit Schema: If a scanner implements getOptionSchema(), that schema is used directly.
2. Inference Fallback: If a scanner only provides legacy options via getAvailableOptions() (a name => description array), the OptionSchemaInferrer attempts to derive types from the description text:
   • (array) or array of $\rightarrow$ array type.
   • JSON object $\rightarrow$ object type.
   • Well-known numeric keys (e.g., limit, count, threshold) $\rightarrow$ integer type.
   • Well-known string keys (e.g., route, model, table, path) $\rightarrow$ string type.
   • Default $\rightarrow$ boolean type.
3. Empty State: If nothing is declared, the schema and options are empty.

The DevToolbox MCP (Model Context Protocol) server allows AI coding agents (like Claude Code, Cursor, or Gemini CLI) to interact directly with your Laravel application by querying its scanners (e.g., detecting unused routes, tracing SQL, or analyzing performance).

Prerequisites

• Laravel 12 or 13
• PHP ≥ 8.3
• laravel/mcp package installed

Installation

Add laravel/mcp to your development dependencies:

composer require laravel/mcp --dev

Configuration

Ensure the MCP server is enabled and restricted to your local/testing environments in config/devtoolbox.php:

'mcp' => [
    'enabled' => env('DEVTOOLBOX_MCP_ENABLED', true),
    'environments' => ['local', 'testing'],
    'max_response_bytes' => 262_144,
],

Registration (Claude/Cursor)

To use the server with an MCP client, register it using the following command (example for Claude):

claude mcp add devtoolbox php artisan mcp:start devtoolbox

Note: The server is only registered automatically if laravel/mcp is present and the current environment is allowed by your configuration.

You can audit your application's routing security and usage using a three-step process:

1. Find unprotected routes: Use devtoolbox-security with the check_unprotected_routes: true option to identify routes missing authentication middleware.
2. Trace controller usage: For any suspicious route, use devtoolbox-route-where-lookup with the target set to that route's controller. This reveals every route that hits that specific piece of code.
3. Detect unused routes: Use devtoolbox-routes with detect_unused: true. Note that unused results should be treated as hints rather than absolute proof before deleting code.

All these tools are available via MCP or as Artisan commands using the --format=json flag (e.g., php artisan dev:routes --detect_unused=true --format=json).

# Example Artisan command for detecting unused routes
php artisan dev:routes --detect_unused=true --format=json

The devtoolbox-analysis skill (installed via php artisan boost:install) provides recipes for common Laravel maintenance tasks. All tools mentioned have Artisan twins using the --format=json flag.

1. Unprotected or Unused Routes

• Find unprotected routes: Use devtoolbox-security with check_unprotected_routes: true to list routes missing auth middleware.
• Trace controller usage: For a specific controller, use devtoolbox-route-where-lookup with the target parameter to see all routes hitting that code.
• Detect unused routes: Use devtoolbox-routes with detect_unused: true before deleting routes. Note: unused is a hint, not absolute proof.

2. N+1 and Duplicate Queries

• Analyze queries: Use devtoolbox-sql-analysis with the route (or url) and the HTTP method to find duplicate query groups.
• Trace exact queries: Use devtoolbox-sql-trace on the same route to see the ordered list of queries and bindings. Look for repeated statements with different IDs.
• Verification: Fix with eager loading (with()) and re-run the analysis to compare counts.
• Warning: These tools execute requests inside the app; use only in local environments.

3. Model or Column Impact

• Model usage: Use devtoolbox-model-usage with the model (class name) to find controllers, views, routes, jobs, and observers using it.
• Column usage: Use devtoolbox-db-column-usage with tables: ["<table>"]. Setting unused_only: true identifies candidates for removal.

4. Slow Boot Performance

• Identify slow providers: Use devtoolbox-provider-timeline with slow_threshold: 20 (in ms).
• Inspect bindings: Use devtoolbox-container-bindings with filter set to the slow provider's namespace to see what it registers.

# Example: Finding unused routes via Artisan
php artisan dev:routes --detect-unused --format=json