Implement Streamable HTTP Transport with SSE (POST request)

- Implement client-initiated request (POST endpoint) with JSON-RPC and
SSE responses.
- Fixes LaravelModelToolkit collection

Author: fsmonter

README.md

@@ -112,13 +112,23 @@ To add to Cursor, or any (most?) MCP clients with a config file:
 }
 ```
 
-### SSE
+### Streamable HTTP Transport with SSE
 
-Coming soon.
+Laravel Loop supports the [streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) for the MCP protocol, which includes SSE capabilities for client-initiated requests (POST).
+
+To enable the Streamable HTTP transport, update your `.env` file:
+
+```bash
+LOOP_STREAMABLE_HTTP_ENABLED=true
+```
+
+This will expose an MCP endpoint at `/mcp` that supports both JSON-RPC and Server-Sent Events. The endpoint is protected by Laravel Sanctum by default.
+
+See [HTTP Streaming Documentation](docs/http-streaming.md) for more details on configuration, and usage.
 
 ## Roadmap
 
 - [ ] Add a chat component to the package, so you can use the tools inside the application without an MCP client.
 - [ ] Refine the existing tools
 - [ ] Add write capabilities to the existing tools
-- [ ] Add tests
+- [ ] Add tests

config/loop.php

@@ -10,18 +10,27 @@
     | provided by the Laravel Loop package.
     |
     */
+    'streamable_http' => [
+        /*
+        |--------------------------------------------------------------------------
+        | Streamable HTTP Endpoint Enabled?
+        |--------------------------------------------------------------------------
+        */
+        'enabled' => env('LOOP_STREAMABLE_HTTP_ENABLED', false),
 
-    'sse' => [
         /*
         |--------------------------------------------------------------------------
-        | SSE Endpoint Enabled?
+        | Streamable HTTP Endpoint Path
         |--------------------------------------------------------------------------
+        |
+        | The path where the MCP HTTP endpoint will be available.
+        |
         */
-        'enabled' => env('LOOP_SSE_ENABLED', false),
+        'path' => env('LOOP_STREAMABLE_HTTP_PATH', '/mcp'),
 
         /*
         |--------------------------------------------------------------------------
-        | SSE Endpoint Authentication Middleware
+        | Streamable HTTP Endpoint Authentication Middleware
         |--------------------------------------------------------------------------
         |
         | The middleware used to authenticate MCP requests.

docs/http-streaming.md

@@ -0,0 +1,61 @@
+# Laravel Loop HTTP Streaming
+
+Laravel Loop provides a streamable HTTP transport for the Model Context Protocol (MCP) that supports client-initiated requests (POST). The MCP HTTP transport is able to process JSON and SSE streaming responses on a single endpoint.
+
+## Configuration
+
+To enable and configure the HTTP MCP endpoint, update your `.env` file and/or `config/loop.php`:
+
+```php
+# Enable the HTTP MCP endpoint
+LOOP_STREAMABLE_HTTP_ENABLED=true
+
+# Set the endpoint path (default: /mcp)
+LOOP_STREAMABLE_HTTP_PATH=/mcp
+```
+
+### Security Considerations
+
+The MCP HTTP endpoint should be protected with proper authentication. By default, it uses Laravel Sanctum, but you can configure the middleware stack in `config/loop.php`:
+
+```php
+'middleware' => ['auth:sanctum'],
+```
+
+## Client-Initiated Messages (POST)
+
+Clients can send JSON-RPC 2.0 messages to the MCP server by making HTTP POST requests to the configured endpoint.
+
+### Single Request
+
+```bash
+curl -X POST http://your-app.test/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"Test Client"},"capabilities":{},"protocolVersion":"2024-11-05"}}'
+```
+
+### Batch Requests
+
+```bash
+curl -X POST http://your-app.test/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '[{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"Test Client"},"capabilities":{},"protocolVersion":"2024-11-05"}},{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}]'
+```
+
+### SSE Streaming Responses
+
+Clients can request SSE responses for batch processing by setting the `Accept` header to include `text/event-stream`:
+
+```bash
+curl -X POST http://your-app.test/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '[{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"Test Client"},"capabilities":{},"protocolVersion":"2024-11-05"}},{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}]'
+```
+
+The server will respond with an SSE stream containing each response as a separate event.

routes/api.php

@@ -2,11 +2,27 @@
 
 use Illuminate\Support\Facades\Route;
 use Kirschbaum\Loop\Http\Controllers\McpController;
-use Kirschbaum\Loop\Http\Middleware\SseEnabledMiddleware;
+use Kirschbaum\Loop\Http\Middleware\StreamableHttpEnabledMiddleware;
 
+<<<<<<< HEAD
 Route::prefix('mcp')
     ->middleware(array_merge([SseEnabledMiddleware::class], (array) config('loop.sse.middleware', [])))
     ->group(function () {
         Route::get('/', McpController::class);
         Route::post('/', McpController::class);
     });
+=======
+$path = config('loop.streamable_http.path', '/mcp');
+$streamableHttpEnabled = config('loop.streamable_http.enabled', false);
+
+if ($streamableHttpEnabled) {
+    Route::prefix($path)
+        ->middleware([
+            StreamableHttpEnabledMiddleware::class,
+            ...config('loop.sse.middleware', []),
+        ])
+        ->group(function () {
+            Route::post('/', McpController::class);
+        });
+}
+>>>>>>> 764429b (Implement Streamable HTTP Transport with SSE (POST request))

src/Http/Controllers/McpController.php

@@ -4,15 +4,122 @@
 
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Kirschbaum\Loop\McpHandler;
+use Kirschbaum\Loop\Services\SseService;
+use Symfony\Component\HttpFoundation\StreamedResponse;
 
 class McpController extends Controller
 {
-    public function __invoke(Request $request, McpHandler $mcpHandler): JsonResponse
+    public function __construct(protected McpHandler $mcpHandler, protected SseService $sseService) {}
+
+    /**
+     * Handle MCP requests.
+     */
+    public function __invoke(Request $request): JsonResponse|StreamedResponse|Response
+    {
+        $acceptsEventStream = strpos($request->header('Accept', ''), 'text/event-stream') !== false;
+        $acceptsJson = strpos($request->header('Accept', ''), 'application/json') !== false;
+
+        if (! $acceptsEventStream && ! $acceptsJson) {
+            return response()->json([
+                'jsonrpc' => '2.0',
+                'id' => null,
+                'error' => [
+                    'message' => 'Not Acceptable: Client must accept text/event-stream or application/json',
+                ],
+            ], 406);
+        }
+
+        $requestData = $request->all();
+        $containsRequests = $this->containsJsonRpcRequests($requestData);
+
+        if (! $containsRequests) {
+            $this->mcpHandler->handle($requestData);
+
+            return response('', 202);
+        }
+
+        if ($this->clientPrefersJson($acceptsJson, $acceptsEventStream)) {
+            return $this->handlePostJsonResponse($requestData);
+        }
+
+        return $this->handlePostSseResponse($requestData);
+    }
+
+    /**
+     * Handle SSE response for POST requests.
+     *
+     * @param  array  $messages  JSON-RPC messages from the client
+     */
+    protected function handlePostSseResponse(
+        array $messages
+    ): StreamedResponse {
+        $response = $this->sseService->createPostSseResponse(
+            $messages,
+            fn ($message) => $this->mcpHandler->handle($message),
+        );
+
+        return $response;
+    }
+
+    /**
+     * Handle JSON response for POST requests.
+     */
+    protected function handlePostJsonResponse(array $messages): JsonResponse
     {
-        $message = $request->all();
+        $response = $this->mcpHandler->handle($messages);
 
-        return response()->json($mcpHandler->handle($message));
+        return response()->json($response);
+    }
+
+    /**
+     * Handle GET requests (server-initiated messages) according to MCP specification.
+     */
+    protected function handleGetRequest(Request $request)
+    {
+        // TODO
+    }
+
+    /**
+     * Check if the input contains any JSON-RPC requests.
+     *
+     * @param  mixed  $input
+     */
+    protected function containsJsonRpcRequests($input): bool
+    {
+        // If input is an array with numeric keys, it's a batch
+        if (is_array($input) && array_keys($input) === range(0, count($input) - 1)) {
+            foreach ($input as $item) {
+                if ($this->isJsonRpcRequest($item)) {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        return $this->isJsonRpcRequest($input);
+    }
+
+    /**
+     * Check if the client prefers JSON over SSE.
+     */
+    protected function clientPrefersJson($acceptsJson, $acceptsEventStream): bool
+    {
+        return $acceptsJson && $acceptsEventStream === false;
+    }
+
+    /**
+     * Check if an item is a JSON-RPC request.
+     */
+    protected function isJsonRpcRequest($item): bool
+    {
+        return is_array($item) &&
+               isset($item['jsonrpc']) &&
+               $item['jsonrpc'] === '2.0' &&
+               isset($item['method']) &&
+               isset($item['id']);
     }
 }

src/Http/Middleware/SseEnabledMiddleware.php renamed to src/Http/Middleware/StreamableHttpEnabledMiddleware.php

@@ -6,11 +6,11 @@
 use Illuminate\Http\Request;
 use Symfony\Component\HttpFoundation\Response;
 
-class SseEnabledMiddleware
+class StreamableHttpEnabledMiddleware
 {
     public function handle(Request $request, Closure $next): Response
     {
-        if (! config('loop.sse.enabled')) {
+        if (! config('loop.streamable_http.enabled')) {
             return response('Not Found', 404);
         }
 

src/LoopServiceProvider.php

@@ -3,6 +3,7 @@
 namespace Kirschbaum\Loop;
 
 use Kirschbaum\Loop\Commands\LoopMcpServerStartCommand;
+use Kirschbaum\Loop\Services\SseService;
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
@@ -34,5 +35,9 @@ public function packageBooted(): void
 
             return $loop;
         });
+
+        $this->app->singleton(SseService::class, function ($app) {
+            return new SseService;
+        });
     }
 }

src/Services/SseService.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace Kirschbaum\Loop\Services;
+
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class SseService
+{
+    /**
+     * Create a streamed SSE response for a POST request.
+     */
+    public function createPostSseResponse(array $messages, callable $processor): StreamedResponse
+    {
+        $headers = [
+            'Content-Type' => 'text/event-stream',
+            'Cache-Control' => 'no-cache, no-store, max-age=0, must-revalidate',
+            'Pragma' => 'no-cache',
+            'X-Accel-Buffering' => 'no',
+        ];
+
+        if (! ini_get('safe_mode')) {
+            set_time_limit(0);
+        }
+
+        return new StreamedResponse(function () use ($messages, $processor) {
+            if (ob_get_level()) {
+                ob_end_clean();
+            }
+
+            echo ": stream opened\n\n";
+            flush();
+
+            if (! isset($messages[0])) {
+                $messages = [$messages];
+            }
+
+            foreach ($messages as $message) {
+                if (! isset($message['id'])) {
+                    logger('Missing ID in message');
+
+                    continue;
+                }
+
+                $response = $processor($message);
+
+                echo $this->formatSseEvent($response, eventId: null);
+                flush();
+            }
+        }, 200, $headers);
+    }
+
+    /**
+     * Format a JSON-RPC message as an SSE event.
+     */
+    public function formatSseEvent(array $message, ?string $eventId = null): string
+    {
+        $output = '';
+
+        if ($eventId !== null) {
+            $output .= "id: {$eventId}\n";
+        }
+
+        // Add event type (default to 'message')
+        $output .= "event: message\n";
+
+        $jsonData = json_encode($message);
+        $output .= "data: {$jsonData}\n\n";
+
+        return $output;
+    }
+}

src/Toolkits/LaravelModelToolkit.php

@@ -37,7 +37,7 @@ public function getTools(): ToolCollection
         $tools = new ToolCollection;
 
         foreach ($this->models as $model) {
-            $tools->merge($this->buildModelTools($model));
+            $tools = $tools->merge($this->buildModelTools($model));
         }
 
         return $tools;