>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3609590. --> Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !21 >>> <h3>Problem/Motivation</h3> <p>The module's MCP transport layer is built on <code>swisnl/mcp-client</code>, pinned to <code>^0.5</code> with <code>minimum-stability: dev</code>. That library is a third-party, pre-1.0 implementation of the Model Context Protocol, and the module already has to work around it in several places:</p> <ul> <li><code>Drupal\mcp_client\Transporter\CustomHeadersHttpTransporter</code> extends <code>Swis\McpClient\Transporters\StreamableHttpTransporter</code> purely to inject custom HTTP headers, because the library offers no supported way to do it.</li> <li>The same class overrides <code>initializeConnection()</code> to strip the library's <code>register_shutdown_function()</code> calls, which stop the ReactPHP event loop before Drupal's request lifecycle is finished and produce "Connection aborted early" errors. The override then reaches into the parent with <code>\ReflectionMethod</code> to call the private <code>updateSessionIdFromResponse()</code>.</li> <li><code>MCPClient::getStderrErrors()</code> uses <code>\ReflectionClass</code> to read the client's protected <code>transporter</code> property just to surface STDIO stderr output on a failed connection.</li> <li><code>MCPClient::listTools()</code> and <code>MCPClient::executeTool()</code> hand-translate the library's result objects back into plain arrays, including <code>method_exists()</code> probing on content items because the content types are not modelled in a way the module can rely on.</li> </ul> <p>Three of these are reflection against private or protected internals. Every one of them is a candidate to break on any <code>0.x</code> release of the upstream library, and none of them are covered by an upstream compatibility promise.</p> <p>Meanwhile, the Model Context Protocol project now ships an official PHP SDK - <a href="https://github.com/modelcontextprotocol/php-sdk">modelcontextprotocol/php-sdk</a> - developed together with the Symfony team, with a documented <a href="https://github.com/modelcontextprotocol/php-sdk#client-sdk">Client SDK</a>. It tracks the MCP specification directly, uses Symfony HttpClient and Process rather than ReactPHP, and exposes transports, headers and STDIO configuration as first-class supported API rather than as things to be reached around.</p> <h3>Proposed Resolution</h3> <p>Replace <code>swisnl/mcp-client</code> with the official <code>modelcontextprotocol/php-sdk</code> as the underlying client, keeping <code>MCPClient</code>'s public surface (<code>listTools()</code>, <code>executeTool()</code>, <code>disconnect()</code>) unchanged so that <code>McpClientFactory</code>, <code>McpToolBase</code> and <code>McpToolDeriver</code> need no behavioural changes.</p> <ul> <li>Swap the Composer requirement from <code>swisnl/mcp-client: ^0.5</code> to the official SDK, and re-evaluate whether <code>minimum-stability: dev</code> is still needed once the dependency changes.</li> <li>Rebuild <code>MCPClient::createHttpClient()</code> on the SDK's HTTP transport, passing custom headers through the SDK's supported configuration instead of subclassing a transporter. Delete <code>CustomHeadersHttpTransporter</code> entirely, along with its <code>initializeConnection()</code> override and the <code>\ReflectionMethod</code> call inside it.</li> <li>Rebuild <code>MCPClient::createStdioClient()</code> on the SDK's STDIO transport. The SDK builds on Symfony Process, so <code>command</code>, <code>env</code> and <code>cwd</code> map across directly, and the <code>$this-&gt;process</code> reference held only to defeat garbage collection can likely be dropped.</li> <li>Replace <code>getStderrErrors()</code> - the SDK is expected to surface process stderr through its own exception or transport API, so the <code>\ReflectionClass</code> access to the protected <code>transporter</code> property can be removed. If no such API exists, this is the one gap worth raising upstream rather than working around locally.</li> <li>Map the SDK's tool and content result objects to the arrays that <code>listTools()</code> and <code>executeTool()</code> already return, replacing the <code>method_exists()</code> probing with typed handling of the SDK's content types.</li> <li>Confirm the ReactPHP event-loop lifecycle problem disappears. The Symfony-based SDK is synchronous, so there should be no loop to stop and no shutdown handler to unregister - this is the main reason the current transporter override exists.</li> </ul> <p>Existing tests in <code>tests/src/Unit/MCPClientTest.php</code> and the kernel tests under <code>tests/src/Kernel/</code> should pass unchanged against the new implementation; where they mock <code>Swis\McpClient\Client</code> directly they need retargeting at the SDK's client class. A test asserting that a configured HTTP header actually reaches the outgoing request, and one asserting that a failed STDIO connection reports the child process's stderr, would lock in the two behaviours that the reflection hacks currently provide.</p> <h3>Remaining Tasks</h3> <ul> <li>Verify the official SDK's client covers both Streamable HTTP and STDIO transports at the maturity this module needs, and note its stability level.</li> <li>Check whether the SDK exposes STDIO stderr; if not, open an upstream issue before removing <code>getStderrErrors()</code>.</li> <li>Perform the swap and delete <code>CustomHeadersHttpTransporter</code>.</li> <li>Retarget the unit tests and add coverage for custom headers and STDIO connection failure.</li> <li>Manually test against a real HTTP MCP server and a real STDIO MCP server.</li> <li>Update <code>README.md</code> and the <code>docs/</code> pages that name the underlying library.</li> </ul> <h3>User Interface Changes</h3> <p>None. Server configuration and the tool plugins behave exactly as before.</p> <h3>API Changes</h3> <p><code>Drupal\mcp_client\Transporter\CustomHeadersHttpTransporter</code> is removed. It is an implementation detail of <code>MCPClient</code> and is not referenced anywhere else in the module, but it is a public class, so this is technically a BC break for any site that extended it. <code>MCPClient</code>, <code>McpClientFactory</code> and the tool plugins keep their signatures.</p> <h3>AI Assistance</h3> <p>Yes, AI was used to explore the issue.</p>