mcp: support "mcp" struct tags

Add the SchemaFor[T] function, which infers the schema for a struct
and also uses the values of "mcp" struct tags to set descriptions.

Fixes #47.

Author: jba

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,61 @@ 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
+}
+
+func addDescriptions(t reflect.Type, s *jsonschema.Schema) error {
+	for t.Kind() == reflect.Pointer {
+		t = t.Elem()
+	}
+	if t.Kind() != reflect.Struct {
+		return nil
+	}
+
+	for i := range t.NumField() {
+		f := t.Field(i)
+		info := util.FieldJSONInfo(f)
+		ps := s.Properties[info.Name]
+		if tag, ok := f.Tag.Lookup("mcp"); ok {
+			if ps == nil {
+				return fmt.Errorf("mcp tag on struct field %s.%s, which is not in schema", t, f.Name)
+			}
+			if tag == "" {
+				return fmt.Errorf("empty mcp tag on struct field %s.%s", t, f.Name)
+			}
+			ps.Description = tag
+		}
+		// Recurse on sub-schemas.
+		if ps != nil {
+			addDescriptions(f.Type, ps)
+		}
+
+	}
+	return 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))
+	}
+}