940eb90872* 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>
78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
# 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);
|
|
```
|