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
 -----
 

Makefile

@@ -23,6 +23,9 @@ cs:
 phpstan:
 	vendor/bin/phpstan --memory-limit=-1
 
+deptrac:
+	vendor/bin/deptrac analyze
+
 tests:
 	vendor/bin/phpunit
 
@@ -74,9 +77,9 @@ coverage:
 
 ci: ci-stable
 
-ci-stable: deps-stable cs phpstan tests
+ci-stable: deps-stable cs phpstan deptrac tests
 
-ci-lowest: deps-low cs phpstan tests
+ci-lowest: deps-low cs phpstan deptrac tests
 
 # The published site is the guides (Zensical) with the phpDocumentor API
 # reference mounted at /api/. `zensical build` wipes site/, so it runs first.

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

@@ -41,6 +41,7 @@
   "require-dev": {
     "ext-openssl": "*",
     "composer/semver": "^3.0",
+    "deptrac/deptrac": "^4.7",
     "firebase/php-jwt": "^6.10 || ^7.0",
     "laminas/laminas-httphandlerrunner": "^2.12",
     "nyholm/psr7": "^1.8",
@@ -84,7 +85,7 @@
       "Mcp\\Tests\\": "tests/"
     },
     "classmap": [
-      "tests/Unit/Capability/Discovery/Fixtures/AlternativeFileNameToolHandler.class.inc"
+      "tests/Unit/Server/Capability/Discovery/Fixtures/AlternativeFileNameToolHandler.class.inc"
     ]
   },
   "config": {

deptrac.yaml

@@ -0,0 +1,29 @@
+deptrac:
+  paths:
+    - src
+  layers:
+    - name: Client
+      collectors:
+        - type: classLike
+          value: Mcp\\Client\\.*
+    - name: Schema
+      collectors:
+        - type: classLike
+          value: Mcp\\Schema\\.*
+    - name: Server
+      collectors:
+        - type: classLike
+          value: Mcp\\Server\\.*
+  ruleset:
+    Client: [Schema]
+    Schema: []
+    Server: [Schema]
+
+  # Slicing of Extensions is currently unclear
+  skip_violations:
+    Mcp\Schema\Extension\ExtensionInterface:
+      - Mcp\Server\Handler\Request\RequestHandlerInterface
+    Mcp\Schema\Extension\AbstractExtension:
+      - Mcp\Server\Handler\Request\RequestHandlerInterface
+    Mcp\Schema\Extension\Apps\McpApps:
+      - Mcp\Server\Handler\Request\RequestHandlerInterface

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;