Add structuredContent & outputSchema Support (#83)

* Add structuredContent responses * fix tests * add Response::structured() * add another test * fix structure * Refactor * Fix Test * Add Tests * Add Tests * Add Tests * Refactor this * Fix CI * Update output schema handling to check for 'properties' key * Fix Test * Fix Test --------- Co-authored-by: Pushpak Chhajed <pushpak1300@gmail.com> Co-authored-by: Taylor Otwell <taylor@laravel.com>

Author: 3 people

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;
@@ -58,6 +59,28 @@ public static function blob(string $content): static
  return new static(new Blob($content));
  }
 
+ /**
+ * @param array<string, mixed> $response
+ *
+ * @throws JsonException
+ */
+ public static function structured(array $response): ResponseFactory
+ {
+ if ($response === []) {
+ throw new InvalidArgumentException('Structured content cannot be empty.');
+ }
+
+ try {
+ $json = json_encode($response, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT);
+ } catch (JsonException $jsonException) {
+ throw new InvalidArgumentException("Invalid structured content: {$jsonException->getMessage()}", 0, $jsonException);
+ }
+
+ $content = Response::text($json);
+
+ return (new ResponseFactory($content))->withStructuredContent($response);
+ }
+
  public static function error(string $text): static
  {
  return new static(new Text($text), isError: true);

src/ResponseFactory.php

@@ -10,11 +10,13 @@
 use Illuminate\Support\Traits\Macroable;
 use InvalidArgumentException;
 use Laravel\Mcp\Server\Concerns\HasMeta;
+use Laravel\Mcp\Server\Concerns\HasStructuredContent;
 
 class ResponseFactory
 {
  use Conditionable;
  use HasMeta;
+ use HasStructuredContent;
  use Macroable;
 
  /**
@@ -50,6 +52,16 @@ public function withMeta(string|array $meta, mixed $value = null): static
  return $this;
  }
 
+ /**
+ * @param array<string, mixed> $structuredContent
+ */
+ public function withStructuredContent(array $structuredContent): static
+ {
+ $this->setStructuredContent($structuredContent);
+
+ return $this;
+ }
+
  /**
  * @return Collection<int, Response>
  */
@@ -65,4 +77,12 @@ public function getMeta(): ?array
  {
  return $this->meta;
  }
+
+ /**
+ * @return array<string, mixed>|null
+ */
+ public function getStructuredContent(): ?array
+ {
+ return $this->structuredContent;
+ }
 }

src/Server/Concerns/HasStructuredContent.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Laravel\Mcp\Server\Concerns;
+
+trait HasStructuredContent
+{
+ /**
+ * @var array<string, mixed>|null
+ */
+ protected ?array $structuredContent = null;
+
+ /**
+ * @param array<string, mixed> $structuredContent
+ */
+ public function setStructuredContent(array $structuredContent): void
+ {
+ $this->structuredContent ??= [];
+
+ $this->structuredContent = array_merge($this->structuredContent, $structuredContent);
+ }
+
+ /**
+ * @param array<string, mixed> $baseArray
+ * @return array<string, mixed>
+ */
+ public function mergeStructuredContent(array $baseArray): array
+ {
+ if ($this->structuredContent === null) {
+ return $baseArray;
+ }
+
+ return array_merge($baseArray, ['structuredContent' => $this->structuredContent]);
+ }
+}

src/Server/Methods/CallTool.php

@@ -65,9 +65,11 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat
  */
  protected function serializable(Tool $tool): callable
  {
- 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()),
- ]);
+ return fn (ResponseFactory $factory): array => $factory->mergeStructuredContent(
+ $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()),
+ ])
+ );
  }
 }

src/Server/Tool.php

@@ -20,6 +20,16 @@ public function schema(JsonSchema $schema): array
  return [];
  }
 
+ /**
+ * Define the output schema for this tool's results.
+ *
+ * @return array<string, mixed>
+ */
+ public function outputSchema(JsonSchema $schema): array
+ {
+ return [];
+ }
+
  /**
  * @return array<string, mixed>
  */
@@ -36,6 +46,7 @@ public function toMethodCall(): array
  * title?: string|null,
  * description?: string|null,
  * inputSchema?: array<string, mixed>,
+ * outputSchema?: array<string, mixed>,
  * annotations?: array<string, mixed>|object,
  * _meta?: array<string, mixed>
  * }
@@ -48,16 +59,26 @@ public function toArray(): array
  $this->schema(...),
  )->toArray();
 
+ $outputSchema = JsonSchema::object(
+ $this->outputSchema(...),
+ )->toArray();
+
  $schema['properties'] ??= (object) [];
 
- // @phpstan-ignore return.type
- return $this->mergeMeta([
+ $result = [
  'name' => $this->name(),
  'title' => $this->title(),
  'description' => $this->description(),
  'inputSchema' => $schema,
  'annotations' => $annotations === [] ? (object) [] : $annotations,
- ]);
+ ];
+
+ if (isset($outputSchema['properties'])) {
+ $result['outputSchema'] = $outputSchema;
+ }
+
+ // @phpstan-ignore return.type
+ return $this->mergeMeta($result);
  }
 
  /**

tests/Fixtures/ResponseFactoryWithStructuredContentTool.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures;
+
+use Illuminate\JsonSchema\JsonSchema;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Tool;
+
+class ResponseFactoryWithStructuredContentTool extends Tool
+{
+ protected string $description = 'This tool returns a ResponseFactory with structured content';
+
+ public function handle(Request $request): ResponseFactory
+ {
+ return Response::make([
+ Response::text('Processing complete with status: success'),
+ ])->withStructuredContent([
+ 'status' => 'success',
+ 'code' => 200,
+ ]);
+ }
+
+ public function schema(JsonSchema $schema): array
+ {
+ return [];
+ }
+}

tests/Fixtures/StructuredContentTool.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures;
+
+use Illuminate\JsonSchema\JsonSchema;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Tool;
+
+class StructuredContentTool extends Tool
+{
+ protected string $description = 'This tool returns structured content';
+
+ public function handle(Request $request): ResponseFactory
+ {
+ return Response::structured([
+ 'temperature' => 22.5,
+ 'conditions' => 'Partly cloudy',
+ 'humidity' => 65,
+ ]);
+ }
+
+ public function schema(JsonSchema $schema): array
+ {
+ return [];
+ }
+}

tests/Fixtures/StructuredContentWithMetaTool.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures;
+
+use Illuminate\JsonSchema\JsonSchema;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Tool;
+
+class StructuredContentWithMetaTool extends Tool
+{
+ protected string $description = 'This tool returns structured content with meta';
+
+ public function handle(Request $request): ResponseFactory
+ {
+ return Response::structured([
+ 'result' => 'The operation completed successfully',
+ ])->withMeta(['requestId' => 'abc123']);
+ }
+
+ public function schema(JsonSchema $schema): array
+ {
+ return [];
+ }
+}

tests/Fixtures/ToolWithOutputSchema.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures;
+
+use Illuminate\JsonSchema\JsonSchema;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\ResponseFactory;
+use Laravel\Mcp\Server\Tool;
+
+class ToolWithOutputSchema extends Tool
+{
+ protected string $description = 'This tool returns user data with output schema';
+
+ public function handle(Request $request): ResponseFactory
+ {
+ return Response::structured([
+ 'id' => 123,
+ 'name' => 'John Doe',
+ 'email' => 'john@example.com',
+ ]);
+ }
+
+ public function schema(JsonSchema $schema): array
+ {
+ return [];
+ }
+
+ public function outputSchema(JsonSchema $schema): array
+ {
+ return [
+ 'id' => $schema->integer()->description('User ID')->required(),
+ 'name' => $schema->string()->description('User name')->required(),
+ 'email' => $schema->string()->description('User email'),
+ ];
+ }
+}

tests/Fixtures/ToolWithoutOutputSchema.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Fixtures;
+
+use Illuminate\JsonSchema\JsonSchema;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\Server\Tool;
+
+class ToolWithoutOutputSchema extends Tool
+{
+ protected string $description = 'This tool does not define an output schema';
+
+ public function handle(Request $request): Response
+ {
+ return Response::text('Simple text response without schema');
+ }
+
+ public function schema(JsonSchema $schema): array
+ {
+ return [];
+ }
+}