feat: Add output schema support to MCP tools #153

bigdevlarry · 2025-11-16T22:05:22Z

The changes add comprehensive support for outputSchema in the Tools definition, enabling MCP servers to specify the expected structure and types of tool responses.

This includes:

Added outputSchema parameter to Builder::addTool() method
Updated the Tool class constructor and JSON serialization to support outputSchema
Added validation for outputSchema structure and type requirements
Enhanced existing tests to verify outputSchema functionality works correctly
Fixed related type annotation issues and code style problems

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
[x ] I have added appropriate error handling
I have added or updated documentation as needed

Additional context

bigdevlarry · 2025-11-16T22:08:07Z

Hi @chr-hertel, & @CodeWithKyrian the OutputSchema support PR is back up

bigdevlarry · 2025-12-01T20:21:19Z

Hi @chr-hertel, @Nyholm can I get some eyes on here for the output schema support. Ty

Nyholm · 2025-12-02T20:01:26Z

Interesting. I do like the idea. I'll spend some more time to read the code.

chr-hertel

In general this looks pretty good already, just one thing i noticed with one test scenario. structuredContent should be optional in response payload

chr-hertel · 2025-12-06T14:00:07Z

...nspector/Http/snapshots/HttpCombinedRegistrationTest-tools_call-discovered_status_check.json

+  "isError": false,
+  "structuredContent": {
+    "result": "System status: OK (discovered)"
+  }


I wonder a bit about this change here - it's not adding value to me. spec is unclear about it, but i think we shouldn't just add it always.

@chr-hertel this has now been actioned, so structrued content will only be added if outputschema is present and explicility specified

bigdevlarry · 2025-12-06T19:07:40Z

@chr-hertel To make structuredContent optional in the response payload, I'll have to change the behavior so that outputSchema is only present when explicitly provided in the #[McpTool] attribute, not auto-generated from return types or DocBlocks. When an outputSchema is explicitly provided, structuredContent must be included in the response (as required by the MCP spec). When no outputSchema is provided, neither outputSchema nor structuredContent is included.

chr-hertel · 2025-12-06T21:07:45Z

The case that i was pointing out was mostly just returning a string, but still had that result => '...' structure on top - i just can't find any reference for that in the spec or do i miss sth?

bigdevlarry · 2025-12-06T23:18:27Z

The case that i was pointing out was mostly just returning a string, but still had that result => '...' structure on top - i just can't find any reference for that in the spec or do i miss sth?

Good shout ! I was working with the wrong assumption that the result wrapper was in the spec. structuredContent now matches the outputSchema properties directly, no more top level result wrapping. The structure is as in the MCP spec example. I've updated the diagram on the PR to reflect the test as well

soyuka · 2025-12-08T18:43:32Z

src/Capability/Registry/ToolReference.php

+            }
+
+            return $toolExecutionResult;
+        }


shouldn't we leave that to implementations of the handler? I'm not sure we should alter the content at any point in the sdk.

soyuka · 2025-12-08T18:46:25Z

src/Capability/Registry/ToolReference.php

+        }
+
+        return $value;
+    }


Not sure to understand this already happens in formatResult if our goal is to return a structured content maybe that we should add a condition above?

soyuka · 2025-12-08T18:47:38Z

src/Schema/Result/CallToolResult.php

+    public static function success(array $content, ?array $meta = null, ?array $structuredContent = null): self
    {
-        return new self($content, false, null, $meta);
+        return new self($content, false, $meta, $structuredContent);


not sure to why this is needed content can be a structured content since #93 or am I missing something?

Missed that PR. We can use the existing structure. Thanks for flagging

soyuka · 2025-12-08T18:49:08Z

src/Schema/Tool.php

 *     required: string[]|null
 * }
+ * @phpstan-type ToolOutputSchema array{
+ *     type: 'object',


Suggested change

* type: 'object',

* type: 'object',

Can't the schema be a list? object type is not specified in the spec for the output.

soyuka · 2025-12-08T18:49:50Z

src/Schema/Tool.php

+            if (isset($data['outputSchema']['properties']) && \is_array($data['outputSchema']['properties']) && empty($data['outputSchema']['properties'])) {
+                $data['outputSchema']['properties'] = new \stdClass();
+            }
+        }


I advise against validating this here we should leave that to the user discretion, it'll make the sdk more portable and subject to specification changes.

I was following the validation pattern we've for the inputSchema setup above. Also, if we don't add validation for outputSchema, how can we have a structured output format? Users might use a structure we don't support, don't you think?

Yeah I'm actually not a huge fan of the above inputSchema implementation either :).

I think it's the responsability of another abstraction to do this, and its also part of a bigger discussion around json schema and validation (I suggested already that these should not be coded into the php-sdk as they're quite complicated subjects).

soyuka · 2025-12-08T18:54:51Z

src/Server/Handler/Request/CallToolHandler.php

+
+            $result = $rawResult;
+            if (!$rawResult instanceof CallToolResult) {
+                $result = new CallToolResult($reference->formatResult($rawResult), structuredContent: $structuredContent);


I'd try not to change this part of the code, I understand we want to comply with the spec that says:

Servers MUST provide structured results that conform to this schema.

If possible I think it should be handled in the formatResult.

My personal opinion would be to throw if the handler doesn't return a structured content.

Yes, we're trying to comply with what the spec says here. I also think it reads better having it here otherwise, @chr-hertel feels otherwise

soyuka · 2025-12-08T18:55:17Z

tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_call-calculate_range.json

+      "text": "{\n    \"result\": 50,\n    \"operation\": \"10 multiply 5\",\n    \"precision\": 2,\n    \"within_bounds\": true\n}"
+    }
+  ],
+  "isError": false


this should probably not change

Just indentation, no code change

I know but why as we didn't change anything to the json serialization this is weird to me and pollutes the diff

soyuka · 2025-12-08T18:55:25Z

tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_call-format_text.json

+    }
+  ],
+  "isError": false
 }


this should probably not change

Just indentation, no code change

soyuka · 2025-12-08T18:55:33Z

tests/Inspector/Http/snapshots/HttpSchemaShowcaseTest-tools_call-generate_config.json

+      "text": "{\n    \"success\": true,\n    \"config\": {\n        \"app\": {\n            \"name\": \"TestApp\",\n            \"env\": \"development\",\n            \"debug\": true,\n            \"url\": \"https://example.com\",\n            \"port\": 8080\n        },\n        \"generated_at\": \"2025-01-01T00:00:00+00:00\",\n        \"version\": \"1.0.0\",\n        \"features\": {\n            \"logging\": true,\n            \"caching\": false,\n            \"analytics\": false,\n            \"rate_limiting\": false\n        }\n    },\n    \"validation\": {\n        \"app_name_valid\": true,\n        \"url_valid\": true,\n        \"port_in_range\": true\n    }\n}"
+    }
+  ],
+  "isError": false


this should probably not change (same for the other snapshots not sure why they change)

Just indentation, no code change

soyuka · 2025-12-08T18:57:21Z

tests/Unit/Capability/Discovery/SchemaGeneratorFixture.php

+            'type' => 'object',
+            'additionalProperties' => true,
+        ]
+    )]


on a general matter I think (if possible) that we should avoid to change existing fixtures but instead add new ones, as for that we need to change existing tests.

soyuka · 2025-12-08T18:57:45Z

Nice addition we definitely miss this! Thanks!

chr-hertel · 2025-12-08T19:57:15Z

@bigdevlarry we have a misunderstanding here: my point was that output schema - in my understanding - is only needed for more complex structures - not for simple string responses for example.

compared with the typescript-sdk:

simple tool response

structured tool response

my take-away here is: there's no need for the structuredContent keyword in the response, if we only return a string - but feel free to point out what i miss

bigdevlarry · 2025-12-08T21:17:35Z

@chr-hertel At the moment, if structuredContent returns a primitive (string, int, bool, etc.), extractStructuredContent() method in the src/Capability/Registry/ToolReference.php returns null, and structuredContent is not included in the response. So image 2, looks valid where you've get_weather because the outputSchema returns an object/array. If this is still not the intended behaviour, maybe you can point out what to add/remove in the extractStructuredContent method

bigdevlarry requested review from CodeWithKyrian, Nyholm and chr-hertel as code owners November 16, 2025 22:05

bigdevlarry mentioned this pull request Nov 16, 2025

[Server] No Ability to set outputSchema #68

Open

bigdevlarry force-pushed the add-support-for-output-schema branch from ec01d9a to a2d7b6d Compare November 16, 2025 23:43

bigdevlarry force-pushed the add-support-for-output-schema branch from 9234613 to b3b69cd Compare November 29, 2025 19:08

chr-hertel requested changes Dec 6, 2025

View reviewed changes

bigdevlarry force-pushed the add-support-for-output-schema branch 2 times, most recently from e8de647 to 329533b Compare December 6, 2025 20:53

bigdevlarry force-pushed the add-support-for-output-schema branch from c8f19cc to 2772869 Compare December 6, 2025 21:10

feat: Add output schema support to MCP tools

13d5b77

bigdevlarry force-pushed the add-support-for-output-schema branch from 4e96598 to 13d5b77 Compare December 6, 2025 22:52

soyuka suggested changes Dec 8, 2025

View reviewed changes

soyuka mentioned this pull request Dec 9, 2025

feat: mcp bundle tool integration api-platform/core#7595

Open

5 tasks

feat: Add output schema support to MCP tools #153

Are you sure you want to change the base?

feat: Add output schema support to MCP tools #153

Conversation

bigdevlarry commented Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

bigdevlarry commented Nov 16, 2025

Uh oh!

bigdevlarry commented Dec 1, 2025

Uh oh!

Nyholm commented Dec 2, 2025

Uh oh!

chr-hertel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bigdevlarry commented Dec 6, 2025

Uh oh!

chr-hertel commented Dec 6, 2025

Uh oh!

bigdevlarry commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soyuka commented Dec 8, 2025

Uh oh!

chr-hertel commented Dec 8, 2025

Uh oh!

bigdevlarry commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

bigdevlarry commented Nov 16, 2025 •

edited

Loading

chr-hertel left a comment •

edited

Loading

bigdevlarry commented Dec 6, 2025 •

edited

Loading

bigdevlarry commented Dec 8, 2025 •

edited

Loading