From dafa9dd96506e34d00800f43d0b4e1af8a9bdf4a Mon Sep 17 00:00:00 2001 From: dajiaohuang Date: Sat, 7 Nov 2026 23:45:19 +0800 Subject: [PATCH 1/2] docs(stdio): keep diagnostics off protocol stdout --- README.md | 6 ++++-- examples/roots_server/main.go | 3 ++- examples/structured_input_and_output/main.go | 3 ++- examples/typed_tools/main.go | 3 ++- www/docs/pages/getting-started.mdx | 3 ++- www/docs/pages/quick-start.mdx | 3 ++- www/docs/pages/servers/advanced.mdx | 4 ++-- www/docs/pages/servers/index.mdx | 3 ++- www/docs/pages/transports/index.mdx | 2 +- 9 files changed, 19 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0c669c0f1..729e9d2bd 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -53,7 +54,7 @@ func main() { // Start the stdio server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } @@ -121,6 +122,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -191,7 +193,7 @@ func main() { // Start the server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } ``` diff --git a/examples/roots_server/main.go b/examples/roots_server/main.go index 9aea5dd9c..87977571e 100644 --- a/examples/roots_server/main.go +++ b/examples/roots_server/main.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "log" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -11,7 +12,7 @@ import ( // handleNotification handles JSON-RPC notifications by printing the notification method to standard output. func handleNotification(ctx context.Context, notification mcp.JSONRPCNotification) { - fmt.Printf("notification received: %v\n", notification.Method) + fmt.Fprintf(os.Stderr, "notification received: %v\n", notification.Method) } // main sets up and runs an MCP stdio server named "roots-stdio-server" with tool and roots capabilities. diff --git a/examples/structured_input_and_output/main.go b/examples/structured_input_and_output/main.go index 467157222..1868496b3 100644 --- a/examples/structured_input_and_output/main.go +++ b/examples/structured_input_and_output/main.go @@ -3,6 +3,7 @@ package main import ( "context" "fmt" + "os" "time" "github.com/mark3labs/mcp-go/mcp" @@ -86,7 +87,7 @@ func main() { s.AddTool(manualTool, mcp.NewTypedToolHandler(manualWeatherHandler)) if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } diff --git a/examples/typed_tools/main.go b/examples/typed_tools/main.go index ea9c7efdb..4a922da69 100644 --- a/examples/typed_tools/main.go +++ b/examples/typed_tools/main.go @@ -3,6 +3,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -76,7 +77,7 @@ func main() { // Start the stdio server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } diff --git a/www/docs/pages/getting-started.mdx b/www/docs/pages/getting-started.mdx index 9a130e48b..b79158e11 100644 --- a/www/docs/pages/getting-started.mdx +++ b/www/docs/pages/getting-started.mdx @@ -42,6 +42,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -69,7 +70,7 @@ func main() { // Start the stdio server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } diff --git a/www/docs/pages/quick-start.mdx b/www/docs/pages/quick-start.mdx index d805c0f3a..bc688afe2 100644 --- a/www/docs/pages/quick-start.mdx +++ b/www/docs/pages/quick-start.mdx @@ -12,6 +12,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" @@ -39,7 +40,7 @@ func main() { // Start the stdio server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } diff --git a/www/docs/pages/servers/advanced.mdx b/www/docs/pages/servers/advanced.mdx index 522c8219b..fb9e6dd11 100644 --- a/www/docs/pages/servers/advanced.mdx +++ b/www/docs/pages/servers/advanced.mdx @@ -819,7 +819,7 @@ func (n *CustomNotifier) BroadcastSystemMessage(message string) { ```go func main() { // Initialize components - logger := log.New(os.Stdout, "[MCP] ", log.LstdFlags) + logger := log.New(os.Stderr, "[MCP] ", log.LstdFlags) metrics := NewPrometheusMetrics() sessionManager := NewSessionManager() notifier := NewCustomNotifier() @@ -925,7 +925,7 @@ func handleCalculate(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToo if clientSession, ok := session.(server.SessionWithClientInfo); ok { clientCapabilities := clientSession.GetClientCapabilities() if clientCapabilities.Sampling == nil { - fmt.Println("sampling is not enabled in client") + fmt.Fprintln(os.Stderr, "sampling is not enabled in client") } } diff --git a/www/docs/pages/servers/index.mdx b/www/docs/pages/servers/index.mdx index 695e93625..86142374f 100644 --- a/www/docs/pages/servers/index.mdx +++ b/www/docs/pages/servers/index.mdx @@ -28,6 +28,7 @@ import ( "context" "encoding/json" "fmt" + "os" "time" "github.com/mark3labs/mcp-go/mcp" @@ -83,7 +84,7 @@ func main() { // Start the server if err := server.ServeStdio(s); err != nil { - fmt.Printf("Server error: %v\n", err) + fmt.Fprintf(os.Stderr, "Server error: %v\n", err) } } diff --git a/www/docs/pages/transports/index.mdx b/www/docs/pages/transports/index.mdx index e8ec5eae4..504164396 100644 --- a/www/docs/pages/transports/index.mdx +++ b/www/docs/pages/transports/index.mdx @@ -70,7 +70,7 @@ func main() { httpServer := server.NewStreamableHTTPServer(s) httpServer.Start(":" + port) default: - fmt.Println("Starting STDIO server") + fmt.Fprintln(os.Stderr, "Starting STDIO server") server.ServeStdio(s) } } From a553738741e113c5f5d322c51f1568e752107311 Mon Sep 17 00:00:00 2001 From: dajiaohuang Date: Sat, 7 Nov 2026 23:56:14 +0800 Subject: [PATCH 2/2] fix(stdio): avoid blocking roots notification diagnostics --- examples/roots_server/main.go | 7 ++----- www/docs/pages/servers/advanced.mdx | 1 + 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/examples/roots_server/main.go b/examples/roots_server/main.go index 87977571e..8621c5e2d 100644 --- a/examples/roots_server/main.go +++ b/examples/roots_server/main.go @@ -4,16 +4,13 @@ import ( "context" "fmt" "log" - "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) -// handleNotification handles JSON-RPC notifications by printing the notification method to standard output. -func handleNotification(ctx context.Context, notification mcp.JSONRPCNotification) { - fmt.Fprintf(os.Stderr, "notification received: %v\n", notification.Method) -} +// handleNotification ignores notifications so diagnostic output cannot block the stdio server. +func handleNotification(context.Context, mcp.JSONRPCNotification) {} // main sets up and runs an MCP stdio server named "roots-stdio-server" with tool and roots capabilities. // It registers a handler for RootsListChanged notifications and adds a "roots" tool diff --git a/www/docs/pages/servers/advanced.mdx b/www/docs/pages/servers/advanced.mdx index fb9e6dd11..bd5638e91 100644 --- a/www/docs/pages/servers/advanced.mdx +++ b/www/docs/pages/servers/advanced.mdx @@ -889,6 +889,7 @@ package main import ( "context" "fmt" + "os" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server"