laravel-route-tracer-mcp

TonyGeez/laravel-route-tracer-mcp

3.2

If you are the rightful owner of laravel-route-tracer-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Laravel Route Tracer MCP Server is a tool that integrates with Laravel applications to provide AI assistants with insights into application structure and execution flow.

Tools
7
Resources
0
Prompts
0

Laravel Route Tracer MCP Server

Model Context Protocol server that enables AI assistants to intelligently work with Laravel applications by tracing route execution and discovering actual file dependencies.

Overview

This MCP server integrates with the tonygeez/laravel-route-tracer package to provide AI assistants with deep insights into Laravel application structure and execution flow. Instead of guessing which files are involved in a route, AI can trace actual runtime dependencies.

Prerequisites

Required Laravel Package

You must have the Laravel Route Tracer package installed and configured:

composer require tonygeez/laravel-route-tracer --dev
php artisan vendor:publish --tag=route-tracer-config

The config publication step is required for the package to function properly.

Node.js Dependencies

npm install @modelcontextprotocol/sdk

Installation

Step 1: Save the MCP Server

Save the laravel-tracer-mcp.js file to your preferred location:

mkdir -p ~/.mcp-servers
cp laravel-tracer-mcp.js ~/.mcp-servers/
chmod +x ~/.mcp-servers/laravel-tracer-mcp.js

Step 2: Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "laravel-tracer": {
      "command": "node",
      "args": ["/absolute/path/to/laravel-tracer-mcp.js"],
      "env": {
        "LARAVEL_PATH": "/absolute/path/to/your/laravel/application"
      }
    }
  }
}

Replace the paths with your actual file locations.

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Available Tools

The MCP server provides six tools that AI assistants can use:

trace_laravel_route

Trace a specific Laravel route to discover all files involved in its execution.

Parameters:

  • route_name (required): Laravel route name or URI pattern
  • method (optional): HTTP method (GET, POST, PUT, DELETE, etc.)

Returns:

  • Complete list of files loaded during execution
  • Categorized by type (controllers, models, policies, etc.)
  • Execution time and memory usage metrics

enable_route_tracing

Enable route tracing for specific routes or globally.

Parameters:

  • routes (optional): Array of route names to trace. Empty array enables globally.

Note: Routes must be triggered via HTTP request after enabling tracing.

disable_route_tracing

Disable route tracing globally.

Parameters: None

view_trace_results

View stored trace results from previous route executions.

Parameters:

  • latest_only (optional): Show only the most recent trace
  • route_filter (optional): Filter traces by route name pattern

list_laravel_routes

List all available routes in the Laravel application.

Parameters:

  • filter (optional): Filter routes by name or URI pattern
  • method (optional): Filter by HTTP method

read_traced_file

Read the contents of a file discovered during route tracing.

Parameters:

  • file_path (required): Relative path from Laravel root

get_laravel_context

Get general context about the Laravel application structure and configuration.

Parameters: None

Returns:

  • Application name and version
  • Laravel and PHP versions
  • Route tracer installation status
  • Key directory locations
  • Recommended workflow

Usage Examples

Once configured, AI assistants can help with tasks like:

Discover Route Dependencies

"Which files does the api.users.index route use?"

The AI will:

  1. Enable tracing for that route
  2. Instruct you to trigger it
  3. Show all loaded files with categories
  4. Provide execution metrics

Analyze Controller Structure

"Show me the UserController and explain what it does"

The AI will:

  1. List routes to find the controller
  2. Read the controller file
  3. Analyze its methods and dependencies

Debug Performance Issues

"Trace the slow dashboard route and tell me what might be causing delays"

The AI will:

  1. Enable tracing with timing metrics
  2. Analyze execution time per file
  3. Identify potential bottlenecks

Understand Feature Implementation

"How is user authentication implemented in this app?"

The AI will:

  1. List auth-related routes
  2. Trace the login/register routes
  3. Read controllers, models, and policies
  4. Explain the authentication flow

Workflow

The typical workflow when AI assists with Laravel development:

  1. AI lists available routes using list_laravel_routes
  2. AI enables tracing for relevant routes using enable_route_tracing
  3. You trigger the routes manually via browser or HTTP client
  4. AI views trace results using view_trace_results or trace_laravel_route
  5. AI reads specific files using read_traced_file
  6. AI provides insights based on actual execution flow

Configuration

Environment Variables

Set LARAVEL_PATH in the MCP server configuration to point to your Laravel application root directory. This is where your artisan file is located.

Laravel Route Tracer Config

After publishing the config, you can modify config/route-tracer.php:

return [
    'enabled' => env('ROUTE_TRACER_ENABLED', false),
    'output_format' => env('ROUTE_TRACER_FORMAT', 'json'),
    'log_channel' => env('ROUTE_TRACER_LOG_CHANNEL', 'stack'),
    'exclude_patterns' => [
        '/vendor/',
        '/bootstrap/',
        '/storage/',
    ],
];

Troubleshooting

Server Not Appearing in Claude

  1. Verify the path in claude_desktop_config.json is absolute
  2. Check that laravel-tracer-mcp.js has execute permissions
  3. Ensure Node.js and required packages are installed
  4. Restart Claude Desktop completely

Artisan Commands Failing

  1. Verify LARAVEL_PATH points to your Laravel root
  2. Ensure PHP is in your system PATH
  3. Confirm the route tracer package is installed
  4. Check that php artisan vendor:publish --tag=route-tracer-config was run

No Trace Data Appearing

  1. Enable tracing first using the tool
  2. Actually trigger the route via HTTP request
  3. Check Laravel logs for any errors
  4. Verify the route exists using list_laravel_routes

Permission Issues

Ensure the MCP server process has read access to:

  • Laravel application directory
  • Composer files
  • Configuration files

Output Format

All CLI output uses consistent color coding:

  • Red (✘): Errors and failures
  • Yellow (⚠): Warnings and important notes
  • Green (✔): Success messages and confirmations
  • Blue (▍): Information pointers and details
  • Cyan (█████): Section headers and titles

Security Considerations

  • The MCP server can read any file in your Laravel application
  • Only use with development environments
  • Do not expose the MCP server to untrusted networks
  • The route tracer package is marked as --dev dependency for a reason

Limitations

  • Requires manual route triggering (HTTP requests)
  • Cannot automatically execute POST/PUT/DELETE routes with data
  • Traces only show files loaded during that specific execution path
  • Performance impact when tracing is enabled

Contributing

Issues and improvements can be directed to the Laravel Route Tracer package repository.

License

This MCP server follows the same license as the Laravel Route Tracer package.

Resources