Add an overview documentation of the SDK

Author: Nyholm

src/mcp-sdk/composer.json

@@ -15,7 +15,7 @@
     ],
     "require": {
         "php": "^8.2",
-        "psr/log": "^3.0",
+        "psr/log": "^1.0 || ^2.0 || ^3.0",
         "symfony/uid": "^6.4 || ^7.0"
     },
     "require-dev": {

src/mcp-sdk/doc/index.rst

@@ -19,8 +19,8 @@ Usage
 The `Model Context Protocol`_ is built on top of JSON-RPC. There two types of
 messages. A Notification and Request. The Notification is just a status update
 that something has happened. There is never a response to a Notification. A Request
-is a message that expects a response. There are 3 concepts that you may request.
-These are::
+is a message that expects a response. There are 3 concepts/capabilities that you
+may use. These are::
 
 1. **Resources**: File-like data that can be read by clients (like API responses or file contents)
 1. **Tools**: Functions that can be called by the LLM (with user approval)
@@ -29,4 +29,136 @@ These are::
 The SDK comes with NotificationHandlers and RequestHandlers which are expected
 to be wired up in your application.
 
+JsonRpcHandler
+..............
+
+The ``Symfony\AI\McpSdk\Server\JsonRpcHandler`` is the heart of the SDK. It is here
+you inject the NotificationHandlers and RequestHandlers. It is recommended to use
+the built-in handlers in ``Symfony\AI\McpSdk\Server\NotificationHandlers\*`` and
+``Symfony\AI\McpSdk\Server\RequestHandlers\*``.
+
+The ``Symfony\AI\McpSdk\Server\JsonRpcHandler`` is started and kept running by
+the ``Symfony\AI\McpSdk\Server``
+
+Transports
+..........
+
+The SDK supports multiple transports for sending and receiving messages. The
+``Symfony\AI\McpSdk\Server`` is using the transport to fetch a message, then
+give it to the ``Symfony\AI\McpSdk\Server\JsonRpcHandler`` and finally send the
+response/error back to the transport. The SDK comes with a few transports::
+
+1. **Symfony Console Transport**: Good for testing and for CLI applications
+1. **Stream Transport**: It uses Server Side Events (SSE) and HTTP streaming
+
+Capabilities
+............
+
+Any client would like to discover the capabilities of the server. Exactly what
+the server supports is defined in the ``Symfony\AI\McpSdk\Server\RequestHandler\InitializeHandler``.
+When the client connects, it sees the capabilities and will ask the server to list
+the tools/resource/prompts etc. When you want to add a new capability, example a
+**Tool** that can tell the current time, you need to provide some metadata to the
+``Symfony\AI\McpSdk\Server\RequestHandler\ToolListHandler``.
+
+.. code-block: php
+
+    namespace App;
+
+    use Symfony\AI\McpSdk\Capability\Tool\MetadataInterface;
+
+    class CurrentTimeToolMetadata implements MetadataInterface
+    {
+        public function getName(): string
+        {
+            return 'Current time';
+        }
+
+        public function getDescription(): string
+        {
+            return 'Returns the current time in UTC';
+        }
+
+        public function getInputSchema(): array
+        {
+            return [
+                'type' => 'object',
+                'properties' => [
+                    'format' => [
+                        'type' => 'string',
+                        'description' => 'The format of the time, e.g. "Y-m-d H:i:s"',
+                        'default' => 'Y-m-d H:i:s',
+                    ],
+                ],
+                'required' => [],
+            ];
+        }
+    }
+
+We would also need a class to actually execute the tool.
+
+.. code-block: php
+
+    namespace App;
+
+    use Symfony\AI\McpSdk\Capability\Tool\ToolExecutorInterface;
+    use Symfony\AI\McpSdk\Capability\Tool\IdentifierInterface;
+    use Symfony\AI\McpSdk\Capability\Tool\ToolCall;
+    use Symfony\AI\McpSdk\Capability\Tool\ToolCallResult;
+
+    class CurrentTimeToolExecutor implements ToolExecutorInterface, IdentifierInterface
+    {
+        public function getName(): string
+        {
+            return 'Current time';
+        }
+
+        public function call(ToolCall $input): ToolCallResult
+        {
+            $format = $input->arguments['format'] ?? 'Y-m-d H:i:s';
+
+            return new ToolCallResult(
+                (new \DateTime('now', new \DateTimeZone('UTC')))->format($format)
+            );
+        }
+    }
+
+If you have multiple tools, you can put them in a ToolChain.
+
+.. code-block: php
+
+    $tools = new ToolChain([
+        new CurrentTimeToolMetadata(),
+        new CurrentTimeToolExecutor(),
+    ]);
+
+    $jsonRpcHandler = new Symfony\AI\McpSdk\Server\JsonRpcHandler(
+        new Symfony\AI\McpSdk\Message\Factory(),
+        [
+            new ToolCallHandler($tools),
+            new ToolListHandler($tools),
+            // Other RequestHandlers ...
+        ],
+        [
+            // Other NotificationHandlers ...
+        ],
+        new NullLogger()
+    );
+
+With this metadata and executor, the client can now call the tool.
+
+Extending the SDK
+-----------------
+
+If you want to extend the SDK, you can create your own RequestHandlers and NotificationHandlers.
+The provided one are very good defaults for most applications but they are not
+a requirement.
+
+If you do decide to use them, you get the benefit of having a well-defined interfaces
+and value objects to work with. They will assure that you follow the `Model Context Protocol`_.
+specification.
+
+You also have the Transport abstraction that allows you to create your own transport
+if non of the standard ones fit your needs.
+
 .. _`Model Context Protocol`: https://modelcontextprotocol.io/