docs: add more about building servers and updating front readme

Author: chr-hertel

README.md

@@ -1,11 +1,10 @@
 # MCP PHP SDK
 
-The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers in PHP.
+The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers
+and clients in PHP.
 
 > [!IMPORTANT]
-> Currently, we are still in the process of merging [Symfony's MCP SDK](https://github.com/symfony/mcp-sdk) and
-> [PHP-MCP](https://github.com/php-mcp) components. Not all code paths are fully tested or complete, and this package
-> may still contain duplicate functionality or dead code.
+> Currently, the SDK is still in active development and not all components of the MCP specification are implemented.
 > 
 > If you want to help us stabilize the SDK, please see the
 > [issue tracker](https://github.com/modelcontextprotocol/php-sdk/issues).
@@ -21,29 +20,17 @@ Until the first major release, this SDK is considered
 ## 🚧 Roadmap
 
 Features
-- [x] Bring back PHP-MCP examples
-- [x] Glue handler, registry and reference handlers
-- [x] Revive `ServerBuilder`
-- [x] Revive transports 
-  - [x] Streamable Transport https://github.com/modelcontextprotocol/php-sdk/issues/7
-  - [ ] ~~Http/SSE-based Transport https://github.com/modelcontextprotocol/php-sdk/issues/8~~
-- [ ] Support pagination
-- [ ] Support Schema validation
-- [ ] Support multiple versions of the MCP specification https://github.com/modelcontextprotocol/php-sdk/issues/14
-- [ ] (Re-)Implement missing Notification & Request Handlers https://github.com/modelcontextprotocol/php-sdk/issues/9
+- [ ] Stabilize server component with all needed handlers and functional tests
+- [ ] Extend documentation, including integration pointer for popular frameworks
+- [ ] Implement Client component
+- [ ] Support multiple schema versions
 
 ## Installation
 
 ```bash
 composer require mcp/sdk
 ```
 
-Since this package has no tagged releases yet, it is required to extend your `composer.json`:
-```json
-"minimum-stability": "dev",
-"prefer-stable": true
-```
-
 ## ⚡ Quick Start: Stdio Server with Discovery
 
 This example demonstrates the most common usage pattern - a `stdio` server using attribute discovery.
@@ -111,16 +98,19 @@ Add to your client configuration (e.g., `mcp.json`):
 Your AI assistant can now call:
 - `add_numbers` - Add two integers
 
+For more examples, see the [examples directory](examples).
+
 ## Documentation
 
-- [SDK documentation](doc/index.rst)
+- [SDK documentation](docs/index.md)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)
 
-## Examples of MCP Tools that use this SDK
+## PHP libraries using the MCP SDK
 
-- https://github.com/pronskiy/mcp
+* https://github.com/pronskiy/mcp - additional DX layer
+* https://github.com/symfony/mcp-bundle - Symfony integration bundle
 
 ## Contributing
 
@@ -130,7 +120,9 @@ the project. See the [contributing guide](CONTRIBUTING.md) to get started before
 [send pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls).
 
 ## Credits
-The starting point for this SDK was the [PHP-MCP](https://github.com/php-mcp/server) project, initiated by [Kyrian Obikwelu](https://github.com/CodeWithKyrian). We are grateful for the work done by Kyrian and other contributors to that repository, which created a solid foundation for this SDK.
+Starting point for this SDK was the [PHP-MCP](https://github.com/php-mcp/server) project, initiated by
+[Kyrian Obikwelu](https://github.com/CodeWithKyrian), and the [Symfony AI initiative](https://github.com/symfony/ai).
+We are grateful for the work done by both projects and their contributors, which created a solid foundation for this SDK.
 
 ## License
 

docs/index.md

@@ -0,0 +1,72 @@
+# MCP PHP SDK
+
+To understand the basics of the Model Context Protocol (MCP), we highly recommend reading the main
+[MCP documentation](https://modelcontextprotocol.io) first.
+
+## Building an MCP Server
+
+This SDK provides a way to build an MCP server and wire it up with various capabilities implemented in your application.
+Therefore, we differentiate between the core server architecture and its extension points for registering MCP elements.
+
+### Server Setup
+
+The server needs to be configured with some basic information and the discovery of MCP elements. On top, you need to
+decide for a transport the server should be connected to, and in the end listen. Which is a long running process in the
+end.
+For easing the setup of a server, we provide a fluent builder interface:
+
+**ServerBuilder**
+
+```php
+use Mcp\Server\ServerBuilder;
+
+$server = ServerBuilder::make()
+    ->setServerInfo('My Server', '1.0.0', 'A description of my server.')
+    ->setDiscovery(__DIR__, ['.']) // Scan current directory recursively for MCP elements
+    ->build();
+```
+There are more options available on the builder, see [Server Builder documentation](docs/server-builder.md) for details.
+
+**Transport**
+
+The transport is responsible for the communication between the server and the client. The SDK comes with two built-in
+transports: `StdioTransport` and `StreamableHttpTransport`.
+
+```php
+use Mcp\Server\Transport\StdioTransport;
+
+# STDIO Transport
+$transport = new StdioTransport();
+
+# Streamable HTTP Transport
+$transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
+
+# Connect the transport to the server
+$server->connect(new StdioTransport());
+
+# Start listening (blocking call)
+$server->listen();
+```
+
+### Implementing MCP Elements
+
+MCP elements are the building blocks of an MCP server. They implement the actual capabilities that can be called by
+the client. The SDK comes with a set of attributes and service classes for discovery, that make it handy to register
+your code as MCP elements.
+
+```php
+final class MyServiceClass
+{
+    #[McpTool('foo_bar', 'This is my Foo Bar tool.')]
+    public function foo(string $bar): string
+    {
+        return sprintf('Foo %s', $bar);
+    }
+}
+```
+
+More about that can be found in the [Server Builder documentation](docs/server-builder.md).
+
+## Building an MCP Client
+
+Building an MCP Client is currently not supported by this SDK, but part of our roadmap.

docs/server-builder.md

@@ -0,0 +1,46 @@
+# Server Builder
+
+The `ServerBuilder` is an optional factory class, that makes it easier to create and configure a `Server` instance,
+including the registration of MCP elements/capabilities.
+
+## Basic Server Configuration
+
+There is a set of basic server configuration, that is required by the specification, and should always be set:
+* Name
+* Version
+* Description (optional)
+
+This can be set via `setServerInfo`:
+```php
+$server = ServerBuilder::make()
+    ->setServerInfo('My MCP Server', '0.1')
+```
+
+## Service Dependencies
+
+All service dependencies are optional and if not set explicitly the builder defaults to skipping them or instantiating
+default implementations.
+
+This includes
+* Logger, as an instance of `Psr\Log\LoggerInterface`
+* Container, as an instance of `Psr\Container\ContainerInterface`
+* and more.
+
+```php
+$server = ServerBuilder::make()
+    ->setLogger($yourLogger)
+    ->setContainer($yourContainer)
+```
+
+## Register Capabilities
+
+There are two ways of registering MCP elements as capabilities on your server: automated discovery based on file system 
+& PHP attributes, and adding them explicitly.
+
+### Discovery
+
+TODO, incl. caching
+
+### Explicit Registration
+
+TODO