Skip to content

Add support for _meta property on Tool definition #123

@tuntisz

Description

@tuntisz

Is your feature request related to a problem? Please describe.

Currently, the ruby-sdk does not support the _meta property for tool definitions, which is part of the MCP specification. The TypeScript SDK and other official SDKs include support for _meta fields, allowing clients and servers to attach additional metadata to their interactions. Without this support in the Ruby SDK, Ruby-based MCP servers cannot provide or consume metadata that may be critical for certain protocol extensions or implementation-specific features.

Describe the solution you'd like

Add support for the _meta property in tool definitions within the ruby-sdk, following the MCP specification guidelines:

  1. Update the MCP::Tool class to accept an optional _meta parameter in both class-based and define method approaches
  2. Include _meta in the tool schema serialization when responding to tools/list requests
  3. Validate _meta keys according to the specification format rules (prefix/name segments)
  4. Pass through _meta in tool responses where appropriate

Implementation should follow the pattern used in the TypeScript SDK where _meta is an optional field in tool definitions.

Example usage:

class MyTool < MCP::Tool
  description "Example tool with metadata"
  input_schema(
    properties: { message: { type: "string" } },
    required: ["message"]
  )
  
  # New _meta support
  meta({
    "example.com/priority" => "high",
    "internal-id" => "tool-123"
  })
  
  def self.call(message:, server_context:)
    MCP::Tool::Response.new([{ type: "text", text: "OK" }])
  end
end

# Or with define method
tool = MCP::Tool.define(
  name: "my_tool",
  description: "Example tool",
  _meta: {
    "example.com/priority" => "high"
  }
) do |args, server_context|
  MCP::Tool::Response.new([{ type: "text", text: "OK" }])
end

Describe alternatives you've considered

  1. Workaround via custom annotations: While the SDK supports custom annotations, these don't follow the MCP specification for _meta and aren't interoperable with other MCP implementations.

  2. Fork and patch: Creating a custom fork of the ruby-sdk with _meta support, but this creates maintenance burden and diverges from the official SDK.

  3. Wait for automatic generation: Since the TypeScript SDK already supports _meta, waiting for this to be ported might be an option, but proactive implementation would benefit Ruby users sooner.

Additional context

The _meta property is defined in the MCP specification ([source](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/basic/index.mdx#general-fields)) as a reserved property for attaching metadata. The TypeScript SDK implementation in types.ts includes _meta as an optional field in tool definitions.

Key specification requirements for _meta:

  • Keys must follow the format: optional prefix (with /) + name
  • Prefixes use dot-separated labels ending with /
  • The modelcontextprotocol.* and mcp.* prefixes are reserved
  • Names must begin/end with alphanumeric characters

This feature would bring the ruby-sdk to feature parity with other official SDKs and enable more sophisticated MCP implementations in Ruby.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions