Prepare package slicing by strict namespace refactoring into Client, Schema, and Server

Author: chr-hertel

.gitignore

@@ -1,3 +1,4 @@
+.deptrac.cache
 .phpunit.cache
 .php-cs-fixer.cache
 composer.lock

CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `mcp/sdk` will be documented in this file.
 
+0.9.0
+-----
+
+* [BC Break] Split the root namespace into `Mcp\Schema`, `Mcp\Client` and `Mcp\Server` to prepare package slicing. `Mcp\Schema` depends on nothing, `Mcp\Client` and `Mcp\Server` depend on `Mcp\Schema` only — enforced by Deptrac (`make deptrac`).
+  * `Mcp\Server` => `Mcp\Server\Server`
+  * `Mcp\Client` => `Mcp\Client\Client`
+  * `Mcp\Capability\*` => `Mcp\Server\Capability\*` (`Attribute`, `Completion`, `Discovery`, `Formatter`, `Logger`, `Registry`, `Tool`, plus `Registry` and `RegistryInterface`)
+  * `Mcp\Event\*` => `Mcp\Server\Event\*`
+  * `Mcp\JsonRpc\MessageFactory` => `Mcp\Schema\MessageFactory`
+  * `Mcp\Server\Stateless\RequestMeta` => `Mcp\Schema\RequestMeta`
+* [BC Break] Distribute `Mcp\Exception\*` across the three namespaces.
+  * `Mcp\Exception\{ExceptionInterface,InvalidArgumentException,LogicException,RuntimeException}` => the same names under `Mcp\Schema\Exception\`, `Mcp\Client\Exception\` and `Mcp\Server\Exception\` — pick the one matching the package you catch around
+  * `Mcp\Exception\Exception` => `Mcp\Client\Exception\Exception` and `Mcp\Server\Exception\Exception`
+  * `Mcp\Exception\{InvalidInputMessageException,MissingRequestMetaException}` => `Mcp\Schema\Exception\*`
+  * `Mcp\Exception\{ConnectionException,ElicitationException,RequestException,RootsException,SamplingException}` => `Mcp\Client\Exception\*`
+  * `Mcp\Exception\{BadMethodCallException,ClientException,ClientRegistrationException,ConfigurationException,ContainerException,InvalidCursorException,MissingRequiredClientCapabilityException,NotFoundExceptionInterface,PromptGetException,PromptNotFoundException,RegistryException,RequestStateException,ResourceNotFoundException,ResourceReadException,ServiceNotFoundException,ToolCallException,ToolNotFoundException}` => `Mcp\Server\Exception\*`
+  * `Mcp\Exception\TimeoutException` and `Mcp\Exception\HandlerNotFoundException` are removed; both were unused.
+  * `Mcp\Server\Exception\ExceptionInterface` and `Mcp\Client\Exception\ExceptionInterface` extend `Mcp\Schema\Exception\ExceptionInterface`, so catching the latter still catches any SDK exception.
+  * The named exceptions now extend their package's `RuntimeException`/`InvalidArgumentException` instead of the global ones, so `catch (Mcp\Server\Exception\RuntimeException)` reaches `ToolCallException`, `PromptGetException` and friends.
+
 0.8.0
 -----
 

README.md

@@ -36,9 +36,9 @@ composer require mcp/sdk
 A server is a plain PHP class plus three lines of wiring:
 
 ```php
-use Mcp\Capability\Attribute\McpResource;
-use Mcp\Capability\Attribute\McpTool;
-use Mcp\Server;
+use Mcp\Server\Capability\Attribute\McpResource;
+use Mcp\Server\Capability\Attribute\McpTool;
+use Mcp\Server\Server;
 use Mcp\Server\Transport\StdioTransport;
 
 class Calculator
@@ -72,7 +72,7 @@ The walkthrough in [First server](docs/get-started/first-server.md) explains eac
 ## Build a client
 
 ```php
-use Mcp\Client;
+use Mcp\Client\Client;
 use Mcp\Client\Transport\StdioTransport;
 
 $client = Client::builder()

composer.json

@@ -84,7 +84,7 @@
       "Mcp\\Tests\\": "tests/"
     },
     "classmap": [
-      "tests/Unit/Capability/Discovery/Fixtures/AlternativeFileNameToolHandler.class.inc"
+      "tests/Unit/Server/Capability/Discovery/Fixtures/AlternativeFileNameToolHandler.class.inc"
     ]
   },
   "config": {

docs/advanced/events.md

@@ -7,8 +7,8 @@ The MCP SDK provides a PSR-14 compatible event system that allows you to hook in
 Configure an event dispatcher when building your server:
 
 ```php
-use Mcp\Event\RequestEvent;
-use Mcp\Server;
+use Mcp\Server\Event\RequestEvent;
+use Mcp\Server\Server;
 use Symfony\Component\EventDispatcher\EventDispatcher;
 
 $dispatcher = new EventDispatcher();
@@ -86,7 +86,7 @@ These events are dispatched when the lists of available capabilities change:
 These events carry no data and are used to notify clients that they should refresh their capability lists.
 
 ```php
-use Mcp\Event\ToolListChangedEvent;
+use Mcp\Server\Event\ToolListChangedEvent;
 
 $dispatcher->addListener(ToolListChangedEvent::class, function (ToolListChangedEvent $event) {
     $logger->info('Tool list has changed, clients should refresh');

docs/advanced/extensions.md

@@ -7,7 +7,7 @@ the SDK places the advertisement correctly for whichever era the client speaks:
 
 ```php
 use Mcp\Schema\Extension\Apps\McpApps;
-use Mcp\Server;
+use Mcp\Server\Server;
 
 $server = Server::builder()
     ->setServerInfo('My Server', '1.0.0')
@@ -112,11 +112,11 @@ descriptor marker: `McpApps::resourceMarker()` is a method call and cannot appea
 in an attribute, so spell it as `new \stdClass()` there.
 
 ```php
-use Mcp\Capability\Attribute\McpResource;
-use Mcp\Capability\Attribute\McpTool;
 use Mcp\Schema\Extension\Apps\McpApps;
 use Mcp\Schema\Extension\Apps\ToolVisibility;
 use Mcp\Schema\Extension\Apps\UiToolMeta;
+use Mcp\Server\Capability\Attribute\McpResource;
+use Mcp\Server\Capability\Attribute\McpTool;
 
 final class WeatherApp
 {

docs/client/connecting.md

@@ -13,7 +13,7 @@ The `Client\Builder` provides fluent configuration of client instances.
 ### Basic Configuration
 
 ```php
-use Mcp\Client;
+use Mcp\Client\Client;
 
 $client = Client::builder()
     ->setClientInfo('My Application', '1.0.0', 'Description of my client')

docs/client/errors.md

@@ -7,7 +7,7 @@ The client throws exceptions for various error conditions:
 Thrown when connection or initialization fails:
 
 ```php
-use Mcp\Exception\ConnectionException;
+use Mcp\Client\Exception\ConnectionException;
 
 try {
     $client->connect($transport);
@@ -21,7 +21,7 @@ try {
 Thrown when a request returns an error response:
 
 ```php
-use Mcp\Exception\RequestException;
+use Mcp\Client\Exception\RequestException;
 
 try {
     $result = $client->callTool('unknown_tool', []);
@@ -38,12 +38,12 @@ Here's a comprehensive example demonstrating client usage:
 ```php-file
 <?php
 
-use Mcp\Client;
+use Mcp\Client\Client;
 use Mcp\Client\Handler\Notification\LoggingNotificationHandler;
 use Mcp\Client\Handler\Request\SamplingCallbackInterface;
 use Mcp\Client\Handler\Request\SamplingRequestHandler;
 use Mcp\Client\Transport\StdioTransport;
-use Mcp\Exception\SamplingException;
+use Mcp\Client\Exception\SamplingException;
 use Mcp\Schema\ClientCapabilities;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\LoggingLevel;

docs/client/index.md

@@ -5,7 +5,7 @@ discover what it offers, and call it. The API is synchronous — every method re
 result or throws.
 
 ```php
-use Mcp\Client;
+use Mcp\Client\Client;
 use Mcp\Client\Transport\StdioTransport;
 
 // Build and configure the client

docs/client/server-requests.md

@@ -10,9 +10,8 @@ needs; your callback presents them to the user and returns an `ElicitResult` wit
 three actions — accept (with the collected content), decline, or cancel:
 
 ```php
-use Mcp\Client\Handler\Request\ElicitationRequestHandler;
 use Mcp\Client\Handler\Request\ElicitationCallbackInterface;
-use Mcp\Exception\ElicitationException;
+use Mcp\Client\Handler\Request\ElicitationRequestHandler;
 use Mcp\Schema\ClientCapabilities;
 use Mcp\Schema\Enum\ElicitAction;
 use Mcp\Schema\Enum\ElicitationMode;
@@ -84,14 +83,14 @@ elicitation demo server.
 Handle server requests for LLM completions:
 
 ```php
-use Mcp\Client\Handler\Request\SamplingRequestHandler;
+use Mcp\Client\Exception\SamplingException;
 use Mcp\Client\Handler\Request\SamplingCallbackInterface;
-use Mcp\Exception\SamplingException;
+use Mcp\Client\Handler\Request\SamplingRequestHandler;
 use Mcp\Schema\ClientCapabilities;
-use Mcp\Schema\Request\CreateSamplingMessageRequest;
-use Mcp\Schema\Result\CreateSamplingMessageResult;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\Role;
+use Mcp\Schema\Request\CreateSamplingMessageRequest;
+use Mcp\Schema\Result\CreateSamplingMessageResult;
 
 class LlmSamplingCallback implements SamplingCallbackInterface
 {