Add support for standard MCP tool annotations

Phase 1: Add Annotation Generation Logic ✅

This MR implements Phase 1 of #73 - adding the core annotation generation logic based on HTTP method semantics.

Related to #73 (does not close the issue - Phase 3/4 still needed for integration testing and documentation)

Task List

Implementation

• Import ToolAnnotations from rmcp::model
• Add generate_annotations() method to ToolMetadata impl
• Implement HTTP verb to annotation mapping for GET/HEAD/OPTIONS
• Implement HTTP verb to annotation mapping for POST
• Implement HTTP verb to annotation mapping for PUT
• Implement HTTP verb to annotation mapping for PATCH
• Implement HTTP verb to annotation mapping for DELETE
• Handle unknown/unsupported HTTP methods (return None)
• Update From<&ToolMetadata> for Tool to use generate_annotations()

Documentation

• Add inline documentation to generate_annotations() method
• Document HTTP verb to annotation mapping rationale in code comments
• Update module-level documentation

Validation

• Verify HTTP method comparison is case-insensitive
• Ensure no breaking changes to existing API
• Confirm code compiles without errors

---

Phase 2: Add Comprehensive Unit Tests ✅

Phase 2 adds comprehensive unit tests for the generate_annotations() method.

Task List

Test Implementation

• Create test module in metadata.rs
• Add helper function create_test_metadata() for creating test fixtures
• Test GET annotations (read-only, non-destructive, idempotent)
• Test POST annotations (non-read-only, non-destructive, non-idempotent)
• Test PUT annotations (non-read-only, destructive, idempotent)
• Test PATCH annotations (non-read-only, destructive, non-idempotent)
• Test DELETE annotations (non-read-only, destructive, idempotent)
• Test HEAD annotations (same as GET)
• Test OPTIONS annotations (same as GET)
• Test unknown method edge case (TRACE, CONNECT, etc. return None)
• Test case-insensitive matching (GET, get, Get, etc.)
• Test annotations title field is always None

Quality Checks

• Run cargo test --package rmcp-openapi --all-features - all tests pass
• Run cargo clippy --package rmcp-openapi --all-features - no warnings
• Run cargo fmt - code formatted

---

Phase 4: Documentation Updates ✅

Phase 4 adds user-facing documentation for the MCP tool annotations feature.

Task List

README Documentation

• Add MCP Tool Annotations bullet to Features section
• Add new "MCP Tool Annotations" section with HTTP method mapping table
• Include example showing annotation values for GET operation
• Add references to HTTP semantics RFC and MCP specification

Quality Checks

• Run cargo fmt - code formatted
• Build documentation with cargo doc - successful

---

Changes

File: crates/rmcp-openapi/src/tool/metadata.rs

• Import ToolAnnotations from rmcp::model
• Add comprehensive generate_annotations() method with HTTP method-based annotation mapping
• Update Tool conversion to include generated annotations
• Add module-level documentation about annotation support
• Add comprehensive test module with 10 unit tests
• Update snapshot tests to reflect new annotations field (StreamableHttp and SSE transports)

File: README.md

• Add "MCP Tool Annotations" feature bullet to Features section
• Add new "MCP Tool Annotations" section (line 306-327) with:
  • HTTP method to annotation mapping table
  • Example annotation values for GET operation
  • Links to RFC 9110 and MCP specification

Updated Snapshot Files:

• test_with_js__js_streamable_http_client_responses.snap
• test_with_js__js_streamable_http_client_responses_with_refs.snap
• test_with_js__sse_tests__js_sse_client_responses.snap (SSE transport)
• test_with_js__sse_tests__js_sse_client_responses_with_refs.snap (SSE transport)
• test_with_python__sse_tests__python_sse_client_responses.snap (SSE transport)
• test_with_python__sse_tests__python_sse_client_responses_with_refs.snap (SSE transport)

---

Completion Status

✅ Phase 1: Core annotation generation logic - COMPLETE ✅ Phase 2: Comprehensive unit tests - COMPLETE ✅ Phase 4: Documentation updates - COMPLETE

Note: Phase 3 (additional integration testing) was determined unnecessary as existing snapshot tests already provide sufficient integration test coverage for the annotations feature.