Proposal: Schema Generation Separation from Core SDK

[butschster]

Hey team!

The core protocol implementation is solid and provides exactly what developers need for building MCP servers.

Architectural Question I've Been Thinking About

I've been working with the SDK on some complex projects, and it got me thinking about the overall architecture. Currently, schema generation is built into the core SDK through the Discovery capability, but I'm wondering if we might want to consider a more modular approach.

Current State

Right now, the SDK handles both:

• ✅ Core MCP Protocol - JSON-RPC transport, message handling, server lifecycle
• ✅ Schema Generation - Converting PHP types to JSON Schema for tool discovery

This works great for getting started, but I'm noticing it creates some coupling between the protocol layer and schema generation logic.

What I'm Proposing

What if we moved toward a philosophy where the SDK focuses purely on being an excellent MCP protocol implementation, and schema generation becomes a separate concern handled by dedicated packages?

Core SDK Responsibilities

// Pure protocol focus
$server = new McpServer($transport);
$server->addTool('my_tool', $callable, $schema); // Schema provided externally
$server->run();

Schema Generation as Separate Packages

// Developer chooses their preferred schema generator
use McpSchemaGenerators\Spiral\SchemaGenerator;
use McpSchemaGenerators\JsonMapper\SchemaGenerator; 
use McpSchemaGenerators\Custom\MySchemaGenerator;

$generator = new SpiralSchemaGenerator();
$schema = $generator->generateFromCallable($myToolMethod);
$server->addTool('my_tool', $myToolMethod, $schema);

Benefits I See

🎯 Single Responsibility: Core SDK just handles MCP protocol brilliantly
🔧 Flexibility: Developers pick schema generators that fit their needs
📦 Smaller Core: SDK stays lightweight and focused
🚀 Innovation: Schema generation can evolve independently
🧪 Experimentation: Easy to try different approaches without SDK changes

Questions for Discussion

1. Does this architectural direction make sense for the project's goals?
2. Would this approach make the SDK more or less approachable for newcomers?
3. Are there any protocol-level reasons why schema generation needs to be tightly coupled?
4. Should we consider this for a future major version, or could it work as an evolution?

I think this could make the SDK both more powerful for complex use cases and simpler for developers who just want the protocol handling. The current implementation could become the "batteries included" reference implementation in a separate package.

What are your thoughts on this direction? I'd be happy to explore a proof of concept if it seems like something worth investigating.

Context

I've been building task management and workflow tools where I need rich schema generation for complex nested objects, but I also want the flexibility to integrate with existing validation systems in my applications. Having the choice of schema generators would solve both problems cleanly.

[chr-hertel]

Looks like you gave this a deeper read here, thanks for your feedback across all issues @butschster 👍

Two things from my end:

• I do share the pain, having two ways of generating schema stuff myself now with this and in Symfony AI
• I don't think that lib users really care - if it was about different DX, okay, but it is only about generating a schema from classes, right? so one end is PHP syntax, the other is standardized Json Schema defined by a specification. there's not a lot of wiggle room, but rather internals.

so just introducing a set of interfaces for example that get 4 different implementations doesn't really click with me. i'd rather have one central implementation shared - but there always small differences. that's also why I opted out for now and have it twice - well and the code was there already :D

buut, tell me where i'm missing things

[butschster]

Thanks for the reply, @chr-hertel — I do agree that most users ultimately want “PHP in, JSON Schema out.” My concern is less about DX flavors and more about capability boundaries and release coupling.

Right now, the built-in generator works well for scalars/enums/simple arrays, but it struggles with realistic DTO-heavy workflows (nested objects, $ref, recursion, constraints, unions). In those cases, it falls back to generic "type": "object", which makes the output hard to use for LLM prompting, validation, and documentation.

Below are small, concrete examples to illustrate where this becomes a blocker in practice.

1) Nested DTOs + arrays of DTOs

DTOs (typical task creation request):

use Spiral\JsonSchemaGenerator\Attribute\Field;

final readonly class ChecklistItem
{
    public function __construct(
        public string $text,
        public bool $completed = false,
        public ?string $dueDate = null,
    ) {}
}

final readonly class TaskPayload
{
    public function __construct(
        #[Field(title: 'Title', description: 'Verb-first summary')]
        public string $title,
        public string $description = '',
        /** @var string[] */
        public array $tags = [],
        /** @var ChecklistItem[] */
        public array $checklist = [],
    ) {}
}

final readonly class TaskRequest
{
    public function __construct(
        public int $listId,
        public TaskPayload $task,            // ← nested object
        /** @var TaskPayload[] */
        public array $subtasks = [],         // ← array of nested objects
    ) {}
}

Tool method:

#[McpTool(name: 'create_task')]
public function createTask(TaskRequest $request): array
{
    // ...
}

What the current generator tends to produce:

{
  "type": "object",
  "properties": {
    "request": { "type": "object" } // ← loses structure
  },
  "required": ["request"]
}

What a production-ready schema should look like (abridged):

{
  "type": "object",
  "properties": {
    "request": {
      "$ref": "#/definitions/TaskRequest"
    }
  },
  "required": ["request"],
  "definitions": {
    "TaskRequest": {
      "type": "object",
      "properties": {
        "listId": { "type": "integer" },
        "task": { "$ref": "#/definitions/TaskPayload" },
        "subtasks": {
          "type": "array",
          "items": { "$ref": "#/definitions/TaskPayload" },
          "default": []
        }
      },
      "required": ["listId", "task"]
    },
    "TaskPayload": {
      "type": "object",
      "properties": {
        "title": { "type": "string", "title": "Title", "description": "Verb-first summary" },
        "description": { "type": "string", "default": "" },
        "tags": { "type": "array", "items": { "type": "string" }, "default": [] },
        "checklist": {
          "type": "array",
          "items": { "$ref": "#/definitions/ChecklistItem" },
          "default": []
        }
      },
      "required": ["title"]
    },
    "ChecklistItem": {
      "type": "object",
      "properties": {
        "text": { "type": "string" },
        "completed": { "type": "boolean", "default": false },
        "dueDate": { "type": ["string", "null"], "format": "date-time" }
      },
      "required": ["text"]
    }
  }
}

2) Self-references and reuse ($ref)

DTO with self-referencing array:

final readonly class Category
{
    public function __construct(
        public string $name,
        /** @var Category[] */
        public array $children = [],
    ) {}
}

A robust generator must detect recursion and switch to $ref definitions to avoid infinite expansion. The current approach doesn’t model that relationship, leading to either generic objects or deep recursion.

3) Unions, nullable, conditional structures

DTO demonstrating unions/nullable:

final readonly class AssignmentConfig
{
    public function __construct(
        /** @var non-empty-string */
        public string $assignee,
        /** @var 'low'|'medium'|'high' */
        public string $priority = 'medium',
    ) {}
}

final readonly class TaskCreationRequest
{
    public function __construct(
        public TaskPayload $task,
        /** @var TaskPayload[] */
        public array $subtasks = [],
        public null|AssignmentConfig $assignment = null, // ← nullable / union
        /** @var list<string|int> */
        public array $notifyUsers = [],                  // ← union items
    ) {}
}

Desired schema features:

• oneOf/anyOf for union types (including null)
• Typed array items with unions
• Reusable $ref blocks for TaskPayload and AssignmentConfig

---

To support the above properly, a generator must implement a lot of non-trivial functionality:

• Recursive class graph traversal with cycle detection and $ref reuse
• Accurate union/nullable mapping (oneOf/anyOf)
• Systematic extraction of constraints from PHP types and PHPDoc and attributes
• Typed collections (list<T>, array<string, T>, polymorphic arrays)
• Format mapping (email, uri, date-time, etc.)
• Configurable extractors and extension points
• Robust tests for edge cases (variance, recursive data, generics-like patterns)

For example, in our projects we use https://github.com/spiral/json-schema-generator. It’s not just a few utility files, but a full-featured library: it handles deep class inspection, unions, nullable types, constraint extraction from PHPDoc and attributes, $ref reuse, recursion, advanced formats, and more. Maintaining this already requires a dedicated support cycle, documentation, and tests.

If schema generation remains part of the MCP SDK itself, the SDK team will naturally receive requests for all those features. That would put maintainers in the position of having to evolve and support a complete schema ecosystem — which is quite different from maintaining the protocol core.

[soyuka]

Hi, may you consider using https://github.com/api-platform/core/blob/main/src/JsonSchema/SchemaFactory.php we handle many of those things already.