Sdk Laravel Package

Getting Started

Minimal Setup for a Laravel Developer

1. Installation:

   composer require mcp/sdk
   

2. First Use Case - Exposing a Laravel Controller as an MCP Tool:

   use Mcp\Server;
   use Mcp\Server\Transport\StdioTransport;
   use Mcp\Capability\Attribute\McpTool;
   
   class CalculatorController {
       #[McpTool]
       public function add(int $a, int $b): int {
           return $a + $b;
       }
   }
   
   $server = Server::builder()
       ->setServerInfo('Laravel MCP Server', '1.0.0')
       ->setDiscovery(__DIR__, ['App/Http/Controllers'])
       ->build();
   
   $transport = new StdioTransport();
   $server->run($transport);
   

3. First Use Case - Consuming an MCP Server from Laravel:

   use Mcp\Client;
   use Mcp\Client\Transport\HttpTransport;
   
   $client = Client::builder()
       ->setClientInfo('Laravel Client', '1.0.0')
       ->build();
   
   $transport = new HttpTransport('http://localhost:8000');
   $client->connect($transport);
   
   $result = $client->callTool('add', ['a' => 5, 'b' => 3]);
   $client->disconnect();
   

Where to Look First

• Server SDK: docs/server-builder.md for configuration options
• Client SDK: docs/client.md for API reference
• Examples: docs/examples.md for Laravel-specific patterns
• Laravel Integration: Check symfony/mcp-bundle for Symfony/Laravel-specific extensions

Implementation Patterns

Laravel-Specific Integration Patterns

1. Service Provider Integration

// app/Providers/McpServiceProvider.php
public function register()
{
    $this->app->singleton('mcp.server', function ($app) {
        return Server::builder()
            ->setServerInfo('Laravel MCP Server', '1.0.0')
            ->setDiscovery(__DIR__.'/../Http/Controllers', ['.php'])
            ->setSession(new FileSessionStore(storage_path('framework/sessions')))
            ->build();
    });
}

2. Laravel Command for MCP Server

// app/Console/Commands/RunMcpServer.php
public function handle()
{
    $server = app('mcp.server');
    $transport = new StreamableHttpTransport(
        $this->laravel->make(Request::class),
        $this->laravel->make(ResponseFactory::class),
        $this->laravel->make(StreamFactory::class)
    );

    $response = $server->run($transport);
    $response->send();
}

3. Dynamic Tool Registration from Database

// Register tools from Laravel database
$server = Server::builder()
    ->setServerInfo('Dynamic MCP Server', '1.0.0')
    ->setDiscovery(__DIR__.'/../Http/Controllers')
    ->build();

foreach (Tool::all() as $tool) {
    $server->getRegistry()->addTool(
        [$this->app->make($tool->handler), $tool->method],
        $tool->name,
        $tool->description
    );
}

4. Client Integration with Laravel HTTP Client

// Use Laravel HTTP client as transport
$client = Client::builder()
    ->setClientInfo('Laravel Client', '1.0.0')
    ->build();

$transport = new HttpTransport(
    $this->http->withOptions(['timeout' => 30])
);

$client->connect($transport);

5. Middleware for Authentication

// Create middleware to validate MCP requests
public function handle($request, Closure $next)
{
    $transport = new StreamableHttpTransport(
        $request,
        $this->app->make(ResponseFactory::class),
        $this->app->make(StreamFactory::class)
    );

    $server = app('mcp.server');
    $response = $server->run($transport);

    return $response->send();
}

6. Event Listeners for MCP Lifecycle

// Listen to MCP server events
public function handle(ServerEvent $event)
{
    switch ($event->getType()) {
        case ServerEvent::CAPABILITIES_DISCOVERED:
            $this->logCapabilities($event->getCapabilities());
            break;
        case ServerEvent::SESSION_CREATED:
            $this->createSessionRecord($event->getSessionId());
            break;
    }
}

7. Resource Templates with Eloquent Models

#[McpResourceTemplate(uri: 'data://users/{id}')]
public function getUserResourceTemplate(int $id): array
{
    return [
        'title' => 'User Data',
        'description' => 'Retrieve user information',
        'schema' => [
            'type' => 'object',
            'properties' => [
                'id' => ['type' => 'integer'],
                'name' => ['type' => 'string']
            ]
        ]
    ];
}

#[McpResource(uri: 'data://users/{id}')]
public function getUserResource(int $id): array
{
    return User::findOrFail($id)->toArray();
}

Gotchas and Tips

Common Pitfalls

1. Attribute Discovery Limitations:

   • Only classes with #[McpTool], #[McpResource], etc. attributes in the discovery paths will be registered
   • Fix: Use manual registration for dynamic capabilities or classes without attributes

2. Session Management:

   • Default in-memory session storage won't persist across server restarts
   • Tip: Configure FileSessionStore or Psr16SessionStore for production:

     $server->setSession(new FileSessionStore(storage_path('framework/sessions')));
     

3. HTTP Transport Quirks:

   • Case sensitivity in headers (e.g., Content-Type vs content-type)
   • Fix: Use StreamableHttpTransport with proper middleware:

     $transport = new StreamableHttpTransport(
         $request,
         $responseFactory,
         $streamFactory,
         defaultMiddleware: [
             new NormalizeHeadersMiddleware()
         ]
     );
     

4. Tool Argument Validation:

   • The SDK validates arguments against the method signature, but complex types (e.g., custom objects) may fail
   • Tip: Use simple types or JSON-serializable data structures

5. Concurrency Issues:

   • The SDK isn't thread-safe by default
   • Fix: Use a single server instance with proper session management

Debugging Tips

1. Enable Verbose Logging:

   $server = Server::builder()
       ->setLogger(new MonologLogger([
           new StreamHandler(storage_path('logs/mcp.log'), Logger::DEBUG)
       ]))
       ->build();
   

2. Inspect Capabilities:

   $capabilities = $server->getCapabilities();
   dump($capabilities->getTools());
   dump($capabilities->getResources());
   

3. Validate Protocol Compliance:

   • Use the conformance tests:

     composer test:conformance
     

4. Check Transport Errors:

   • Wrap transport operations in try-catch:

     try {
         $client->connect($transport);
     } catch (TransportException $e) {
         Log::error('MCP Transport Error', ['error' => $e->getMessage()]);
     }
     

Extension Points

1. Custom Transports:

   • Implement TransportInterface for custom protocols (e.g., WebSocket, gRPC):

     class CustomTransport implements TransportInterface {
         public function send(Request $request): Response {
             // Custom implementation
         }
     }
     

2. Protocol Extensions:

   • Register custom extensions during capability negotiation:

     $server->getCapabilities()->addExtension('my-extension', [
         'version' => '1.0',
         'features' => ['custom-feature']
     ]);
     

3. Custom Validation:

   • Override argument validation:

     $server->getRegistry()->setArgumentValidator(
         new CustomArgumentValidator()
     );
     

4. Session Storage:

   • Implement SessionStoreInterface for custom storage backends:

     class DatabaseSessionStore implements SessionStoreInterface {
         public function save(Session $session): void {
             // Save to database
         }
         // ... other methods
     }
     

5. Event Subscribers:

   • Create custom event subscribers:

     $server->addEventSubscriber(new class implements EventSubscriberInterface {
         public function onCapabilitiesDiscovered(CapabilitiesDiscoveredEvent $event) {
             // Custom logic
         }
     });
     

Laravel-Specific Tips

1. Service Container Integration:

   • Bind MCP components to Laravel's container:

     $this->app->bind(TransportInterface::class, function ($app) {
         return new HttpTransport('http://mcp-server');
     });
     

2. **Queue Jobs for Long-R