start weaving examples

Author: findleyr

docs/README.md

@@ -10,8 +10,9 @@ https://modelcontextprotocol.io/specification/2025-06-18
 
 1. [Lifecycle (Clients, Servers, and Sessions)](protocol.md#lifecycle).
 1. [Transports](protocol.md#transports)
+    1. [Stdio transport](protocol.md#stdio-transport)
     1. [Streamable transport](protocol.md#streamable-transport)
-    1. [Stateless mode](protocol.md#stateless-mode)
+    1. [Custom transports](protocol.md#stateless-mode)
 1. [Authorization](protocol.md#authorization)
 1. [Security](protocol.md#security)
 1. [Utilities](protocol.md#utilities)

docs/protocol.md

@@ -9,13 +9,86 @@
 
 ## Lifecycle
 
-
-
 ## Transports
 
+Transports should not be reused for multiple connections: if you need to create
+multiple connections, use different transports.
+
 ### Streamable Transport
 
-### Stateless Mode
+### Streamable Transport API
+
+The streamable transport API is implemented across three types:
+
+- `StreamableHTTPHandler`: an`http.Handler` that serves streamable MCP
+  sessions.
+- `StreamableServerTransport`: a `Transport` that implements the server side of
+  the streamable transport.
+- `StreamableClientTransport`: a `Transport` that implements the client side of
+  the streamable transport.
+
+To create a streamable MCP server, you create a `StreamableHTTPHandler` and
+pass it an `mcp.Server`:
+
+```go
+func ExampleStreamableHTTPHandler() {
+	// Create a new stramable handler, using the same MCP server for every request.
+	//
+	// Here, we configure it to serves application/json responses rather than
+	// text/event-stream, just so the output below doesn't use random event ids.
+	server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.1.0"}, nil)
+	handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
+		return server
+	}, &mcp.StreamableHTTPOptions{JSONResponse: true})
+	httpServer := httptest.NewServer(handler)
+	defer httpServer.Close()
+
+	// The SDK is currently permissive of some missing keys in "params".
+	resp := mustPostMessage(`{"jsonrpc": "2.0", "id": 1, "method":"initialize", "params": {}}`, httpServer.URL)
+	fmt.Println(resp)
+	// Output: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{}},"protocolVersion":"2025-06-18","serverInfo":{"name":"server","version":"v0.1.0"}}}
+}
+```
+
+The `StreamableHTTPHandler` handles the HTTP requests and creates a new
+`StreamableServerTransport` for each new session. The transport is then used to
+communicate with the client.
+
+On the client side, you create a `StreamableClientTransport` and use it to
+connect to the server:
+
+```go
+transport := &mcp.StreamableClientTransport{
+	Endpoint: "http://localhost:8080/mcp",
+}
+client, err := mcp.Connect(context.Background(), transport, &mcp.ClientOptions{...})
+```
+
+The `StreamableClientTransport` handles the HTTP requests and communicates with
+the server using the streamable transport protocol.
+
+#### Stateless Mode
+
+#### Sessionless mode
+
+### Custom transports
+
+### Concurrency
+
+In general, MCP offers no guarantees about concurrency semantics: if a client
+or server sends a notification, the spec says nothing about when the peer
+observes that notification relative to other request. However, the Go SDK
+implements the following heuristics:
+
+- If a notifying method (such as progress notification or
+  `notifications/initialized`) returns, then it is guaranteed that the peer
+  observes that notification before other notifications or calls.
+- Calls (such as `tools/call`) are handled asynchronously with respect to
+  eachother.
+
+See
+[modelcontextprotocol/go-sdk#26](https://github.com/modelcontextprotocol/go-sdk/issues/26)
+for more background.
 
 ## Authorization
 
@@ -29,28 +102,15 @@ Cancellation is implemented with context cancellation. Cancelling a context
 used in a method on `ClientSession` or `ServerSession` will terminate the RPC
 and send a "notifications/cancelled" message to the peer.
 
-For example, consider the following slow tool
-
-	// go get golang.org/x/example/docs/../../mcp
-
 ```go
-var (
-	start     = make(chan struct{})
-	cancelled = make(chan struct{}, 1) // don't block the request
-)
-slowTool := func(ctx context.Context, req *CallToolRequest, args any) (*CallToolResult, any, error) {
-	start <- struct{}{}
-	select {
-	case <-ctx.Done():
-		cancelled <- struct{}{}
-	case <-time.After(5 * time.Second):
-		return nil, nil, nil
-	}
-	return nil, nil, nil
-}
+ctx, cancel := context.WithCancel(context.Background())
+go cs.CallTool(ctx, &CallToolParams{Name: "slow"})
+cancel() // cancel the tool call
 ```
 
-When an RPC exits due to a cancellation error, there's a guarantee
+When an RPC exits due to a cancellation error, there's a guarantee that the
+cancellation notification has been sent, but there's no guarantee that the
+server has observed it (see [concurrency](#concurrency)).
 
 ### Ping
 

internal/docs/doc.go

@@ -12,4 +12,4 @@
 // The doc package generates the documentation at /doc, via go:generate.
 //
 // Tests in this package are used for examples.
-package doc
+package docs

internal/docs/protocol.src.md

@@ -11,6 +11,39 @@ multiple connections, use different transports.
 
 ### Streamable Transport
 
+### Streamable Transport API
+
+The streamable transport API is implemented across three types:
+
+- `StreamableHTTPHandler`: an`http.Handler` that serves streamable MCP
+  sessions.
+- `StreamableServerTransport`: a `Transport` that implements the server side of
+  the streamable transport.
+- `StreamableClientTransport`: a `Transport` that implements the client side of
+  the streamable transport.
+
+To create a streamable MCP server, you create a `StreamableHTTPHandler` and
+pass it an `mcp.Server`:
+
+%include ../../mcp/streamable_example_test.go streamablehandler -
+
+The `StreamableHTTPHandler` handles the HTTP requests and creates a new
+`StreamableServerTransport` for each new session. The transport is then used to
+communicate with the client.
+
+On the client side, you create a `StreamableClientTransport` and use it to
+connect to the server:
+
+```go
+transport := &mcp.StreamableClientTransport{
+	Endpoint: "http://localhost:8080/mcp",
+}
+client, err := mcp.Connect(context.Background(), transport, &mcp.ClientOptions{...})
+```
+
+The `StreamableClientTransport` handles the HTTP requests and communicates with
+the server using the streamable transport protocol.
+
 #### Stateless Mode
 
 #### Sessionless mode

internal/readme/client/client.go

@@ -44,4 +44,4 @@ func main() {
 	}
 }
 
-//!-
+// !-

mcp/streamable.go

@@ -70,9 +70,12 @@ type StreamableHTTPOptions struct {
 	// documentation for [StreamableServerTransport].
 	Stateless bool
 
-	// TODO: support session retention (?)
+	// TODO(#148): support session retention (?)
 
-	// JSONResponse is forwarded to StreamableServerTransport.jsonResponse.
+	// JSONResponse causes streamable responses to return application/json rather
+	// than text/event-stream ([§2.1.5] of the spec).
+	//
+	// [§2.1.5]: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#sending-messages-to-the-server
 	JSONResponse bool
 }
 
@@ -181,7 +184,7 @@ func (h *StreamableHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Reque
 		return
 	}
 
-	// Section 2.7 of the spec (2025-06-18) states:
+	// [§2.7] of the spec (2025-06-18) states:
 	//
 	// "If using HTTP, the client MUST include the MCP-Protocol-Version:
 	// <protocol-version> HTTP header on all subsequent requests to the MCP
@@ -209,6 +212,8 @@ func (h *StreamableHTTPHandler) ServeHTTP(w http.ResponseWriter, req *http.Reque
 	//     assume 2025-03-26 if the client doesn't say anything).
 	//
 	// This logic matches the typescript SDK.
+	//
+	// [§2.7]: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#protocol-version-header
 	protocolVersion := req.Header.Get(protocolVersionHeader)
 	if protocolVersion == "" {
 		protocolVersion = protocolVersion20250326
@@ -370,6 +375,9 @@ type StreamableServerTransport struct {
 	// request contain only a single message. In this case, notifications or
 	// requests made within the context of a server request will be sent to the
 	// hanging GET request, if any.
+	//
+	// TODO(rfindley): jsonResponse should be exported, since
+	// StreamableHTTPOptions.JSONResponse is exported.
 	jsonResponse bool
 
 	// connection is non-nil if and only if the transport has been connected.
@@ -1188,7 +1196,7 @@ func (c *streamableClientConn) Write(ctx context.Context, msg jsonrpc.Message) e
 		return fmt.Errorf("%s: %v", requestSummary, err)
 	}
 
-	// Section 2.5.3: "The server MAY terminate the session at any time, after
+	// §2.5.3: "The server MAY terminate the session at any time, after
 	// which it MUST respond to requests containing that session ID with HTTP
 	// 404 Not Found."
 	if resp.StatusCode == http.StatusNotFound {

mcp/streamable_example_test.go

@@ -0,0 +1,54 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package mcp_test
+
+import (
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// !+streamablehandler
+func ExampleStreamableHTTPHandler() {
+	// Create a new stramable handler, using the same MCP server for every request.
+	//
+	// Here, we configure it to serves application/json responses rather than
+	// text/event-stream, just so the output below doesn't use random event ids.
+	server := mcp.NewServer(&mcp.Implementation{Name: "server", Version: "v0.1.0"}, nil)
+	handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
+		return server
+	}, &mcp.StreamableHTTPOptions{JSONResponse: true})
+	httpServer := httptest.NewServer(handler)
+	defer httpServer.Close()
+
+	// The SDK is currently permissive of some missing keys in "params".
+	resp := mustPostMessage(`{"jsonrpc": "2.0", "id": 1, "method":"initialize", "params": {}}`, httpServer.URL)
+	fmt.Println(resp)
+	// Output: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{}},"protocolVersion":"2025-06-18","serverInfo":{"name":"server","version":"v0.1.0"}}}
+}
+
+// !-streamablehandler
+
+func mustPostMessage(msg, url string) string {
+	req := orFatal(http.NewRequest("POST", url, strings.NewReader(msg)))
+	req.Header["Content-Type"] = []string{"application/json"}
+	req.Header["Accept"] = []string{"application/json", "text/event-stream"}
+	resp := orFatal(http.DefaultClient.Do(req))
+	defer resp.Body.Close()
+	body := orFatal(io.ReadAll(resp.Body))
+	return string(body)
+}
+
+func orFatal[T any](t T, err error) T {
+	if err != nil {
+		log.Fatal(err)
+	}
+	return t
+}