UserGeneratedLLC
diff --git a/‎crates/rmcp/Cargo.toml‎
Lines changed: 7 additions & 0 deletions b/‎crates/rmcp/Cargo.toml‎
Lines changed: 7 additions & 0 deletions
diff --git a/‎crates/rmcp/src/anthropic_ext.rs‎
Lines changed: 301 additions & 27 deletions b/‎crates/rmcp/src/anthropic_ext.rs‎
Lines changed: 301 additions & 27 deletions
@@ -16,6 +16,7 @@ exhaustive_enums = "warn"
 [package.metadata.docs.rs]
 features = [
   "anthropic-ext",
+  "sep-2243-draft",
   "auth",
   "auth-client-credentials-jwt",
   "base64",
@@ -125,6 +126,12 @@ elicitation = ["dep:url"]
 # the fleet targets Claude Code as the MCP client.
 anthropic-ext = []
 
+# Forward-looking scaffold for SEP-2243 (HTTP Header Standardization, Draft).
+# Exposes header-name constants, `Tool::with_mcp_header_param` builder, and
+# server-side header extraction. Full transport-layer plumbing lands when
+# SEP-2243 finalizes. Off by default.
+sep-2243-draft = []
+
 # reqwest http client
 __reqwest = ["dep:reqwest"]
 
 
@@ -1,22 +1,54 @@
 //! Claude Code-specific MCP extensions.
 //!
-//! Claude Code (claude-cli) implements two server-facing extensions that aren't in
-//! the upstream MCP spec: a per-tool output-size override carried in `_meta`
-//! (`anthropic/maxResultSizeChars`, raising the default 25k-token cap up to a
-//! 500 000-char ceiling), and an experimental push-message capability
-//! (`claude/channel`). This module exposes constants plus a [`Tool`] builder
-//! extension so servers can opt into both without hand-rolling JSON keys.
+//! Claude Code (claude-cli) implements several server-facing extensions that
+//! aren't in the upstream MCP spec. This module exposes first-class Rust APIs
+//! for each of them so servers can opt in without hand-rolling JSON keys or
+//! notification wire formats.
+//!
+//! - `anthropic/maxResultSizeChars` - per-tool `_meta` entry raising Claude
+//!   Code's default 25 000-token output cap up to a 500 000-char ceiling.
+//! - `claude/channel` - experimental capability Claude Code honours when
+//!   started with `--channels`, allowing the server to push out-of-band
+//!   events into the running session.
+//! - `claude/channel/permission` - companion capability (Claude Code v2.1.81+)
+//!   that opts the channel into remote permission-relay for tool approvals.
+//! - `notifications/claude/channel` - the notification method a channel emits
+//!   to push events; payload is `{ content, meta? }`.
+//! - `structured_with_text_fallback` - MCP 2025-11-25 spec ("a tool that
+//!   returns structured content SHOULD also return the serialized JSON in a
+//!   TextContent block") + workaround for Claude Code #41361 (blank UI when
+//!   `structuredContent` fails `outputSchema.safeParse`). Pushes a
+//!   human-readable summary `Content::text` alongside the `Json<T>` structured
+//!   value.
+//! - `lint::warn_if_over_2kb` - pure `tracing::warn!` helper catching Claude
+//!   Code's silent 2 KB truncation of tool descriptions and server
+//!   `instructions`.
 //!
 //! All members are passive: they emit what Claude Code expects and are
 //! silently ignored by every other MCP client.
 //!
-//! See <https://docs.anthropic.com/en/docs/claude-code/mcp>.
+//! See <https://docs.anthropic.com/en/docs/claude-code/mcp> and
+//! <https://code.claude.com/docs/en/channels-reference>.
 //!
 //! Enable via the `anthropic-ext` cargo feature on `rmcp`.
 
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
-use crate::model::{ExtensionCapabilities, JsonObject, Meta, Tool};
+use crate::model::{ExperimentalCapabilities, JsonObject, Meta, Tool};
+#[cfg(feature = "server")]
+use crate::{
+    RoleServer,
+    handler::server::{tool::IntoCallToolResult, wrapper::Json},
+    model::{CallToolResult, Content, CustomNotification, ServerNotification},
+    service::{Peer, ServiceError},
+};
+
+// ---------------------------------------------------------------------------
+// Per-tool output-size override (`anthropic/maxResultSizeChars`)
+// ---------------------------------------------------------------------------
 
 /// `_meta` key Claude Code honours on a tool's `tools/list` entry to raise the
 /// per-tool text-output size threshold past the default 25 000-token cap.
@@ -28,13 +60,6 @@ pub const MAX_RESULT_SIZE_CHARS_META_KEY: &str = "anthropic/maxResultSizeChars";
 /// Tools requesting a larger threshold are clamped to this value.
 pub const MAX_RESULT_SIZE_CHARS_CEILING: u32 = 500_000;
 
-/// Experimental capability key Claude Code looks for when started with
-/// `--channels`, allowing the server to push messages into the session
-/// as out-of-band notifications.
-///
-/// See <https://docs.anthropic.com/en/docs/claude-code/mcp#push-messages-with-channels>.
-pub const CLAUDE_CHANNEL_CAPABILITY: &str = "claude/channel";
-
 impl Tool {
     /// Claude Code-specific: set the `anthropic/maxResultSizeChars` `_meta`
     /// entry on this tool, raising the per-tool text-output threshold in
@@ -91,19 +116,176 @@ pub fn anthropic_max_result_size_chars_meta(chars: u32) -> Meta {
     meta
 }
 
-/// Insert the `claude/channel` extension capability into an
-/// [`ExtensionCapabilities`] map with empty settings. Pass the resulting map
-/// to [`ServerCapabilitiesBuilder::enable_extensions_with`] when building
-/// your server's [`ServerCapabilities`].
+// ---------------------------------------------------------------------------
+// Channels (`claude/channel` + `claude/channel/permission`)
+// ---------------------------------------------------------------------------
+
+/// Experimental capability key Claude Code looks for when started with
+/// `--channels`, allowing the server to push messages into the session
+/// as out-of-band notifications.
+///
+/// See <https://code.claude.com/docs/en/channels-reference>.
+pub const CLAUDE_CHANNEL_CAPABILITY: &str = "claude/channel";
+
+/// Experimental capability key Claude Code looks for on channel servers that
+/// want tool-approval prompts relayed through the channel (Claude Code
+/// v2.1.81+). Declare alongside [`CLAUDE_CHANNEL_CAPABILITY`] to opt in.
+///
+/// See <https://code.claude.com/docs/en/channels-reference#relay-permission-prompts>.
+pub const CLAUDE_CHANNEL_PERMISSION_CAPABILITY: &str = "claude/channel/permission";
+
+/// JSON-RPC method name Claude Code listens on for channel events.
+///
+/// See <https://code.claude.com/docs/en/channels-reference#notification-format>.
+pub const CLAUDE_CHANNEL_NOTIFICATION_METHOD: &str = "notifications/claude/channel";
+
+/// Insert the `claude/channel` capability into an
+/// [`ExperimentalCapabilities`] map with empty settings. Pass the resulting
+/// map to
+/// [`ServerCapabilitiesBuilder::enable_experimental_with`](crate::model::ServerCapabilities)
+/// when building your server's [`ServerCapabilities`](crate::model::ServerCapabilities).
+///
+/// Claude Code reads this key from `capabilities.experimental['claude/channel']`
+/// specifically - not the `extensions` field - per the
+/// [Claude Code channels reference](https://code.claude.com/docs/en/channels-reference#server-options).
+/// Silently ignored by every MCP client other than Claude Code.
+pub fn insert_claude_channel(capabilities: &mut ExperimentalCapabilities) {
+    capabilities.insert(CLAUDE_CHANNEL_CAPABILITY.to_string(), JsonObject::new());
+}
+
+/// Insert the `claude/channel/permission` capability into an
+/// [`ExperimentalCapabilities`] map with empty settings. Declare alongside
+/// [`insert_claude_channel`] when the channel wants to receive relayed
+/// tool-approval prompts. Requires Claude Code v2.1.81+.
 ///
 /// Silently ignored by every MCP client other than Claude Code.
+/// See <https://code.claude.com/docs/en/channels-reference#relay-permission-prompts>.
+pub fn insert_claude_channel_permission(capabilities: &mut ExperimentalCapabilities) {
+    capabilities.insert(
+        CLAUDE_CHANNEL_PERMISSION_CAPABILITY.to_string(),
+        JsonObject::new(),
+    );
+}
+
+/// Payload of a [`CLAUDE_CHANNEL_NOTIFICATION_METHOD`] notification.
+///
+/// `content` becomes the body of the `<channel source="..." ...>` tag injected
+/// into Claude's context; each entry in `meta` becomes an attribute on that
+/// tag. Meta keys must be identifiers (letters, digits, underscore) - keys
+/// containing hyphens or other characters are silently dropped by Claude Code
+/// on the receiving side.
+///
+/// See <https://code.claude.com/docs/en/channels-reference#notification-format>.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+#[expect(clippy::exhaustive_structs, reason = "intentionally exhaustive")]
+pub struct ClaudeChannelNotificationParam {
+    /// Body of the `<channel>` tag.
+    pub content: String,
+    /// Optional meta attributes. Keys must match `[A-Za-z0-9_]+`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub meta: Option<BTreeMap<String, String>>,
+}
+
+impl ClaudeChannelNotificationParam {
+    /// Build a new notification payload with only the required `content`.
+    pub fn new(content: impl Into<String>) -> Self {
+        Self {
+            content: content.into(),
+            meta: None,
+        }
+    }
+
+    /// Attach a single meta attribute. The key must match `[A-Za-z0-9_]+` or
+    /// Claude Code will silently drop it.
+    #[must_use]
+    pub fn with_meta(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+        self.meta
+            .get_or_insert_with(BTreeMap::new)
+            .insert(key.into(), value.into());
+        self
+    }
+
+    /// Replace the meta map wholesale.
+    #[must_use]
+    pub fn with_meta_map(mut self, meta: BTreeMap<String, String>) -> Self {
+        self.meta = Some(meta);
+        self
+    }
+}
+
+#[cfg(feature = "server")]
+impl Peer<RoleServer> {
+    /// Push a `notifications/claude/channel` event into the running Claude
+    /// Code session. No-op on every other MCP client (wire-level: the client
+    /// sees an unknown notification and drops it).
+    ///
+    /// See <https://code.claude.com/docs/en/channels-reference#notification-format>.
+    pub async fn notify_claude_channel(
+        &self,
+        params: ClaudeChannelNotificationParam,
+    ) -> Result<(), ServiceError> {
+        // ClaudeChannelNotificationParam contains only `String` + `BTreeMap<String, String>`
+        // fields; serde_json cannot fail for that shape, so an `.expect` is sound.
+        let value = serde_json::to_value(&params)
+            .expect("ClaudeChannelNotificationParam is always serializable");
+        self.send_notification(ServerNotification::CustomNotification(
+            CustomNotification::new(CLAUDE_CHANNEL_NOTIFICATION_METHOD, Some(value)),
+        ))
+        .await
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Structured-content + text-fallback helper
+// ---------------------------------------------------------------------------
+
+/// Build a [`CallToolResult`] carrying both structured JSON (`structured_content`)
+/// and a **human-readable** text summary (`content`). Addresses two concerns at
+/// once:
+///
+/// - **MCP 2025-11-25 spec:** `/server/tools` says "a tool that returns
+///   structured content SHOULD also return the serialized JSON in a
+///   TextContent block". [`Json<T>::into_call_tool_result`] already emits the
+///   serialized JSON as text. This helper appends a second text block that is
+///   human-readable rather than a raw JSON dump.
+/// - **Claude Code #41361:** if `structuredContent` fails the client-side
+///   `outputSchema.safeParse`, Claude Code renders the tool call **blank** in
+///   the UI even though the model still receives the structured value. The
+///   extra human-readable text block stays visible to both.
+///
+/// `text_summary` receives a borrow of the value so callers can render fields
+/// without cloning.
+///
+/// # Example
 ///
-/// [`ServerCapabilitiesBuilder::enable_extensions_with`]: crate::model::ServerCapabilities
-/// [`ServerCapabilities`]: crate::model::ServerCapabilities
-pub fn insert_claude_channel(extensions: &mut ExtensionCapabilities) {
-    extensions.insert(CLAUDE_CHANNEL_CAPABILITY.to_string(), JsonObject::new());
+/// ```ignore
+/// use rmcp::anthropic_ext::structured_with_text_fallback;
+///
+/// let resp = ListPlacesResponse { places, next_cursor, truncated: false };
+/// return structured_with_text_fallback(resp, |r| {
+///     format!("{} places{}", r.places.len(), if r.truncated { " (truncated)" } else { "" })
+/// })
+/// .map_err(|e| e.to_string());
+/// ```
+#[cfg(feature = "server")]
+pub fn structured_with_text_fallback<T>(
+    value: T,
+    text_summary: impl FnOnce(&T) -> String,
+) -> Result<CallToolResult, crate::ErrorData>
+where
+    T: serde::Serialize + schemars::JsonSchema + 'static,
+{
+    let summary = text_summary(&value);
+    let mut result = Json(value).into_call_tool_result()?;
+    result.content.push(Content::text(summary));
+    Ok(result)
 }
 
+// ---------------------------------------------------------------------------
+// Lint helpers
+// ---------------------------------------------------------------------------
+
 /// Lint helpers for catching common Claude Code integration pitfalls at
 /// runtime. All helpers are pure - they `tracing::warn!` when a condition is
 /// violated but never change behavior.
@@ -171,13 +353,76 @@ mod tests {
     }
 
     #[test]
-    fn claude_channel_extension_inserted_empty() {
-        let mut ext = ExtensionCapabilities::new();
-        insert_claude_channel(&mut ext);
-        let stored = ext.get(CLAUDE_CHANNEL_CAPABILITY).expect("capability set");
+    fn claude_channel_capability_inserted_empty() {
+        let mut experimental = ExperimentalCapabilities::new();
+        insert_claude_channel(&mut experimental);
+        let stored = experimental
+            .get(CLAUDE_CHANNEL_CAPABILITY)
+            .expect("capability set");
         assert!(stored.is_empty(), "expected empty settings object");
     }
 
+    #[test]
+    fn claude_channel_capability_lands_on_experimental_builder_field() {
+        use crate::model::ServerCapabilities;
+
+        let mut experimental = ExperimentalCapabilities::new();
+        insert_claude_channel(&mut experimental);
+        let caps = ServerCapabilities::builder()
+            .enable_experimental_with(experimental)
+            .build();
+
+        let experimental = caps.experimental.expect("experimental populated");
+        assert!(
+            experimental.contains_key(CLAUDE_CHANNEL_CAPABILITY),
+            "channel key must land on `capabilities.experimental`, not `.extensions`"
+        );
+        assert!(
+            caps.extensions.is_none(),
+            "extensions field must stay empty when only `experimental` was populated"
+        );
+    }
+
+    #[test]
+    fn claude_channel_permission_coexists_with_channel() {
+        let mut experimental = ExperimentalCapabilities::new();
+        insert_claude_channel(&mut experimental);
+        insert_claude_channel_permission(&mut experimental);
+        assert!(experimental.contains_key(CLAUDE_CHANNEL_CAPABILITY));
+        assert!(experimental.contains_key(CLAUDE_CHANNEL_PERMISSION_CAPABILITY));
+        assert_eq!(experimental.len(), 2);
+    }
+
+    #[test]
+    fn channel_notification_param_round_trips() {
+        let param = ClaudeChannelNotificationParam::new("hello")
+            .with_meta("chat_id", "42")
+            .with_meta("severity", "high");
+
+        let json = serde_json::to_value(&param).expect("serialize");
+        assert_eq!(json["content"], "hello");
+        assert_eq!(json["meta"]["chat_id"], "42");
+        assert_eq!(json["meta"]["severity"], "high");
+
+        let back: ClaudeChannelNotificationParam =
+            serde_json::from_value(json).expect("deserialize");
+        assert_eq!(back.content, "hello");
+        let meta = back.meta.expect("meta preserved");
+        assert_eq!(meta.get("chat_id").map(String::as_str), Some("42"));
+        assert_eq!(meta.get("severity").map(String::as_str), Some("high"));
+    }
+
+    #[test]
+    fn channel_notification_param_omits_meta_when_empty() {
+        let param = ClaudeChannelNotificationParam::new("ping");
+        let json = serde_json::to_value(&param).expect("serialize");
+        assert_eq!(json["content"], "ping");
+        assert!(
+            json.get("meta").is_none(),
+            "meta key should be omitted when None via skip_serializing_if"
+        );
+    }
+
     #[test]
     fn anthropic_max_result_size_chars_meta_under_ceiling() {
         let meta = anthropic_max_result_size_chars_meta(100_000);
@@ -217,4 +462,33 @@ mod tests {
         let body = "x".repeat(lint::SIZE_LIMIT_BYTES);
         assert!(!lint::warn_if_over_2kb("test", &body));
     }
+
+    #[cfg(feature = "server")]
+    #[test]
+    fn structured_with_text_fallback_appends_summary() {
+        #[derive(serde::Serialize, schemars::JsonSchema)]
+        struct Resp {
+            count: u32,
+        }
+
+        let result =
+            structured_with_text_fallback(Resp { count: 3 }, |r| format!("{} items", r.count))
+                .expect("structured result");
+
+        assert!(
+            result.structured_content.is_some(),
+            "structured content set"
+        );
+        // Json<T>::into_call_tool_result pushes one text entry (the serialized
+        // JSON); we append a second human-readable summary.
+        assert_eq!(result.content.len(), 2, "serialized JSON + summary");
+
+        let last_text = result
+            .content
+            .last()
+            .expect("content non-empty")
+            .as_text()
+            .expect("final entry is text");
+        assert_eq!(last_text.text, "3 items");
+    }
 }