test(openapi): add test and docs for nullable field schema workaround (modelcontextprotocol#135)

Author: Hendler

README.md

@@ -206,3 +206,6 @@ See [examples](examples/README.md)
 
 ## Development with Dev Container
 See [docs/DEVCONTAINER.md](docs/DEVCONTAINER.md) for instructions on using Dev Container for development.
+
+## Workarounds
+See [docs/WORKAROUNDS.md](docs/WORKAROUNDS.md) for common issues.

crates/rmcp/tests/test_tool_macros.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
 use rmcp::{ServerHandler, handler::server::tool::ToolCallContext, tool};
-use schemars::JsonSchema;
+use schemars::{JsonSchema, schema_for};
 use serde::{Deserialize, Serialize};
 
 #[derive(Serialize, Deserialize, JsonSchema)]
@@ -100,3 +100,87 @@ async fn test_tool_macros_with_generics() {
 }
 
 impl GetWeatherRequest {}
+
+#[test]
+fn test_optional_field_schema_generation() {
+    // tests https://github.com/modelcontextprotocol/rust-sdk/issues/135
+    #[derive(Debug, Deserialize, Serialize, JsonSchema)]
+    pub struct DefaultOptionalSchema {
+        #[schemars(description = "An optional description field")]
+        pub description: Option<String>,
+    }
+
+    let schema = schema_for!(DefaultOptionalSchema);
+    let schema_json = serde_json::to_value(&schema).unwrap();
+
+    // Print the actual generated schema for debugging
+    println!(
+        "Actual schema for DefaultOptionalSchema: {:#?}",
+        schema_json
+    );
+
+    // Verify the default schema generation for Option<String>
+    // This format (`type: [T, 'null']`) is reported as incompatible with some clients (Cursor, Windsurf).
+    let description_schema = &schema_json["properties"]["description"];
+    assert_eq!(
+        description_schema["type"],
+        serde_json::json!(["string", "null"]),
+        "Default schema for Option<String> should be type: [\"string\", \"null\"] as per schemars default"
+    );
+    // Ensure 'nullable' field is NOT present at this level in the default schema
+    assert!(
+        description_schema.get("nullable").is_none(),
+        "Default schema should not have top-level 'nullable' field"
+    );
+
+    // We still check the description is correct
+    assert_eq!(
+        description_schema["description"],
+        "An optional description field"
+    );
+
+    // --- Demonstrate the workaround ---
+
+    // Custom schema function for the workaround for https://github.com/modelcontextprotocol/rust-sdk/issues/135
+    pub fn nullable_string_schema(
+        _: &mut schemars::r#gen::SchemaGenerator,
+    ) -> schemars::schema::Schema {
+        serde_json::from_value(serde_json::json!({
+            "type": "string",
+            "nullable": true,
+            // Note: Description needs to be reapplied here if using schema_with
+            "description": "An optional description field (workaround)"
+        }))
+        .unwrap()
+    }
+
+    #[derive(Debug, Deserialize, Serialize, JsonSchema)]
+    pub struct WorkaroundOptionalSchema {
+        #[schemars(
+            schema_with = "nullable_string_schema",
+            description = "An optional description field (workaround)" // Description here is mainly for docs, schema_with overrides generated schema description
+        )]
+        #[serde(default)] // Needed for deserialization when field is absent
+        pub description: Option<String>,
+    }
+
+    let schema_workaround = schema_for!(WorkaroundOptionalSchema);
+    let schema_workaround_json = serde_json::to_value(&schema_workaround).unwrap();
+
+    // Verify the workaround schema generation
+    let description_schema_workaround = &schema_workaround_json["properties"]["description"];
+    assert_eq!(
+        description_schema_workaround["type"],
+        serde_json::json!("string"),
+        "Workaround schema for Option<String> should be type: \"string\""
+    );
+    assert_eq!(
+        description_schema_workaround["nullable"],
+        serde_json::json!(true),
+        "Workaround schema for Option<String> should have nullable: true"
+    );
+    assert_eq!(
+        description_schema_workaround["description"],
+        "An optional description field (workaround)"
+    );
+}

docs/WORKAROUNDS.md

@@ -0,0 +1,70 @@
+# Workarounds
+
+## Optional Field Schema Compatibility (OpenAPI 3.0 vs 3.1 Style)
+
+### Reason
+
+The `schemars` crate, used for generating JSON schemas for tool parameters, defaults to representing optional fields (like `Option<String>`) using the `type: ["string", "null"]` format. This is valid according to the OpenAPI 3.0 specification.
+
+However, some clients or tools (e.g., Cursor, Windsurf, tools expecting OpenAPI 3.1+ style schemas) might expect optional fields to be represented differently, typically using `type: "string", nullable: true`.
+
+This difference in representation can lead to compatibility issues where the client fails to correctly interpret the schema for optional parameters.
+
+### Workaround
+
+To ensure maximum compatibility, you can explicitly instruct `schemars` to generate the `type: "T", nullable: true` format using a combination of `#[schemars(schema_with = ...)]` and `#[serde(default)]`.
+
+1.  **Define a helper function** that generates the desired schema format:
+
+    ```rust
+    // Place this in a shared module or utils file
+    pub fn nullable_string_schema(_: &mut schemars::r#gen::SchemaGenerator) -> schemars::schema::Schema {
+        serde_json::from_value(serde_json::json!({
+            "type": "string",
+            "nullable": true,
+            // Note: The description from the field's #[schemars] attribute
+            // needs to be manually added here if desired in the final schema.
+            // Alternatively, omit it if the description from the attribute is sufficient.
+            // "description": "An optional description field (workaround)"
+        })).unwrap()
+    }
+    
+    // Add similar functions for other types like Option<i64>, Option<bool> etc. if needed
+    pub fn nullable_i64_schema(_: &mut schemars::r#gen::SchemaGenerator) -> schemars::schema::Schema {
+        serde_json::from_value(serde_json::json!({
+            "type": "integer",
+            "format": "int64",
+            "nullable": true
+        })).unwrap()
+    }
+    ```
+
+2.  **Apply the attributes** to your `Option<T>` field:
+
+    ```rust
+    use schemars::JsonSchema;
+    use serde::{Deserialize, Serialize};
+    // Assuming nullable_string_schema is in scope
+    // use path::to::nullable_string_schema;
+    
+    #[derive(Debug, Deserialize, Serialize, JsonSchema)]
+    pub struct UpdateTaskRequest {
+        #[schemars(
+            schema_with = "nullable_string_schema",
+            description = "A new short description of the task" // This description is still useful for documentation generation
+        )]
+        #[serde(default)] // Needed for correct deserialization when the field is absent
+        pub description: Option<String>,
+    }
+    ```
+
+This forces the generation of the more widely compatible schema format for the optional field.
+
+### Status
+
+- Tracked in issue: [https://github.com/modelcontextprotocol/rust-sdk/issues/135](https://github.com/modelcontextprotocol/rust-sdk/issues/135)
+
+
+
+
+