mcp: export SchemaCache type and improve documentation

Export SchemaCache (was schemaCache) so users can properly type-annotate
variables. Add trade-offs documentation covering memory behavior and
pointer identity caching. Add brief mention in server.md pointing to
the type documentation. Remove benchmarks (functional tests suffice).
Clean up redundant comments throughout.

Co-authored-by: Adam Holt <[email protected]>
Co-authored-by: Ksenia Bobrova <[email protected]>

Author: 3 people

docs/server.md

@@ -400,6 +400,23 @@ _See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
 example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
 for more examples of customizing tool schemas._
 
+**Stateless server deployments:** Some deployments create a new
+[`Server`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server)
+for each incoming request, re-registering tools every time. To avoid repeated
+schema generation, create a
+[`SchemaCache`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#SchemaCache)
+and share it across server instances:
+
+```go
+var schemaCache = mcp.NewSchemaCache() // create once at startup
+
+func handleRequest(w http.ResponseWriter, r *http.Request) {
+    s := mcp.NewServer(impl, &mcp.ServerOptions{SchemaCache: schemaCache})
+    mcp.AddTool(s, myTool, myHandler)
+    // ...
+}
+```
+
 ## Utilities
 
 ### Completion

internal/docs/server.src.md

@@ -193,6 +193,23 @@ _See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
 example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
 for more examples of customizing tool schemas._
 
+**Stateless server deployments:** Some deployments create a new
+[`Server`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server)
+for each incoming request, re-registering tools every time. To avoid repeated
+schema generation, create a
+[`SchemaCache`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#SchemaCache)
+and share it across server instances:
+
+```go
+var schemaCache = mcp.NewSchemaCache() // create once at startup
+
+func handleRequest(w http.ResponseWriter, r *http.Request) {
+    s := mcp.NewServer(impl, &mcp.ServerOptions{SchemaCache: schemaCache})
+    mcp.AddTool(s, myTool, myHandler)
+    // ...
+}
+```
+
 ## Utilities
 
 ### Completion

mcp/schema_cache.go

@@ -11,64 +11,59 @@ import (
 	"github.com/google/jsonschema-go/jsonschema"
 )
 
-// schemaCache provides concurrent-safe caching for JSON schemas.
-// It caches both by reflect.Type (for auto-generated schemas) and
-// by schema pointer (for pre-defined schemas).
+// A SchemaCache caches JSON schemas to avoid repeated reflection and resolution.
 //
-// This cache significantly improves performance for stateless server deployments
-// where tools are re-registered on every request. Without caching, each AddTool
-// call would trigger expensive reflection-based schema generation and resolution.
+// This is useful for stateless server deployments (one [Server] per request)
+// where tools are re-registered on every request. Without caching, each
+// [AddTool] call triggers expensive reflection-based schema generation.
 //
-// Create a cache using [NewSchemaCache] and pass it to [ServerOptions.SchemaCache].
-type schemaCache struct {
-	// byType caches schemas generated from Go types via jsonschema.ForType.
-	// Key: reflect.Type, Value: *cachedSchema
-	byType sync.Map
-
-	// bySchema caches resolved schemas for pre-defined Schema objects.
-	// Key: *jsonschema.Schema (pointer identity), Value: *jsonschema.Resolved
-	// This uses pointer identity because integrators typically reuse the same
-	// Tool objects across requests, so the schema pointer remains stable.
-	bySchema sync.Map
+// A SchemaCache is safe for concurrent use by multiple goroutines.
+//
+// # Trade-offs
+//
+// The cache is unbounded: it stores one entry per unique Go type or schema
+// pointer. For typical MCP servers with a fixed set of tools, memory usage
+// is negligible. However, if tool input types are generated dynamically,
+// the cache will grow without bound.
+//
+// The cache uses pointer identity for pre-defined schemas. If a schema's
+// contents change but the pointer remains the same, stale resolved schemas
+// may be returned. In practice, this is not an issue because tool schemas
+// are typically defined once at startup.
+type SchemaCache struct {
+	byType   sync.Map // reflect.Type -> *cachedSchema
+	bySchema sync.Map // *jsonschema.Schema -> *jsonschema.Resolved
 }
 
-// cachedSchema holds both the generated schema and its resolved form.
 type cachedSchema struct {
 	schema   *jsonschema.Schema
 	resolved *jsonschema.Resolved
 }
 
-// NewSchemaCache creates a new schema cache for use with [ServerOptions.SchemaCache].
-// Safe for concurrent use, unbounded.
-func NewSchemaCache() *schemaCache {
-	return &schemaCache{}
+// NewSchemaCache creates a new [SchemaCache].
+func NewSchemaCache() *SchemaCache {
+	return &SchemaCache{}
 }
 
-// getByType retrieves a cached schema by Go type.
-// Returns the schema, resolved schema, and whether the cache hit.
-func (c *schemaCache) getByType(t reflect.Type) (*jsonschema.Schema, *jsonschema.Resolved, bool) {
+func (c *SchemaCache) getByType(t reflect.Type) (*jsonschema.Schema, *jsonschema.Resolved, bool) {
 	if v, ok := c.byType.Load(t); ok {
 		cs := v.(*cachedSchema)
 		return cs.schema, cs.resolved, true
 	}
 	return nil, nil, false
 }
 
-// setByType caches a schema by Go type.
-func (c *schemaCache) setByType(t reflect.Type, schema *jsonschema.Schema, resolved *jsonschema.Resolved) {
+func (c *SchemaCache) setByType(t reflect.Type, schema *jsonschema.Schema, resolved *jsonschema.Resolved) {
 	c.byType.Store(t, &cachedSchema{schema: schema, resolved: resolved})
 }
 
-// getBySchema retrieves a cached resolved schema by the original schema pointer.
-// This is used when integrators provide pre-defined schemas (e.g., github-mcp-server pattern).
-func (c *schemaCache) getBySchema(schema *jsonschema.Schema) (*jsonschema.Resolved, bool) {
+func (c *SchemaCache) getBySchema(schema *jsonschema.Schema) (*jsonschema.Resolved, bool) {
 	if v, ok := c.bySchema.Load(schema); ok {
 		return v.(*jsonschema.Resolved), true
 	}
 	return nil, false
 }
 
-// setBySchema caches a resolved schema by the original schema pointer.
-func (c *schemaCache) setBySchema(schema *jsonschema.Schema, resolved *jsonschema.Resolved) {
+func (c *SchemaCache) setBySchema(schema *jsonschema.Schema, resolved *jsonschema.Resolved) {
 	c.bySchema.Store(schema, resolved)
 }