jsonschema: support "jsonschema" struct tags

Struct fields may have the "jsonschema" struct tag, which is used
as the description of the property.

Fixes #47.

Author: jba

jsonschema/infer.go

@@ -9,6 +9,7 @@ package jsonschema
 import (
 	"fmt"
 	"reflect"
+	"regexp"
 
 	"github.com/modelcontextprotocol/go-sdk/internal/util"
 )
@@ -37,6 +38,11 @@ import (
 //   - unsafe pointers
 //
 // The types must not have cycles.
+//
+// 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]())
@@ -114,7 +120,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)
+			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 err != nil {
 				return nil, err
 			}
@@ -132,3 +151,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]*=")

jsonschema/infer_test.go

@@ -22,6 +22,11 @@ func forType[T any]() *jsonschema.Schema {
 
 func TestForType(t *testing.T) {
 	type schema = jsonschema.Schema
+
+	type S struct {
+		B int `jsonschema:"bdesc"`
+	}
+
 	tests := []struct {
 		name string
 		got  *jsonschema.Schema
@@ -44,9 +49,9 @@ func TestForType(t *testing.T) {
 		{
 			"struct",
 			forType[struct {
-				F           int `json:"f"`
+				F           int `json:"f" jsonschema:"fdesc"`
 				G           []float64
-				P           *bool
+				P           *bool  `jsonschema:"pdesc"`
 				Skip        string `json:"-"`
 				NoSkip      string `json:",omitempty"`
 				unexported  float64
@@ -55,13 +60,13 @@ func TestForType(t *testing.T) {
 			&schema{
 				Type: "object",
 				Properties: map[string]*schema{
-					"f":      {Type: "integer"},
+					"f":      {Type: "integer", Description: "fdesc"},
 					"G":      {Type: "array", Items: &schema{Type: "number"}},
-					"P":      {Types: []string{"null", "boolean"}},
+					"P":      {Types: []string{"null", "boolean"}, Description: "pdesc"},
 					"NoSkip": {Type: "string"},
 				},
 				Required:             []string{"f", "G", "P"},
-				AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+				AdditionalProperties: falseSchema(),
 			},
 		},
 		{
@@ -74,7 +79,37 @@ func TestForType(t *testing.T) {
 					"Y": {Type: "integer"},
 				},
 				Required:             []string{"X", "Y"},
-				AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+				AdditionalProperties: falseSchema(),
+			},
+		},
+		{
+			"nested and embedded",
+			forType[struct {
+				A S
+				S
+			}](),
+			&schema{
+				Type: "object",
+				Properties: map[string]*schema{
+					"A": {
+						Type: "object",
+						Properties: map[string]*schema{
+							"B": {Type: "integer", Description: "bdesc"},
+						},
+						Required:             []string{"B"},
+						AdditionalProperties: falseSchema(),
+					},
+					"S": {
+						Type: "object",
+						Properties: map[string]*schema{
+							"B": {Type: "integer", Description: "bdesc"},
+						},
+						Required:             []string{"B"},
+						AdditionalProperties: falseSchema(),
+					},
+				},
+				Required:             []string{"A", "S"},
+				AdditionalProperties: falseSchema(),
 			},
 		},
 	}
@@ -91,3 +126,7 @@ func TestForType(t *testing.T) {
 		})
 	}
 }
+
+func falseSchema() *jsonschema.Schema {
+	return &jsonschema.Schema{Not: &jsonschema.Schema{}}
+}

mcp/tool.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"reflect"
 
+	"github.com/modelcontextprotocol/go-sdk/internal/util"
 	"github.com/modelcontextprotocol/go-sdk/jsonschema"
 )
 
@@ -89,7 +90,7 @@ func newServerTool[In, Out any](t *Tool, h ToolHandlerFor[In, Out]) (*serverTool
 func setSchema[T any](sfield **jsonschema.Schema, rfield **jsonschema.Resolved) error {
 	var err error
 	if *sfield == nil {
-		*sfield, err = jsonschema.For[T]()
+		*sfield, err = SchemaFor[T]()
 	}
 	if err != nil {
 		return err
@@ -125,6 +126,31 @@ func unmarshalSchema(data json.RawMessage, resolved *jsonschema.Resolved, v any)
 	return nil
 }
 
+// SchemaFor returns a JSON Schema for type T.
+// It is like [jsonschema.For], but also uses "mcp" struct field tags
+// for property descriptions.
+//
+// For example, the call
+//
+//	SchemaFor[struct{ B int `mcp:"desc"` }]()
+//
+// returns a schema with this value for "properties":
+//
+//	{"B": {"type": "integer", "description": "desc"}}
+func SchemaFor[T any]() (*jsonschema.Schema, error) {
+	// Infer the schema based on "json" tags alone.
+	s, err := jsonschema.For[T]()
+	if err != nil {
+		return nil, err
+	}
+
+	// Add descriptions from "mcp" tags.
+	if err := addDescriptions(reflect.TypeFor[T](), s); err != nil {
+		return nil, err
+	}
+	return s, nil
+}
+
 // schemaJSON returns the JSON value for s as a string, or a string indicating an error.
 func schemaJSON(s *jsonschema.Schema) string {
 	m, err := json.Marshal(s)

mcp/tool_test.go

@@ -132,3 +132,49 @@ func TestUnmarshalSchema(t *testing.T) {
 
 	}
 }
+
+func TestSchemaFor(t *testing.T) {
+	type S1 struct {
+		G int `mcp:"gdesc"`
+	}
+	type S2 struct {
+		A int
+		B int `json:"b"`
+		C int `mcp:"cdesc"`
+		D int `json:"d" mcp:"ddesc"`
+		E int `json:"-"`
+		F S1  `json:"f"`
+		S1
+	}
+
+	got, err := SchemaFor[S2]()
+	if err != nil {
+		t.Fatal(err)
+	}
+	i := "integer"
+	s1 := &jsonschema.Schema{
+		Type:                 "object",
+		Required:             []string{"G"},
+		AdditionalProperties: falseSchema(),
+		Properties: map[string]*jsonschema.Schema{
+			"G": {Type: i, Description: "gdesc"},
+		},
+	}
+	want := &jsonschema.Schema{
+		Type: "object",
+		Properties: map[string]*jsonschema.Schema{
+			"A":  {Type: i},
+			"b":  {Type: i},
+			"C":  {Type: i, Description: "cdesc"},
+			"d":  {Type: i, Description: "ddesc"},
+			"f":  s1,
+			"S1": s1,
+		},
+		Required:             []string{"A", "b", "C", "d", "f", "S1"},
+		AdditionalProperties: falseSchema(),
+	}
+	if diff := cmp.Diff(want, got, cmp.AllowUnexported(jsonschema.Schema{})); diff != "" {
+		t.Errorf("mismatch (-want, +got):\n%s", diff)
+		t.Log(schemaJSON(got))
+	}
+}