Migrating to 1.x

[alexhancock]

Upgrading to RMCP 1.x — Migration Guide

After PR #715 lands, most public model structs become #[non_exhaustive] and gain builder-style constructors. Direct struct-literal construction will no longer compile. This guide covers every breaking change and how to fix it.

---

TL;DR

What changed	Old pattern	New pattern
Struct construction	Foo { field_a, field_b, .. }	Foo::new(required_fields).with_optional(val)
#[non_exhaustive] on structs	Could use ..Default::default()	Must use ::new() + .with_*() builders
#[non_exhaustive] on enums/errors	Exhaustive match	Add _ => {} catch-all arm
Tool::with_execution signature	with_execution(self, ToolExecution)	with_execution(self, Option<ToolExecution>)

---

1. ServerInfo / InitializeResult

Before:

ServerInfo {
    instructions: Some("A calculator".into()),
    capabilities: ServerCapabilities::builder().enable_tools().build(),
    ..Default::default()
}

After:

ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
    .with_instructions("A calculator")

Other builders: .with_server_info(impl), .with_protocol_version(ver).

---

2. CallToolRequestParams

Before:

CallToolRequestParams {
    meta: None,
    name: "my_tool".into(),
    arguments: Some(serde_json::json!({"a": 1}).as_object().cloned().unwrap()),
    task: None,
}

After:

CallToolRequestParams::new("my_tool")
    .with_arguments(serde_json::json!({"a": 1}).as_object().cloned().unwrap())

---

3. GetPromptRequestParams

Before:

GetPromptRequestParams {
    meta: None,
    name: "my_prompt".into(),
    arguments: Some(args),
}

After:

GetPromptRequestParams::new("my_prompt")
    .with_arguments(args)

---

4. GetPromptResult

Before:

GetPromptResult {
    description: Some("Help text".to_string()),
    messages: vec![...],
}

After:

GetPromptResult::new(vec![...])
    .with_description("Help text")

---

5. InitializeRequestParams / ClientInfo

Before:

InitializeRequestParams {
    meta: None,
    protocol_version: ProtocolVersion::LATEST,
    capabilities: ClientCapabilities { elicitation: Some(...), ..Default::default() },
    client_info: Implementation {
        name: "my-client".to_string(),
        version: "1.0.0".to_string(),
        title: None,
        description: None,
        website_url: None,
        icons: None,
    },
}

After:

InitializeRequestParams::new(
    ClientCapabilities::builder()
        .enable_elicitation_with(elicitation_cap)
        .build(),
    Implementation::new("my-client", "1.0.0"),
)

---

6. Implementation

Before:

Implementation {
    name: "my-server".to_string(),
    version: "0.1.0".to_string(),
    title: None, description: None, website_url: None, icons: None,
}

After:

Implementation::new("my-server", "0.1.0")

---

7. CreateMessageResult

Before:

CreateMessageResult {
    message: SamplingMessage::assistant_text("Hello"),
    model: "test-model".to_string(),
    stop_reason: Some("endTurn".to_string()),
}

After:

CreateMessageResult::new(
    SamplingMessage::assistant_text("Hello"),
    "test-model".to_string(),
)
.with_stop_reason(Some("endTurn".to_string()))

---

8. CreateMessageRequestParams

Before:

CreateMessageRequestParams {
    meta: None, task: None,
    messages: vec![...],
    model_preferences: None,
    system_prompt: Some("You are helpful".into()),
    include_context: None,
    temperature: Some(0.7),
    max_tokens: 1024,
    stop_sequences: None, metadata: None, tools: None, tool_choice: None,
}

After:

CreateMessageRequestParams::new(vec![...], 1024)
    .with_system_prompt("You are helpful")
    .with_temperature(0.7)

---

9. Tool (manual construction)

Before:

Tool {
    name: "my_tool".into(),
    title: None,
    description: Some("Does stuff".into()),
    input_schema: schema.into(),
    output_schema: None,
    annotations: None,
    execution: None,
    icons: None,
    meta: None,
}

After:

Tool::new_with_raw("my_tool", Some("Does stuff".into()), schema)

Optional chaining: .with_title(t), .with_annotations(a), .with_execution(e), .with_icons(i), .with_meta(m), .with_raw_output_schema(s).

⚠️ Signature change: Tool::with_execution now takes Option<ToolExecution> instead of ToolExecution. Wrap your value in Some(...).

---

10. ToolAnnotations

Before:

Some(ToolAnnotations {
    title: Some("My Tool".into()),
    read_only_hint: Some(true),
    destructive_hint: None,
    idempotent_hint: None,
    open_world_hint: None,
})

After:

Some(ToolAnnotations::from_raw(
    Some("My Tool".into()),
    Some(true),  // read_only_hint
    None,        // destructive_hint
    None,        // idempotent_hint
    None,        // open_world_hint
))

Or use the existing builder: ToolAnnotations::new().with_title("My Tool")...

---

11. Task

Before:

Task {
    task_id, status: TaskStatus::Working,
    status_message: Some("Accepted".into()),
    created_at: ts.clone(), last_updated_at: ts,
    ttl: None, poll_interval: None,
}

After:

Task::new(task_id, TaskStatus::Working, ts.clone(), ts)
    .with_status_message("Accepted")

---

12. Other Structs with New Constructors

Struct	Constructor
ReadResourceRequestParams	::new(uri)
ReadResourceResult	::new(contents)
SubscribeRequestParams	::new(uri)
SetLevelRequestParams	::new(level)
ProgressNotificationParam	::new(token, progress)
CompleteRequestParams	::new(ref, argument).with_context(ctx)
CompleteResult	::new(completion)
Icon	::new(src).with_mime_type(m).with_sizes(s)
Prompt	::new(name, desc).with_title(t) or ::from_raw(...)
PromptArgument	::new(name).with_description(d).with_required(b)
PromptMessage	::new(role, content)
ModelPreferences	::new().with_hints(h).with_cost_priority(f)
ModelHint	::new(name)
CreateElicitationResult	::new(action) or ::with_content(action, val)
ListTasksResult	::new(tasks)
CreateTaskResult	::new(task)
GetTaskPayloadResult	::new(value)
JsonRpcRequest	::new(id, request)
JsonRpcError	::new(id, error)
RequestContext	::new(id, peer)
RawEmbeddedResource	::new(resource)
ConstTitle	::new(const_, title)
TitledSingleSelectEnumSchema	::new(one_of)
TitledMultiSelectEnumSchema	::new(items).with_min_items(n)...
TitledItems	::new(any_of)
ResourceUpdatedNotificationParam	::new(uri)
LoggingMessageNotificationParam	::new(level, data) or ::with_logger(level, logger, data)
ElicitationResponseNotificationParam	::new(elicitation_id)

---

13. #[non_exhaustive] Enums & Errors

Several error enums and a few other enums are now #[non_exhaustive]:

• RmcpError
• ClientInitializeError
• ServerInitializeError
• ElicitationError
• AuthError
• StreamableHttpError
• StreamableHttpProtocolError
• StreamableHttpPostResponse
• WorkerQuitReason
• SessionQuitReason
• LocalSessionWorkerError
• QuitReason
• ElicitationAction (add _ => {} in match arms)

Fix: Add a wildcard arm to any match on these types:

match err {
    RmcpError::Service(e) => { /* ... */ }
    // ... other variants ...
    _ => { /* handle unknown future variants */ }
}

---

14. Notification Construction

Notifications now have a ::new(params) constructor instead of struct literals:

Before:

ElicitationCompletionNotification {
    method: ElicitationCompletionNotificationMethod,
    params: notification_params,
    extensions: Default::default(),
}

After:

ElicitationCompletionNotification::new(notification_params)

Same pattern applies to CreateElicitationRequest::new(params).

---

15. ClientCapabilities Builder

Elicitation capabilities now go through the builder:

Before:

ClientCapabilities {
    elicitation: Some(ElicitationCapability { ... }),
    ..Default::default()
}

After:

ClientCapabilities::builder()
    .enable_elicitation_with(ElicitationCapability { ... })
    .build()

---

Quick Migration Checklist

• Search for struct-literal construction of any type listed above → replace with ::new() + .with_*()
• Search for ..Default::default() on affected types → replace with builder
• Search for match on any newly #[non_exhaustive] enum → add _ => {} arm
• Check Tool::with_execution call sites → wrap argument in Some(...)
• Run cargo build and follow remaining compiler errors — the compiler is your friend here

---

Generated 2026-03-02. Based on rust-sdk PR #715.