mcp: introduce Requests (#267)

Handlers and client/server methods take a single request argument
combining the session and params. This slightly simplifies the signature
for handlers, since there is no longer an often-ignored session
argument.

But more importantly, it opens the door to adding more information in
requests, such as auth info and HTTP request headers.

For #243.

Author: jba

README.md

@@ -115,9 +115,9 @@ type HiParams struct {
 	Name string `json:"name" jsonschema:"the name of the person to greet"`
 }
 
-func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[HiParams]) (*mcp.CallToolResultFor[any], error) {
+func SayHi(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[HiParams]]) (*mcp.CallToolResultFor[any], error) {
 	return &mcp.CallToolResultFor[any]{
-		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + params.Arguments.Name}},
+		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + req.Params.Arguments.Name}},
 	}, nil
 }
 

design/design.md

@@ -408,33 +408,30 @@ We provide a mechanism to add MCP-level middleware on the both the client and se
 
 ```go
 // A MethodHandler handles MCP messages.
-// The params argument is an XXXParams struct pointer, such as *GetPromptParams.
-// For methods, a MethodHandler must return either an XXResult struct pointer and a nil error, or
-// nil with a non-nil error.
-// For notifications, a MethodHandler must return nil, nil.
-type MethodHandler[S Session] func(
-	ctx context.Context, _ *S, method string, params Params) (result Result, err error)
+// For methods, exactly one of the return values must be nil.
+// For notifications, both must be nil.
+type MethodHandler func(ctx context.Context, method string, req Request) (result Result, err error)
 
 // Middleware is a function from MethodHandlers to MethodHandlers.
-type Middleware[S Session] func(MethodHandler[S]) MethodHandler[S]
+type Middleware func(MethodHandler) MethodHandler
 
 // AddMiddleware wraps the client/server's current method handler using the provided
 // middleware. Middleware is applied from right to left, so that the first one
 // is executed first.
 //
 // For example, AddMiddleware(m1, m2, m3) augments the server method handler as
 // m1(m2(m3(handler))).
-func (c *Client) AddSendingMiddleware(middleware ...Middleware[*ClientSession])
-func (c *Client) AddReceivingMiddleware(middleware ...Middleware[*ClientSession])
-func (s *Server) AddSendingMiddleware(middleware ...Middleware[*ServerSession])
-func (s *Server) AddReceivingMiddleware(middleware ...Middleware[*ServerSession])
+func (c *Client) AddSendingMiddleware(middleware ...Middleware)
+func (c *Client) AddReceivingMiddleware(middleware ...Middleware)
+func (s *Server) AddSendingMiddleware(middleware ...Middleware)
+func (s *Server) AddReceivingMiddleware(middleware ...Middleware)
 ```
 
 As an example, this code adds server-side logging:
 
 ```go
-func withLogging(h mcp.MethodHandler[*mcp.ServerSession]) mcp.MethodHandler[*mcp.ServerSession]{
-    return func(ctx context.Context, s *mcp.ServerSession, method string, params mcp.Params) (res mcp.Result, err error) {
+func withLogging(h mcp.MethodHandler) mcp.MethodHandler{
+    return func(ctx context.Context, method string, req mcp.Request) (res mcp.Result, err error) {
         log.Printf("request: %s %v", method, params)
         defer func() { log.Printf("response: %v, %v", res, err) }()
         return h(ctx, s , method, params)
@@ -597,8 +594,9 @@ type Tool struct {
 	Name string                    `json:"name"`
 }
 
-type ToolHandlerFor[In, Out any] func(context.Context, *ServerSession, *CallToolParamsFor[In]) (*CallToolResultFor[Out], error)
-type ToolHandler = ToolHandlerFor[map[string]any, any]
+// A ToolHandlerFor handles a call to tools/call with typed arguments and results.
+type ToolHandlerFor[In, Out any] func(context.Context, *ServerRequest[*CallToolParamsFor[In]]) (*CallToolResultFor[Out], error)
+
 ```
 
 Add tools to a server with the `AddTool` method or function. The function is generic and infers schemas from the handler
@@ -648,8 +646,8 @@ type AddParams struct {
     Y int `json:"y"`
 }
 
-func addHandler(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[AddParams]) (*mcp.CallToolResultFor[int], error) {
-    return &mcp.CallToolResultFor[int]{StructuredContent: params.Arguments.X + params.Arguments.Y}, nil
+func addHandler(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[AddParams]]) (*mcp.CallToolResultFor[int], error) {
+    return &mcp.CallToolResultFor[int]{StructuredContent: req.Params.Arguments.X + req.Params.Arguments.Y}, nil
 }
 ```
 
@@ -665,8 +663,6 @@ Client sessions can call the spec method `ListTools` or an iterator method `Tool
 
 ```go
 func (cs *ClientSession) CallTool(context.Context, *CallToolParams[json.RawMessage]) (*CallToolResult, error)
-
-func CallTool[TArgs any](context.Context, *ClientSession, *CallToolParams[TArgs]) (*CallToolResult, error)
 ```
 
 **Differences from mcp-go**: We provide a full JSON Schema implementation for validating tool input schemas against incoming arguments. The `jsonschema.Schema` type provides exported features for all keywords in the JSON Schema draft2020-12 spec. Tool definers can use it to construct any schema they want. The `jsonschema.For[T]` function can infer a schema from a Go struct. These combined features eliminate the need for variadic arguments to construct tool schemas.
@@ -752,10 +748,10 @@ If a server author wants to support resource subscriptions, they must provide ha
 ```go
 type ServerOptions struct {
   ...
-  // Function called when a client session subscribes to a resource.
-  SubscribeHandler func(context.Context, ss *ServerSession, *SubscribeParams) error
-  // Function called when a client session unsubscribes from a resource.
-  UnsubscribeHandler func(context.Context, ss *ServerSession, *UnsubscribeParams) error
+	// Function called when a client session subscribes to a resource.
+	SubscribeHandler func(context.Context, *ServerRequest[*SubscribeParams]) error
+	// Function called when a client session unsubscribes from a resource.
+	UnsubscribeHandler func(context.Context, *ServerRequest[*UnsubscribeParams]) error
 }
 ```
 
@@ -774,10 +770,10 @@ When a list of tools, prompts or resources changes as the result of an AddXXX or
 ```go
 type ClientOptions struct {
   ...
-  ToolListChangedHandler func(context.Context, *ClientSession, *ToolListChangedParams)
-  PromptListChangedHandler func(context.Context, *ClientSession, *PromptListChangedParams)
+	ToolListChangedHandler      func(context.Context, *ClientRequest[*ToolListChangedParams])
+	PromptListChangedHandler    func(context.Context, *ClientRequest[*PromptListChangedParams])
   // For both resources and resource templates.
-  ResourceListChangedHandler func(context.Context, *ClientSession, *ResourceListChangedParams)
+	ResourceListChangedHandler  func(context.Context, *ClientRequest[*ResourceListChangedParams])
 }
 ```
 
@@ -788,13 +784,10 @@ type ClientOptions struct {
 Clients call the spec method `Complete` to request completions. If a server installs a `CompletionHandler`, it will be called when the client sends a completion request.
 
 ```go
-// A CompletionHandler handles a call to completion/complete.
-type CompletionHandler func(context.Context, *ServerSession, *CompleteParams) (*CompleteResult, error)
-
 type ServerOptions struct {
   ...
   // If non-nil, called when a client sends a completion request.
-  CompletionHandler CompletionHandler
+	CompletionHandler func(context.Context, *ServerRequest[*CompleteParams]) (*CompleteResult, error)
 }
 ```
 

examples/server/completion/main.go

@@ -16,17 +16,17 @@ import (
 // a CompletionHandler to an MCP Server's options.
 func main() {
 	// Define your custom CompletionHandler logic.
-	myCompletionHandler := func(_ context.Context, _ *mcp.ServerSession, params *mcp.CompleteParams) (*mcp.CompleteResult, error) {
+	myCompletionHandler := func(_ context.Context, req *mcp.ServerRequest[*mcp.CompleteParams]) (*mcp.CompleteResult, error) {
 		// In a real application, you'd implement actual completion logic here.
 		// For this example, we return a fixed set of suggestions.
 		var suggestions []string
-		switch params.Ref.Type {
+		switch req.Params.Ref.Type {
 		case "ref/prompt":
 			suggestions = []string{"suggestion1", "suggestion2", "suggestion3"}
 		case "ref/resource":
 			suggestions = []string{"suggestion4", "suggestion5", "suggestion6"}
 		default:
-			return nil, fmt.Errorf("unrecognized content type %s", params.Ref.Type)
+			return nil, fmt.Errorf("unrecognized content type %s", req.Params.Ref.Type)
 		}
 
 		return &mcp.CompleteResult{

examples/server/custom-transport/main.go

@@ -85,10 +85,10 @@ type HiArgs struct {
 }
 
 // SayHi is a tool handler that responds with a greeting.
-func SayHi(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[HiArgs]) (*mcp.CallToolResultFor[struct{}], error) {
+func SayHi(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[HiArgs]]) (*mcp.CallToolResultFor[struct{}], error) {
 	return &mcp.CallToolResultFor[struct{}]{
 		Content: []mcp.Content{
-			&mcp.TextContent{Text: "Hi " + params.Arguments.Name},
+			&mcp.TextContent{Text: "Hi " + req.Params.Arguments.Name},
 		},
 	}, nil
 }

examples/server/hello/main.go

@@ -22,10 +22,10 @@ type HiArgs struct {
 	Name string `json:"name" jsonschema:"the name to say hi to"`
 }
 
-func SayHi(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[HiArgs]) (*mcp.CallToolResultFor[struct{}], error) {
+func SayHi(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[HiArgs]]) (*mcp.CallToolResultFor[struct{}], error) {
 	return &mcp.CallToolResultFor[struct{}]{
 		Content: []mcp.Content{
-			&mcp.TextContent{Text: "Hi " + params.Arguments.Name},
+			&mcp.TextContent{Text: "Hi " + req.Params.Arguments.Name},
 		},
 	}, nil
 }
@@ -69,8 +69,8 @@ var embeddedResources = map[string]string{
 	"info": "This is the hello example server.",
 }
 
-func handleEmbeddedResource(_ context.Context, _ *mcp.ServerSession, params *mcp.ReadResourceParams) (*mcp.ReadResourceResult, error) {
-	u, err := url.Parse(params.URI)
+func handleEmbeddedResource(_ context.Context, req *mcp.ServerRequest[*mcp.ReadResourceParams]) (*mcp.ReadResourceResult, error) {
+	u, err := url.Parse(req.Params.URI)
 	if err != nil {
 		return nil, err
 	}
@@ -84,7 +84,7 @@ func handleEmbeddedResource(_ context.Context, _ *mcp.ServerSession, params *mcp
 	}
 	return &mcp.ReadResourceResult{
 		Contents: []*mcp.ResourceContents{
-			{URI: params.URI, MIMEType: "text/plain", Text: text},
+			{URI: req.Params.URI, MIMEType: "text/plain", Text: text},
 		},
 	}, nil
 }

examples/server/memory/kb.go

@@ -84,7 +84,7 @@ func (fs *fileStore) Read() ([]byte, error) {
 
 // Write saves data to file with 0600 permissions.
 func (fs *fileStore) Write(data []byte) error {
-	if err := os.WriteFile(fs.path, data, 0600); err != nil {
+	if err := os.WriteFile(fs.path, data, 0o600); err != nil {
 		return fmt.Errorf("failed to write file %s: %w", fs.path, err)
 	}
 	return nil
@@ -431,10 +431,10 @@ func (k knowledgeBase) openNodes(names []string) (KnowledgeGraph, error) {
 	}, nil
 }
 
-func (k knowledgeBase) CreateEntities(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[CreateEntitiesArgs]) (*mcp.CallToolResultFor[CreateEntitiesResult], error) {
+func (k knowledgeBase) CreateEntities(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[CreateEntitiesArgs]]) (*mcp.CallToolResultFor[CreateEntitiesResult], error) {
 	var res mcp.CallToolResultFor[CreateEntitiesResult]
 
-	entities, err := k.createEntities(params.Arguments.Entities)
+	entities, err := k.createEntities(req.Params.Arguments.Entities)
 	if err != nil {
 		return nil, err
 	}
@@ -450,10 +450,10 @@ func (k knowledgeBase) CreateEntities(ctx context.Context, ss *mcp.ServerSession
 	return &res, nil
 }
 
-func (k knowledgeBase) CreateRelations(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[CreateRelationsArgs]) (*mcp.CallToolResultFor[CreateRelationsResult], error) {
+func (k knowledgeBase) CreateRelations(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[CreateRelationsArgs]]) (*mcp.CallToolResultFor[CreateRelationsResult], error) {
 	var res mcp.CallToolResultFor[CreateRelationsResult]
 
-	relations, err := k.createRelations(params.Arguments.Relations)
+	relations, err := k.createRelations(req.Params.Arguments.Relations)
 	if err != nil {
 		return nil, err
 	}
@@ -469,10 +469,10 @@ func (k knowledgeBase) CreateRelations(ctx context.Context, ss *mcp.ServerSessio
 	return &res, nil
 }
 
-func (k knowledgeBase) AddObservations(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[AddObservationsArgs]) (*mcp.CallToolResultFor[AddObservationsResult], error) {
+func (k knowledgeBase) AddObservations(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[AddObservationsArgs]]) (*mcp.CallToolResultFor[AddObservationsResult], error) {
 	var res mcp.CallToolResultFor[AddObservationsResult]
 
-	observations, err := k.addObservations(params.Arguments.Observations)
+	observations, err := k.addObservations(req.Params.Arguments.Observations)
 	if err != nil {
 		return nil, err
 	}
@@ -488,10 +488,10 @@ func (k knowledgeBase) AddObservations(ctx context.Context, ss *mcp.ServerSessio
 	return &res, nil
 }
 
-func (k knowledgeBase) DeleteEntities(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[DeleteEntitiesArgs]) (*mcp.CallToolResultFor[struct{}], error) {
+func (k knowledgeBase) DeleteEntities(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[DeleteEntitiesArgs]]) (*mcp.CallToolResultFor[struct{}], error) {
 	var res mcp.CallToolResultFor[struct{}]
 
-	err := k.deleteEntities(params.Arguments.EntityNames)
+	err := k.deleteEntities(req.Params.Arguments.EntityNames)
 	if err != nil {
 		return nil, err
 	}
@@ -503,10 +503,10 @@ func (k knowledgeBase) DeleteEntities(ctx context.Context, ss *mcp.ServerSession
 	return &res, nil
 }
 
-func (k knowledgeBase) DeleteObservations(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[DeleteObservationsArgs]) (*mcp.CallToolResultFor[struct{}], error) {
+func (k knowledgeBase) DeleteObservations(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[DeleteObservationsArgs]]) (*mcp.CallToolResultFor[struct{}], error) {
 	var res mcp.CallToolResultFor[struct{}]
 
-	err := k.deleteObservations(params.Arguments.Deletions)
+	err := k.deleteObservations(req.Params.Arguments.Deletions)
 	if err != nil {
 		return nil, err
 	}
@@ -518,10 +518,10 @@ func (k knowledgeBase) DeleteObservations(ctx context.Context, ss *mcp.ServerSes
 	return &res, nil
 }
 
-func (k knowledgeBase) DeleteRelations(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[DeleteRelationsArgs]) (*mcp.CallToolResultFor[struct{}], error) {
+func (k knowledgeBase) DeleteRelations(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[DeleteRelationsArgs]]) (*mcp.CallToolResultFor[struct{}], error) {
 	var res mcp.CallToolResultFor[struct{}]
 
-	err := k.deleteRelations(params.Arguments.Relations)
+	err := k.deleteRelations(req.Params.Arguments.Relations)
 	if err != nil {
 		return nil, err
 	}
@@ -533,7 +533,7 @@ func (k knowledgeBase) DeleteRelations(ctx context.Context, ss *mcp.ServerSessio
 	return &res, nil
 }
 
-func (k knowledgeBase) ReadGraph(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[struct{}]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
+func (k knowledgeBase) ReadGraph(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[struct{}]]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
 	var res mcp.CallToolResultFor[KnowledgeGraph]
 
 	graph, err := k.loadGraph()
@@ -549,10 +549,10 @@ func (k knowledgeBase) ReadGraph(ctx context.Context, ss *mcp.ServerSession, par
 	return &res, nil
 }
 
-func (k knowledgeBase) SearchNodes(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[SearchNodesArgs]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
+func (k knowledgeBase) SearchNodes(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[SearchNodesArgs]]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
 	var res mcp.CallToolResultFor[KnowledgeGraph]
 
-	graph, err := k.searchNodes(params.Arguments.Query)
+	graph, err := k.searchNodes(req.Params.Arguments.Query)
 	if err != nil {
 		return nil, err
 	}
@@ -565,10 +565,10 @@ func (k knowledgeBase) SearchNodes(ctx context.Context, ss *mcp.ServerSession, p
 	return &res, nil
 }
 
-func (k knowledgeBase) OpenNodes(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[OpenNodesArgs]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
+func (k knowledgeBase) OpenNodes(ctx context.Context, req *mcp.ServerRequest[*mcp.CallToolParamsFor[OpenNodesArgs]]) (*mcp.CallToolResultFor[KnowledgeGraph], error) {
 	var res mcp.CallToolResultFor[KnowledgeGraph]
 
-	graph, err := k.openNodes(params.Arguments.Names)
+	graph, err := k.openNodes(req.Params.Arguments.Names)
 	if err != nil {
 		return nil, err
 	}