Modernize MCP inputSchema generation with JsonSchemaExporter by vcolin7 · Pull Request #2995 · microsoft/mcp

vcolin7 · 2026-07-04T02:53:22Z

What does this PR do?

Modernizes how the Azure MCP Server builds each tool's inputSchema so it aligns with the latest MCP spec and stops relying on a bespoke reflection-based schema builder.

Today the loaders construct inputSchema through a hand-rolled TypeToJsonTypeMapper plus custom ToolInputSchema / ToolPropertySchema models. That code has to re-implement JSON Schema semantics that the framework already understands (nullability, enums, arrays, Guid formats), and it is easy to drift from what the MCP SDK and OpenAI strict mode expect. This PR replaces that machinery with System.Text.Json.Schema.JsonSchemaExporter, the standard exporter, so schema shape comes from one well-understood source.

To be followed by #3000.

Approach:

Adds OptionSchemaGenerator (in Microsoft.Mcp.Core) as the single place that turns a command's options into an inputSchema. Both CommandFactoryToolLoader and NamespaceToolLoader now call it, so the two loaders can no longer produce divergent schemas.
Emits a strict object schema (type: object + properties + additionalProperties: false) for OpenAI strict-mode compatibility, with required populated from required options.
Sets TreatNullObliviousAsNonNullable = true so bare reference types (string, string[]) stay single-typed. Only genuine value-type nullables (Guid?, int?) become ["...", "null"], and Guid maps to format: "uuid". This preserves the existing generated shapes rather than churning every tool's schema.
Leaves the raw-passthrough path untouched: commands that declare a raw-mcp-tool-input option (e.g. deploy_architecture_diagram_generate) still emit their hand-authored schema verbatim. The marker constant (RawMcpToolInputOptionName) and the detection helper (IsRawMcpToolInputOption) now live on the shared BaseToolLoader, so both loaders inherit one source of truth and the new discovery test reuses that same check instead of mirroring it. The Deploy toolset's option references were repointed to the relocated constant.
Removes the now-dead TypeToJsonTypeMapper, ToolInputSchema, ToolPropertySchema, and their tests (9 files).

Testing:

Adds a discovery test that walks every registered tool and asserts it produces a valid strict-object input schema, skipping only the raw-passthrough commands. Because the MCP SDK's tool.InputSchema setter already runs IsValidMcpToolSchema, a passing run also proves SDK acceptance.
All ToolLoading and core unit tests pass (CommandFactoryToolLoaderTests: 33/33 green); verified AOT-safe via a trimmed publish. The two [UnconditionalSuppressMessage] attributes on the generator are load-bearing under IsAotCompatible=true and are documented inline.

Scope note: This is the input-schema half only. outputSchema / structuredContent support is a deliberate follow-up PR so reviewers get a smaller, focused diff here.

GitHub issue number?

Lays the groundwork for addressing #260

Pre-merge Checklist

Invoking Livetests

Copilot submitted PRs are not trustworthy by default. Users with write access to the repo need to validate the contents of this PR before leaving a comment with the text /azp run mcp - pullrequest - live. This will trigger the necessary livetest workflows to complete required validation.

…a types

…om subclasses

Copilot

Pull request overview

Modernizes Azure MCP tool inputSchema generation by replacing the bespoke reflection-based schema builder with System.Text.Json.Schema.JsonSchemaExporter, centralizing schema creation to keep tool loaders consistent and MCP/OpenAI strict-mode compatible.

Changes:

Added OptionSchemaGenerator to generate strict-object JSON Schemas (type: object, properties, additionalProperties: false) and populate required.
Updated both CommandFactoryToolLoader and NamespaceToolLoader to use the shared generator, while preserving raw passthrough behavior via a shared BaseToolLoader helper/constant.
Removed legacy schema models (ToolInputSchema / ToolPropertySchema), type-mapper utilities, and their associated unit tests; added a broad discovery test for schema shape validity.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/Azure.Mcp.Tools.Deploy/src/Options/DeployOptionDefinitions.cs	Repoints raw-input option constant to the new shared location on `BaseToolLoader`.
tools/Azure.Mcp.Tools.Deploy/src/Options/Architecture/DiagramGenerateOptions.cs	Repoints `JsonPropertyName` raw-input marker to `BaseToolLoader`.
servers/Azure.Mcp.Server/changelog-entries/vcolin7-modernize-input-schema.yaml	Adds changelog entry describing the input schema modernization.
core/Microsoft.Mcp.Core/tests/Microsoft.Mcp.Core.Tests/Areas/Server/Models/ToolPropertySchemaTests.cs	Removes tests tied to deleted schema model types.
core/Microsoft.Mcp.Core/tests/Microsoft.Mcp.Core.Tests/Areas/Server/Models/ToolInputSchemaTests.cs	Removes tests tied to deleted schema model types.
core/Microsoft.Mcp.Core/tests/Microsoft.Mcp.Core.Tests/Areas/Server/Commands/TypeToJsonTypeMapperTests.cs	Removes tests tied to deleted legacy mapper behavior.
core/Microsoft.Mcp.Core/src/Areas/Server/ServerJsonContext.cs	Updates source-gen context to serialize `JsonObject` for schemas (removes old schema types).
core/Microsoft.Mcp.Core/src/Areas/Server/Models/ToolPropertySchema.cs	Removes legacy schema model.
core/Microsoft.Mcp.Core/src/Areas/Server/Models/ToolInputSchema.cs	Removes legacy schema model.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/TypeToJsonTypeMapper.cs	Removes legacy reflection-based type mapper.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/ToolLoading/NamespaceToolLoader.cs	Switches to `OptionSchemaGenerator`; shares raw-passthrough detection via `BaseToolLoader`.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/ToolLoading/CommandFactoryToolLoader.cs	Switches to `OptionSchemaGenerator`; shares raw-passthrough detection via `BaseToolLoader`.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/ToolLoading/BaseToolLoader.cs	Introduces shared raw-input constant and detection helper used by both loaders/tests.
core/Microsoft.Mcp.Core/src/Areas/Server/Commands/OptionSchemaGenerator.cs	Adds the new centralized schema generator based on `JsonSchemaExporter`.
core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/TypeToJsonTypeMapperTests.cs	Removes tests tied to deleted legacy mapper behavior.
core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/OptionTypeTests.cs	Removes tests tied to deleted legacy mapper behavior.
core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/Commands/ToolLoading/CommandFactoryToolLoaderTests.cs	Adds a broad discovery test validating strict-object schema shape for all tools (skipping raw passthrough).
core/Azure.Mcp.Core/tests/Azure.Mcp.Core.Tests/Areas/Server/ArrayOrCollectionElementTypeTests.cs	Removes tests tied to deleted legacy mapper behavior.

conniey · 2026-07-13T21:51:48Z

+    /// Builds the <c>inputSchema</c> root <see cref="JsonObject"/> for the supplied options.
+    /// Always emits an <c>"object"</c> schema with <c>additionalProperties: false</c> for OpenAI strict-mode compatibility.
+    /// </summary>
+    public static JsonObject CreateInputSchema(IReadOnlyList<Option> options)


Did we have tests for this? I was trying to look for the case where options == 0 since that path was removed from the original source.

We did not. I just added tests for this case and a few more :)

conniey · 2026-07-13T21:55:48Z

+/// </remarks>
+internal static class OptionSchemaGenerator
+{
+    private static readonly JsonSerializerOptions s_schemaOptions = CreateSchemaOptions();


I believe our naming for static was just to use SchemaOptions rather than s_

We use both naming conventions in the codebase but I've updated this class to omit the s_ like other classes in the same folder. We should consolidate the naming at some point though.

conniey · 2026-07-13T21:58:42Z

/azp run mcp - pullrequest - live

azure-pipelines · 2026-07-13T21:59:29Z

Azure Pipelines successfully started running 1 pipeline(s).

vcolin7 · 2026-07-14T01:15:19Z

@conniey It looks like the live test failures are not related to my changes and have been around for a while. Here's a comparison with a run for a PR from last week:

vcolin7 · 2026-07-14T01:19:22Z

Actually, most errors are related to resource deployment issues or missing parameters. Maybe we messed up in a couple of places when we updated how we handle options a few weeks back. I'll open an issue for someone to look into that.

/cc @alzimmermsft

…ables

vcolin7 added 5 commits July 2, 2026 23:24

Add OptionSchemaGenerator for exporter-based input schemas

2b0dbd3

Generate input schemas via OptionSchemaGenerator; remove legacy schem…

bc9904f

…a types

Add discovery test asserting every tool emits a valid input schema

f9af959

Add changelog entry for input schema modernization

aae54f0

Reuse loader's raw-input detection in discovery test

7c3fb5b

github-project-automation Bot added this to Azure MCP Server Jul 4, 2026

github-project-automation Bot moved this to Untriaged in Azure MCP Server Jul 4, 2026

vcolin7 added 2 commits July 3, 2026 22:14

Updated docs in OptionSchemaGenerator

6431e35

Moved IsRawMcpToolInputOption() into BaseToolLoader and removed it fr…

73d1d40

…om subclasses

vcolin7 force-pushed the vcolin7/input-output-schema-v2 branch from 479b43f to 73d1d40 Compare July 4, 2026 04:43

vcolin7 requested review from alzimmermsft, conniey and g2vinay July 4, 2026 05:02

vcolin7 self-assigned this Jul 4, 2026

vcolin7 added the tools-Core AZMCP Core functionality that all other tools build on top of label Jul 4, 2026

vcolin7 moved this from Untriaged to In Progress in Azure MCP Server Jul 4, 2026

vcolin7 added this to the 2026-06 milestone Jul 4, 2026

vcolin7 marked this pull request as ready for review July 4, 2026 05:09

vcolin7 requested review from a team, wchigit and xfz11 as code owners July 4, 2026 05:09

Copilot AI review requested due to automatic review settings July 4, 2026 05:09

vcolin7 requested a review from a team as a code owner July 4, 2026 05:09

vcolin7 requested review from KarishmaGhiya, RickWinter, jairmyree and xirzec July 4, 2026 05:09

Copilot started reviewing on behalf of vcolin7 July 4, 2026 05:09 View session

Copilot AI reviewed Jul 4, 2026

View reviewed changes

Comment thread ...ests/Azure.Mcp.Core.Tests/Areas/Server/Commands/ToolLoading/CommandFactoryToolLoaderTests.cs

Add enum spot-check to input schema discovery test

25a2196

vcolin7 added 2 commits July 6, 2026 14:54

Assert every enum type-union entry via Assert.All

39c1fa3

Decouple enum schema test from shipping tool

ede34b9

This was referenced Jul 7, 2026

Add outputSchema and structuredContent infrastructure with App Config pilot #2999

Closed

Add outputSchema and structuredContent infrastructure with App Config pilot #3000

Open

vcolin7 modified the milestones: 2026-06, 2026-07 Jul 7, 2026

conniey reviewed Jul 13, 2026

View reviewed changes

Add tests for OptionSchemaGenerator and update naming for static vari…

2357332

…ables

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Modernize MCP inputSchema generation with JsonSchemaExporter#2995

Modernize MCP inputSchema generation with JsonSchemaExporter#2995
vcolin7 wants to merge 11 commits into
mainfrom
vcolin7/input-output-schema-v2

vcolin7 commented Jul 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

conniey Jul 13, 2026

Uh oh!

vcolin7 Jul 14, 2026

Uh oh!

conniey Jul 13, 2026

Uh oh!

vcolin7 Jul 14, 2026

Uh oh!

conniey commented Jul 13, 2026

Uh oh!

azure-pipelines Bot commented Jul 13, 2026

Uh oh!

vcolin7 commented Jul 14, 2026

Uh oh!

vcolin7 commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

vcolin7 commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

GitHub issue number?

Pre-merge Checklist

Invoking Livetests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

conniey Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

vcolin7 Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

conniey Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

vcolin7 Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

conniey commented Jul 13, 2026

Uh oh!

azure-pipelines Bot commented Jul 13, 2026

Uh oh!

vcolin7 commented Jul 14, 2026

Uh oh!

vcolin7 commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vcolin7 commented Jul 4, 2026 •

edited

Loading