Add API documentation generation with phpDocumentor (#184)

* Add API documentation generation with phpDocumentor

- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fix phpDocumentor errors in type annotations

Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fix CI: pin phar-io/composer-distributor ^1.0.2

phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Integrate markdown guides into phpDocumentor output

Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.

- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Fine-tuning for path, config, and layout

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

docs/index.md

@@ -0,0 +1,7 @@
+# MCP PHP SDK Guides
+
+- [MCP Elements](mcp-elements.md) — Core capabilities (Tools, Resources, Resource Templates, and Prompts) with registration methods.
+- [Server Builder](server-builder.md) — Fluent builder class for creating and configuring MCP server instances.
+- [Transports](transports.md) — STDIO and HTTP transport implementations with guidance on choosing between them.
+- [Server-Client Communication](server-client-communication.md) — Methods for servers to communicate back to clients: sampling, logging, progress, and notifications.
+- [Examples](examples.md) — Example projects demonstrating attribute-based discovery, dependency injection, HTTP transport, and more.

docs/server-client-communication.md

@@ -0,0 +1,78 @@
+# Client Communication
+
+MCP supports various ways a server can communicate back to a server on top of the main request-response flow.
+
+## Table of Contents
+
+- [ClientGateway](#client-gateway)
+- [Sampling](#sampling)
+- [Logging](#logging)
+- [Notification](#notification)
+- [Progress](#progress)
+
+## ClientGateway
+
+Every communication back to client is handled using the `Mcp\Server\ClientGateway` and its dedicated methods per
+operation. To use the `ClientGateway` in your code, you need to use method argument injection for `RequestContext`.
+
+Every reference of a MCP element, that translates to an actual method call, can just add an type-hinted argument for the
+`RequestContext` and the SDK will take care to include the gateway in the arguments of the method call:
+
+```php
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Server\RequestContext;
+
+class MyService
+{
+    #[McpTool('my_tool', 'My Tool Description')]
+    public function myTool(RequestContext $context): string
+    {
+        $context->getClientGateway()->log(...);
+```
+
+## Sampling
+
+With [sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) servers can request clients to
+execute "completions" or "generations" with a language model for them:
+
+```php
+$result = $clientGateway->sample('Roses are red, violets are', 350, 90, ['temperature' => 0.5]);
+```
+
+The `sample` method accepts four arguments:
+
+1. `message`, which is **required** and accepts a string, an instance of `Content` or an array of `SampleMessage` instances.
+2. `maxTokens`, which defaults to `1000`
+3. `timeout` in seconds, which defaults to `120`
+4. `options` which might include `system_prompt`, `preferences` for model choice, `includeContext`, `temperature`, `stopSequences` and `metadata`
+
+[Find more details to sampling payload in the specification.](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling#protocol-messages)
+
+## Logging
+
+The [Logging](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging) utility enables servers
+to send structured log messages as notifcation to clients:
+
+```php
+use Mcp\Schema\Enum\LoggingLevel;
+
+$clientGateway->log(LoggingLevel::Warning, 'The end is near.');
+```
+
+## Progress
+
+With a [Progress](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress#progress)
+notification a server can update a client while an operation is ongoing:
+
+```php
+$clientGateway->progress(4.2, 10, 'Downloading needed images.');
+```
+
+## Notification
+
+Lastly, the server can push all kind of notifications, that implement the `Mcp\Schema\JsonRpc\Notification` interface
+to the client to:
+
+```php
+$clientGateway->notify($yourNotification);
+```