internal/mcp: design.md: polishing

Various typo and style changes.

Change-Id: Ifd4322dcf0bf2b2653bb38a023a51056424cca39
Reviewed-on: https://go-review.googlesource.com/c/tools/+/672815
Reviewed-by: Robert Findley <rfindley@google.com>
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Commit-Queue: Jonathan Amsterdam <jba@google.com>
TryBot-Bypass: Jonathan Amsterdam <jba@google.com>
This commit is contained in:
Jonathan Amsterdam 2025-05-14 13:18:23 -04:00
commit 0c7d8180a6

View file

@ -1,6 +1,6 @@
# Go MCP SDK design # Go MCP SDK design
This file discusses the design of a Go SDK for the [model context This document discusses the design of a Go SDK for the [model context
protocol](https://modelcontextprotocol.io/specification/2025-03-26). It is protocol](https://modelcontextprotocol.io/specification/2025-03-26). It is
intended to seed a GitHub discussion about the official Go MCP SDK. intended to seed a GitHub discussion about the official Go MCP SDK.
@ -18,7 +18,7 @@ writing, it is imported by over 400 packages that span over 200 modules.
We admire mcp-go, and seriously considered simply adopting it as a starting We admire mcp-go, and seriously considered simply adopting it as a starting
point for this SDK. However, as we looked at doing so, we realized that a point for this SDK. However, as we looked at doing so, we realized that a
significant amount of its API would probably need to change. In some cases, significant amount of its API would probably need to change. In some cases,
mcp-go has older APIs that predated newer variations--an obvious opportunity mcp-go has older APIs that predated newer variations—an obvious opportunity
for cleanup. In others, it took a batteries-included approach that is probably for cleanup. In others, it took a batteries-included approach that is probably
not viable for an official SDK. In yet others, we simply think there is room for not viable for an official SDK. In yet others, we simply think there is room for
API refinement, and we should take this opportunity to consider our options. API refinement, and we should take this opportunity to consider our options.
@ -332,7 +332,7 @@ marshalling/unmarshalling can be delegated to the business logic of the client
or server. or server.
For union types, which can't be represented in Go (specifically `Content` and For union types, which can't be represented in Go (specifically `Content` and
`Resource`), we prefer distinguished unions: struct types with fields `ResourceContents`), we prefer distinguished unions: struct types with fields
corresponding to the union of all properties for union elements. corresponding to the union of all properties for union elements.
For brevity, only a few examples are shown here: For brevity, only a few examples are shown here:
@ -353,11 +353,11 @@ type CallToolResult struct {
// The Type field distinguishes the type of the content. // The Type field distinguishes the type of the content.
// At most one of Text, MIMEType, Data, and Resource is non-zero. // At most one of Text, MIMEType, Data, and Resource is non-zero.
type Content struct { type Content struct {
Type string `json:"type"` Type string `json:"type"`
Text string `json:"text,omitempty"` Text string `json:"text,omitempty"`
MIMEType string `json:"mimeType,omitempty"` MIMEType string `json:"mimeType,omitempty"`
Data []byte `json:"data,omitempty"` Data []byte `json:"data,omitempty"`
Resource *Resource `json:"resource,omitempty"` Resource *ResourceContents `json:"resource,omitempty"`
} }
``` ```
@ -386,7 +386,7 @@ change.
Following the terminology of the Following the terminology of the
[spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management), [spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management),
we call the logical connection between a client and server a "session". There we call the logical connection between a client and server a "session." There
must necessarily be a `ClientSession` and a `ServerSession`, corresponding to must necessarily be a `ClientSession` and a `ServerSession`, corresponding to
the APIs available from the client and server perspective, respectively. the APIs available from the client and server perspective, respectively.
@ -436,7 +436,7 @@ transport := mcp.NewCommandTransport(exec.Command("myserver"))
session, err := client.Connect(ctx, transport) session, err := client.Connect(ctx, transport)
if err != nil { ... } if err != nil { ... }
// Call a tool on the server. // Call a tool on the server.
content, err := session.CallTool(ctx, "greet", map[string]any{"name": "you"}, nil}) content, err := session.CallTool(ctx, "greet", map[string]any{"name": "you"}, nil)
... ...
return session.Close() return session.Close()
``` ```
@ -446,7 +446,7 @@ A server that can handle that client call would look like this:
```go ```go
// Create a server with a single tool. // Create a server with a single tool.
server := mcp.NewServer("greeter", "v1.0.0", nil) server := mcp.NewServer("greeter", "v1.0.0", nil)
server.AddTool(mcp.NewTool("greet", "say hi", SayHi)) server.AddTools(mcp.NewTool("greet", "say hi", SayHi))
// Run the server over stdin/stdout, until the client disconnects. // Run the server over stdin/stdout, until the client disconnects.
transport := mcp.NewStdIOTransport() transport := mcp.NewStdIOTransport()
session, err := server.Connect(ctx, transport) session, err := server.Connect(ctx, transport)
@ -541,8 +541,8 @@ func (*ClientSession) ResourceTemplates(context.Context, *ListResourceTemplatesP
### Middleware ### Middleware
We provide a mechanism to add MCP-level middleware, which runs after the We provide a mechanism to add MCP-level middleware on the server side, which runs after the
request has been parsed, but before any normal handling. request has been parsed but before any normal handling.
```go ```go
// A Dispatcher dispatches an MCP message to the appropriate handler. // A Dispatcher dispatches an MCP message to the appropriate handler.
@ -551,14 +551,14 @@ request has been parsed, but before any normal handling.
type Dispatcher func(ctx context.Context, s *ServerSession, method string, params any) (result any, err error) type Dispatcher func(ctx context.Context, s *ServerSession, method string, params any) (result any, err error)
// AddDispatchers calls each function from right to left on the previous result, beginning // AddDispatchers calls each function from right to left on the previous result, beginning
// with the server's current dispatcher, and installs the result as the new handler. // with the server's current dispatcher, and installs the result as the new dispatcher.
func (*Server) AddDispatchers(middleware ...func(Handler) Handler)) func (*Server) AddDispatchers(middleware ...func(Dispatcher) Dispatcher))
``` ```
As an example, this code adds server-side logging: As an example, this code adds server-side logging:
```go ```go
func withLogging(h mcp.Handler) mcp.Handler { func withLogging(h mcp.Dispatcher) mcp.Dispatcher {
return func(ctx context.Context, s *mcp.ServerSession, method string, params any) (res any, err error) { return func(ctx context.Context, s *mcp.ServerSession, method string, params any) (res any, err error) {
log.Printf("request: %s %v", method, params) log.Printf("request: %s %v", method, params)
defer func() { log.Printf("response: %v, %v", res, err) }() defer func() { log.Printf("response: %v, %v", res, err) }()
@ -621,11 +621,9 @@ The server observes a client cancellation as a cancelled context.
A caller can request progress notifications by setting the `ProgressToken` field on any request. A caller can request progress notifications by setting the `ProgressToken` field on any request.
```go ```go
type ProgressToken any // string or int
type XXXParams struct { // where XXX is each type of call type XXXParams struct { // where XXX is each type of call
... ...
ProgressToken ProgressToken ProgressToken any // string or int
} }
``` ```
@ -681,7 +679,7 @@ Roots can be added and removed from a `Client` with `AddRoots` and `RemoveRoots`
// AddRoots adds the given roots to the client, // AddRoots adds the given roots to the client,
// replacing any with the same URIs, // replacing any with the same URIs,
// and notifies any connected servers. // and notifies any connected servers.
func (*Client) AddRoots(roots ...Root) func (*Client) AddRoots(roots ...*Root)
// RemoveRoots removes the roots with the given URIs. // RemoveRoots removes the roots with the given URIs.
// and notifies any connected servers if the list has changed. // and notifies any connected servers if the list has changed.
@ -689,7 +687,7 @@ func (*Client) AddRoots(roots ...Root)
func (*Client) RemoveRoots(uris ...string) func (*Client) RemoveRoots(uris ...string)
``` ```
Servers can call the spec method `ListRoots` to get the roots. If a server installs a Server sessions can call the spec method `ListRoots` to get the roots. If a server installs a
`RootsChangedHandler`, it will be called when the client sends a roots-changed `RootsChangedHandler`, it will be called when the client sends a roots-changed
notification, which happens whenever the list of roots changes after a notification, which happens whenever the list of roots changes after a
connection has been established. connection has been established.
@ -705,7 +703,7 @@ type ServerOptions {
### Sampling ### Sampling
Clients that support sampling are created with a `CreateMessageHandler` option Clients that support sampling are created with a `CreateMessageHandler` option
for handling server calls. To perform sampling, a server calls the spec method `CreateMessage`. for handling server calls. To perform sampling, a server session calls the spec method `CreateMessage`.
```go ```go
type ClientOptions struct { type ClientOptions struct {
@ -742,7 +740,7 @@ Add tools to a server with `AddTools`:
```go ```go
server.AddTools( server.AddTools(
mcp.NewTool("add", "add numbers", addHandler), mcp.NewTool("add", "add numbers", addHandler),
mcp.NewTools("subtract, subtract numbers", subHandler)) mcp.NewTool("subtract, subtract numbers", subHandler))
``` ```
Remove them by name with `RemoveTools`: Remove them by name with `RemoveTools`:
@ -836,7 +834,7 @@ Schemas are validated on the server before the tool handler is called.
Since all the fields of the Tool struct are exported, a Tool can also be created Since all the fields of the Tool struct are exported, a Tool can also be created
directly with assignment or a struct literal. directly with assignment or a struct literal.
Clients can call the spec method `ListTools` or an iterator method `Tools` Client sessions can call the spec method `ListTools` or an iterator method `Tools`
to list the available tools. to list the available tools.
**Differences from mcp-go**: using variadic options to configure tools was **Differences from mcp-go**: using variadic options to configure tools was
@ -862,7 +860,7 @@ each occur only once (and in an SDK that wraps mcp-go).
For registering tools, we provide only `AddTools`; mcp-go's `SetTools`, For registering tools, we provide only `AddTools`; mcp-go's `SetTools`,
`AddTool`, `AddSessionTool`, and `AddSessionTools` are deemed unnecessary. `AddTool`, `AddSessionTool`, and `AddSessionTools` are deemed unnecessary.
(similarly for Delete/Remove). (Similarly for Delete/Remove).
### Prompts ### Prompts
@ -893,8 +891,8 @@ server.AddPrompts(
server.RemovePrompts("code_review") server.RemovePrompts("code_review")
``` ```
Clients can call the spec method `ListPrompts` or an iterator method `Prompts` Client sessions can call the spec method `ListPrompts` or the iterator method `Prompts`
to list the available prompts and the spec method `GetPrompt` to get one. to list the available prompts, and the spec method `GetPrompt` to get one.
**Differences from mcp-go**: We provide a `NewPrompt` helper to bind a prompt **Differences from mcp-go**: We provide a `NewPrompt` helper to bind a prompt
handler to a Go function using reflection to derive its arguments. We provide handler to a Go function using reflection to derive its arguments. We provide
@ -926,7 +924,8 @@ type ServerResourceTemplate struct {
``` ```
To add a resource or resource template to a server, users call the `AddResources` and To add a resource or resource template to a server, users call the `AddResources` and
`AddResourceTemplates` methods with one or more `ServerResource`s or `ServerResourceTemplate`s: `AddResourceTemplates` methods with one or more `ServerResource`s or `ServerResourceTemplate`s.
We also provide methods to remove them.
```go ```go
func (*Server) AddResources(...*ServerResource) func (*Server) AddResources(...*ServerResource)
@ -938,14 +937,12 @@ func (s *Server) RemoveResourceTemplates(uriTemplates ...string)
The `ReadResource` method finds a resource or resource template matching the argument URI and calls The `ReadResource` method finds a resource or resource template matching the argument URI and calls
its assocated handler. its assocated handler.
If the argument URI matches a template, the `Resource` argument to the handler is constructed
from the fields in the `ResourceTemplate`.
To read files from the local filesystem, we recommend using `FileResourceHandler` to construct a handler: To read files from the local filesystem, we recommend using `FileResourceHandler` to construct a handler:
```go ```go
// FileResourceHandler returns a ResourceHandler that reads paths using dir as a root directory. // FileResourceHandler returns a ResourceHandler that reads paths using dir as a root directory.
// It protects against path traversal attacks. // It protects against path traversal attacks.
// It will not read any file that is not in the root set of the client requesting the resource. // It will not read any file that is not in the root set of the client session requesting the resource.
func (*Server) FileResourceHandler(dir string) ResourceHandler func (*Server) FileResourceHandler(dir string) ResourceHandler
``` ```
Here is an example: Here is an example:
@ -957,17 +954,8 @@ s.AddResources(&mcp.ServerResource{
Handler: s.FileReadResourceHandler("/public")}) Handler: s.FileReadResourceHandler("/public")})
``` ```
Servers support all of the resource-related spec methods: Server sessions also support the spec methods `ListResources` and `ListResourceTemplates`,
and the corresponding iterator methods `Resources` and `ResourceTemplates`.
- `ListResources` and `ListResourceTemplates` for listings.
- `ReadResource` to get the contents of a resource.
- `Subscribe` and `Unsubscribe` to manage subscriptions on resources.
We also provide iterator methods `Resources` and `ResourceTemplates`.
`ReadResource` checks the incoming URI against the server's list of
resources and resource templates to make sure it matches one of them,
then returns the result of calling the associated reader function.
#### Subscriptions #### Subscriptions
@ -1017,6 +1005,7 @@ type ClientOptions struct {
... ...
ToolListChangedHandler func(context.Context, *ClientSession, *ToolListChangedParams) ToolListChangedHandler func(context.Context, *ClientSession, *ToolListChangedParams)
PromptListChangedHandler func(context.Context, *ClientSession, *PromptListChangedParams) PromptListChangedHandler func(context.Context, *ClientSession, *PromptListChangedParams)
// For both resources and resource templates.
ResourceListChangedHandler func(context.Context, *ClientSession, *ResourceListChangedParams) ResourceListChangedHandler func(context.Context, *ClientSession, *ResourceListChangedParams)
} }
``` ```
@ -1049,8 +1038,8 @@ type ServerOptions {
} }
``` ```
ServerSessions have access to a `slog.Logger` that writes to the client. A call to Server sessions have a field `Logger` holding a `slog.Logger` that writes to the client session.
a log method like `Info` is translated to a `LoggingMessageNotification` as A call to a log method like `Info` is translated to a `LoggingMessageNotification` as
follows: follows:
- The attributes and the message populate the "data" property with the - The attributes and the message populate the "data" property with the
@ -1060,11 +1049,11 @@ follows:
- If the `LoggerName` server option is set, it populates the "logger" property. - If the `LoggerName` server option is set, it populates the "logger" property.
- The standard slog levels `Info`, `Debug`, `Warn` and `Error` map to the - The standard slog levels `Info`, `Debug`, `Warn` and `Error` map to the
corresponding levels in the MCP spec. The other spec levels will be mapped corresponding levels in the MCP spec. The other spec levels map
to integers between the slog levels. For example, "notice" is level 2 because to integers between the slog levels. For example, "notice" is level 2 because
it is between "warning" (slog value 4) and "info" (slog value 0). it is between "warning" (slog value 4) and "info" (slog value 0).
The `mcp` package defines consts for these levels. To log at the "notice" The `mcp` package defines consts for these levels. To log at the "notice"
level, a handler would call `session.Log(ctx, mcp.LevelNotice, "message")`. level, a handler would call `session.Logger.Log(ctx, mcp.LevelNotice, "message")`.
A client that wishes to receive log messages must provide a handler: A client that wishes to receive log messages must provide a handler:
@ -1080,7 +1069,7 @@ type ClientOptions struct {
Servers initiate pagination for `ListTools`, `ListPrompts`, `ListResources`, Servers initiate pagination for `ListTools`, `ListPrompts`, `ListResources`,
and `ListResourceTemplates`, dictating the page size and providing a and `ListResourceTemplates`, dictating the page size and providing a
`NextCursor` field in the Result if more pages exist. The SDK implements keyset `NextCursor` field in the Result if more pages exist. The SDK implements keyset
pagination, using the `unique ID` as the key for a stable sort order and encoding pagination, using the unique ID of the feature as the key for a stable sort order and encoding
the cursor as an opaque string. the cursor as an opaque string.
For server implementations, the page size for the list operation may be For server implementations, the page size for the list operation may be