php-mcp/client

**PHP MCP Client is a PHP library for interacting with servers that implement the Model Context Protocol (MCP).**
It provides a developer-friendly interface to connect to individual MCP servers using different transports (stdio, http+sse), manage the connection lifecycle, discover server capabilities (Tools, Resources, Prompts), and execute requests like calling tools or reading resources.
While utilizing asynchronous I/O internally via ReactPHP for robustness and handling features like server-sent events, the library offers **both** a straightforward **synchronous (blocking) API** for common use cases and an **asynchronous (Promise-based) API** for advanced control and concurrency.
This library aligns with the MCP specification's model where one client instance manages a stateful connection to one server.
Introduction to MCP
The Model Context Protocol (MCP) is an open standard designed to standardize how AI assistants and applications connect to external data sources, APIs, and tools (like codebases, databases, web browsers). It acts as a communication layer, enabling AI models (like Claude, or models integrated via frameworks like OpenAI's) to securely access and interact with context provided by different servers.
This client library allows your PHP application (acting as the "Host" in MCP terminology) to *consume* capabilities offered by one or more MCP servers.
Features
* **Client-per-Server Model:** Each Client instance manages a stateful connection to a single configured MCP server, aligning with the MCP specification.
* **Fluent Configuration:** Easy setup for each client instance using a Client::make()->with...() builder pattern.
* **Dual API:**
* **Synchronous Facade:** Interact with the server using straightforward, blocking methods (e.g., $client->listTools(), $client->callTool(...)) for simple integration.
* **Asynchronous API:** Access underlying Promise-based methods (e.g., $client->listToolsAsync(), $client->callToolAsync(...)) for concurrency and integration with async PHP applications.
* **Multiple Transports:** Built-in support for:
* stdio: Communicating with server processes via Standard Input/Output.
* http: Communicating with servers via HTTP POST and Server-Sent Events (SSE).
* **Explicit Connection Lifecycle:** Requires ->initialize() or ->initializeAsync() to connect and perform the handshake before making requests. Provides disconnect() / disconnectAsync().
* **Tool/Resource/Prompt Interaction:** Provides comprehensive methods (sync & async) to list available elements and execute requests like tools/call, resources/read, prompts/get.
* **PSR Compliance:** Integrates with standard PHP interfaces:
* PSR-3 (LoggerInterface): Integrate your application's logger.
* PSR-16 (SimpleCacheInterface): Optional caching for server definitions.
* PSR-14 (EventDispatcherInterface): Optional handling of server-sent notifications via events (requires async handling).
* **Robust Error Handling:** Specific exceptions for different failure modes.
* **Asynchronous Core:** Utilizes ReactPHP internally for non-blocking I/O.
Requirements
* PHP >= 8.1
* Composer
* *(For Stdio Transport)*: Ability to execute the server command.
* *(For Http Transport)*: Network access to the MCP server URL.
Installation
Install the package via Composer:
The necessary ReactPHP dependencies (event-loop, promise, stream, child-process, http) should be installed automatically.
Quick Start: Simple Synchronous Usage (Stdio)
This example connects to a local filesystem server running via npx.
Configuration
Configuration involves setting up:
1. **Client Identity:** Your application's name and version, passed directly to the builder.
2. **Client Capabilities:** Features your client supports using ClientCapabilities.
3. **Server Connection:** Details for the *single server* this client instance will connect to, using ServerConfig.