feat(fxmcpserver): Provided streamable HTTP transport (#357)

Author: ekkinox

docs/modules/fxmcpserver.md

@@ -23,12 +23,12 @@ It comes with:
 - automatic requests logging and tracing (method, target, duration, ...)
 - automatic requests metrics (count and duration)
 - possibility to register MCP resources, resource templates, prompts and tools
-- possibility to register MCP SSE server context hooks
-- possibility to expose the MCP server via Stdio (local) and/or HTTP SSE (remote)
+- possibility to register MCP Streamable HTTP and SSE server context hooks
+- possibility to expose the MCP server via Streamable HTTP (remote), HTTP SSE (remote) and Stdio (local)
 
 ## Installation
 
-First install the module:
+First, install the module:
 
 ```shell
 go get github.com/ankorstore/yokai/fxmcpserver
@@ -60,10 +60,17 @@ modules:
       name: "MCP Server"                  # server name ("MCP server" by default)
       version: 1.0.0                      # server version (1.0.0 by default)
       capabilities:
-        resources: true                   # to expose MCP resources & resource templates (disabled by default)
+        resources: true                   # to expose MCP resources and resource templates (disabled by default)
         prompts: true                     # to expose MCP prompts (disabled by default)
         tools: true                       # to expose MCP tools (disabled by default)
       transport:
+        stream:
+          expose: true                    # to remotely expose the MCP server via Streamable HTTP (disabled by default)
+          address: ":8083"                # exposition address (":8083" by default)
+          stateless: false                # stateless server mode (disabled by default)
+          base_path: "/mcp"               # base path ("/mcp" by default)
+          keep_alive: true                # to keep the connections alive
+          keep_alive_interval: 10         # keep alive interval in seconds (10 by default)
         sse:
           expose: true                    # to remotely expose the MCP server via SSE (disabled by default)
           address: ":8082"                # exposition address (":8082" by default)
@@ -74,7 +81,7 @@ modules:
           keep_alive: true                # to keep connection alive
           keep_alive_interval: 10         # keep alive interval in seconds (10 by default)
         stdio:
-          expose: false                   # to locally expose the MCP server via Stdio (disabled by default)
+          expose: true                   # to locally expose the MCP server via Stdio (disabled by default)
       log:
         request: true                     # to log MCP requests contents (disabled by default)
         response: true                    # to log MCP responses contents (disabled by default)
@@ -270,7 +277,7 @@ import (
 
 func Register() fx.Option {
 	return fx.Options(
-		// registers UserProfileResource as MCP resource
+		// registers UserProfileResource as MCP resource template
 		fxmcpserver.AsMCPServerResourceTemplate(resource.NewUserProfileResource),
 		// ...
 	)
@@ -519,6 +526,70 @@ modules:
 
 ## Hooks
 
+This module provides hooking mechanisms for the `StreamableHTTP` and `SSE` servers requests handling.
+
+### StreamableHTTP server hooks
+
+This module offers the possibility to provide context hooks with [MCPStreamableHTTPServerContextHook](https://github.com/ankorstore/yokai/blob/main/fxmcpserver/server/stream/context.go) implementations, that will be applied on each MCP StreamableHTTP request.
+
+For example, an MCP StreamableHTTP server context hook that adds a config value to the context:
+
+```go title="internal/mcp/resource/readme.go"
+package hook
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/ankorstore/yokai/config"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+type ExampleHook struct {
+	config *config.Config
+}
+
+func NewExampleHook(config *config.Config) *ExampleHook {
+	return &ExampleHook{
+		config: config,
+	}
+}
+
+func (h *ExampleHook) Handle() server.HTTPContextFunc {
+	return func(ctx context.Context, r *http.Request) context.Context {
+		return context.WithValue(ctx, "foo", h.config.GetString("foo"))
+	}
+}
+```
+
+You can register your MCP StreamableHTTP server context hook:
+
+- with `AsMCPStreamableHTTPServerContextHook()` to register a single MCP StreamableHTTP server context hook
+- with `AsMCPStreamableHTTPServerContextHooks()` to register several MCP StreamableHTTP server context hooks at once
+
+```go title="internal/register.go"
+package internal
+
+import (
+	"github.com/ankorstore/yokai/fxmcpserver"
+	"github.com/foo/bar/internal/mcp/hook"
+	"go.uber.org/fx"
+)
+
+func Register() fx.Option {
+	return fx.Options(
+		// registers ExampleHook as MCP StreamableHTTP server context hook
+		fxmcpserver.AsMCPStreamableHTTPServerContextHook(hook.NewExampleHook),
+		// ...
+	)
+}
+```
+
+The dependencies of your MCP StreamableHTTP server context hooks will be autowired.
+
+### SSE server hooks
+
 This module offers the possibility to provide context hooks with [MCPSSEServerContextHook](https://github.com/ankorstore/yokai/blob/main/fxmcpserver/server/sse/context.go) implementations, that will be applied on each MCP SSE request.
 
 For example, an MCP SSE server context hook that adds a config value to the context:
@@ -568,7 +639,7 @@ import (
 
 func Register() fx.Option {
 	return fx.Options(
-		// registers ReadmeResource as MCP resource
+		// registers ExampleHook as MCP SSE server context hook
 		fxmcpserver.AsMCPSSEServerContextHook(hook.NewExampleHook),
 		// ...
 	)
@@ -684,7 +755,98 @@ mcp_server_requests_total{method="tools/call",status="success",target="calculato
 
 ## Testing
 
-This module provides a [MCPSSETestServer](https://github.com/ankorstore/yokai/blob/main/fxmcpserver/fxmcpservertest/server.go) to enable you to easily test your exposed MCP registrations.
+This module provide `StreamableHTTP` and `SSE` test servers, to functionally test your applications.
+
+### StreamableHTTP test server
+
+This module provides a [MCPStreamableHTTPTestServer](https://github.com/ankorstore/yokai/blob/main/fxmcpserver/fxmcpservertest/stream.go) to enable you to easily test your exposed MCP registrations.
+
+From this server, you can create a ready to use client via `StartClient()` to perform MCP requests, to functionally test your MCP server.
+
+You can easily assert on:
+
+- MCP responses
+- logs
+- traces
+- metrics
+
+For example, to test an `MCP ping`:
+
+```go title="internal/mcp/ping_test.go"
+package handler_test
+
+import (
+	"testing"
+
+	"github.com/ankorstore/yokai/log/logtest"
+	"github.com/ankorstore/yokai/trace/tracetest"
+	"github.com/foo/bar/internal"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
+	"github.com/stretchr/testify/assert"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/fx"
+)
+
+func TestMCPPing(t *testing.T) {
+	var testServer *fxmcpservertest.MCPStreamableHTTPTestServer
+	var logBuffer logtest.TestLogBuffer
+	var traceExporter tracetest.TestTraceExporter
+	var metricsRegistry *prometheus.Registry
+
+	internal.RunTest(t, fx.Populate(&testServer, &logBuffer, &traceExporter, &metricsRegistry))
+
+	// close the test server once done
+	defer testServer.Close()
+
+	// start test client
+	testClient, err := testServer.StartClient(context.Background())
+	assert.NoError(t, err)
+
+	// close the test client once done
+	defer testClient.Close()
+
+	// send MCP ping request
+	err = testClient.Ping(context.Background())
+	assert.NoError(t, err)
+
+	// assertion on the logs buffer
+	logtest.AssertHasLogRecord(t, logBuffer, map[string]interface{}{
+		"level":        "info",
+		"mcpMethod":    "ping",
+		"mcpTransport": "streamable-http",
+		"message":      "MCP request success",
+	})
+
+	// assertion on the traces exporter
+	tracetest.AssertHasTraceSpan(
+		t,
+		traceExporter,
+		"MCP ping",
+		attribute.String("mcp.method", "ping"),
+		attribute.String("mcp.transport", "streamable-http"),
+	)
+
+	// assertion on the metrics registry
+	expectedMetric := `
+		# HELP mcp_server_requests_total Number of processed MCP requests
+		# TYPE mcp_server_requests_total counter
+		mcp_server_requests_total{method="ping",status="success",target=""} 1
+	`
+
+	err = testutil.GatherAndCompare(
+		metricsRegistry,
+		strings.NewReader(expectedMetric),
+		"mcp_server_requests_total",
+	)
+	assert.NoError(t, err)
+}
+```
+
+### SSE test server
+
+This module provides a [MCPSSETestServer](https://github.com/ankorstore/yokai/blob/main/fxmcpserver/fxmcpservertest/sse.go) to enable you to easily test your exposed MCP registrations.
 
 From this server, you can create a ready to use client via `StartClient()` to perform MCP requests, to functionally test your MCP server.