feat(mcp): Add WithAny for flexible tool properties

[otaviof]

Description

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

Fixes #345

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• MCP spec compatibility implementation
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring (no functional changes)
• Performance improvement
• Tests only (no functional changes)
• Other (please describe):

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• I have updated the documentation accordingly

MCP Spec Compliance

• This PR implements a feature defined in the MCP specification
• Implementation follows the specification exactly

Summary by CodeRabbit

• New Features
  • Added support for tool parameters with flexible typing, enabling tools to accept arbitrary data alongside strictly-typed fields.

[coderabbitai]

Walkthrough

This PR adds support for schema-less "any" type tool arguments to the mcp-go SDK. It introduces a new WithAny tool option function that creates properties with no predefined type constraint, includes comprehensive test coverage for marshaling/unmarshaling operations with various argument types, and demonstrates usage in an example.

Changes

Cohort / File(s)	Summary
Core functionality mcp/tools.go	Adds WithAny(name string, opts ...PropertyOption) function that creates input schema properties with no explicit type by starting with an empty schema map and applying provided options. Handles required flag management consistent with existing property-adding methods.
Test coverage mcp/tools_test.go	Adds TestToolWithAny that validates the WithAny option through tool construction, JSON serialization/deserialization, and argument type handling with various payloads (string, integer, float, boolean, object, slice, struct). Verifies property structure and required field presence.
Example usage examples/typed_tools/main.go	Adds AnyData field to GreetingArgs struct and uses mcp.WithAny("any_data", ...) in tool construction. Updates handler to utilize the new field when present.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The PR introduces a straightforward new function following established patterns (mirroring WithBoolean, WithNumber), includes comprehensive tests exercising multiple argument types, and demonstrates practical usage. While the logic is not complex, the breadth of test scenarios and type handling variations requires careful review across all three files.

Possibly related PRs

• tools: add WithObject and WithArray to supplement type definition utility #47: Both PRs add new property-type helper functions to mcp/tools.go with corresponding tests, creating consistent patterns for tool argument schema definition.
• refactor: make CallToolRequest.Arguments more flexible (Breaking Change) #287: This PR's CallToolRequest marshaling/unmarshaling and GetArguments() accessor usage directly depend on flexible argument handling infrastructure introduced in that PR.

Suggested labels

type: enhancement, area: sdk

Suggested reviewers

• robert-jackson-glean
• pottekkat

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "feat(mcp): Add WithAny for flexible tool properties" directly and clearly summarizes the main change—introducing a new tool option called WithAny that enables flexible property definitions. The title is concise, specific, and accurately reflects the primary objective of the pull request without unnecessary verbosity or generic language.
Linked Issues Check	✅ Passed	The implementation satisfies the requirements specified in issue #345. The PR adds a new WithAny function that creates a tool property with an empty JSON Schema object (no predefined type), exactly as requested in the issue. The function signature WithAny(name string, opts ...PropertyOption) ToolOption matches the proposed pattern, the example usage demonstrates its application, and comprehensive tests validate the functionality including JSON serialization/deserialization and handling of various argument types.
Out of Scope Changes Check	✅ Passed	All code changes are directly aligned with the objectives defined in issue #345. The modifications include the core WithAny function implementation, example usage demonstrating the feature, and comprehensive tests validating its behavior. There are no unrelated refactorings, unrelated bug fixes, or extraneous changes; every modification serves the primary purpose of implementing flexible tool properties via the WithAny option.
Description Check	✅ Passed	The pull request description includes all main required sections: a clear and concise description explaining the new mcp.WithAny() tool option, appropriate selections in the Type of Change section, and a fully completed checklist confirming code style adherence, self-review, test coverage, and documentation updates. The description references issue #345 as intended. The MCP Spec Compliance section is partially filled out, with the main "implements a feature" checkbox unchecked and no specification link provided, though the author indicated "MCP spec compatibility implementation" in the Type of Change selections.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[otaviof]

@coderabbitai generate docstrings

[coderabbitai]

✅ Actions performed

Initiated docstring generation; will generate only if new commits exist.

[coderabbitai]

Note

Docstrings generation - SUCCESS
Generated docstrings for this pull request at #619

[otaviof]

Apologies, I didn't know CodeRabbit would create yet another PR directly. 🫥