From 62401f56bdb0149ca1e002082cdf8dbaa454ecf1 Mon Sep 17 00:00:00 2001
From: Jonathan Amsterdam <jba@google.com>
Date: Fri, 9 May 2025 08:15:27 -0400
Subject: [PATCH] internal/mcp/design.md: client features

Change-Id: Iaed3461bcb35ca65c3118cafa0a5bbddfbd41ecc
Reviewed-on: https://go-review.googlesource.com/c/tools/+/671375
Reviewed-by: Robert Findley <rfindley@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
---
 design/design.md | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/design/design.md b/design/design.md
index d7a205d..cd43234 100644
--- a/design/design.md
+++ b/design/design.md
@@ -352,15 +352,49 @@ parameterizing automatic keepalive.
 
 ### Roots
 
-<!--
-TODO:
-Client.AddRoots
-Client.RemoveRoots
--->
+Clients support the MCP Roots feature out of the box, including roots-changed notifications.
+Roots can be added and removed from a `Client` with `AddRoots` and `RemoveRoots`:
+
+```
+// AddRoots adds the roots to the client's list of roots.
+// If the list changes, the client notifies the server.
+// If a root does not begin with a valid URI schema such as "https://" or "file://",
+// it is intepreted as a directory path on the local filesystem.
+func (*Client) AddRoots(roots ...string)
+
+// RemoveRoots removes the given roots from the client's list, and notifies
+// the server if the list has changed.
+// It is not an error to remove a nonexistent root.
+func (*Client) RemoveRoots(roots ...string)
+```
+
+Servers can call `ListRoots` to get the roots.
+If a server installs a `RootsChangedHandler`, it will be called when the client sends a
+roots-changed notification, which happens whenever the list of roots changes after a
+connection has been established.
+```
+func (*Server) ListRoots(context.Context, *ListRootsParams) (*ListRootsResult, error)
+
+type ServerOptions {
+  ...
+  // If non-nil, called when a client sends a roots-changed notification.
+  RootsChangedHandler func(context.Context, *ServerConnection, *RootsChangedParams)
+}
+```
 
 ### Sampling
 
-<!-- TODO: needs design -->
+Clients that support sampling are created with a `CreateMessageHandler` option for handling server
+calls.
+To perform sampling, a server calls `CreateMessage`.
+```
+type ClientOptions struct {
+  ...
+  CreateMessageHandler func(context.Context, *CreateMessageParams) (*CreateMessageResult, error)
+}
+
+func (*Server) CreateMessage(context.Context, *CreateMessageParams) (*CreateMessageResult, error)
+```
 
 ## Server Features