Merge branch 'main' into implem

Author: jba

examples/rate-limiting/go.mod

@@ -5,6 +5,6 @@ go 1.23.0
 toolchain go1.24.4
 
 require (
-	github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89
+	github.com/modelcontextprotocol/go-sdk v0.1.0
 	golang.org/x/time v0.12.0
 )

examples/rate-limiting/go.sum

@@ -1,7 +1,7 @@
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89 h1:kUGBYP25FTv3ZRBhLT4iQvtx4FDl7hPkWe3isYrMxyo=
-github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89/go.mod h1:DcXfbr7yl7e35oMpzHfKw2nUYRjhIGS2uou/6tdsTB0=
+github.com/modelcontextprotocol/go-sdk v0.1.0 h1:ItzbFWYNt4EHcUrScX7P8JPASn1FVYb29G773Xkl+IU=
+github.com/modelcontextprotocol/go-sdk v0.1.0/go.mod h1:DcXfbr7yl7e35oMpzHfKw2nUYRjhIGS2uou/6tdsTB0=
 golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
 golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
 golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=

examples/rate-limiting/main.go

@@ -7,6 +7,8 @@ package main
 import (
 	"context"
 	"errors"
+	"log"
+	"sync"
 	"time"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -43,12 +45,52 @@ func PerMethodRateLimiterMiddleware[S mcp.Session](limiters map[string]*rate.Lim
 	}
 }
 
+// PerSessionRateLimiterMiddleware creates a middleware that applies rate limiting
+// on a per-session basis for receiving requests.
+func PerSessionRateLimiterMiddleware[S mcp.Session](limit rate.Limit, burst int) mcp.Middleware[S] {
+	// A map to store limiters, keyed by the session ID.
+	var (
+		sessionLimiters = make(map[string]*rate.Limiter)
+		mu              sync.Mutex
+	)
+
+	return func(next mcp.MethodHandler[S]) mcp.MethodHandler[S] {
+		return func(ctx context.Context, session S, method string, params mcp.Params) (mcp.Result, error) {
+			// It's possible that session.ID() may be empty at this point in time
+			// for some transports (e.g., stdio) or until the MCP initialize handshake
+			// has completed.
+			sessionID := session.ID()
+			if sessionID == "" {
+				// In this situation, you could apply a single global identifier
+				// if session ID is empty or bypass the rate limiter.
+				// In this example, we bypass the rate limiter.
+				log.Printf("Warning: Session ID is empty for method %q. Skipping per-session rate limiting.", method)
+				return next(ctx, session, method, params) // Skip limiting if ID is unavailable
+			}
+			mu.Lock()
+			limiter, ok := sessionLimiters[sessionID]
+			if !ok {
+				limiter = rate.NewLimiter(limit, burst)
+				sessionLimiters[sessionID] = limiter
+			}
+			mu.Unlock()
+			if !limiter.Allow() {
+				return nil, errors.New("JSON RPC overloaded")
+			}
+			return next(ctx, session, method, params)
+		}
+	}
+}
+
 func main() {
 	server := mcp.NewServer("greeter1", "v0.0.1", nil)
 	server.AddReceivingMiddleware(GlobalRateLimiterMiddleware[*mcp.ServerSession](rate.NewLimiter(rate.Every(time.Second/5), 10)))
 	server.AddReceivingMiddleware(PerMethodRateLimiterMiddleware[*mcp.ServerSession](map[string]*rate.Limiter{
 		"callTool":  rate.NewLimiter(rate.Every(time.Second), 5),  // once a second with a burst up to 5
 		"listTools": rate.NewLimiter(rate.Every(time.Minute), 20), // once a minute with a burst up to 20
 	}))
+	server.AddReceivingMiddleware(PerSessionRateLimiterMiddleware[*mcp.ServerSession](rate.Every(time.Second/5), 10))
 	// Run Server logic.
+	log.Println("MCP Server instance created with Middleware (but not running).")
+	log.Println("This example demonstrates configuration, not live interaction.")
 }

jsonrpc/jsonrpc.go

@@ -0,0 +1,20 @@
+// 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 jsonrpc exposes part of a JSON-RPC v2 implementation
+// for use by mcp transport authors.
+package jsonrpc
+
+import "github.com/modelcontextprotocol/go-sdk/internal/jsonrpc2"
+
+type (
+	// ID is a JSON-RPC request ID.
+	ID = jsonrpc2.ID
+	// Message is a JSON-RPC message.
+	Message = jsonrpc2.Message
+	// Request is a JSON-RPC request.
+	Request = jsonrpc2.Request
+	// Response is a JSON-RPC response.
+	Response = jsonrpc2.Response
+)

jsonschema/infer.go

@@ -9,6 +9,7 @@ package jsonschema
 import (
 	"fmt"
 	"reflect"
+	"regexp"
 
 	"github.com/modelcontextprotocol/go-sdk/internal/util"
 )
@@ -36,18 +37,24 @@ import (
 //   - complex numbers
 //   - unsafe pointers
 //
-// The types must not have cycles.
+// It will return an error if there is a cycle in the types.
+//
+// For recognizes struct field tags named "jsonschema".
+// A jsonschema tag on a field is used as the description for the corresponding property.
+// For future compatibility, descriptions must not start with "WORD=", where WORD is a
+// sequence of non-whitespace characters.
 func For[T any]() (*Schema, error) {
 	// TODO: consider skipping incompatible fields, instead of failing.
-	s, err := forType(reflect.TypeFor[T]())
+	seen := make(map[reflect.Type]bool)
+	s, err := forType(reflect.TypeFor[T](), seen)
 	if err != nil {
 		var z T
 		return nil, fmt.Errorf("For[%T](): %w", z, err)
 	}
 	return s, nil
 }
 
-func forType(t reflect.Type) (*Schema, error) {
+func forType(t reflect.Type, seen map[reflect.Type]bool) (*Schema, error) {
 	// Follow pointers: the schema for *T is almost the same as for T, except that
 	// an explicit JSON "null" is allowed for the pointer.
 	allowNull := false
@@ -56,6 +63,16 @@ func forType(t reflect.Type) (*Schema, error) {
 		t = t.Elem()
 	}
 
+	// Check for cycles
+	// User defined types have a name, so we can skip those that are natively defined
+	if t.Name() != "" {
+		if seen[t] {
+			return nil, fmt.Errorf("cycle detected for type %v", t)
+		}
+		seen[t] = true
+		defer delete(seen, t)
+	}
+
 	var (
 		s   = new(Schema)
 		err error
@@ -81,14 +98,14 @@ func forType(t reflect.Type) (*Schema, error) {
 			return nil, fmt.Errorf("unsupported map key type %v", t.Key().Kind())
 		}
 		s.Type = "object"
-		s.AdditionalProperties, err = forType(t.Elem())
+		s.AdditionalProperties, err = forType(t.Elem(), seen)
 		if err != nil {
 			return nil, fmt.Errorf("computing map value schema: %v", err)
 		}
 
 	case reflect.Slice, reflect.Array:
 		s.Type = "array"
-		s.Items, err = forType(t.Elem())
+		s.Items, err = forType(t.Elem(), seen)
 		if err != nil {
 			return nil, fmt.Errorf("computing element schema: %v", err)
 		}
@@ -114,10 +131,20 @@ func forType(t reflect.Type) (*Schema, error) {
 			if s.Properties == nil {
 				s.Properties = make(map[string]*Schema)
 			}
-			s.Properties[info.Name], err = forType(field.Type)
+			fs, err := forType(field.Type, seen)
 			if err != nil {
 				return nil, err
 			}
+			if tag, ok := field.Tag.Lookup("jsonschema"); ok {
+				if tag == "" {
+					return nil, fmt.Errorf("empty jsonschema tag on struct field %s.%s", t, field.Name)
+				}
+				if disallowedPrefixRegexp.MatchString(tag) {
+					return nil, fmt.Errorf("tag must not begin with 'WORD=': %q", tag)
+				}
+				fs.Description = tag
+			}
+			s.Properties[info.Name] = fs
 			if !info.Settings["omitempty"] && !info.Settings["omitzero"] {
 				s.Required = append(s.Required, info.Name)
 			}
@@ -132,3 +159,6 @@ func forType(t reflect.Type) (*Schema, error) {
 	}
 	return s, nil
 }
+
+// Disallow jsonschema tag values beginning "WORD=", for future expansion.
+var disallowedPrefixRegexp = regexp.MustCompile("^[^ \t\n]*=")