[chr-hertel]

Prepares slicing mcp/sdk into separate packages, see #489

1. Moved everything below Mcp\Client, Mcp\Schema, or Mcp\Server
2. Distributed Mcp\Exception into component specific namespaces
3. Enforced the boundaries with Deptrac (make deptrac, part of the qa job): Schema depends on nothing, Client and Server on Schema only

Besides the namespaces there's one more BC break: getRequestHandlers() moved from ExtensionInterface to the new Mcp\Server\Extension\ServerExtensionInterface, since Schema must not know server handlers. Both are in the CHANGELOG.

SecureUrl lives in Mcp\Schema now, with internal wrappers in Client and Server that throw the package's own exception - not a perfect fit for Schema, but the only shared place until we split.

Deptrac is on 3.0, since 4.x requires Symfony ^6.4 and we still test 5.4.

---

Next steps, as follow ups:

• a composer.json per component, with its own dependencies
• split the packages on release with splitsh, like API Platform does (see the workflow linked below)
• keep the tests global to this repo

[Copilot]

🟡 Changes recommended

Numerous tests expect exceptions from the wrong slice, several examples reference invalid namespaces, and Deptrac is not enforced by CI.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Refactors the SDK into distinct Client, Schema, and Server namespaces in preparation for package slicing.

Changes:

• Moves facades, capabilities, events, exceptions, and shared protocol types into slice-specific namespaces.
• Updates tests, examples, documentation, and autoloading references.
• Adds Deptrac boundaries and inspector snapshots.

File summaries

File group	Description
src/Client/**	Refactors client APIs and exceptions.
src/Schema/**	Consolidates shared protocol types and schema exceptions.
src/Server/**	Refactors server APIs, capabilities, events, and exceptions.
tests/Unit/**	Migrates unit tests and fixtures.
tests/Integration/**	Updates integration imports and fixtures.
tests/Conformance/**	Updates conformance entry points.
tests/Inspector/**	Adds structured-result snapshots.
examples/**	Migrates client and server examples.
docs/**, README.md	Updates public namespace guidance.
composer.json, deptrac.yaml, phpstan.dist.neon, .gitignore	Configures architecture tooling and relocated paths.

Review details

Suppressed comments (1)

docs/client/errors.md:24

• Client requests throw Mcp\Client\Exception\RequestException. Catching the server-slice sibling will not handle $client->callTool() failures.

• Files reviewed: 299/423 changed files
• Comments generated: 43
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[soyuka]

For splitsh this is how we did on API Platform: https://github.com/api-platform/core/blob/main/.github/workflows/release.yml#L21-L50

Pretty straightforward, not sure how it works on Symfony but AFAIR it was a bit more complex :p. Note that testing may also be a bit of a headache if we allow wider version constraint on one of these packages... +1 to keep tests global to this repo (sometimes its interesting to have component specific tests especially that tests also get published along the source code though it makes things more complicated).

[Copilot]

🟡 Changes recommended

Unchanged persistent cache keys can reuse discovery objects serialized under old namespaces, causing return-type failures after an upgrade instead of rediscovering capabilities.

1 open issue

• Version discovery cache keys to avoid stale serialized objects · New

43 resolved since last review

• Changing this test namespace changes the ::class values passed to HandlerResolver, but the…
• Tool now raises the schema-slice exception, so expecting the unrelated server exception causes…
• ToolChoice now throws Mcp\Schema\Exception\InvalidArgumentException; this sibling server…
• This result object throws Mcp\Schema\Exception\InvalidArgumentException; expecting the unrelated…
• This result object throws Mcp\Schema\Exception\InvalidArgumentException; expecting the unrelated…
• This result object throws Mcp\Schema\Exception\InvalidArgumentException; expecting the unrelated…
• This result object throws Mcp\Schema\Exception\InvalidArgumentException; expecting the unrelated…
• ResourceTemplate throws Mcp\Schema\Exception\InvalidArgumentException; the sibling server…
• ResourceDefinition throws Mcp\Schema\Exception\InvalidArgumentException; the sibling server…
• CreateSamplingMessageRequest now throws the schema-slice exception; expecting the server…
• The schema value object throws the schema-slice exception, so this server exception cannot satisfy…
• MessageFactory now throws Mcp\Schema\Exception\InvalidArgumentException; expecting the server…
• The schema class now throws Mcp\Schema\Exception\InvalidArgumentException; expecting the…
• Icon throws Mcp\Schema\Exception\InvalidArgumentException; the server exception is unrelated…
• ExtensionIdentifier throws the schema-slice exception; the server exception is unrelated and…
• The schema classes under test throw Mcp\Schema\Exception\InvalidArgumentException; this server…
• This schema definition throws the schema-slice exception; the server exception is unrelated and…
• This schema definition throws the schema-slice exception; the server exception is unrelated and…
• This schema definition throws the schema-slice exception; the server exception is unrelated and…
• This schema definition throws the schema-slice exception; the server exception is unrelated and…

And 23 more resolved.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues were identified for the namespace and dependency-boundary changes preparing the PHP SDK package split.

No open issues 🎉

1 resolved since last review

• Version discovery cache keys to avoid stale serialized objects

_{Review effort: Balanced}