feat: make Hub MCP self-hosting production-ready (#66)

* feat: make Hub MCP self-hosting production-ready

* chore: additional test

* chore: remove "local development server" from response

* chore: address pr comments

* chore: address pr comments

* chore: fixed logging

Author: xernobyl

.env.example

@@ -27,6 +27,13 @@ DATABASE_URL=postgres://postgres:postgres@localhost:5432/test_db?sslmode=disable
 # Default: 8080
 PORT=8080
 
+# Public base URL advertised in runtime OpenAPI responses (optional but recommended for production)
+# Set this when Hub is exposed through ingress, TLS termination, a reverse proxy, or a path prefix.
+# Examples:
+# PUBLIC_BASE_URL=https://hub.example.com
+# PUBLIC_BASE_URL=https://example.com/hub
+# PUBLIC_BASE_URL=
+
 # Logging level (optional)
 # Default: info
 # Valid values: debug, info, warn, error

Dockerfile

@@ -43,6 +43,7 @@ COPY --from=builder /go/bin/river /usr/local/bin/river
 
 # Copy migration files
 COPY --from=builder /build/migrations /app/migrations
+COPY --from=builder /build/openapi.yaml /app/openapi.yaml
 
 # Switch to non-root user
 USER app

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all test help tests tests-coverage check-coverage build build-api build-worker build-backfill-embeddings run run-api run-worker run-backfill-embeddings init-db clean docker-up docker-down docker-clean deps install-tools fmt lint lint-new lint-openapi dev-setup test-all test-unit schemathesis install-hooks migrate-status migrate-validate river-migrate
+.PHONY: all test help tests mcp-smoke tests-coverage check-coverage build build-api build-worker build-backfill-embeddings run run-api run-worker run-backfill-embeddings init-db clean docker-up docker-down docker-clean deps install-tools fmt lint lint-new lint-openapi dev-setup test-all test-unit schemathesis install-hooks migrate-status migrate-validate river-migrate
 
 # Aliases for checkmake/lint expectations
 all: build
@@ -19,6 +19,7 @@ help:
 	@echo "  make run-backfill-embeddings - Run the backfill-embeddings command (enqueues embedding jobs; loads .env)"
 	@echo "  make test-unit        - Run unit tests (fast, no database)"
 	@echo "  make tests            - Run integration tests"
+	@echo "  make mcp-smoke        - Run the live MCP package smoke test (requires Hub env vars)"
 	@echo "  make test-all         - Run all tests (unit + integration)"
 	@echo "  make tests-coverage   - Run tests with coverage report"
 	@echo "  make check-coverage   - Run tests and fail if coverage below COVERAGE_THRESHOLD (excludes cmd/api)"
@@ -49,6 +50,13 @@ tests:
 	@echo "Running integration tests..."
 	@(set -a && [ -f .env ] && . ./.env && set +a; go test ./tests/... -v -timeout 120s)
 
+# Run the opt-in live MCP package smoke test.
+# Requires HUB_API_KEY, FORMBRICKS_HUB_BASE_URL (or HUB_BASE_URL), and either
+# HUB_MCP_PACKAGE or HUB_MCP_COMMAND/HUB_MCP_ARGS.
+mcp-smoke:
+	@echo "Running MCP package smoke test..."
+	@(set -a && [ -f .env ] && . ./.env && set +a; RUN_MCP_SMOKE_TEST=1 go test ./tests -run TestMCPPackageSmoke -count=1 -v -timeout 120s)
+
 # Run unit tests (fast, no database required)
 test-unit:
 	@echo "Running unit tests..."

charts/hub/templates/NOTES.txt

@@ -7,6 +7,11 @@ Required configuration
 - DATABASE_URL (Secret): PostgreSQL connection string (requires pgvector extension)
 - API_KEY (Secret): protects all /v1/* endpoints
 
+Recommended production configuration
+------------------------------------
+- PUBLIC_BASE_URL (ConfigMap/env): set this when Hub is exposed through ingress, TLS termination,
+  or a reverse-proxy path prefix so /openapi.yaml and /openapi.json advertise the correct public URL.
+
 Secret management options (choose one):
 1) Chart-managed Secret:
   values.secrets.create=true and set:

charts/hub/values.yaml

@@ -104,6 +104,10 @@ config:
   existingConfigMap: ""
   data:
     PORT: "8080"
+    # Recommended for production when Hub is exposed through ingress, TLS termination,
+    # or a reverse-proxy path prefix. Example: https://hub.example.com or
+    # https://example.com/hub
+    PUBLIC_BASE_URL: ""
     LOG_LEVEL: "info"
     SHUTDOWN_TIMEOUT_SECONDS: "30"
     MESSAGE_PUBLISHER_QUEUE_MAX_SIZE: "16384"

cmd/api/app.go

@@ -46,7 +46,10 @@ var (
 		"google-gemini requires EMBEDDING_GOOGLE_CLOUD_PROJECT and EMBEDDING_GOOGLE_CLOUD_LOCATION")
 )
 
-const riverQueueDepthInterval = 15 * time.Second
+const (
+	riverQueueDepthInterval = 15 * time.Second
+	startupCleanupTimeout   = 5 * time.Second
+)
 
 // embeddingProviderAndModel returns (provider, model) when embeddings are enabled: both EMBEDDING_PROVIDER
 // and EMBEDDING_MODEL must be set and the provider must be supported. Otherwise returns ("", "") so no
@@ -254,6 +257,8 @@ func NewApp(cfg *config.Config, db *pgxpool.Pool) (*App, error) {
 			feedbackRecordsService, embeddingsRepo, embeddingMetrics,
 			metrics, riverWorkers)
 		if err != nil {
+			cleanupNewAppStartupFailure(context.Background(), messageManager, nil, tracerProvider, meterProvider)
+
 			if errors.Is(err, service.ErrEmbeddingProviderAPIKey) {
 				return nil, fmt.Errorf("%w: %s", errEmbeddingProviderAPIKeyRequired, embeddingProviderName)
 			}
@@ -275,19 +280,7 @@ func NewApp(cfg *config.Config, db *pgxpool.Pool) (*App, error) {
 		Workers: riverWorkers,
 	})
 	if err != nil {
-		messageManager.Shutdown()
-
-		if tracerProvider != nil {
-			if err2 := observability.ShutdownTracerProvider(context.Background(), tracerProvider); err2 != nil {
-				slog.Error("shutdown tracer provider after River client error", "error", err2)
-			}
-		}
-
-		if meterProvider != nil {
-			if err2 := observability.ShutdownMeterProvider(context.Background(), meterProvider); err2 != nil {
-				slog.Error("shutdown meter provider after River client error", "error", err2)
-			}
-		}
+		cleanupNewAppStartupFailure(context.Background(), messageManager, nil, tracerProvider, meterProvider)
 
 		return nil, fmt.Errorf("create River client: %w", err)
 	}
@@ -327,8 +320,15 @@ func NewApp(cfg *config.Config, db *pgxpool.Pool) (*App, error) {
 	feedbackRecordsHandler := handlers.NewFeedbackRecordsHandler(feedbackRecordsService)
 	healthHandler := handlers.NewHealthHandler()
 
+	openapiHandler, err := handlers.NewOpenAPIHandler(handlers.ResolveOpenAPISpecPath(), cfg.Server.PublicBaseURL)
+	if err != nil {
+		cleanupNewAppStartupFailure(context.Background(), messageManager, riverClient, tracerProvider, meterProvider)
+
+		return nil, fmt.Errorf("create openapi handler: %w", err)
+	}
+
 	server := newHTTPServer(
-		cfg, healthHandler, feedbackRecordsHandler, webhooksHandler, searchHandler,
+		cfg, healthHandler, openapiHandler, feedbackRecordsHandler, webhooksHandler, searchHandler,
 		meterProvider, tracerProvider,
 	)
 
@@ -344,11 +344,12 @@ func NewApp(cfg *config.Config, db *pgxpool.Pool) (*App, error) {
 	}, nil
 }
 
-// newHTTPServer builds the HTTP server and muxes (no auth on /health, API key on /v1/).
+// newHTTPServer builds the HTTP server and muxes (no auth on /health or /openapi.*, API key on /v1/).
 // Handler chain: RequestID -> otelhttp(Logging(mux)) so access logs get trace_id/span_id from context.
 func newHTTPServer(
 	cfg *config.Config,
 	health *handlers.HealthHandler,
+	openapi *handlers.OpenAPIHandler,
 	feedback *handlers.FeedbackRecordsHandler,
 	webhooks *handlers.WebhooksHandler,
 	search *handlers.SearchHandler,
@@ -357,6 +358,8 @@ func newHTTPServer(
 ) *http.Server {
 	public := http.NewServeMux()
 	public.HandleFunc("GET /health", health.Check)
+	public.HandleFunc("GET /openapi.yaml", openapi.YAML)
+	public.HandleFunc("GET /openapi.json", openapi.JSON)
 
 	protected := http.NewServeMux()
 	protected.HandleFunc("POST /v1/feedback-records", feedback.Create)
@@ -500,6 +503,31 @@ func shutdownObservability(ctx context.Context, tracer *sdktrace.TracerProvider,
 	return first
 }
 
+func cleanupNewAppStartupFailure(
+	ctx context.Context,
+	messageManager *service.MessagePublisherManager,
+	riverClient *river.Client[pgx.Tx],
+	tracerProvider *sdktrace.TracerProvider,
+	meterProvider *sdkmetric.MeterProvider,
+) {
+	cleanupCtx, cancel := context.WithTimeout(ctx, startupCleanupTimeout)
+	defer cancel()
+
+	if messageManager != nil {
+		messageManager.Shutdown()
+	}
+
+	if riverClient != nil {
+		if err := riverClient.Stop(cleanupCtx); err != nil {
+			slog.Error("river stop after startup error", "error", err)
+		}
+	}
+
+	if err := shutdownObservability(cleanupCtx, tracerProvider, meterProvider); err != nil {
+		slog.Error("shutdown observability after startup error", "error", err)
+	}
+}
+
 // Shutdown stops the server, message publisher, and River in order. Call after Run returns.
 // Observability is shut down once via defer; its error is returned only when server and River shut down successfully.
 func (a *App) Shutdown(ctx context.Context) (err error) {