[Schema][Client][Server] Deprecate Roots, Sampling and Logging (SEP-2577) (#427)

* [Schema][Client][Server] Deprecate Roots, Sampling and Logging (SEP-2577)

* Emit runtime deprecation notices and document the migration (SEP-2596)

src/Capability/Logger/ClientLogger.php

@@ -22,6 +22,9 @@ use Psr\Log\AbstractLogger;
  *
  * @author Adam Jamiu <jamiuadam120@gmail.com>
  * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Log to stderr (stdio) or use OpenTelemetry instead.
  */
 final class ClientLogger extends AbstractLogger
 {

src/Client/Handler/Notification/LoggingNotificationHandler.php

@@ -18,6 +18,9 @@ use Mcp\Schema\Notification\LoggingMessageNotification;
  * Handler for logging message notifications from the server.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Log to stderr (stdio) or use OpenTelemetry instead.
  */
 class LoggingNotificationHandler implements NotificationHandlerInterface
 {
@@ -27,6 +30,7 @@ class LoggingNotificationHandler implements NotificationHandlerInterface
     public function __construct(
         private readonly mixed $callback,
     ) {
+        trigger_deprecation('mcp/sdk', '0.8', 'MCP logging is deprecated since protocol revision 2026-07-28 (SEP-2577); log to stderr or use OpenTelemetry instead.');
     }
 
     public function supports(Notification $notification): bool

src/Client/Handler/Request/ListRootsRequestHandler.php

@@ -30,6 +30,10 @@ use Psr\Log\NullLogger;
  * @implements RequestHandlerInterface<ListRootsResult>
  *
  * @author Johannes Wachter <johannes@sulu.io>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Pass directories or files through tool arguments, resource
+ * URIs or server configuration instead.
  */
 class ListRootsRequestHandler implements RequestHandlerInterface
 {
@@ -37,6 +41,7 @@ class ListRootsRequestHandler implements RequestHandlerInterface
         private readonly RootsCallbackInterface $callback,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
+        trigger_deprecation('mcp/sdk', '0.8', 'MCP roots are deprecated since protocol revision 2026-07-28 (SEP-2577); pass directories through tool arguments or resource URIs instead.');
     }
 
     public function supports(Request $request): bool

src/Client/Handler/Request/RootsCallbackInterface.php

@@ -21,6 +21,10 @@ use Mcp\Schema\Result\ListRootsResult;
  * requested by the server.
  *
  * @author Johannes Wachter <johannes@sulu.io>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Pass directories or files through tool arguments, resource
+ * URIs or server configuration instead.
  */
 interface RootsCallbackInterface
 {

src/Client/Handler/Request/SamplingCallbackInterface.php

@@ -18,6 +18,9 @@ use Mcp\Schema\Result\CreateSamplingMessageResult;
  * Contract for callbacks used by SamplingRequestHandler.
  *
  * Implementations perform the actual LLM sampling when requested by the server.
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 interface SamplingCallbackInterface
 {

src/Client/Handler/Request/SamplingRequestHandler.php

@@ -30,6 +30,9 @@ use Psr\Log\NullLogger;
  * @implements RequestHandlerInterface<CreateSamplingMessageResult>
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 class SamplingRequestHandler implements RequestHandlerInterface
 {
@@ -37,6 +40,7 @@ class SamplingRequestHandler implements RequestHandlerInterface
         private readonly SamplingCallbackInterface $callback,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
+        trigger_deprecation('mcp/sdk', '0.8', 'MCP sampling is deprecated since protocol revision 2026-07-28 (SEP-2577); integrate with an LLM provider\'s API directly instead.');
     }
 
     public function supports(Request $request): bool

src/Schema/Content/SamplingMessage.php

@@ -31,6 +31,9 @@ use Mcp\Schema\Enum\Role;
  * }
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 class SamplingMessage extends Content
 {

src/Schema/Content/ToolResultContent.php

@@ -20,6 +20,9 @@ use Mcp\Exception\InvalidArgumentException;
  * {@see \Mcp\Schema\Result\CallToolResult} does.
  *
  * @phpstan-type ToolResultBlock TextContent|ImageContent|AudioContent|ResourceLink|EmbeddedResource
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 final class ToolResultContent extends Content
 {

src/Schema/Content/ToolUseContent.php

@@ -15,6 +15,9 @@ use Mcp\Exception\InvalidArgumentException;
 
 /**
  * A request from the assistant to call a tool.
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 final class ToolUseContent extends Content
 {

src/Schema/Enum/LoggingLevel.php

@@ -18,6 +18,9 @@ namespace Mcp\Schema\Enum;
  * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Log to stderr (stdio) or use OpenTelemetry instead.
  */
 enum LoggingLevel: string
 {

src/Schema/Enum/SamplingContext.php

@@ -11,6 +11,15 @@
 
 namespace Mcp\Schema\Enum;
 
+/**
+ * Which servers' context a sampling request asks the client to attach.
+ *
+ * `thisServer` and `allServers` are themselves deprecated since 2025-11-25
+ * (SEP-2596): omit the field or use `none`.
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
+ */
 enum SamplingContext: string
 {
     case NONE = 'none';

src/Schema/Enum/ToolChoiceMode.php

@@ -11,6 +11,12 @@
 
 namespace Mcp\Schema\Enum;
 
+/**
+ * How the model may use the tools offered on a sampling request.
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
+ */
 enum ToolChoiceMode: string
 {
     case Auto = 'auto';

src/Schema/ModelHint.php

@@ -17,6 +17,9 @@ namespace Mcp\Schema;
  * Keys not declared here are currently left unspecified by the spec and are up to the client to interpret.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 class ModelHint implements \JsonSerializable
 {

src/Schema/ModelPreferences.php

@@ -34,6 +34,9 @@ use Mcp\Exception\InvalidArgumentException;
  * }
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 class ModelPreferences implements \JsonSerializable
 {

src/Schema/Notification/LoggingMessageNotification.php

@@ -17,6 +17,9 @@ use Mcp\Schema\JsonRpc\Notification;
 
 /**
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Log to stderr (stdio) or use OpenTelemetry instead.
  */
 class LoggingMessageNotification extends Notification
 {

src/Schema/Notification/RootsListChangedNotification.php

@@ -19,6 +19,10 @@ use Mcp\Schema\JsonRpc\Notification;
  * The server should then request an updated list of roots using the ListRootsRequest.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Pass directories or files through tool arguments, resource
+ * URIs or server configuration instead.
  */
 class RootsListChangedNotification extends Notification
 {

src/Schema/Request/CreateSamplingMessageRequest.php

@@ -28,6 +28,9 @@ use Mcp\Schema\ToolChoice;
  * loop) and decide whether to approve it.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 final class CreateSamplingMessageRequest extends Request
 {

src/Schema/Request/ListRootsRequest.php

@@ -23,6 +23,10 @@ use Mcp\Schema\JsonRpc\Request;
  * structure or access specific locations that the client has permission to read from.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Pass directories or files through tool arguments, resource
+ * URIs or server configuration instead.
  */
 final class ListRootsRequest extends Request
 {

src/Schema/Request/SetLogLevelRequest.php

@@ -19,6 +19,9 @@ use Mcp\Schema\JsonRpc\Request;
  * A request from the client to the server, to enable or adjust logging.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Log to stderr (stdio) or use OpenTelemetry instead.
  */
 final class SetLogLevelRequest extends Request
 {

src/Schema/Result/CreateSamplingMessageResult.php

@@ -25,6 +25,9 @@ use Mcp\Schema\JsonRpc\ResultInterface;
  * the server to see it.
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
+ *
+ * @deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28.
+ *  Integrate with an LLM provider's API directly instead.
  */
 class CreateSamplingMessageResult implements ResultInterface
 {