Improved error propagation via hooks

This commit enhances the MCP server's error handling capabilities by:

1. Improving error propagation through the OnError hook system
2. Adding comprehensive documentation with usage examples
3. Ensuring error types can be properly inspected with Go's standard error handling patterns

We've added better support for typed errors that propagate through the request handling chain:

- `ErrUnsupported`: Used when a capability is not enabled on the server
- `UnparseableMessageError`: Used when parsing a message fails
- `ErrResourceNotFound`: Used when a requested resource doesn't exist
- `ErrPromptNotFound`: Used when a requested prompt doesn't exist
- `ErrToolNotFound`: Used when a requested tool doesn't exist

These errors can be interrogated using `errors.Is` and `errors.As` to provide more targeted error handling.

The documentation now includes examples like:

```go
hooks.AddOnError(func(id any, method mcp.MCPMethod, message any, err error) {
  // Check for specific error types using errors.Is
  if errors.Is(err, ErrUnsupported) {
    // Handle capability not supported errors
    log.Printf("Capability not supported: %v", err)
  }

  // Use errors.As to get specific error types
  var parseErr = &UnparseableMessageError{}
  if errors.As(err, &parseErr) {
    // Access specific methods/fields of the error type
    log.Printf("Failed to parse message for method %s: %v",
               parseErr.GetMethod(), parseErr.Unwrap())
    // Access the raw message that failed to parse
    rawMsg := parseErr.GetMessage()
  }

  // Check for specific resource/prompt/tool errors
  switch {
  case errors.Is(err, ErrResourceNotFound):
    log.Printf("Resource not found: %v", err)
  case errors.Is(err, ErrPromptNotFound):
    log.Printf("Prompt not found: %v", err)
  case errors.Is(err, ErrToolNotFound):
    log.Printf("Tool not found: %v", err)
  }
})
```

We've also added examples for testing scenarios:

```go
// Create a channel to receive errors for testing
errChan := make(chan error, 1)

// Register hook to capture and inspect errors
hooks := &Hooks{}
hooks.AddOnError(func(id any, method mcp.MCPMethod, message any, err error) {
    // For capability-related errors
    if errors.Is(err, ErrUnsupported) {
        // Handle capability not supported
        errChan <- err
        return
    }

    // For parsing errors
    var parseErr = &UnparseableMessageError{}
    if errors.As(err, &parseErr) {
        // Handle unparseable message errors
        fmt.Printf("Failed to parse %s request: %v\n",
                   parseErr.GetMethod(), parseErr.Unwrap())
        errChan <- parseErr
        return
    }

    // For resource/prompt/tool not found errors
    if errors.Is(err, ErrResourceNotFound) ||
       errors.Is(err, ErrPromptNotFound) ||
       errors.Is(err, ErrToolNotFound) {
        // Handle not found errors
        errChan <- err
        return
    }

    // For other errors
    errChan <- err
})
```

These improvements make the MCP server more robust and user-friendly by providing clear error patterns and detailed documentation.

Author: tylergannon

server/callbacks.go renamed to server/hooks.go

@@ -18,14 +18,14 @@ var MCPRequestTypes = []MCPRequestType{
 		ParamType:      "InitializeRequest",
 		ResultType:     "InitializeResult",
 		HookName:       "Initialize",
-		UnmarshalError: "Invalid initialize request",
+		UnmarshalError: "invalid initialize request",
 		HandlerFunc:    "handleInitialize",
 	}, {
 		MethodName:     "MethodPing",
 		ParamType:      "PingRequest",
 		ResultType:     "EmptyResult",
 		HookName:       "Ping",
-		UnmarshalError: "Invalid ping request",
+		UnmarshalError: "invalid ping request",
 		HandlerFunc:    "handlePing",
 	}, {
 		MethodName:     "MethodResourcesList",
@@ -35,7 +35,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Resources",
 		GroupHookName:  "Resource",
 		HookName:       "ListResources",
-		UnmarshalError: "Invalid list resources request",
+		UnmarshalError: "invalid list resources request",
 		HandlerFunc:    "handleListResources",
 	}, {
 		MethodName:     "MethodResourcesTemplatesList",
@@ -45,7 +45,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Resources",
 		GroupHookName:  "Resource",
 		HookName:       "ListResourceTemplates",
-		UnmarshalError: "Invalid list resource templates request",
+		UnmarshalError: "invalid list resource templates request",
 		HandlerFunc:    "handleListResourceTemplates",
 	}, {
 		MethodName:     "MethodResourcesRead",
@@ -55,7 +55,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Resources",
 		GroupHookName:  "Resource",
 		HookName:       "ReadResource",
-		UnmarshalError: "Invalid read resource request",
+		UnmarshalError: "invalid read resource request",
 		HandlerFunc:    "handleReadResource",
 	}, {
 		MethodName:     "MethodPromptsList",
@@ -65,7 +65,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Prompts",
 		GroupHookName:  "Prompt",
 		HookName:       "ListPrompts",
-		UnmarshalError: "Invalid list prompts request",
+		UnmarshalError: "invalid list prompts request",
 		HandlerFunc:    "handleListPrompts",
 	}, {
 		MethodName:     "MethodPromptsGet",
@@ -75,7 +75,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Prompts",
 		GroupHookName:  "Prompt",
 		HookName:       "GetPrompt",
-		UnmarshalError: "Invalid get prompt request",
+		UnmarshalError: "invalid get prompt request",
 		HandlerFunc:    "handleGetPrompt",
 	}, {
 		MethodName:     "MethodToolsList",
@@ -85,7 +85,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Tools",
 		GroupHookName:  "Tool",
 		HookName:       "ListTools",
-		UnmarshalError: "Invalid list tools request",
+		UnmarshalError: "invalid list tools request",
 		HandlerFunc:    "handleListTools",
 	}, {
 		MethodName:     "MethodToolsCall",
@@ -95,7 +95,7 @@ var MCPRequestTypes = []MCPRequestType{
 		GroupName:      "Tools",
 		GroupHookName:  "Tool",
 		HookName:       "CallTool",
-		UnmarshalError: "Invalid call tool request",
+		UnmarshalError: "invalid call tool request",
 		HandlerFunc:    "handleToolCall",
 	},
 }

server/internal/gen/data.go

@@ -5,6 +5,7 @@ package server
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/mark3labs/mcp-go/mcp"
@@ -20,6 +21,36 @@ type OnAfterAnyHookFunc func(id any, method mcp.MCPMethod, message any, result a
 
 // OnErrorHookFunc is a hook that will be called when an error occurs,
 // either during the request parsing or the method execution.
+// 
+// Example usage:
+// ```
+// hooks.AddOnError(func(id any, method mcp.MCPMethod, message any, err error) {
+//   // Check for specific error types using errors.Is
+//   if errors.Is(err, ErrUnsupported) {
+//     // Handle capability not supported errors
+//     log.Printf("Capability not supported: %v", err)
+//   }
+//
+//   // Use errors.As to get specific error types
+//   var parseErr = &UnparseableMessageError{}
+//   if errors.As(err, &parseErr) {
+//     // Access specific methods/fields of the error type
+//     log.Printf("Failed to parse message for method %s: %v", 
+//                parseErr.GetMethod(), parseErr.Unwrap())
+//     // Access the raw message that failed to parse
+//     rawMsg := parseErr.GetMessage()
+//   }
+//
+//   // Check for specific resource/prompt/tool errors
+//   switch {
+//   case errors.Is(err, ErrResourceNotFound):
+//     log.Printf("Resource not found: %v", err)
+//   case errors.Is(err, ErrPromptNotFound):
+//     log.Printf("Prompt not found: %v", err)
+//   case errors.Is(err, ErrToolNotFound):
+//     log.Printf("Tool not found: %v", err)
+//   }
+// })
 type OnErrorHookFunc func(id any, method mcp.MCPMethod, message any, err error)
 
 {{range .}}
@@ -45,6 +76,50 @@ func (c *Hooks) AddAfterAny(hook OnAfterAnyHookFunc) {
 	c.OnAfterAny = append(c.OnAfterAny, hook)
 }
 
+// AddOnError registers a hook function that will be called when an error occurs.
+// The error parameter contains the actual error object, which can be interrogated
+// using Go's error handling patterns like errors.Is and errors.As.
+//
+// Example:
+// ```
+// // Create a channel to receive errors for testing
+// errChan := make(chan error, 1)
+// 
+// // Register hook to capture and inspect errors
+// hooks := &Hooks{}
+// hooks.AddOnError(func(id any, method mcp.MCPMethod, message any, err error) {
+//     // For capability-related errors
+//     if errors.Is(err, ErrUnsupported) {
+//         // Handle capability not supported
+//         errChan <- err
+//         return
+//     }
+//
+//     // For parsing errors
+//     var parseErr = &UnparseableMessageError{}
+//     if errors.As(err, &parseErr) {
+//         // Handle unparseable message errors
+//         fmt.Printf("Failed to parse %s request: %v\n", 
+//                    parseErr.GetMethod(), parseErr.Unwrap())
+//         errChan <- parseErr
+//         return
+//     }
+//
+//     // For resource/prompt/tool not found errors
+//     if errors.Is(err, ErrResourceNotFound) ||
+//        errors.Is(err, ErrPromptNotFound) ||
+//        errors.Is(err, ErrToolNotFound) {
+//         // Handle not found errors
+//         errChan <- err
+//         return
+//     }
+//
+//     // For other errors
+//     errChan <- err
+// })
+//
+// server := NewMCPServer("test-server", "1.0.0", WithHooks(hooks))
+// ```
 func (c *Hooks) AddOnError(hook OnErrorHookFunc) {
 	c.OnError = append(c.OnError, hook)
 }
@@ -67,6 +142,20 @@ func (c *Hooks) afterAny(id any, method mcp.MCPMethod, message any, result any)
 	}
 }
 
+// onError calls all registered error hooks with the error object.
+// The err parameter contains the actual error that occurred, which implements
+// the standard error interface and may be a wrapped error or custom error type.
+//
+// This allows consumer code to use Go's error handling patterns:
+// - errors.Is(err, ErrUnsupported) to check for specific sentinel errors
+// - errors.As(err, &customErr) to extract custom error types
+//
+// Common error types include:
+// - ErrUnsupported: When a capability is not enabled
+// - UnparseableMessageError: When request parsing fails
+// - ErrResourceNotFound: When a resource is not found
+// - ErrPromptNotFound: When a prompt is not found
+// - ErrToolNotFound: When a tool is not found
 func (c *Hooks) onError(id any, method mcp.MCPMethod, message any, err error) {
 	if c == nil {
 		return

server/internal/gen/hooks.go.tmpl

@@ -8,6 +8,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"text/template"
 )
 
@@ -29,7 +30,9 @@ func RenderTemplateToFile(templateContent, destPath, fileName string, data any)
 	defer os.Remove(tempFilePath) // Clean up temp file when done
 
 	// Parse and execute template to temp file
-	tmpl, err := template.New(fileName).Parse(templateContent)
+	tmpl, err := template.New(fileName).Funcs(template.FuncMap{
+		"toLower": strings.ToLower,
+	}).Parse(templateContent)
 	if err != nil {
 		tempFile.Close()
 		return err

server/internal/gen/main.go

@@ -5,6 +5,7 @@ package server
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 
 	"github.com/mark3labs/mcp-go/mcp"
@@ -64,13 +65,13 @@ func (s *MCPServer) HandleMessage(
 			err = &requestError{
 				id:   baseMessage.ID,
 				code: mcp.METHOD_NOT_FOUND,
-				err:  "{{.GroupName}} not supported",
+				err:  fmt.Errorf("{{toLower .GroupName}} %w", ErrUnsupported),
 			}
-		} else{{ end }} if json.Unmarshal(message, &request) != nil {
+		} else{{ end }} if unmarshalErr := json.Unmarshal(message, &request); unmarshalErr != nil {
 			err = &requestError{
 				id:   baseMessage.ID,
 				code: mcp.INVALID_REQUEST,
-				err:  "{{.UnmarshalError}}",
+				err:  &UnparseableMessageError{message: message, err: unmarshalErr, method: baseMessage.Method},
 			}
 		} else {
 			s.hooks.before{{.HookName}}(baseMessage.ID, &request)