feat(mcp): Add WithAny for flexible tool properties (#618)

Introduces `mcp.WithAny`, a new tool option that allows defining a
property of `any` type. This is useful for creating tools that can
accept a variety of data structures for a given parameter.

- `mcp.WithAny` function: A new WithAny function has been added to
  to support properties of any type in tool schemas. This allows for
  more flexible tool definitions where a property can accept a string,
  number, boolean, object, slice, etc.
- Testing: `TestToolWithAny`, has been introduced ensure the `WithAny`
  functionality is working correctly. The tests cover various data types
  to validate that the schema is correctly generated and that arguments
  are properly parsed.
- Example Usage: The `typed_tools`` example has been updated to
  demonstrate how to use `mcp.WithAny`. This includes adding a new field
  of type any to the arguments struct and updating the tool handler to
  process the new field

Author: otaviof

examples/typed_tools/main.go

@@ -18,6 +18,7 @@ type GreetingArgs struct {
 		Location string `json:"location"`
 		Timezone string `json:"timezone"`
 	} `json:"metadata"`
+	AnyData any `json:"any_data"`
 }
 
 func main() {
@@ -61,6 +62,9 @@ func main() {
 				},
 			}),
 		),
+		mcp.WithAny("any_data",
+			mcp.Description("Any kind of data, e.g., an integer"),
+		),
 	)
 
 	// Add tool handler using the typed handler
@@ -101,5 +105,9 @@ func typedGreetingHandler(ctx context.Context, request mcp.CallToolRequest, args
 		}
 	}
 
+	if args.AnyData != nil {
+		greeting += fmt.Sprintf(" I also received some other data: %v.", args.AnyData)
+	}
+
 	return mcp.NewToolResultText(greeting), nil
 }

mcp/tools.go

@@ -1113,6 +1113,26 @@ func WithArray(name string, opts ...PropertyOption) ToolOption {
 	}
 }
 
+// WithAny adds a property of any type to the tool schema.
+// It accepts property options to configure the property's behavior and constraints.
+func WithAny(name string, opts ...PropertyOption) ToolOption {
+	return func(t *Tool) {
+		schema := map[string]any{}
+
+		for _, opt := range opts {
+			opt(schema)
+		}
+
+		// Remove required from property schema and add to InputSchema.required
+		if required, ok := schema["required"].(bool); ok && required {
+			delete(schema, "required")
+			t.InputSchema.Required = append(t.InputSchema.Required, name)
+		}
+
+		t.InputSchema.Properties[name] = schema
+	}
+}
+
 // Properties defines the properties for an object schema
 func Properties(props map[string]any) PropertyOption {
 	return func(schema map[string]any) {

mcp/tools_test.go

@@ -242,6 +242,108 @@ func TestToolWithObjectAndArray(t *testing.T) {
 	assert.Contains(t, required, "books")
 }
 
+func TestToolWithAny(t *testing.T) {
+	const desc = "Can be any value: string, number, bool, object, or slice"
+
+	tool := NewTool("any-tool",
+		WithDescription("A tool with an 'any' type property"),
+		WithAny("data",
+			Description(desc),
+			Required(),
+		),
+	)
+
+	data, err := json.Marshal(tool)
+	assert.NoError(t, err)
+
+	var result map[string]any
+	err = json.Unmarshal(data, &result)
+	assert.NoError(t, err)
+
+	assert.Equal(t, "any-tool", result["name"])
+
+	schema, ok := result["inputSchema"].(map[string]any)
+	assert.True(t, ok)
+	assert.Equal(t, "object", schema["type"])
+
+	properties, ok := schema["properties"].(map[string]any)
+	assert.True(t, ok)
+
+	dataProp, ok := properties["data"].(map[string]any)
+	assert.True(t, ok)
+	_, typeExists := dataProp["type"]
+	assert.False(t, typeExists, "The 'any' type property should not have a 'type' field")
+	assert.Equal(t, desc, dataProp["description"])
+
+	required, ok := schema["required"].([]any)
+	assert.True(t, ok)
+	assert.Contains(t, required, "data")
+
+	type testStruct struct {
+		A string `json:"A"`
+	}
+	testCases := []struct {
+		description string
+		arg         any
+		expect      any
+	}{{
+		description: "string",
+		arg:         "hello world",
+		expect:      "hello world",
+	}, {
+		description: "integer",
+		arg:         123,
+		expect:      float64(123), // JSON unmarshals numbers to float64
+	}, {
+		description: "float",
+		arg:         3.14,
+		expect:      3.14,
+	}, {
+		description: "boolean",
+		arg:         true,
+		expect:      true,
+	}, {
+		description: "object",
+		arg:         map[string]any{"key": "value"},
+		expect:      map[string]any{"key": "value"},
+	}, {
+		description: "slice",
+		arg:         []any{1, "two", false},
+		expect:      []any{float64(1), "two", false},
+	}, {
+		description: "struct",
+		arg:         testStruct{A: "B"},
+		expect:      map[string]any{"A": "B"},
+	}}
+
+	for _, tc := range testCases {
+		t.Run(fmt.Sprintf("with_%s", tc.description), func(t *testing.T) {
+			req := CallToolRequest{
+				Request: Request{},
+				Params: CallToolParams{
+					Name: "any-tool",
+					Arguments: map[string]any{
+						"data": tc.arg,
+					},
+				},
+			}
+
+			// Marshal and unmarshal to simulate a real request
+			reqBytes, err := json.Marshal(req)
+			assert.NoError(t, err)
+
+			var unmarshaledReq CallToolRequest
+			err = json.Unmarshal(reqBytes, &unmarshaledReq)
+			assert.NoError(t, err)
+
+			args := unmarshaledReq.GetArguments()
+			value, ok := args["data"]
+			assert.True(t, ok)
+			assert.Equal(t, tc.expect, value)
+		})
+	}
+}
+
 func TestParseToolCallToolRequest(t *testing.T) {
 	request := CallToolRequest{}
 	request.Params.Name = "test-tool"