feat: implement structured tool output support

This commit introduces the core functionality for structured tool outputs.

In `mcp/tools.go`:
- Adds `OutputSchema` to `Tool` and `StructuredContent` to `CallToolResult`.
- Renames `ToolInputSchema` to `ToolSchema` for unified handling.
- Implements `ValidateStructuredOutput` with schema compilation and caching.
- Adds a series of `WithOutput*` functions for programmatic schema creation.
- Adds comments for new public APIs and internal logic.

In `mcp/utils.go`:
- Adds `NewStructuredToolResult` and `NewStructuredToolError` helpers to
  simplify creating structured results with backward-compatible text content.

Author: davidleitw

mcp/tools.go

@@ -1,11 +1,14 @@
 package mcp
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"reflect"
 	"strconv"
+
+	"github.com/santhosh-tekuri/jsonschema"
 )
 
 var errToolSchemaConflict = errors.New("provide either InputSchema or RawInputSchema, not both")
@@ -36,6 +39,8 @@ type ListToolsResult struct {
 type CallToolResult struct {
 	Result
 	Content []Content `json:"content"` // Can be TextContent, ImageContent, AudioContent, or EmbeddedResource
+	// Structured content that conforms to the tool's output schema
+	StructuredContent any `json:"structuredContent,omitempty"`
 	// Whether the tool call ended in an error.
 	//
 	// If not set, this is assumed to be false (the call was successful).
@@ -472,10 +477,17 @@ type ToolListChangedNotification struct {
 type Tool struct {
 	// The name of the tool.
 	Name string `json:"name"`
+	// A human-friendly display name for the tool.
+	// This is used for UI display purposes, while Name is used for programmatic identification.
+	Title string `json:"title,omitempty"`
 	// A human-readable description of the tool.
 	Description string `json:"description,omitempty"`
 	// A JSON Schema object defining the expected parameters for the tool.
-	InputSchema ToolInputSchema `json:"inputSchema"`
+	InputSchema ToolSchema `json:"inputSchema"`
+	// A JSON Schema object defining the expected output for the tool.
+	OutputSchema ToolSchema `json:"outputSchema,omitempty"`
+	// Compiled JSON schema validator for output validation, cached for performance
+	compiledOutputSchema *jsonschema.Schema `json:"-"`
 	// Alternative to InputSchema - allows arbitrary JSON Schema to be provided
 	RawInputSchema json.RawMessage `json:"-"` // Hide this from JSON marshaling
 	// Optional properties describing tool behavior
@@ -487,14 +499,83 @@ func (t Tool) GetName() string {
 	return t.Name
 }
 
+// GetTitle returns the display title for the tool.
+// It follows the precedence: direct title field → annotations.title → empty string.
+func (t Tool) GetTitle() string {
+	if title := t.Title; title != "" {
+		return title
+	}
+	return t.Annotations.Title
+}
+
+// HasOutputSchema returns true if the tool has an output schema defined.
+// This indicates that the tool can return structured content.
+func (t Tool) HasOutputSchema() bool {
+	return t.OutputSchema.Type != "" && len(t.OutputSchema.Properties) > 0
+}
+
+// validateStructuredOutput performs the actual validation using the compiled schema
+func (t Tool) validateStructuredOutput(result *CallToolResult) error {
+	return t.compiledOutputSchema.ValidateInterface(result.StructuredContent)
+}
+
+// ensureOutputSchemaValidator compiles and caches the JSON schema validator if not already done
+func (t *Tool) ensureOutputSchemaValidator() error {
+	if t.compiledOutputSchema != nil {
+		return nil
+	}
+
+	schemaBytes, err := t.OutputSchema.MarshalJSON()
+	if err != nil {
+		return err
+	}
+
+	compiler := jsonschema.NewCompiler()
+
+	const validatorKey = "output-schema-validator"
+	if err := compiler.AddResource(validatorKey, bytes.NewReader(schemaBytes)); err != nil {
+		return err
+	}
+
+	compiledSchema, err := compiler.Compile(validatorKey)
+	if err != nil {
+		return err
+	}
+
+	t.compiledOutputSchema = compiledSchema
+	return nil
+}
+
+// ValidateStructuredOutput validates the structured content against the tool's output schema.
+// Returns nil if the tool has no output schema or if validation passes.
+// Returns an error if the tool has an output schema but the structured content is invalid.
+func (t Tool) ValidateStructuredOutput(result *CallToolResult) error {
+	if !t.HasOutputSchema() {
+		return nil
+	}
+
+	if result.StructuredContent == nil {
+		return fmt.Errorf("tool %s has output schema but structuredContent is nil", t.Name)
+	}
+
+	if err := t.ensureOutputSchemaValidator(); err != nil {
+		return err
+	}
+
+	return t.validateStructuredOutput(result)
+}
+
 // MarshalJSON implements the json.Marshaler interface for Tool.
 // It handles marshaling either InputSchema or RawInputSchema based on which is set.
 func (t Tool) MarshalJSON() ([]byte, error) {
 	// Create a map to build the JSON structure
-	m := make(map[string]any, 3)
+	m := make(map[string]any, 6)
 
-	// Add the name and description
+	// Add the name and title
 	m["name"] = t.Name
+	if t.Title != "" {
+		m["title"] = t.Title
+	}
 	if t.Description != "" {
 		m["description"] = t.Description
 	}
@@ -510,29 +591,34 @@ func (t Tool) MarshalJSON() ([]byte, error) {
 		m["inputSchema"] = t.InputSchema
 	}
 
+	// Add output schema if defined
+	if t.HasOutputSchema() {
+		m["outputSchema"] = t.OutputSchema
+	}
+
 	m["annotations"] = t.Annotations
 
 	return json.Marshal(m)
 }
 
-type ToolInputSchema struct {
+type ToolSchema struct {
 	Type       string         `json:"type"`
 	Properties map[string]any `json:"properties,omitempty"`
 	Required   []string       `json:"required,omitempty"`
 }
 
-// MarshalJSON implements the json.Marshaler interface for ToolInputSchema.
-func (tis ToolInputSchema) MarshalJSON() ([]byte, error) {
+// MarshalJSON implements the json.Marshaler interface for ToolSchema.
+func (schema ToolSchema) MarshalJSON() ([]byte, error) {
 	m := make(map[string]any)
-	m["type"] = tis.Type
+	m["type"] = schema.Type
 
 	// Marshal Properties to '{}' rather than `nil` when its length equals zero
-	if tis.Properties != nil {
-		m["properties"] = tis.Properties
+	if schema.Properties != nil {
+		m["properties"] = schema.Properties
 	}
 
-	if len(tis.Required) > 0 {
-		m["required"] = tis.Required
+	if len(schema.Required) > 0 {
+		m["required"] = schema.Required
 	}
 
 	return json.Marshal(m)
@@ -569,11 +655,17 @@ type PropertyOption func(map[string]any)
 func NewTool(name string, opts ...ToolOption) Tool {
 	tool := Tool{
 		Name: name,
-		InputSchema: ToolInputSchema{
+		InputSchema: ToolSchema{
 			Type:       "object",
 			Properties: make(map[string]any),
 			Required:   nil, // Will be omitted from JSON if empty
 		},
+		OutputSchema: ToolSchema{
+			Type:       "",
+			Properties: make(map[string]any),
+			Required:   nil, // Will be omitted from JSON if empty
+		},
+		compiledOutputSchema: nil,
 		Annotations: ToolAnnotation{
 			Title:           "",
 			ReadOnlyHint:    ToBoolPtr(false),
@@ -615,6 +707,14 @@ func WithDescription(description string) ToolOption {
 	}
 }
 
+// WithTitle sets the direct title field of the Tool.
+// This title takes precedence over the annotation title when displaying the tool.
+func WithTitle(title string) ToolOption {
+	return func(t *Tool) {
+		t.Title = title
+	}
+}
+
 // WithToolAnnotation adds optional hints about the Tool.
 func WithToolAnnotation(annotation ToolAnnotation) ToolOption {
 	return func(t *Tool) {
@@ -1076,3 +1176,151 @@ func WithBooleanItems(opts ...PropertyOption) PropertyOption {
 		schema["items"] = itemSchema
 	}
 }
+
+//
+// Output Schema Configuration Functions
+//
+
+// WithOutputSchema sets the output schema for the Tool.
+// This allows the tool to define the structure of its return data.
+func WithOutputSchema(schema ToolSchema) ToolOption {
+	return func(t *Tool) {
+		t.OutputSchema = schema
+	}
+}
+
+// WithOutputBoolean adds a boolean property to the tool's output schema.
+// It accepts property options to configure the boolean property's behavior and constraints.
+func WithOutputBoolean(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		// Initialize output schema if not set
+		if t.OutputSchema.Type == "" {
+			t.OutputSchema.Type = "object"
+		}
+
+		schema := map[string]any{
+			"type": "boolean",
+		}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to OutputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.OutputSchema.Required = append(t.OutputSchema.Required, name)
+		}
+
+		t.OutputSchema.Properties[name] = schema
+	}
+}
+
+// WithOutputNumber adds a number property to the tool's output schema.
+// It accepts property options to configure the number property's behavior and constraints.
+func WithOutputNumber(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		// Initialize output schema if not set
+		if t.OutputSchema.Type == "" {
+			t.OutputSchema.Type = "object"
+		}
+
+		schema := map[string]any{
+			"type": "number",
+		}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to OutputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.OutputSchema.Required = append(t.OutputSchema.Required, name)
+		}
+
+		t.OutputSchema.Properties[name] = schema
+	}
+}
+
+// WithOutputString adds a string property to the tool's output schema.
+// It accepts property options to configure the string property's behavior and constraints.
+func WithOutputString(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		// Initialize output schema if not set
+		if t.OutputSchema.Type == "" {
+			t.OutputSchema.Type = "object"
+		}
+
+		schema := map[string]any{
+			"type": "string",
+		}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to OutputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.OutputSchema.Required = append(t.OutputSchema.Required, name)
+		}
+
+		t.OutputSchema.Properties[name] = schema
+	}
+}
+
+// WithOutputObject adds an object property to the tool's output schema.
+// It accepts property options to configure the object property's behavior and constraints.
+func WithOutputObject(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		// Initialize output schema if not set
+		if t.OutputSchema.Type == "" {
+			t.OutputSchema.Type = "object"
+		}
+
+		schema := map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+		}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to OutputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.OutputSchema.Required = append(t.OutputSchema.Required, name)
+		}
+
+		t.OutputSchema.Properties[name] = schema
+	}
+}
+
+// WithOutputArray adds an array property to the tool's output schema.
+// It accepts property options to configure the array property's behavior and constraints.
+func WithOutputArray(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		// Initialize output schema if not set
+		if t.OutputSchema.Type == "" {
+			t.OutputSchema.Type = "object"
+		}
+
+		schema := map[string]any{
+			"type": "array",
+		}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to OutputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.OutputSchema.Required = append(t.OutputSchema.Required, name)
+		}
+
+		t.OutputSchema.Properties[name] = schema
+	}
+}