From c588582acc76e02adc538e33fa1f740e3cc6227f Mon Sep 17 00:00:00 2001
From: Yuki Minamiya <y.minamiya@gmail.com>
Date: Sun, 14 Jun 2026 16:25:44 +0900
Subject: [PATCH] Add range validation for `MCP::Annotations#priority` per MCP
 specification
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Motivation and Context

The MCP specification constrains `Annotations.priority` to the 0–1 range
(`@minimum 0`, `@maximum 1`), but the Ruby SDK accepts any value. The other
official SDKs already enforce this (TypeScript, Python, and PHP).

This follows the existing pattern in `MCP::Icon`, which validates its
constrained `theme` value in the constructor and raises `ArgumentError`.

## How Has This Been Tested?

Added tests in `test/mcp/annotations_test.rb`:

- valid `priority` at the lower (0) and upper (1) bounds is accepted
- out-of-range `priority` (above 1, below 0) raises `ArgumentError`

The full unit suite and RuboCop pass locally.

## Breaking Changes

Strictly speaking yes: a caller that currently passes an out-of-range
`priority` (e.g. `priority: 99`) will now get an `ArgumentError`. Such values
already violate the MCP specification, and `nil` / in-range values are
unaffected.
---
 lib/mcp/annotations.rb       |  2 ++
 test/mcp/annotations_test.rb | 26 ++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/lib/mcp/annotations.rb b/lib/mcp/annotations.rb
index 9674c73e..540588a6 100644
--- a/lib/mcp/annotations.rb
+++ b/lib/mcp/annotations.rb
@@ -5,6 +5,8 @@ class Annotations
     attr_reader :audience, :priority, :last_modified
 
     def initialize(audience: nil, priority: nil, last_modified: nil)
+      raise ArgumentError, "The value of priority must be between 0 and 1." if priority && !priority.between?(0, 1)
+
       @audience = audience
       @priority = priority
       @last_modified = last_modified
diff --git a/test/mcp/annotations_test.rb b/test/mcp/annotations_test.rb
index 60bfa722..a82b9552 100644
--- a/test/mcp/annotations_test.rb
+++ b/test/mcp/annotations_test.rb
@@ -55,5 +55,31 @@ def test_initialization_with_last_modified_only
 
       assert_equal({ lastModified: timestamp }, annotations.to_h)
     end
+
+    def test_valid_priority_at_lower_bound
+      assert_nothing_raised do
+        Annotations.new(priority: 0)
+      end
+    end
+
+    def test_valid_priority_at_upper_bound
+      assert_nothing_raised do
+        Annotations.new(priority: 1)
+      end
+    end
+
+    def test_invalid_priority_above_upper_bound
+      exception = assert_raises(ArgumentError) do
+        Annotations.new(priority: 1.5)
+      end
+      assert_equal("The value of priority must be between 0 and 1.", exception.message)
+    end
+
+    def test_invalid_priority_below_lower_bound
+      exception = assert_raises(ArgumentError) do
+        Annotations.new(priority: -0.1)
+      end
+      assert_equal("The value of priority must be between 0 and 1.", exception.message)
+    end
   end
 end