feat: add tests and documentation for client state persistence and restoration

Author: Kedlub

client/client_test.go

@@ -0,0 +1,79 @@
+package client
+
+import (
+	"context"
+	"testing"
+
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+func TestStateRestoration(t *testing.T) {
+	mcpServer := server.NewMCPServer(
+		"test-server",
+		"1.0.0",
+		server.WithToolCapabilities(true),
+	)
+
+	// First client lifecycle
+	client1, err := NewInProcessClient(mcpServer)
+	if err != nil {
+		t.Fatalf("Failed to create first client: %v", err)
+	}
+
+	ctx := context.Background()
+
+	if err := client1.Start(ctx); err != nil {
+		t.Fatalf("Failed to start first client: %v", err)
+	}
+
+	initRequest := mcp.InitializeRequest{}
+	initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
+	initRequest.Params.ClientInfo = mcp.Implementation{
+		Name:    "test-client",
+		Version: "1.0.0",
+	}
+
+	if _, err := client1.Initialize(ctx, initRequest); err != nil {
+		t.Fatalf("Failed to initialize first client: %v", err)
+	}
+
+	if err := client1.Ping(ctx); err != nil {
+		t.Fatalf("Ping on first client failed: %v", err)
+	}
+
+	exportedState := client1.ExportState()
+
+	if err := client1.Close(); err != nil {
+		t.Fatalf("Failed to close first client: %v", err)
+	}
+
+	// Second client lifecycle (state restoration)
+	client2, err := NewInProcessClient(mcpServer)
+	if err != nil {
+		t.Fatalf("Failed to create second client: %v", err)
+	}
+	defer client2.Close()
+
+	if err := client2.Start(ctx); err != nil {
+		t.Fatalf("Failed to start second client: %v", err)
+	}
+
+	if err := client2.ImportState(ctx, exportedState); err != nil {
+		t.Fatalf("Failed to import state into second client: %v", err)
+	}
+
+	if err := client2.Ping(ctx); err != nil {
+		t.Fatalf("Ping on restored client failed: %v", err)
+	}
+
+	restoredState := client2.ExportState()
+
+	if !restoredState.Initialized {
+		t.Errorf("Expected restored client to be initialized")
+	}
+
+	if restoredState.RequestID <= exportedState.RequestID {
+		t.Errorf("Expected request ID to increase after restoration; before=%d, after=%d", exportedState.RequestID, restoredState.RequestID)
+	}
+}

www/docs/pages/clients/basics.mdx

@@ -297,6 +297,41 @@ func (mc *ManagedClient) Close() error {
 }
 ```
 
+### Persisting & Restoring Client State
+
+MCP-Go lets you snapshot a running client and resume it later — even in a new
+process — with `ExportState()` and `ImportState()`.
+
+```go
+// Save state before shutting down
+state := client.ExportState()
+if err := client.Close(); err != nil {
+    log.Printf("close failed: %v", err)
+}
+
+// Later, or in another process
+restoredClient, _ := client.NewStreamableHttpClient(baseURL)
+_ = restoredClient.Start(ctx)          // transport must be running
+if err := restoredClient.ImportState(ctx, state); err != nil {
+    log.Fatal(err)
+}
+
+// Continue exactly where you left off
+if err := restoredClient.Ping(ctx); err != nil {
+    log.Fatal(err)
+}
+```
+
+`ExportState()` captures:
+
+* initialization status  
+* last JSON-RPC request ID (so IDs continue monotonically)  
+* negotiated client / server capabilities  
+* HTTP session ID (for StreamableHTTP transports)
+
+`ImportState()` re-hydrates those values.  After a successful call the
+restored client can immediately issue normal requests without re-initializing.
+
 ## Error Handling
 
 Proper error handling is essential for robust client applications.