Custom C# data models usage in MCP Tool by generating JSON Schema

[IvanMurzak]

Pre-submission Checklist

• This post follows the MCP community guidelines

What would you like to share?

Problem

Need to have easy way to generate Json Schema for complex Input/Output data arguments for MCP Tool, Prompt, Resources. Sample:

[McpServerTool]
public static Result Command(List<Data> dataList, EnumFlag flag, Data? optionalData = null)
{
     return new Result();
}

public class Data
{
    public int? optionalInt;
    [Description("THIS IS THE DEMO DESCRIPTION.")]
    public string address;
    public List<Data> list; // recursive
}

public struct Result
{
    public bool isDone;
    public string? errorMessage;
}

[Description("DEMO ENUM DESCRIPTION.")]
public enum EnumFlag { red, green, yellow }

Expected Json Schema: Input Arguments

{
  "type": "object",
  "properties": {
    "dataList": {
      "$ref": "#/$defs/System.Collections.Generic.List\u003CData\u003E"
    },
    "flag": {
      "type": "string",
      "enum": [
        "red",
        "green",
        "yellow"
      ],
      "description": "DEMO ENUM DESCRIPTION."
    },
    "optionalData": {
      "$ref": "#/$defs/Data"
    }
  },
  "$defs": {
    "Data": {
      "type": "object",
      "properties": {
        "optionalInt": {
          "type": "integer"
        },
        "address": {
          "type": "string",
          "description": "THIS IS THE DEMO DESCRIPTION."
        },
        "list": {
          "$ref": "#/$defs/System.Collections.Generic.List\u003CData\u003E"
        }
      }
    },
    "System.Collections.Generic.List\u003CData\u003E": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Data"
      }
    }
  },
  "required": [
    "dataList",
    "flag"
  ]
}

Expected Json Schema: Output Result

{
  "type": "object",
  "properties": {
    "result": {
      "$ref": "#/$defs/Result"
    }
  },
  "$defs": {
    "Result": {
      "type": "object",
      "properties": {
        "isDone": {
          "type": "boolean"
        },
        "errorMessage": {
          "type": "string"
        }
      },
      "required": [
        "isDone"
      ]
    }
  },
  "required": [
    "result"
  ]
}

Solution - Automatic JSON Schema Generation

I made ReflectorNet isn't just about reflection; it bridges the gap between strong C# typing and dynamic data formats. One of its most powerful features is the Automatic JSON Schema Generator.

var reflector = new Reflector();
var methodInfo = typeof(Sample).GetMethod(nameof(Sample.Command));

var argumentsSchema = reflector.GetArgumentsSchema(methodInfo);
var outputSchema = reflector.GetReturnSchema(methodInfo);

It creates Json Schema with respect to Optional arguments, with respect to almost any type of C# data models (generic, nested class, struct, array, collections and any combinations of all of them). Even if you still have something very exotic, just register your custom ReflectionConverter with Json Schema generation overridden method.

ReflectorNet solves this with a single line of code.

🚀 Capabilities

The schema generator recursively analyzes your types to produce standard JSON Schemas. It handles edge cases that often break other libraries:

• ✅ Generics: Correctly resolves T in types like Response<User>.
• ✅ Collections & Arrays: List<T>, T[], IEnumerable<T>, HashSet<T>.
• ✅ Complex Structures: Deeply nested classes and mixed object graphs.
• ✅ Value Types: Proper mapping for struct and primitives (int, bool, double).
• ✅ Dictionaries: Maps Dictionary<string, T> to object properties.

📦 Installation

dotnet add package com.IvanMurzak.ReflectorNet

💻 Usage Example

Here is a demonstration of generating a schema for a complex, real-world data model involving generics, nested structs, and dictionaries.

1. Define Your Data Model

using System;
using System.Collections.Generic;

namespace MyProject.Models
{
    // A simple value type
    public struct GeoPoint
    {
        public double Latitude;
        public double Longitude;
    }

    // A complex entity
    public class PlayerProfile
    {
        public Guid Id { get; set; }
        public string Username { get; set; }
        public string[] Badges { get; set; } // Array
        public Dictionary<string, int> Stats { get; set; } // Dictionary
    }

    // A generic wrapper (common in Game State or API responses)
    public class GameState<T>
    {
        public long Timestamp { get; set; }
        public T Player { get; set; }
        public List<GeoPoint> Checkpoints { get; set; } // List of Structs
    }
}

2. Generate the Schema

You do not need to decorate your classes with attributes. Just create the Reflector and call GetSchema.

using com.IvanMurzak.ReflectorNet;
using MyProject.Models;

var reflector = new Reflector();

// Generate schema for 'GameState' typed with 'PlayerProfile'
string schemaJson = reflector.GetSchema<GameState<PlayerProfile>>();

Console.WriteLine(schemaJson);

3. The Result

ReflectorNet resolves the Generic T, correctly identifies the List of structs, and maps the Dictionary.

{
  "type": "object",
  "properties": {
    "Timestamp": {
      "type": "integer"
    },
    "Player": {
      "$ref": "#/$defs/PlayerProfile"
    },
    "Checkpoints": {
      "$ref": "#/$defs/System.Collections.Generic.List\u003CGeoPoint\u003E"
    }
  },
  "required": [
    "Timestamp"
  ],
  "$defs": {
    "GameState\u003CPlayerProfile\u003E": {
      "type": "object",
      "properties": {
        "Timestamp": {
          "type": "integer"
        },
        "Player": {
          "$ref": "#/$defs/PlayerProfile"
        },
        "Checkpoints": {
          "$ref": "#/$defs/System.Collections.Generic.List\u003CGeoPoint\u003E"
        }
      },
      "required": [
        "Timestamp"
      ]
    },
    "PlayerProfile": {
      "type": "object",
      "properties": {
        "Id": {
          "type": "string",
          "format": "uuid"
        },
        "Username": {
          "type": "string"
        },
        "Badges": {
          "$ref": "#/$defs/System.String[]"
        },
        "Stats": {
          "$ref": "#/$defs/System.Collections.Generic.Dictionary\u003CSystem.String,System.Int32\u003E"
        }
      },
      "required": [
        "Id"
      ]
    },
    "System.String[]": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "System.Collections.Generic.Dictionary\u003CSystem.String,System.Int32\u003E": {
      "type": "object",
      "additionalProperties": {
        "type": "integer"
      }
    },
    "System.Collections.Generic.List\u003CGeoPoint\u003E": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/GeoPoint"
      }
    },
    "GeoPoint": {
      "type": "object",
      "properties": {
        "Latitude": {
          "type": "number"
        },
        "Longitude": {
          "type": "number"
        }
      },
      "required": [
        "Latitude",
        "Longitude"
      ]
    }
  }
}

Relevant Links

• ReflectorNet - the Json Schema generation solution
• AI Game Developer - Unity MCP - successful use case
• AI Game Developer - Unity MCP - successful use case