Mcp Server Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require app-dev-panel/mcp-server
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       AppDevPanel\McpServer\McpServerServiceProvider::class,
   ],
   

2. Publish Config

   php artisan vendor:publish --provider="AppDevPanel\McpServer\McpServerServiceProvider" --tag="mcp-server-config"
   

   Configure config/mcp-server.php with your AI assistant endpoint and credentials.

3. First Use Case Register a model to expose via MCP:

   use AppDevPanel\McpServer\Facades\McpServer;
   
   // In a service provider or boot method
   McpServer::registerModel(\App\Models\User::class, [
       'fields' => ['id', 'name', 'email'],
       'readOnly' => true,
   ]);
   

4. Start the Server

   php artisan mcp-server:serve
   

   Default endpoint: http://localhost:8080/mcp

Implementation Patterns

Model Registration

• Dynamic Registration Register models programmatically (e.g., in a boot() method):

  McpServer::registerModel(\App\Models\Product::class, [
      'fields' => ['sku', 'name', 'price'],
      'filters' => ['category', 'in_stock'],
  ]);
  

• Bulk Registration Use a service class to register multiple models:

  class McpModelRegistrar {
      public function __construct() {
          McpServer::registerModel(\App\Models\Order::class, [...]);
          McpServer::registerModel(\App\Models\Review::class, [...]);
      }
  }
  

Query Handling

• Custom Query Logic Override default query behavior via a resolver:

  McpServer::registerResolver(\App\Models\Post::class, function ($query, $params) {
      return $query->where('published_at', '>=', now()->subDays(30))
                   ->with('author');
  });
  

• Pagination Enable pagination in config:

  'pagination' => [
      'enabled' => true,
      'default_per_page' => 20,
  ],
  

Integration with AI Assistants

• Webhook Endpoint Configure the MCP server as a webhook for AI tools:

  // config/mcp-server.php
  'webhook' => [
      'enabled' => true,
      'secret' => env('MCP_WEBHOOK_SECRET'),
  ],
  

• Real-Time Updates Use Laravel Events to push updates to the MCP server:

  event(new \App\Events\UserUpdated($user));
  // MCP server listens for this event and refreshes cached data
  

Gotchas and Tips

Common Pitfalls

• Field Whitelisting Forgetting to whitelist fields in the config will result in 403 Forbidden errors. Always validate fields against the registered schema.

• Rate Limiting The package enforces rate limits by default (configurable in config/mcp-server.php). Exceeding limits returns 429 Too Many Requests.

• Caching Quirks The server caches model metadata. Clear cache after schema changes:

  php artisan mcp-server:clear-cache
  

Debugging

• Enable Verbose Logging Set debug: true in config to log raw MCP requests/responses to storage/logs/mcp-server.log.

• Test Endpoint Use php artisan mcp-server:test to validate your setup and check registered models.

Extension Points

• Custom Auth Middleware Override the default auth logic by binding a middleware:

  McpServer::extend(function ($server) {
      $server->middleware(function ($request, $next) {
          // Custom auth logic
          return $next($request);
      });
  });
  

• Field Transformers Transform fields before returning them to the AI assistant:

  McpServer::registerTransformer(\App\Models\User::class, function ($user) {
      return [
          'id' => $user->id,
          'name' => strtoupper($user->name), // Example transformation
      ];
  });
  

• Event Listeners Listen for MCP events (e.g., McpServer\Events\ModelRegistered):

  McpServer::listen(function ($event) {
      Log::info("Model registered: {$event->model}");
  });