Feature: Request Hooks (mark3labs#62)

* Add Callbacks Feature

MCPServer is upgraded with the capacity to notify before and/or
after requests run.  Developers can choose Before / After events,
and can submit callbacks that are notified during EVERY request
lifecycle, or else specific request methods.  The specific request
method callbacks receive typed message and/or result objects.

A special OnError callback is also provided.

To accomplish this with a minimal margin for error, a bit of a
refactoring was done:

- The `MCPServer.HandleMessage` method was moved from server.go
  into its own file.
- The individual request handlers' prototypes were changed.
  rather than returning `mcp.JSONRPCMessage`, they return a tuple
  of their specific result type and error.
- A code generation schema was introduced, to facilitate adding
  functionality to each clause in the switch statement within
  `HandleMessage()`.
- Now that HandleMessage() now receives a typed result object
  and possible error, it is able to pass those results to any
  configured callbacks.

I considered several options including a strategy pattern to make
HandleMessage() more DRY, but opted to stick with the minimal
reorganization of the code, and to keep the algorithm as flat
and obvious as possible.  I think the codegen mitigates the
repetitiveness of that section of code.

* Added documentation to MCP method descriptions

* Rename Callbacks --> Hooks

Reinstate test

* 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.

* Correct the indirection of message propagation

Added tests to verify that messages are propagated to the BeforeAny
and AfterAny hooks

* Rename AfterAny --> OnSuccess to clarify convention

Author: tylergannon

README.md

@@ -509,6 +509,18 @@ Prompts can include:
 
 For examples, see the `examples/` directory.
 
+## Extras
+
+### Request Hooks
+
+Hook into the request lifecycle by creating a `Hooks` object with your
+selection among the possible callbacks.  This enables telemetry across all
+functionality, and observability of various facts, for example the ability
+to count improperly-formatted requests, or to log the agent identity during
+initialization.
+
+Add the `Hooks` to the server at the time of creation using the
+`server.WithHooks` option.
 
 ## Contributing
 

examples/everything/main.go

@@ -29,12 +29,38 @@ const (
 )
 
 func NewMCPServer() *server.MCPServer {
+
+	hooks := &server.Hooks{}
+
+	hooks.AddBeforeAny(func(id any, method mcp.MCPMethod, message any) {
+		fmt.Printf("beforeAny: %s, %v, %v\n", method, id, message)
+	})
+	hooks.AddOnSuccess(func(id any, method mcp.MCPMethod, message any, result any) {
+		fmt.Printf("onSuccess: %s, %v, %v, %v\n", method, id, message, result)
+	})
+	hooks.AddOnError(func(id any, method mcp.MCPMethod, message any, err error) {
+		fmt.Printf("onError: %s, %v, %v, %v\n", method, id, message, err)
+	})
+	hooks.AddBeforeInitialize(func(id any, message *mcp.InitializeRequest) {
+		fmt.Printf("beforeInitialize: %v, %v\n", id, message)
+	})
+	hooks.AddAfterInitialize(func(id any, message *mcp.InitializeRequest, result *mcp.InitializeResult) {
+		fmt.Printf("afterInitialize: %v, %v, %v\n", id, message, result)
+	})
+	hooks.AddAfterCallTool(func(id any, message *mcp.CallToolRequest, result *mcp.CallToolResult) {
+		fmt.Printf("afterCallTool: %v, %v, %v\n", id, message, result)
+	})
+	hooks.AddBeforeCallTool(func(id any, message *mcp.CallToolRequest) {
+		fmt.Printf("beforeCallTool: %v, %v\n", id, message)
+	})
+
 	mcpServer := server.NewMCPServer(
 		"example-servers/everything",
 		"1.0.0",
 		server.WithResourceCapabilities(true, true),
 		server.WithPromptCapabilities(true),
 		server.WithLogging(),
+		server.WithHooks(hooks),
 	)
 
 	mcpServer.AddResource(mcp.NewResource("test://static/resource",

go.mod

@@ -5,11 +5,11 @@ go 1.23
 require (
 	github.com/google/uuid v1.6.0
 	github.com/stretchr/testify v1.9.0
+	github.com/yosida95/uritemplate/v3 v3.0.2
 )
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

mcp/types.go

@@ -8,6 +8,46 @@ import (
 	"github.com/yosida95/uritemplate/v3"
 )
 
+type MCPMethod string
+
+const (
+	// Initiates connection and negotiates protocol capabilities.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization
+	MethodInitialize MCPMethod = "initialize"
+
+	// Verifies connection liveness between client and server.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/utilities/ping/
+	MethodPing MCPMethod = "ping"
+
+	// Lists all available server resources.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/
+	MethodResourcesList MCPMethod = "resources/list"
+
+	// Provides URI templates for constructing resource URIs.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/
+	MethodResourcesTemplatesList MCPMethod = "resources/templates/list"
+
+	// Retrieves content of a specific resource by URI.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/
+	MethodResourcesRead MCPMethod = "resources/read"
+
+	// Lists all available prompt templates.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/
+	MethodPromptsList MCPMethod = "prompts/list"
+
+	// Retrieves a specific prompt template with filled parameters.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/
+	MethodPromptsGet MCPMethod = "prompts/get"
+
+	// Lists all available executable tools.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/
+	MethodToolsList MCPMethod = "tools/list"
+
+	// Invokes a specific tool with provided parameters.
+	// https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/
+	MethodToolsCall MCPMethod = "tools/call"
+)
+
 type URITemplate struct {
 	*uritemplate.Template
 }