Symfony Inspector Mcp Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Symfony project:

   composer require --dev alya/symfony-inspector-mcp
   

2. Enable the bundle in config/bundles.php (only for dev environment):

   return [
       Alya\SymfonyInspectorMcp\SymfonyInspectorMcpBundle::class => ['dev' => true],
   ];
   

3. Configure MCP in config/packages/mcp_inspector.yaml:

   mcp_inspector:
       transport: stdio
       allowed_commands:
           - cache:clear
           - list
       log_file: '%kernel.logs_dir%/%kernel.environment%.log'
       log_tail_lines: 200
   

4. Configure MCP client transports in config/packages/mcp.yaml:

   mcp:
       client_transports:
           stdio: true
           http: false
   

First Use Case

Start the MCP server and connect an LLM agent (e.g., Claude Desktop):

php bin/console mcp:server

Then, in your LLM agent, ask questions like:

• "Show me all routes handling POST requests to /api."
• "List all services with logger in their name."

Implementation Patterns

Workflows

1. Debugging Routes/Entities:

   • Use list_routes to inspect route definitions dynamically.
   • Use inspect_entity to debug Doctrine entities without restarting the app.

2. Log Inspection:

   • Tail logs with read_logs or access symfony://logs/latest for real-time debugging.
   • Example: "Explain the last 50 lines of the dev log."

3. Configuration Exploration:

   • Query show_config for bundle/extension settings (e.g., "framework" or "doctrine").
   • Access symfony://config/{name} for structured config dumps.

4. Command Execution:

   • Whitelist safe commands (e.g., cache:clear) in allowed_commands.
   • Run tests or commands via run_console or run_tests.

5. Integration with AI Agents:

   • Configure the agent (e.g., Claude Desktop) to point to bin/console mcp:server.
   • Use symfony://resources URIs (e.g., symfony://routes) for direct data access.

Integration Tips

• Laravel Equivalent: Replace Symfony’s bin/console with Laravel’s artisan in the agent’s config (if adapting for Laravel).
• Security: Always restrict allowed_commands to trusted operations (e.g., avoid debug:config in production).
• Performance: Tail logs (log_tail_lines) to balance responsiveness and resource usage.
• Testing: Use run_tests to automate test execution from the agent (e.g., "Run the UserTest suite.").

Gotchas and Tips

Pitfalls

1. Dev-Only Enforcement:

   • The bundle throws a LogicException if enabled outside dev. Avoid accidental production exposure.
   • Fix: Double-check bundles.php and environment variables.

2. Command Whitelisting:

   • Unlisted commands in allowed_commands return errors. Test whitelisted commands manually first.
   • Tip: Start with safe commands (e.g., list, cache:clear) before adding risky ones.

3. Doctrine Dependencies:

   • inspect_entity and symfony://entities require doctrine/orm. Install it if missing:

     composer require doctrine/orm
     

   • Migrations status (symfony://migrations/status) needs doctrine/migrations.

4. Log File Paths:

   • log_file must point to a valid path (e.g., %kernel.logs_dir%/%kernel.environment%.log). Verify paths in dev and test environments.

5. Transport Limitations:

   • stdio transport requires the agent to connect via the console process. For remote agents, enable http transport (though this requires additional security setup).

Debugging

• Server Not Starting: Check mcp.yaml for valid client_transports (e.g., stdio: true).
• Permission Errors: Ensure the log file (log_file) is readable by the PHP process.
• Tool Failures: Use symfony://config/{name} to verify configuration before querying tools like show_config.

Extension Points

1. Custom Tools:

   • Extend the bundle by creating new MCP tools. Example:

     // src/Mcp/CustomTool.php
     use Symfony\Component\Mcp\Tool\ToolInterface;
     class CustomTool implements ToolInterface { ... }
     

   • Register in services.yaml:

     services:
         App\Mcp\CustomTool:
             tags: [mcp.tool]
     

2. Resource URIs:

   • Add custom URIs (e.g., symfony://custom/data) by implementing a ResourceProvider and tagging it:

     services:
         App\Mcp\CustomResourceProvider:
             tags: [mcp.resource_provider]
     

3. Transport Customization:

   • Override the default stdio transport by creating a custom McpTransport service and configuring it in mcp.yaml.

Laravel-Specific Notes

• Artisan Integration: Replace bin/console with php artisan in the agent’s config (e.g., "args": ["php", "artisan", "mcp:server"]).
• Service Container: Use Laravel’s container (app()) instead of Symfony’s ContainerInterface in custom tools.
• Configuration: Adapt YAML configs to Laravel’s config/mcp_inspector.php format:

  return [
      'transport' => 'stdio',
      'allowed_commands' => ['cache:clear', 'list'],
      'log_file' => storage_path('logs/laravel.log'),
  ];