[Server] Registry Architecture Refactoring - Enhanced Separation of Concerns

examples/09-standalone-cli/src/ExampleTool.php

@@ -12,15 +12,15 @@
 namespace App;
 
 use Mcp\Capability\Tool\MetadataInterface;
-use Mcp\Capability\Tool\ToolExecutorInterface;
+use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
 
 /**
  * @author Tobias Nyholm <[email protected]>
  */
-class ExampleTool implements MetadataInterface, ToolExecutorInterface
+class ExampleTool implements MetadataInterface, ToolCallerInterface
 {
     public function call(CallToolRequest $request): CallToolResult
     {

src/Capability/Tool/ToolExecutor.php → src/Capability/Tool/ToolCaller.php

@@ -13,7 +13,7 @@
 
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
-use Mcp\Exception\ToolExecutionException;
+use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Content\AudioContent;
 use Mcp\Schema\Content\EmbeddedResource;
@@ -30,7 +30,7 @@
  *
  * @author Pavel Buchnev <[email protected]>
  */
-final class ToolExecutor implements ToolExecutorInterface
+final class ToolCaller implements ToolCallerInterface
 {
     public function __construct(
         private readonly ReferenceProviderInterface $referenceProvider,
@@ -40,7 +40,7 @@ public function __construct(
     }
 
     /**
-     * @throws ToolExecutionException if the tool execution fails
+     * @throws ToolCallException if the tool execution fails
      * @throws ToolNotFoundException  if the tool is not found
      */
     public function call(CallToolRequest $request): CallToolResult
@@ -75,7 +75,7 @@ public function call(CallToolRequest $request): CallToolResult
                 'trace' => $e->getTraceAsString(),
             ]);
 
-            throw new ToolExecutionException($request, $e);
+            throw new ToolCallException($request, $e);
         }
     }
 }

src/Capability/Tool/ToolExecutorInterface.php → src/Capability/Tool/ToolCallerInterface.php

@@ -11,18 +11,18 @@
 
 namespace Mcp\Capability\Tool;
 
-use Mcp\Exception\ToolExecutionException;
+use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
 
 /**
  * @author Tobias Nyholm <[email protected]>
  */
-interface ToolExecutorInterface
+interface ToolCallerInterface
 {
     /**
-     * @throws ToolExecutionException if the tool execution fails
+     * @throws ToolCallException if the tool execution fails
      * @throws ToolNotFoundException  if the tool is not found
      */
     public function call(CallToolRequest $request): CallToolResult;

src/Capability/ToolChain.php

@@ -14,9 +14,9 @@
 use Mcp\Capability\Tool\CollectionInterface;
 use Mcp\Capability\Tool\IdentifierInterface;
 use Mcp\Capability\Tool\MetadataInterface;
-use Mcp\Capability\Tool\ToolExecutorInterface;
+use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\InvalidCursorException;
-use Mcp\Exception\ToolExecutionException;
+use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
@@ -26,7 +26,7 @@
  *
  * @author Tobias Nyholm <[email protected]>
  */
-class ToolChain implements ToolExecutorInterface, CollectionInterface
+class ToolChain implements ToolCallerInterface, CollectionInterface
 {
     public function __construct(
         /**
@@ -63,11 +63,11 @@ public function getMetadata(int $count, ?string $lastIdentifier = null): iterabl
     public function call(CallToolRequest $request): CallToolResult
     {
         foreach ($this->items as $item) {
-            if ($item instanceof ToolExecutorInterface && $request->name === $item->getName()) {
+            if ($item instanceof ToolCallerInterface && $request->name === $item->getName()) {
                 try {
                     return $item->call($request);
                 } catch (\Throwable $e) {
-                    throw new ToolExecutionException($request, $e);
+                    throw new ToolCallException($request, $e);
                 }
             }
         }

src/Exception/ToolExecutionException.php → src/Exception/ToolCallException.php

@@ -16,12 +16,12 @@
 /**
  * @author Tobias Nyholm <[email protected]>
  */
-final class ToolExecutionException extends \RuntimeException implements ExceptionInterface
+final class ToolCallException extends \RuntimeException implements ExceptionInterface
 {
     public function __construct(
         public readonly CallToolRequest $request,
         ?\Throwable $previous = null,
     ) {
-        parent::__construct(\sprintf('Execution of tool "%s" failed with error: "%s".', $request->name, $previous?->getMessage() ?? ''), previous: $previous);
+        parent::__construct(\sprintf('Tool call "%s" failed with error: "%s".', $request->name, $previous?->getMessage() ?? ''), previous: $previous);
     }
 }

src/Server/RequestHandler/CallToolHandler.php

@@ -11,7 +11,7 @@
 
 namespace Mcp\Server\RequestHandler;
 
-use Mcp\Capability\Tool\ToolExecutorInterface;
+use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\ExceptionInterface;
 use Mcp\Schema\JsonRpc\Error;
 use Mcp\Schema\JsonRpc\HasMethodInterface;
@@ -28,7 +28,7 @@
 final class CallToolHandler implements MethodHandlerInterface
 {
     public function __construct(
-        private readonly ToolExecutorInterface $toolExecutor,
+        private readonly ToolCallerInterface $toolExecutor,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
     }

src/Server/ServerBuilder.php

@@ -25,8 +25,8 @@
 use Mcp\Capability\Registry\ReferenceHandler;
 use Mcp\Capability\Resource\ResourceReader;
 use Mcp\Capability\Resource\ResourceReaderInterface;
-use Mcp\Capability\Tool\ToolExecutor;
-use Mcp\Capability\Tool\ToolExecutorInterface;
+use Mcp\Capability\Tool\ToolCaller;
+use Mcp\Capability\Tool\ToolCallerInterface;
 use Mcp\Exception\ConfigurationException;
 use Mcp\JsonRpc\Handler;
 use Mcp\Schema\Annotations;
@@ -55,7 +55,7 @@ final class ServerBuilder
 
     private ?CacheInterface $cache = null;
 
-    private ?ToolExecutorInterface $toolExecutor = null;
+    private ?ToolCallerInterface $toolExecutor = null;
 
     private ?ResourceReaderInterface $resourceReader = null;
 
@@ -161,7 +161,7 @@ public function withEventDispatcher(EventDispatcherInterface $eventDispatcher):
         return $this;
     }
 
-    public function withToolExecutor(ToolExecutorInterface $toolExecutor): self
+    public function withToolExecutor(ToolCallerInterface $toolExecutor): self
     {
         $this->toolExecutor = $toolExecutor;
 
@@ -281,7 +281,7 @@ public function build(): Server
         $registry = new Registry($this->eventDispatcher, $logger);
 
         $referenceHandler = new ReferenceHandler($container);
-        $toolExecutor = $this->toolExecutor ??= new ToolExecutor($registry, $referenceHandler, $logger);
+        $toolExecutor = $this->toolExecutor ??= new ToolCaller($registry, $referenceHandler, $logger);
         $resourceReader = $this->resourceReader ??= new ResourceReader($registry, $referenceHandler, $logger);
         $promptGetter = $this->promptGetter ??= new PromptGetter($registry, $referenceHandler, $logger);
 

tests/Capability/Tool/ToolExecutorTest.php → tests/Capability/Tool/ToolCallerTest.php

@@ -14,8 +14,8 @@
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
 use Mcp\Capability\Registry\ToolReference;
-use Mcp\Capability\Tool\ToolExecutor;
-use Mcp\Exception\ToolExecutionException;
+use Mcp\Capability\Tool\ToolCaller;
+use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Request\CallToolRequest;
@@ -25,9 +25,9 @@
 use PHPUnit\Framework\TestCase;
 use Psr\Log\LoggerInterface;
 
-class ToolExecutorTest extends TestCase
+class ToolCallerTest extends TestCase
 {
-    private ToolExecutor $toolExecutor;
+    private ToolCaller $toolExecutor;
     private ReferenceProviderInterface|MockObject $referenceProvider;
     private ReferenceHandlerInterface|MockObject $referenceHandler;
     private LoggerInterface|MockObject $logger;
@@ -38,7 +38,7 @@ protected function setUp(): void
         $this->referenceHandler = $this->createMock(ReferenceHandlerInterface::class);
         $this->logger = $this->createMock(LoggerInterface::class);
 
-        $this->toolExecutor = new ToolExecutor(
+        $this->toolExecutor = new ToolCaller(
             $this->referenceProvider,
             $this->referenceHandler,
             $this->logger,
@@ -211,13 +211,13 @@ public function testCallThrowsToolExecutionExceptionWhenHandlerThrowsException()
                 })
             );
 
-        $this->expectException(ToolExecutionException::class);
-        $this->expectExceptionMessage('Execution of tool "failing_tool" failed with error: "Handler failed".');
+        $this->expectException(ToolCallException::class);
+        $this->expectExceptionMessage('Tool call "failing_tool" failed with error: "Handler failed".');
 
         $thrownException = null;
         try {
             $this->toolExecutor->call($request);
-        } catch (ToolExecutionException $e) {
+        } catch (ToolCallException $e) {
             $thrownException = $e;
             throw $e;
         } finally {
@@ -404,8 +404,8 @@ public function testCallWithDifferentExceptionTypes(): void
                 })
             );
 
-        $this->expectException(ToolExecutionException::class);
-        $this->expectExceptionMessage('Execution of tool "error_tool" failed with error: "Invalid input".');
+        $this->expectException(ToolCallException::class);
+        $this->expectExceptionMessage('Tool call "error_tool" failed with error: "Invalid input".');
 
         $this->toolExecutor->call($request);
     }
@@ -493,10 +493,10 @@ public function testCallLogsResultTypeCorrectlyForArray(): void
 
     public function testConstructorWithDefaultLogger(): void
     {
-        $executor = new ToolExecutor($this->referenceProvider, $this->referenceHandler);
+        $executor = new ToolCaller($this->referenceProvider, $this->referenceHandler);
 
         // Verify it's constructed without throwing exceptions
-        $this->assertInstanceOf(ToolExecutor::class, $executor);
+        $this->assertInstanceOf(ToolCaller::class, $executor);
     }
 
     public function testCallHandlesEmptyArrayResult(): void

tests/Server/RequestHandler/CallToolHandlerTest.php

@@ -11,8 +11,8 @@
 
 namespace Mcp\Tests\Server\RequestHandler;
 
-use Mcp\Capability\Tool\ToolExecutorInterface;
-use Mcp\Exception\ToolExecutionException;
+use Mcp\Capability\Tool\ToolCallerInterface;
+use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\JsonRpc\Error;
@@ -28,12 +28,12 @@
 class CallToolHandlerTest extends TestCase
 {
     private CallToolHandler $handler;
-    private ToolExecutorInterface|MockObject $toolExecutor;
+    private ToolCallerInterface|MockObject $toolExecutor;
     private LoggerInterface|MockObject $logger;
 
     protected function setUp(): void
     {
-        $this->toolExecutor = $this->createMock(ToolExecutorInterface::class);
+        $this->toolExecutor = $this->createMock(ToolCallerInterface::class);
         $this->logger = $this->createMock(LoggerInterface::class);
 
         $this->handler = new CallToolHandler(
@@ -145,7 +145,7 @@ public function testHandleToolNotFoundExceptionReturnsError(): void
     public function testHandleToolExecutionExceptionReturnsError(): void
     {
         $request = $this->createCallToolRequest('failing_tool', ['param' => 'value']);
-        $exception = new ToolExecutionException($request, new \RuntimeException('Tool execution failed'));
+        $exception = new ToolCallException($request, new \RuntimeException('Tool execution failed'));
 
         $this->toolExecutor
             ->expects($this->once())
@@ -157,7 +157,7 @@ public function testHandleToolExecutionExceptionReturnsError(): void
             ->expects($this->once())
             ->method('error')
             ->with(
-                'Error while executing tool "failing_tool": "Execution of tool "failing_tool" failed with error: "Tool execution failed".".',
+                'Error while executing tool "failing_tool": "Tool call "failing_tool" failed with error: "Tool execution failed".".',
                 [
                     'tool' => 'failing_tool',
                     'arguments' => ['param' => 'value'],
@@ -217,7 +217,7 @@ public function testConstructorWithDefaultLogger(): void
     public function testHandleLogsErrorWithCorrectParameters(): void
     {
         $request = $this->createCallToolRequest('test_tool', ['key1' => 'value1', 'key2' => 42]);
-        $exception = new ToolExecutionException($request, new \RuntimeException('Custom error message'));
+        $exception = new ToolCallException($request, new \RuntimeException('Custom error message'));
 
         $this->toolExecutor
             ->expects($this->once())
@@ -228,7 +228,7 @@ public function testHandleLogsErrorWithCorrectParameters(): void
             ->expects($this->once())
             ->method('error')
             ->with(
-                'Error while executing tool "test_tool": "Execution of tool "test_tool" failed with error: "Custom error message".".',
+                'Error while executing tool "test_tool": "Tool call "test_tool" failed with error: "Custom error message".".',
                 [
                     'tool' => 'test_tool',
                     'arguments' => ['key1' => 'value1', 'key2' => 42],
@@ -277,7 +277,10 @@ public function testHandleWithSpecialCharactersInArguments(): void
         $this->assertSame($expectedResult, $response->result);
     }
 
-    private function createCallToolRequest(string $name, array $arguments): Request
+    /**
+     * @param array<string, mixed> $arguments
+     */
+    private function createCallToolRequest(string $name, array $arguments): CallToolRequest
     {
         return CallToolRequest::fromArray([
             'jsonrpc' => '2.0',

tests/Server/RequestHandler/GetPromptHandlerTest.php

@@ -325,7 +325,12 @@ public function testHandlePromptGetWithLargeNumberOfArguments(): void
         $this->assertSame($expectedResult, $response->result);
     }
 
-    private function createGetPromptRequest(string $name, ?array $arguments = null): Request
+    /**
+     * @param string $name
+     * @param array<string, mixed>|null $arguments
+     * @return GetPromptRequest
+     */
+    private function createGetPromptRequest(string $name, ?array $arguments = null): GetPromptRequest
     {
         return GetPromptRequest::fromArray([
             'jsonrpc' => '2.0',

tests/Server/RequestHandler/ReadResourceHandlerTest.php

@@ -244,6 +244,7 @@ public function testHandleResourceReadWithEmptyContent(): void
 
         $this->assertInstanceOf(Response::class, $response);
         $this->assertSame($expectedResult, $response->result);
+        $this->assertInstanceOf(TextResourceContents::class, $response->result->contents[0]);
         $this->assertEquals('', $response->result->contents[0]->text);
     }
 
@@ -337,7 +338,7 @@ public function testHandleResourceReadWithEmptyResult(): void
         $this->assertCount(0, $response->result->contents);
     }
 
-    private function createReadResourceRequest(string $uri): Request
+    private function createReadResourceRequest(string $uri): ReadResourceRequest
     {
         return ReadResourceRequest::fromArray([
             'jsonrpc' => '2.0',