Merge branch 'main' of https://github.com/bitechdev/ResolveSpec into feature-keystore

pkg/resolvemcp/README.md

@@ -67,52 +67,81 @@ Each call immediately creates four MCP **tools** and one MCP **resource** for th
 
 ---
 
-## HTTP / SSE Transport
-
-The `*server.SSEServer` returned by any of the helpers below implements `http.Handler`, so it works with every Go HTTP framework.
+## HTTP Transports
 
 `Config.BasePath` is required and used for all route registration.
 `Config.BaseURL` is optional — when empty it is detected from each request.
 
-### Gorilla Mux
+Two transports are supported: **SSE** (legacy, two-endpoint) and **Streamable HTTP** (recommended, single-endpoint).
+
+---
+
+### SSE Transport
+
+Two endpoints: `GET {BasePath}/sse` (subscribe) + `POST {BasePath}/message` (send).
+
+#### Gorilla Mux
 
 ```go
 resolvemcp.SetupMuxRoutes(r, handler)
 ```
 
-Registers:
-
 | Route | Method | Description |
 |---|---|---|
 | `{BasePath}/sse` | GET | SSE connection — clients subscribe here |
 | `{BasePath}/message` | POST | JSON-RPC — clients send requests here |
-| `{BasePath}/*` | any | Full SSE server (convenience prefix) |
 
-### bunrouter
+#### bunrouter
 
 ```go
 resolvemcp.SetupBunRouterRoutes(router, handler)
 ```
 
-Registers `GET {BasePath}/sse` and `POST {BasePath}/message` on the provided `*bunrouter.Router`.
-
-### Gin (or any `http.Handler`-compatible framework)
-
-Use `handler.SSEServer()` to get an `http.Handler` and wrap it with the framework's adapter:
+#### Gin / net/http / Echo
 
 ```go
 sse := handler.SSEServer()
 
-// Gin
-engine.Any("/mcp/*path", gin.WrapH(sse))
-
-// net/http
-http.Handle("/mcp/", sse)
-
-// Echo
-e.Any("/mcp/*", echo.WrapHandler(sse))
+engine.Any("/mcp/*path", gin.WrapH(sse))  // Gin
+http.Handle("/mcp/", sse)                  // net/http
+e.Any("/mcp/*", echo.WrapHandler(sse))     // Echo
 ```
 
+---
+
+### Streamable HTTP Transport
+
+Single endpoint at `{BasePath}`. Handles POST (client→server) and GET (server→client streaming). Preferred for new integrations.
+
+#### Gorilla Mux
+
+```go
+resolvemcp.SetupMuxStreamableHTTPRoutes(r, handler)
+```
+
+Mounts the handler at `{BasePath}` (all methods).
+
+#### bunrouter
+
+```go
+resolvemcp.SetupBunRouterStreamableHTTPRoutes(router, handler)
+```
+
+Registers GET, POST, DELETE on `{BasePath}`.
+
+#### Gin / net/http / Echo
+
+```go
+h := handler.StreamableHTTPServer()
+// or: h := resolvemcp.NewStreamableHTTPHandler(handler)
+
+engine.Any("/mcp", gin.WrapH(h))      // Gin
+http.Handle("/mcp", h)                 // net/http
+e.Any("/mcp", echo.WrapHandler(h))     // Echo
+```
+
+---
+
 ### Authentication
 
 Add middleware before the MCP routes. The handler itself has no auth layer.

pkg/resolvemcp/handler.go

@@ -69,6 +69,14 @@ func (h *Handler) SSEServer() http.Handler {
 	return &dynamicSSEHandler{h: h}
 }
 
+// StreamableHTTPServer returns an http.Handler that serves MCP over the streamable HTTP transport.
+// Unlike SSE (which requires two endpoints), streamable HTTP uses a single endpoint for all
+// client-server communication (POST for requests, GET for server-initiated messages).
+// Mount the returned handler at the desired path; the path itself becomes the MCP endpoint.
+func (h *Handler) StreamableHTTPServer() http.Handler {
+	return server.NewStreamableHTTPServer(h.mcpServer)
+}
+
 // newSSEServer creates a concrete *server.SSEServer for known baseURL and basePath values.
 func (h *Handler) newSSEServer(baseURL, basePath string) *server.SSEServer {
 	return server.NewSSEServer(
@@ -189,8 +197,19 @@ func (h *Handler) getSchemaAndTable(defaultSchema, entity string, model interfac
 	return defaultSchema, entity
 }
 
+// recoverPanic catches a panic from the current goroutine and returns it as an error.
+// Usage: defer recoverPanic(&returnedErr)
+func recoverPanic(err *error) {
+	if r := recover(); r != nil {
+		msg := fmt.Sprintf("%v", r)
+		logger.Error("[resolvemcp] panic recovered: %s", msg)
+		*err = fmt.Errorf("internal error: %s", msg)
+	}
+}
+
 // executeRead reads records from the database and returns raw data + metadata.
-func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, options common.RequestOptions) (interface{}, *common.Metadata, error) {
+func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, options common.RequestOptions) (_ interface{}, _ *common.Metadata, retErr error) {
+	defer recoverPanic(&retErr)
 	model, err := h.registry.GetModelByEntity(schema, entity)
 	if err != nil {
 		return nil, nil, fmt.Errorf("model not found: %w", err)
@@ -246,15 +265,6 @@ func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, op
 		query = query.ColumnExpr(fmt.Sprintf("(%s) AS %s", cu.Expression, cu.Name))
 	}
 
-	// Preloads
-	if len(options.Preload) > 0 {
-		var err error
-		query, err = h.applyPreloads(model, query, options.Preload)
-		if err != nil {
-			return nil, nil, fmt.Errorf("failed to apply preloads: %w", err)
-		}
-	}
-
 	// Filters
 	query = h.applyFilters(query, options.Filters)
 
@@ -296,7 +306,7 @@ func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, op
 		}
 	}
 
-	// Count
+	// Count — must happen before preloads are applied; Bun panics when counting with relations.
 	total, err := query.Count(ctx)
 	if err != nil {
 		return nil, nil, fmt.Errorf("error counting records: %w", err)
@@ -310,6 +320,15 @@ func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, op
 		query = query.Offset(*options.Offset)
 	}
 
+	// Preloads — applied after count to avoid Bun panic when counting with relations.
+	if len(options.Preload) > 0 {
+		var preloadErr error
+		query, preloadErr = h.applyPreloads(model, query, options.Preload)
+		if preloadErr != nil {
+			return nil, nil, fmt.Errorf("failed to apply preloads: %w", preloadErr)
+		}
+	}
+
 	// BeforeRead hook
 	hookCtx.Query = query
 	if err := h.hooks.Execute(BeforeRead, hookCtx); err != nil {
@@ -370,7 +389,8 @@ func (h *Handler) executeRead(ctx context.Context, schema, entity, id string, op
 }
 
 // executeCreate inserts one or more records.
-func (h *Handler) executeCreate(ctx context.Context, schema, entity string, data interface{}) (interface{}, error) {
+func (h *Handler) executeCreate(ctx context.Context, schema, entity string, data interface{}) (_ interface{}, retErr error) {
+	defer recoverPanic(&retErr)
 	model, err := h.registry.GetModelByEntity(schema, entity)
 	if err != nil {
 		return nil, fmt.Errorf("model not found: %w", err)
@@ -454,7 +474,8 @@ func (h *Handler) executeCreate(ctx context.Context, schema, entity string, data
 }
 
 // executeUpdate updates a record by ID.
-func (h *Handler) executeUpdate(ctx context.Context, schema, entity, id string, data interface{}) (interface{}, error) {
+func (h *Handler) executeUpdate(ctx context.Context, schema, entity, id string, data interface{}) (_ interface{}, retErr error) {
+	defer recoverPanic(&retErr)
 	model, err := h.registry.GetModelByEntity(schema, entity)
 	if err != nil {
 		return nil, fmt.Errorf("model not found: %w", err)
@@ -564,7 +585,8 @@ func (h *Handler) executeUpdate(ctx context.Context, schema, entity, id string,
 }
 
 // executeDelete deletes a record by ID.
-func (h *Handler) executeDelete(ctx context.Context, schema, entity, id string) (interface{}, error) {
+func (h *Handler) executeDelete(ctx context.Context, schema, entity, id string) (_ interface{}, retErr error) {
+	defer recoverPanic(&retErr)
 	if id == "" {
 		return nil, fmt.Errorf("delete requires an ID")
 	}

pkg/resolvemcp/resolvemcp.go

@@ -98,3 +98,36 @@ func SetupBunRouterRoutes(router *bunrouter.Router, handler *Handler) {
 func NewSSEServer(handler *Handler) http.Handler {
 	return handler.SSEServer()
 }
+
+// SetupMuxStreamableHTTPRoutes mounts the MCP streamable HTTP endpoint on the given Gorilla Mux router.
+// The streamable HTTP transport uses a single endpoint (Config.BasePath) for all communication:
+// POST for client→server messages, GET for server→client streaming.
+//
+// Example:
+//
+//	resolvemcp.SetupMuxStreamableHTTPRoutes(r, handler) // mounts at Config.BasePath
+func SetupMuxStreamableHTTPRoutes(muxRouter *mux.Router, handler *Handler) {
+	basePath := handler.config.BasePath
+	h := handler.StreamableHTTPServer()
+	muxRouter.PathPrefix(basePath).Handler(http.StripPrefix(basePath, h))
+}
+
+// SetupBunRouterStreamableHTTPRoutes mounts the MCP streamable HTTP endpoint on a bunrouter router.
+// The streamable HTTP transport uses a single endpoint (Config.BasePath).
+func SetupBunRouterStreamableHTTPRoutes(router *bunrouter.Router, handler *Handler) {
+	basePath := handler.config.BasePath
+	h := handler.StreamableHTTPServer()
+	router.GET(basePath, bunrouter.HTTPHandler(h))
+	router.POST(basePath, bunrouter.HTTPHandler(h))
+	router.DELETE(basePath, bunrouter.HTTPHandler(h))
+}
+
+// NewStreamableHTTPHandler returns an http.Handler that serves MCP over the streamable HTTP transport.
+// Mount it at the desired path; that path becomes the MCP endpoint.
+//
+//	h := resolvemcp.NewStreamableHTTPHandler(handler)
+//	http.Handle("/mcp", h)
+//	engine.Any("/mcp", gin.WrapH(h))
+func NewStreamableHTTPHandler(handler *Handler) http.Handler {
+	return handler.StreamableHTTPServer()
+}