[Client] Feat: Implement MCP client component (#192)
* feat(client): add complete MCP client SDK with STDIO and HTTP transports Add Client, Builder, ClientProtocol, ClientSession, and transport implementations for communicating with MCP servers. Supports tools, resources, prompts, and real-time progress/logging notifications. * refactor(examples): reorganize examples into server/ and client/ folders * feat: add SamplingRequestHandler for handling server sampling requests * feat: add setLoggingLevel method to control server logging verbosity * refactor: make progress token dependent on request ID * docs: Update server IP in usage instructions and add notes on sampling server requirements. * feat: add complete() method for completion/complete requests * refactor: properly parse and type initialize result * refactor: standardize method names * fix: revert changes to server related components * fix: revert changes to server related components * refactor: Restructure client transports and handlers into dedicated namespaces. * fix: cs and php-stan errors fixes(partial) * feat: Refactor request handlers to return `Response` or `Error` objects directly, adding a `SamplingException` and error logging for sampling requests. * feat: Replace `ClientTransportInterface` with `TransportInterface` and move response result deserialization to client methods. * refactor: remove redundant timeout check for intialize on transports The processFiber that executes per tick while fiber is suspended already handles timeouts while waiting * feat: broaden symfony/http-client dependency to support Symfony 5.4 to 8.0 * Update examples/client/README.md Co-authored-by: Christopher Hertel <mail@christopher-hertel.de> * Update examples/client/README.md Co-authored-by: Christopher Hertel <mail@christopher-hertel.de> * refactor: remove outgoing message queue from session and simplify transport send method to directly dispatch messages. * refactor: Replace ClientSession with ClientState for clearer intent on runtime state management * refactor: rename connectAndInitialize to connect for consistency * chore: cs fix * chore: use SamplingCallbackInterface instead of a closure for sampling request handler --------- Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
This commit is contained in:
Kyrian Obikwelu
GitHub
parent
a5a738396d
commit
3ef864c444
1 changed files with 2731 additions and 9 deletions
284
src/Client.php
Normal file
284
src/Client.php
Normal file
|
|
@ -0,0 +1,284 @@
|
|||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the official PHP MCP SDK.
|
||||
*
|
||||
* A collaboration between Symfony and the PHP Foundation.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace Mcp;
|
||||
|
||||
use Mcp\Client\Builder;
|
||||
use Mcp\Client\Configuration;
|
||||
use Mcp\Client\Protocol;
|
||||
use Mcp\Client\Transport\TransportInterface;
|
||||
use Mcp\Exception\ConnectionException;
|
||||
use Mcp\Exception\RequestException;
|
||||
use Mcp\Schema\Enum\LoggingLevel;
|
||||
use Mcp\Schema\Implementation;
|
||||
use Mcp\Schema\JsonRpc\Error;
|
||||
use Mcp\Schema\JsonRpc\Request;
|
||||
use Mcp\Schema\JsonRpc\Response;
|
||||
use Mcp\Schema\PromptReference;
|
||||
use Mcp\Schema\Request\CallToolRequest;
|
||||
use Mcp\Schema\Request\CompletionCompleteRequest;
|
||||
use Mcp\Schema\Request\GetPromptRequest;
|
||||
use Mcp\Schema\Request\ListPromptsRequest;
|
||||
use Mcp\Schema\Request\ListResourcesRequest;
|
||||
use Mcp\Schema\Request\ListResourceTemplatesRequest;
|
||||
use Mcp\Schema\Request\ListToolsRequest;
|
||||
use Mcp\Schema\Request\PingRequest;
|
||||
use Mcp\Schema\Request\ReadResourceRequest;
|
||||
use Mcp\Schema\Request\SetLogLevelRequest;
|
||||
use Mcp\Schema\ResourceReference;
|
||||
use Mcp\Schema\Result\CallToolResult;
|
||||
use Mcp\Schema\Result\CompletionCompleteResult;
|
||||
use Mcp\Schema\Result\GetPromptResult;
|
||||
use Mcp\Schema\Result\ListPromptsResult;
|
||||
use Mcp\Schema\Result\ListResourcesResult;
|
||||
use Mcp\Schema\Result\ListResourceTemplatesResult;
|
||||
use Mcp\Schema\Result\ListToolsResult;
|
||||
use Mcp\Schema\Result\ReadResourceResult;
|
||||
use Psr\Log\LoggerInterface;
|
||||
use Psr\Log\NullLogger;
|
||||
|
||||
/**
|
||||
* Main MCP Client facade.
|
||||
*
|
||||
* Provides a synchronous API for communicating with MCP servers.
|
||||
* All blocking operations are delegated to the transport.
|
||||
*
|
||||
* @author Kyrian Obikwelu <koshnawaza@gmail.com>
|
||||
*/
|
||||
class Client
|
||||
{
|
||||
private ?TransportInterface $transport = null;
|
||||
|
||||
public function __construct(
|
||||
private readonly Protocol $protocol,
|
||||
private readonly Configuration $config,
|
||||
private readonly LoggerInterface $logger = new NullLogger(),
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new client builder for fluent configuration.
|
||||
*/
|
||||
public static function builder(): Builder
|
||||
{
|
||||
return new Builder();
|
||||
}
|
||||
|
||||
/**
|
||||
* Connect to an MCP server using the provided transport.
|
||||
*
|
||||
* @throws ConnectionException If connection or initialization fails
|
||||
*/
|
||||
public function connect(TransportInterface $transport): void
|
||||
{
|
||||
$this->transport = $transport;
|
||||
$this->protocol->connect($transport, $this->config);
|
||||
|
||||
$transport->connect();
|
||||
|
||||
$this->logger->info('Client connected and initialized');
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if connected and initialized.
|
||||
*/
|
||||
public function isConnected(): bool
|
||||
{
|
||||
return null !== $this->transport && $this->protocol->getState()->isInitialized();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get server information from initialization.
|
||||
*/
|
||||
public function getServerInfo(): ?Implementation
|
||||
{
|
||||
return $this->protocol->getState()->getServerInfo();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get server instructions.
|
||||
*/
|
||||
public function getInstructions(): ?string
|
||||
{
|
||||
return $this->protocol->getState()->getInstructions();
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a ping request to the server.
|
||||
*/
|
||||
public function ping(): void
|
||||
{
|
||||
$request = new PingRequest();
|
||||
|
||||
$this->sendRequest($request);
|
||||
}
|
||||
|
||||
/**
|
||||
* List available tools from the server.
|
||||
*/
|
||||
public function listTools(?string $cursor = null): ListToolsResult
|
||||
{
|
||||
$request = new ListToolsRequest($cursor);
|
||||
|
||||
$response = $this->sendRequest($request);
|
||||
|
||||
return ListToolsResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Call a tool on the server.
|
||||
*
|
||||
* @param string $name Tool name
|
||||
* @param array<string, mixed> $arguments Tool arguments
|
||||
* @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
|
||||
* Optional callback for progress updates
|
||||
*/
|
||||
public function callTool(string $name, array $arguments = [], ?callable $onProgress = null): CallToolResult
|
||||
{
|
||||
$request = new CallToolRequest($name, $arguments);
|
||||
|
||||
$response = $this->sendRequest($request, $onProgress);
|
||||
|
||||
return CallToolResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* List available resources from the server.
|
||||
*/
|
||||
public function listResources(?string $cursor = null): ListResourcesResult
|
||||
{
|
||||
$request = new ListResourcesRequest($cursor);
|
||||
|
||||
$response = $this->sendRequest($request);
|
||||
|
||||
return ListResourcesResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* List available resource templates from the server.
|
||||
*/
|
||||
public function listResourceTemplates(?string $cursor = null): ListResourceTemplatesResult
|
||||
{
|
||||
$request = new ListResourceTemplatesRequest($cursor);
|
||||
|
||||
$response = $this->sendRequest($request);
|
||||
|
||||
return ListResourceTemplatesResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read a resource by URI.
|
||||
*
|
||||
* @param string $uri The resource URI
|
||||
* @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
|
||||
* Optional callback for progress updates
|
||||
*/
|
||||
public function readResource(string $uri, ?callable $onProgress = null): ReadResourceResult
|
||||
{
|
||||
$request = new ReadResourceRequest($uri);
|
||||
|
||||
$response = $this->sendRequest($request, $onProgress);
|
||||
|
||||
return ReadResourceResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* List available prompts from the server.
|
||||
*/
|
||||
public function listPrompts(?string $cursor = null): ListPromptsResult
|
||||
{
|
||||
$request = new ListPromptsRequest($cursor);
|
||||
|
||||
$response = $this->sendRequest($request);
|
||||
|
||||
return ListPromptsResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get a prompt from the server.
|
||||
*
|
||||
* @param string $name Prompt name
|
||||
* @param array<string, string> $arguments Prompt arguments
|
||||
* @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
|
||||
* Optional callback for progress updates
|
||||
*/
|
||||
public function getPrompt(string $name, array $arguments = [], ?callable $onProgress = null): GetPromptResult
|
||||
{
|
||||
$request = new GetPromptRequest($name, $arguments);
|
||||
|
||||
$response = $this->sendRequest($request, $onProgress);
|
||||
|
||||
return GetPromptResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Request completion suggestions for a prompt or resource argument.
|
||||
*
|
||||
* @param PromptReference|ResourceReference $ref The prompt or resource reference
|
||||
* @param array{name: string, value: string} $argument The argument to complete
|
||||
*/
|
||||
public function complete(PromptReference|ResourceReference $ref, array $argument): CompletionCompleteResult
|
||||
{
|
||||
$request = new CompletionCompleteRequest($ref, $argument);
|
||||
|
||||
$response = $this->sendRequest($request);
|
||||
|
||||
return CompletionCompleteResult::fromArray($response->result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Set the minimum logging level for server log messages.
|
||||
*/
|
||||
public function setLoggingLevel(LoggingLevel $level): void
|
||||
{
|
||||
$request = new SetLogLevelRequest($level);
|
||||
|
||||
$this->sendRequest($request);
|
||||
}
|
||||
|
||||
/**
|
||||
* Send a request to the server and wait for response.
|
||||
*
|
||||
* @param (callable(float $progress, ?float $total, ?string $message): void)|null $onProgress
|
||||
*
|
||||
* @return Response<mixed>
|
||||
*
|
||||
* @throws RequestException|ConnectionException
|
||||
*/
|
||||
private function sendRequest(Request $request, ?callable $onProgress = null): Response
|
||||
{
|
||||
if (!$this->isConnected()) {
|
||||
throw new ConnectionException('Client is not connected. Call connect() first.');
|
||||
}
|
||||
|
||||
$withProgress = null !== $onProgress;
|
||||
$fiber = new \Fiber(fn () => $this->protocol->request($request, $this->config->requestTimeout, $withProgress));
|
||||
$response = $this->transport->runRequest($fiber, $onProgress);
|
||||
|
||||
if ($response instanceof Error) {
|
||||
throw RequestException::fromError($response);
|
||||
}
|
||||
|
||||
return $response;
|
||||
}
|
||||
|
||||
/**
|
||||
* Disconnect from the server.
|
||||
*/
|
||||
public function disconnect(): void
|
||||
{
|
||||
if (null !== $this->transport) {
|
||||
$this->transport->close();
|
||||
$this->transport = null;
|
||||
$this->logger->info('Client disconnected');
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue