Escape quotes propertly, preserve paragraph breaks, but replace single paragraph breaks with space. Fixes #12

Author: odrobnik

Demos/SwiftMCPDemo/Calculator.swift

@@ -3,12 +3,22 @@ import SwiftMCP
 
 /**
  A Calculator for simple math doing additionals, subtractions etc.
+ 
+ Testing "quoted" stuff. And on multiple lines. 'single quotes'
  */
 @MCPServer(name: "SwiftMCP Demo")
 actor Calculator {
 
 	// must be CaseIterable to 
-	enum Options {
+	enum Options: CaseIterable, CustomStringConvertible {
+		var description: String
+		{
+			switch self {
+				case .all: return "ALL"
+				case .unread: return "UNREAD"
+			}
+		}
+		
 		case all
 		case unread
 	}

Sources/SwiftMCPMacros/Documentation.swift

@@ -23,6 +23,7 @@ struct Documentation {
 
 		// Remove comment markers and extra whitespace from each line.
 		var cleanedLines = [String]()
+		var previousLineWasEmpty = false
 		for var line in lines {
 			// Trim whitespace first.
 			line = line.trimmingCharacters(in: .whitespaces)
@@ -51,10 +52,15 @@ struct Documentation {
 			// Remove unprintable ASCII characters
 			line = line.removingUnprintableCharacters
 
-			// If the line isn't empty after cleaning, keep it.
-			if !line.isEmpty {
+			// If the line is empty and the previous line wasn't empty, keep it to preserve paragraph breaks
+			if line.isEmpty {
+				if !previousLineWasEmpty {
+					cleanedLines.append(line)
+				}
+			} else {
 				cleanedLines.append(line)
 			}
+			previousLineWasEmpty = line.isEmpty
 		}
 
 		// We'll accumulate the initial description and any parameter descriptions.
@@ -73,7 +79,8 @@ struct Documentation {
 		func flushCurrentParameter() {
 			if let paramName = currentParameterName {
 				let fullDescription = currentParameterLines.joined(separator: " ").trimmingCharacters(in: .whitespaces)
-				parameters[paramName] = fullDescription
+				// Escape the description when storing it
+				parameters[paramName] = fullDescription.escapedForSwiftString
 			}
 			currentParameterName = nil
 			currentParameterLines = []
@@ -209,15 +216,45 @@ struct Documentation {
 		// Flush any parameter still being accumulated.
 		flushCurrentParameter()
 
-		// Combine initial description lines into a single string.
-		let initialDescription = initialDescriptionLines.joined(separator: " ").trimmingCharacters(in: .whitespaces)
+		// Combine initial description lines into a single string, preserving paragraph breaks
+		var initialDescription = ""
+		previousLineWasEmpty = false  // Reuse the existing variable
+		for line in initialDescriptionLines {
+			if line.isEmpty {
+				if !previousLineWasEmpty {
+					initialDescription += "\n\n"
+				}
+			} else {
+				if !initialDescription.isEmpty && !previousLineWasEmpty {
+					initialDescription += " "
+				}
+				initialDescription += line
+			}
+			previousLineWasEmpty = line.isEmpty
+		}
+		initialDescription = initialDescription.trimmingCharacters(in: .whitespacesAndNewlines)
 
-		// Combine returns lines into a single string.
-		let returnsDescription = returnsLines.isEmpty ? nil : returnsLines.joined(separator: " ").trimmingCharacters(in: .whitespaces)
+		// Combine returns lines into a single string, preserving paragraph breaks
+		var returnsDescription = ""
+		previousLineWasEmpty = false  // Reuse the existing variable
+		for line in returnsLines {
+			if line.isEmpty {
+				if !previousLineWasEmpty {
+					returnsDescription += "\n\n"
+				}
+			} else {
+				if !returnsDescription.isEmpty && !previousLineWasEmpty {
+					returnsDescription += " "
+				}
+				returnsDescription += line
+			}
+			previousLineWasEmpty = line.isEmpty
+		}
+		returnsDescription = returnsDescription.trimmingCharacters(in: .whitespacesAndNewlines)
 
-		self.description = initialDescription
+		self.description = initialDescription.escapedForSwiftString
 		self.parameters = parameters
-		self.returns = returnsDescription
+		self.returns = returnsDescription.isEmpty ? nil : returnsDescription.escapedForSwiftString
 	}
 }
 
@@ -239,13 +276,3 @@ fileprivate func parseParameterLine(from line: String) -> (name: String, descrip
 	}
 	return nil
 }
-
-extension String {
-	var removingUnprintableCharacters: String {
-		// Create a character set of printable ASCII characters (32-126) plus newline, tab, etc.
-		let printableCharacters = CharacterSet(charactersIn: " \t\n\r").union(CharacterSet(charactersIn: UnicodeScalar(32)...UnicodeScalar(126)))
-		
-		// Filter out any characters that are not in the printable set
-		return unicodeScalars.filter { printableCharacters.contains($0) }.map { String($0) }.joined()
-	}
-}

Sources/SwiftMCPMacros/MCPServerMacro.swift

@@ -100,7 +100,7 @@ public struct MCPServerMacro: MemberMacro, ExtensionMacro {
 		// Extract description from leading documentation
 		let leadingTrivia = declaration.leadingTrivia.description
 		let documentation = Documentation(from: leadingTrivia)
-		let serverDescription = documentation.description.isEmpty ? "nil" : "\"\(documentation.description.replacingOccurrences(of: "\"", with: "\\\""))\""
+		let serverDescription = documentation.description.isEmpty ? "nil" : "\"\(documentation.description)\""
 
 		let nameProperty = "private let __mcpServerName = \"\(serverName)\""
 		let versionProperty = "private let __mcpServerVersion = \"\(serverVersion)\""

Sources/SwiftMCPMacros/MCPToolMacro.swift

@@ -82,7 +82,6 @@ public struct MCPToolMacro: PeerMacro {
 					let stringValue = stringLiteral.segments.description
 					// Remove quotes and escape special characters for string interpolation
 					let cleanedValue = stringValue
-						.replacingOccurrences(of: "\"", with: "\\\"")
 					descriptionArg = "\"\(cleanedValue)\""
 					hasExplicitDescription = true
 					break
@@ -111,12 +110,8 @@ public struct MCPToolMacro: PeerMacro {
 			}
 			// Use the extracted description if available
 			else if !documentation.description.isEmpty {
-				// Ensure the description is properly escaped and doesn't contain unprintable characters
-				let escapedDescription = documentation.description
-					.replacingOccurrences(of: "\"", with: "\\\"")
-					.replacingOccurrences(of: "\t", with: " ")  // Replace tabs with spaces
-				
-				descriptionArg = "\"\(escapedDescription)\""
+				// The description is already escaped from the Documentation struct
+				descriptionArg = "\"\(documentation.description)\""
 				foundDescriptionInDocs = true
 			}
 		}
@@ -169,12 +164,8 @@ public struct MCPToolMacro: PeerMacro {
 			} 
 			// Get parameter description from the Documentation struct
 			else if let description = documentation.parameters[paramName], !description.isEmpty {
-				// Ensure the parameter description is properly escaped and doesn't contain unprintable characters
-				let escapedDescription = description
-					.replacingOccurrences(of: "\"", with: "\\\"")
-					.replacingOccurrences(of: "\t", with: " ")  // Replace tabs with spaces
-				
-				paramDescription = "\"\(escapedDescription)\""
+				// The description is already escaped from the Documentation struct
+				paramDescription = "\"\(description)\""
 			}
 
 			// Extract default value if it exists
@@ -228,7 +219,7 @@ public struct MCPToolMacro: PeerMacro {
 				\(parameterString.split(separator: ",").map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }.joined(separator: ",\n        "))
 			],
 			returnType: \(returnTypeString),
-			returnTypeDescription: \(documentation.returns.map { "\"\($0.replacingOccurrences(of: "\"", with: "\\\"").replacingOccurrences(of: "\t", with: " "))\"" } ?? "nil"),
+			returnTypeDescription: \(documentation.returns.map { "\"\($0)\"" } ?? "nil"),
 			isAsync: \(funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil),
 			isThrowing: \(funcDecl.signature.effectSpecifiers?.throwsClause?.throwsSpecifier != nil)
 		)

Sources/SwiftMCPMacros/String+Documentation.swift

@@ -0,0 +1,31 @@
+//
+//  String+Documentation.swift
+//  SwiftMCP
+//
+//  Created by Oliver Drobnik on 27.03.25.
+//
+
+import Foundation
+
+extension String {
+	var removingUnprintableCharacters: String {
+		// Create a character set of printable ASCII characters (32-126) plus newline, tab, etc.
+		let printableCharacters = CharacterSet(charactersIn: " \t\n\r").union(CharacterSet(charactersIn: UnicodeScalar(32)...UnicodeScalar(126)))
+		
+		// Filter out any characters that are not in the printable set
+		return unicodeScalars.filter { printableCharacters.contains($0) }.map { String($0) }.joined()
+	}
+	
+	/// Escapes a string for use in a Swift string literal.
+	/// This handles quotes, backslashes, and other special characters.
+	var escapedForSwiftString: String {
+		return self
+			.replacingOccurrences(of: "\\", with: "\\\\")  // Escape backslashes first
+			.replacingOccurrences(of: "\"", with: "\\\"")  // Escape double quotes
+			.replacingOccurrences(of: "\'", with: "\\\'")  // Escape single quotes
+			.replacingOccurrences(of: "\n", with: "\\n")   // Escape newlines
+			.replacingOccurrences(of: "\r", with: "\\r")   // Escape carriage returns
+			.replacingOccurrences(of: "\t", with: "\\t")   // Escape tabs
+			.replacingOccurrences(of: "\0", with: "\\0")   // Escape null bytes
+	}
+}

Tests/SwiftMCPTests/MacroDocumentationTests.swift

@@ -225,6 +225,19 @@ func testEmptyLinesBetweenFields() {
     #expect(doc.description == "This is a function description")
     #expect(doc.parameters["x"] == "X parameter")
     #expect(doc.returns == "Return value")
-} 
+}
+
+@Test("Preserves paragraph breaks and escapes quotes in documentation")
+func testParagraphBreaksAndQuotes() {
+    let docText = """
+    /**
+     A Calculator for simple math doing additionals, subtractions etc.
+     
+     Testing "quoted" stuff. And on multiple lines. 'single quotes'
+     */
+    """
+    let doc = Documentation(from: docText)
+    #expect(doc.description == "A Calculator for simple math doing additionals, subtractions etc.\\n\\nTesting \\\"quoted\\\" stuff. And on multiple lines. \\'single quotes\\'")
+}
 
 #endif