Add _meta support

src/Request.php

@@ -24,10 +24,12 @@ class Request implements Arrayable
 
     /**
      * @param  array<string, mixed>  $arguments
+     * @param  array<string, mixed>|null  $meta
      */
     public function __construct(
         protected array $arguments = [],
-        protected ?string $sessionId = null
+        protected ?string $sessionId = null,
+        protected ?array $meta = null,
     ) {
         //
     }
@@ -92,6 +94,14 @@ public function sessionId(): ?string
         return $this->sessionId;
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function meta(): ?array
+    {
+        return $this->meta;
+    }
+
     /**
      * @param  array<string, mixed>  $arguments
      */
@@ -104,4 +114,12 @@ public function setSessionId(?string $sessionId): void
     {
         $this->sessionId = $sessionId;
     }
+
+    /**
+     * @param  array<string, mixed>|null  $meta
+     */
+    public function setMeta(?array $meta): void
+    {
+        $this->meta = $meta;
+    }
 }

src/Response.php

@@ -6,6 +6,7 @@
 
 use Illuminate\Support\Traits\Conditionable;
 use Illuminate\Support\Traits\Macroable;
+use InvalidArgumentException;
 use JsonException;
 use Laravel\Mcp\Enums\Role;
 use Laravel\Mcp\Exceptions\NotImplementedException;
@@ -68,6 +69,35 @@ public function content(): Content
         return $this->content;
     }
 
+    /**
+     * @param  Response|array<int, Response>  $responses
+     */
+    public static function make(Response|array $responses): ResponseFactory
+    {
+        if (is_array($responses)) {
+            foreach ($responses as $index => $response) {
+                // @phpstan-ignore instanceof.alwaysTrue
+                if (! $response instanceof Response) {
+                    throw new InvalidArgumentException(
+                        "Invalid response type at index {$index}: Expected ".Response::class.', but received '.get_debug_type($response).'.'
+                    );
+                }
+            }
+        }
+
+        return new ResponseFactory($responses);
+    }
+
+    /**
+     * @param  string|array<string, mixed>  $meta
+     */
+    public function withMeta(string|array $meta, mixed $value = null): static
+    {
+        $this->content->setMeta($meta, $value);
+
+        return $this;
+    }
+
     /**
      * @throws NotImplementedException
      */

src/ResponseFactory.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp;
+
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Traits\Conditionable;
+use Illuminate\Support\Traits\Macroable;
+use Laravel\Mcp\Server\Concerns\HasMeta;
+
+class ResponseFactory
+{
+    use Conditionable;
+    use HasMeta;
+    use Macroable;
+
+    /**
+     * @var Collection<int, Response>
+     */
+    public Collection $responses;
+
+    /**
+     * @param  Response|array<int, Response>  $responses
+     */
+    public function __construct(Response|array $responses)
+    {
+        $this->responses = collect(Arr::wrap($responses));
+    }
+
+    /**
+     * @param  string|array<string, mixed>  $meta
+     */
+    public function withMeta(string|array $meta, mixed $value = null): static
+    {
+        $this->setMeta($meta, $value);
+
+        return $this;
+    }
+
+    /**
+     * @return Collection<int, Response>
+     */
+    public function responses(): Collection
+    {
+        return $this->responses;
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function getMeta(): ?array
+    {
+        return $this->meta;
+    }
+}

src/Server/Concerns/HasMeta.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Concerns;
+
+use InvalidArgumentException;
+
+trait HasMeta
+{
+    /**
+     * @var array<string, mixed>|null
+     */
+    protected ?array $meta = null;
+
+    /**
+     * @param  string|array<string, mixed>  $meta
+     */
+    public function setMeta(string|array $meta, mixed $value = null): void
+    {
+        $this->meta ??= [];
+
+        if (! is_array($meta)) {
+            if (is_null($value)) {
+                throw new InvalidArgumentException('Value is required when using key-value signature.');
+            }
+
+            $this->meta[$meta] = $value;
+
+            return;
+        }
+
+        $this->meta = array_merge($this->meta, $meta);
+    }
+
+    /**
+     * @template T of array<string, mixed>
+     *
+     * @param  T  $baseArray
+     * @return T&array{_meta?: array<string, mixed>}
+     */
+    public function mergeMeta(array $baseArray): array
+    {
+        return ($meta = $this->meta)
+            ? [...$baseArray, '_meta' => $meta]
+            : $baseArray;
+    }
+}

src/Server/Content/Blob.php

@@ -5,13 +5,16 @@
 namespace Laravel\Mcp\Server\Content;
 
 use InvalidArgumentException;
+use Laravel\Mcp\Server\Concerns\HasMeta;
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
 use Laravel\Mcp\Server\Tool;
 
 class Blob implements Content
 {
+    use HasMeta;
+
     public function __construct(protected string $content)
     {
         //
@@ -42,13 +45,13 @@ public function toPrompt(Prompt $prompt): array
      */
     public function toResource(Resource $resource): array
     {
-        return [
+        return $this->mergeMeta([
             'blob' => base64_encode($this->content),
             'uri' => $resource->uri(),
             'name' => $resource->name(),
             'title' => $resource->title(),
             'mimeType' => $resource->mimeType(),
-        ];
+        ]);
     }
 
     public function __toString(): string
@@ -61,9 +64,9 @@ public function __toString(): string
      */
     public function toArray(): array
     {
-        return [
+        return $this->mergeMeta([
             'type' => 'blob',
             'blob' => $this->content,
-        ];
+        ]);
     }
 }

src/Server/Content/Notification.php

@@ -4,13 +4,16 @@
 
 namespace Laravel\Mcp\Server\Content;
 
+use Laravel\Mcp\Server\Concerns\HasMeta;
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
 use Laravel\Mcp\Server\Tool;
 
 class Notification implements Content
 {
+    use HasMeta;
+
     /**
      * @param  array<string, mixed>  $params
      */
@@ -53,9 +56,15 @@ public function __toString(): string
      */
     public function toArray(): array
     {
+        $params = $this->params;
+
+        if ($this->meta !== null && $this->meta !== [] && ! isset($params['_meta'])) {
+            $params['_meta'] = $this->meta;
+        }
+
         return [
             'method' => $this->method,
-            'params' => $this->params,
+            'params' => $params,
         ];
     }
 }

src/Server/Content/Text.php

@@ -4,13 +4,16 @@
 
 namespace Laravel\Mcp\Server\Content;
 
+use Laravel\Mcp\Server\Concerns\HasMeta;
 use Laravel\Mcp\Server\Contracts\Content;
 use Laravel\Mcp\Server\Prompt;
 use Laravel\Mcp\Server\Resource;
 use Laravel\Mcp\Server\Tool;
 
 class Text implements Content
 {
+    use HasMeta;
+
     public function __construct(protected string $text)
     {
         //
@@ -37,13 +40,13 @@ public function toPrompt(Prompt $prompt): array
      */
     public function toResource(Resource $resource): array
     {
-        return [
+        return $this->mergeMeta([
             'text' => $this->text,
             'uri' => $resource->uri(),
             'name' => $resource->name(),
             'title' => $resource->title(),
             'mimeType' => $resource->mimeType(),
-        ];
+        ]);
     }
 
     public function __toString(): string
@@ -56,9 +59,9 @@ public function __toString(): string
      */
     public function toArray(): array
     {
-        return [
+        return $this->mergeMeta([
             'type' => 'text',
             'text' => $this->text,
-        ];
+        ]);
     }
 }

src/Server/Contracts/Content.php

@@ -30,5 +30,10 @@ public function toPrompt(Prompt $prompt): array;
      */
     public function toResource(Resource $resource): array;
 
+    /**
+     * @param  string|array<string, mixed>  $meta
+     */
+    public function setMeta(string|array $meta, mixed $value = null): void;
+
     public function __toString(): string;
 }

src/Server/McpServiceProvider.php

@@ -80,6 +80,7 @@ protected function registerContainerCallbacks(): void
 
                 $request->setArguments($currentRequest->all());
                 $request->setSessionId($currentRequest->sessionId());
+                $request->setMeta($currentRequest->meta());
             }
         });
     }

src/Server/Methods/CallTool.php

@@ -6,9 +6,9 @@
 
 use Generator;
 use Illuminate\Container\Container;
-use Illuminate\Support\Collection;
 use Illuminate\Validation\ValidationException;
 use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
 use Laravel\Mcp\Server\Contracts\Errable;
 use Laravel\Mcp\Server\Contracts\Method;
 use Laravel\Mcp\Server\Exceptions\JsonRpcException;
@@ -61,13 +61,13 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat
     }
 
     /**
-     * @return callable(Collection<int, Response>): array{content: array<int, array<string, mixed>>, isError: bool}
+     * @return callable(ResponseFactory): array<string, mixed>
      */
     protected function serializable(Tool $tool): callable
     {
-        return fn (Collection $responses): array => [
-            'content' => $responses->map(fn (Response $response): array => $response->content()->toTool($tool))->all(),
-            'isError' => $responses->contains(fn (Response $response): bool => $response->isError()),
-        ];
+        return fn (ResponseFactory $factory): array => $factory->mergeMeta([
+            'content' => $factory->responses()->map(fn (Response $response): array => $response->content()->toTool($tool))->all(),
+            'isError' => $factory->responses()->contains(fn (Response $response): bool => $response->isError()),
+        ]);
     }
 }