fix: stdio server

Author: linhdmn

.cursor/settings.json

@@ -1,5 +1,6 @@
 {
-  "mcp.executablePath": "/Users/harvey/Work/dev/FreePeak/Opensource/cortex/bin/echo-stdio-server",
+  "mcp.executablePath": "/Users/harvey/Work/dev/FreePeak/Opensource/cortex/bin/stdio-server",
   "mcp.transport": "stdio",
-  "mcp.logging": true
+  "mcp.logging": true,
+  "mcp.logLevel": "debug"
 }

bin/multi-protocol-server

@@ -18,8 +18,9 @@ func getTimestamp() string {
 }
 
 func main() {
-	// Create a logger
-	logger := log.New(os.Stdout, "[cortex-stdio] ", log.LstdFlags)
+	// Create a logger that writes to stderr instead of stdout
+	// This is critical for STDIO servers as stdout must only contain JSON-RPC messages
+	logger := log.New(os.Stderr, "[cortex-stdio] ", log.LstdFlags)
 
 	// Create the server with name and version
 	mcpServer := server.NewMCPServer("Cortex Stdio Server", "1.0.0", logger)
@@ -57,15 +58,12 @@ func main() {
 		logger.Fatalf("Error adding weather tool: %v", err)
 	}
 
-	// Print server ready message
-	fmt.Println("Server ready. You can now send JSON-RPC requests via stdin.")
-	fmt.Println("The following tools are available:")
-	fmt.Println("- echo / cortex_echo")
-	fmt.Println("- weather / cortex_weather")
-	fmt.Println("Example call:")
-	fmt.Println(`{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","parameters":{"message":"Hello, World!"}}}`)
+	// Write server status to stderr instead of stdout to maintain clean JSON protocol
+	fmt.Fprintf(os.Stderr, "Server ready. The following tools are available:\n")
+	fmt.Fprintf(os.Stderr, "- echo\n")
+	fmt.Fprintf(os.Stderr, "- weather\n")
 
-	// Start the server
+	// Start the STDIO server
 	if err := mcpServer.ServeStdio(); err != nil {
 		fmt.Fprintf(os.Stderr, "Error serving stdio: %v\n", err)
 		os.Exit(1)
@@ -74,8 +72,8 @@ func main() {
 
 // Echo tool handler
 func handleEcho(ctx context.Context, request server.ToolCallRequest) (interface{}, error) {
-	// Log request details
-	log.Printf("Handling echo request with name: %s", request.Name)
+	// Log request details to stderr via the logger
+	log.Printf("Handling echo tool call with name: %s", request.Name)
 
 	// Extract the message parameter
 	message, ok := request.Parameters["message"].(string)
@@ -100,8 +98,8 @@ func handleEcho(ctx context.Context, request server.ToolCallRequest) (interface{
 
 // Weather tool handler
 func handleWeather(ctx context.Context, request server.ToolCallRequest) (interface{}, error) {
-	// Log request details
-	log.Printf("Handling weather request with name: %s", request.Name)
+	// Log request details to stderr via the logger
+	log.Printf("Handling weather tool call with name: %s", request.Name)
 
 	// Extract the location parameter
 	location, ok := request.Parameters["location"].(string)

bin/sse-server

@@ -8,7 +8,6 @@ import (
 	"fmt"
 	"io"
 	"log"
-	"math/rand"
 	"os"
 	"os/signal"
 	"strings"
@@ -18,6 +17,7 @@ import (
 	"github.com/FreePeak/cortex/internal/domain"
 	"github.com/FreePeak/cortex/internal/infrastructure/logging"
 	"github.com/FreePeak/cortex/internal/interfaces/rest"
+	"github.com/google/uuid"
 )
 
 // Constants for JSON-RPC
@@ -70,11 +70,12 @@ func WithStdioContextFunc(fn StdioContextFunc) StdioOption {
 // It will create a custom logger that wraps the standard log.Logger
 func WithErrorLogger(stdLogger *log.Logger) StdioOption {
 	return func(s *StdioServer) {
-		// Create a development logger that outputs to stderr
+		// Create a development logger that always outputs to stderr
+		// In STDIO mode, stdout is reserved for JSON-RPC messages only
 		logger, err := logging.New(logging.Config{
 			Level:       logging.InfoLevel,
 			Development: true,
-			OutputPaths: []string{"stderr"},
+			OutputPaths: []string{"stderr"}, // Force stderr for all logging
 		})
 		if err != nil {
 			// If we can't create the logger, use the default one
@@ -87,11 +88,11 @@ func WithErrorLogger(stdLogger *log.Logger) StdioOption {
 // NewStdioServer creates a new stdio server wrapper around an MCPServer.
 // It initializes the server with a default logger that logs to stderr.
 func NewStdioServer(server *rest.MCPServer, opts ...StdioOption) *StdioServer {
-	// Create default logger
+	// Create default logger - always use stderr for STDIO servers
 	defaultLogger, err := logging.New(logging.Config{
 		Level:       logging.InfoLevel,
 		Development: true,
-		OutputPaths: []string{"stderr"},
+		OutputPaths: []string{"stderr"}, // Force stderr for all logging output
 		InitialFields: logging.Fields{
 			"component": "stdio-server",
 		},
@@ -453,160 +454,51 @@ func (p *MessageProcessor) handleToolsCall(ctx context.Context, params interface
 		}
 	}
 
-	// Get available tools from the service
-	tools, err := p.server.GetService().ListTools(ctx)
-	if err != nil {
-		return nil, &domain.JSONRPCError{
-			Code:    InternalErrorCode,
-			Message: fmt.Sprintf("Internal error: %v", err),
-		}
+	// Create a client session for the tool handler
+	clientSession := &domain.ClientSession{
+		ID:        generateSessionID(),
+		Connected: true,
 	}
 
-	// Find the requested tool
-	var foundTool *domain.Tool
-	var toolFound bool
-
-	for _, tool := range tools {
-		if tool.Name == toolName {
-			foundTool = tool
-			toolFound = true
-			break
-		}
-	}
-
-	if !toolFound {
-		return nil, &domain.JSONRPCError{
-			Code:    MethodNotFoundCode,
-			Message: fmt.Sprintf("Tool not found: %s", toolName),
-		}
-	}
+	// Access the service to get the tool handler
+	service := p.server.GetService()
 
-	// Validate required parameters
-	missingParams := []string{}
-	for _, param := range foundTool.Parameters {
-		if param.Required {
-			paramValue, exists := toolParams[param.Name]
-			if !exists || paramValue == nil {
-				missingParams = append(missingParams, param.Name)
+	// Try to get a registered handler for this tool
+	handler := service.GetToolHandler(toolName)
+	if handler != nil {
+		// We have a registered handler, use it
+		p.logger.Info("Using registered handler for tool", logging.Fields{"tool": toolName})
+		result, err := handler(ctx, toolParams, clientSession)
+		if err != nil {
+			p.logger.Error("Error executing tool handler", logging.Fields{"tool": toolName, "error": err})
+			return nil, &domain.JSONRPCError{
+				Code:    InternalErrorCode,
+				Message: fmt.Sprintf("Error executing tool: %v", err),
 			}
 		}
-	}
-
-	if len(missingParams) > 0 {
-		return nil, &domain.JSONRPCError{
-			Code:    InvalidParamsCode,
-			Message: fmt.Sprintf("Missing required parameters: %s", strings.Join(missingParams, ", ")),
-		}
-	}
-
-	// Handle different tool types using a strategy pattern
-	var toolResult interface{}
-	var toolErr error
-
-	// Use exact tool name matching instead of prefix matching
-	switch toolName {
-	case "mcp_golang_mcp_server_stdio_echo", "mcp_golang_mcp_server_stdio_cortex_echo":
-		toolResult, toolErr = handleEchoTool(toolParams)
-	case "mcp_golang_mcp_server_stdio_weather", "mcp_golang_mcp_server_stdio_cortex_weather":
-		toolResult, toolErr = handleWeatherTool(toolParams)
-	default:
-		return nil, &domain.JSONRPCError{
-			Code:    InternalErrorCode,
-			Message: fmt.Sprintf("Tool '%s' is registered but has no implementation", toolName),
-		}
-	}
 
-	if toolErr != nil {
-		return nil, &domain.JSONRPCError{
-			Code:    InternalErrorCode,
-			Message: toolErr.Error(),
-		}
+		p.logger.Info("Tool executed successfully", logging.Fields{"tool": toolName})
+		return result, nil
 	}
 
-	return toolResult, nil
-}
+	// No handler found - log available handlers and return error
+	availableHandlers := service.GetAllToolHandlerNames()
+	p.logger.Warn("No registered handler found for tool", logging.Fields{
+		"tool":              toolName,
+		"availableHandlers": fmt.Sprintf("%+v", availableHandlers),
+	})
 
-// Handle echo tool types
-func handleEchoTool(params map[string]interface{}) (interface{}, error) {
-	var message string
-
-	// Extract message parameter
-	messageVal, exists := params["message"]
-	if !exists || messageVal == nil {
-		return nil, fmt.Errorf("missing 'message' parameter")
-	}
-
-	// Convert to string based on type
-	switch v := messageVal.(type) {
-	case string:
-		message = v
-	case float64, int, int64, float32:
-		message = fmt.Sprintf("%v", v)
-	default:
-		// Try JSON conversion for complex types
-		jsonBytes, err := json.Marshal(v)
-		if err != nil {
-			message = fmt.Sprintf("%v", v)
-		} else {
-			message = string(jsonBytes)
-		}
+	return nil, &domain.JSONRPCError{
+		Code:    InternalErrorCode,
+		Message: fmt.Sprintf("Tool '%s' is registered but has no implementation", toolName),
 	}
-
-	// Return formatted result using the MCP content format
-	return map[string]interface{}{
-		"content": []map[string]interface{}{
-			{
-				"type": "text",
-				"text": message,
-			},
-		},
-	}, nil
 }
 
-// Handle weather tool types
-func handleWeatherTool(params map[string]interface{}) (interface{}, error) {
-	// Extract location parameter
-	locationVal, exists := params["location"]
-	if !exists || locationVal == nil {
-		return nil, fmt.Errorf("missing 'location' parameter")
-	}
-
-	location, ok := locationVal.(string)
-	if !ok {
-		return nil, fmt.Errorf("location must be a string")
-	}
-
-	// Generate random weather data for testing
-	rand.Seed(time.Now().UnixNano())
-	conditions := []string{"Sunny", "Partly Cloudy", "Cloudy", "Rainy", "Thunderstorms", "Snowy", "Foggy", "Windy"}
-	tempF := rand.Intn(50) + 30 // Random temperature between 30°F and 80°F
-	tempC := (tempF - 32) * 5 / 9
-	humidity := rand.Intn(60) + 30 // Random humidity between 30% and 90%
-	windSpeed := rand.Intn(20) + 5 // Random wind speed between 5-25mph
-
-	// Select a random condition
-	condition := conditions[rand.Intn(len(conditions))]
-
-	// Format today's date
-	today := time.Now().Format("Monday, January 2, 2006")
-
-	// Format the weather response
-	weatherInfo := fmt.Sprintf("Weather for %s on %s:\nCondition: %s\nTemperature: %d°F (%d°C)\nHumidity: %d%%\nWind Speed: %d mph",
-		location, today, condition, tempF, tempC, humidity, windSpeed)
-
-	// Return the weather response in the format expected by the MCP protocol
-	return map[string]interface{}{
-		"content": []map[string]interface{}{
-			{
-				"type": "text",
-				"text": weatherInfo,
-			},
-		},
-	}, nil
+// generateSessionID creates a unique session ID
+func generateSessionID() string {
+	return uuid.New().String()
 }
 
-// Helper functions for error handling and response creation
-
 // isTerminalError determines if an error should cause the server to shut down
 func isTerminalError(err error) bool {
 	if err == nil {

bin/stdio-server

@@ -222,14 +222,20 @@ func (s *MCPServer) UnregisterProvider(ctx context.Context, providerID string) e
 
 // ServeStdio serves the MCP server over standard I/O.
 func (s *MCPServer) ServeStdio() error {
+	// In STDIO mode, we must write all logs to stderr, as stdout is reserved for JSON-RPC messages
 	s.logger.Printf("Starting MCP server over stdio: %s v%s", s.name, s.version)
 
 	// Create stdio options
 	var stdioOpts []stdio.StdioOption
 
-	// Add the default error logger
+	// Always use stderr for logging in STDIO mode
 	stdioOpts = append(stdioOpts, stdio.WithErrorLogger(s.logger))
 
+	// Log registered tools for debugging
+	service := s.builder.BuildService()
+	toolHandlers := service.GetAllToolHandlerNames()
+	s.logger.Printf("Available tools in the server: %v", toolHandlers)
+
 	// Start the stdio server with our custom handler
 	return s.builder.ServeStdio(stdioOpts...)
 }