feat(mcp): add E2E testing with GitHub Actions

.github/workflows/e2e.yml

@@ -0,0 +1,82 @@
+# Copyright 2025 StreamNative
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: E2E Tests
+
+on:
+  push:
+    branches: [main, "release/**"]
+  pull_request:
+    branches: [main, "release/**"]
+
+permissions:
+  contents: read
+
+jobs:
+  pulsar-e2e:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: "go.mod"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Start Pulsar container
+        run: |
+          docker run -d --name pulsar-standalone \
+            -p 6650:6650 \
+            -p 8080:8080 \
+            -v ${{ github.workspace }}/scripts/pulsar-e2e-entrypoint.sh:/pulsar-entrypoint.sh \
+            --entrypoint /bin/bash \
+            apachepulsar/pulsar:3.3.0 \
+            /pulsar-entrypoint.sh
+
+      - name: Wait for Pulsar to be ready
+        run: |
+          echo "Waiting for Pulsar to be ready..."
+          READY=0
+          for i in {1..60}; do
+            if curl -f http://localhost:8080/admin/v2/clusters > /dev/null 2>&1; then
+              READY=1
+              echo "Pulsar is ready!"
+              break
+            fi
+            echo "Attempt $i/60: Pulsar not ready yet..."
+            sleep 2
+          done
+          if [ "$READY" -ne 1 ]; then
+            echo "Pulsar failed to become ready within the expected time."
+            exit 1
+          fi
+
+      - name: Run E2E tests
+        run: go test -v -tags=e2e -race ./pkg/mcp/e2e/...
+        env:
+          PULSAR_ADMIN_URL: http://localhost:8080
+          PULSAR_SERVICE_URL: pulsar://localhost:6650
+
+      - name: Show Pulsar logs on failure
+        if: failure()
+        run: docker logs pulsar-standalone
+
+      - name: Stop Pulsar container
+        if: always()
+        run: docker rm -f pulsar-standalone || true

Makefile

@@ -92,3 +92,43 @@ license-check:
 .PHONY: license-fix
 license-fix:
 	license-eye header fix
+
+# E2E Testing targets
+.PHONY: test-e2e-pulsar-start
+test-e2e-pulsar-start:
+	docker-compose -f test/docker-compose-pulsar.yml up -d
+	@echo "Waiting for Pulsar to be ready..."
+	@for i in 1 2 3 4 5 6 7 8 9 10; do \
+		if curl -s http://localhost:8080/admin/v2/clusters > /dev/null 2>&1; then \
+			echo "Pulsar is ready!"; \
+			exit 0; \
+		fi; \
+		echo "Waiting for Pulsar... ($$i/10)"; \
+		sleep 3; \
+	done
+	@echo "Error: Pulsar failed to become ready"; \
+	exit 1
+
+.PHONY: test-e2e-pulsar-stop
+test-e2e-pulsar-stop:
+	docker-compose -f test/docker-compose-pulsar.yml down
+
+.PHONY: test-e2e-pulsar-logs
+test-e2e-pulsar-logs:
+	docker-compose -f test/docker-compose-pulsar.yml logs
+
+.PHONY: test-e2e
+test-e2e:
+	go test -tags=e2e -v ./pkg/mcp/e2e/...
+
+.PHONY: test-e2e-race
+test-e2e-race:
+	go test -race -tags=e2e -v ./pkg/mcp/e2e/...
+
+.PHONY: test-e2e-run
+test-e2e-run: test-e2e-pulsar-start
+	@echo "Running E2E tests..."
+	@$(MAKE) test-e2e; \
+	result=$$?; \
+	$(MAKE) test-e2e-pulsar-stop; \
+	exit $$result

go.mod

@@ -8,8 +8,9 @@ require (
 	github.com/dgrijalva/jwt-go v3.2.0+incompatible
 	github.com/google/go-cmp v0.7.0
 	github.com/hamba/avro/v2 v2.28.0
-	github.com/mark3labs/mcp-go v0.43.2
+	github.com/invopop/jsonschema v0.13.0
 	github.com/mitchellh/go-homedir v1.1.0
+	github.com/modelcontextprotocol/go-sdk v1.2.0
 	github.com/pkg/errors v0.9.1
 	github.com/sirupsen/logrus v1.9.3
 	github.com/spf13/cobra v1.9.1
@@ -22,7 +23,7 @@ require (
 	github.com/twmb/franz-go/pkg/kadm v1.16.0
 	github.com/twmb/franz-go/pkg/sr v1.3.0
 	github.com/twmb/tlscfg v1.2.1
-	golang.org/x/oauth2 v0.27.0
+	golang.org/x/oauth2 v0.30.0
 	gopkg.in/yaml.v2 v2.4.0
 	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 )
@@ -49,12 +50,11 @@ require (
 	github.com/golang-jwt/jwt/v4 v4.5.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.2.2 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
-	github.com/google/uuid v1.6.0 // indirect
+	github.com/google/jsonschema-go v0.3.0 // indirect
 	github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/invopop/jsonschema v0.13.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.17.11 // indirect
 	github.com/kris-nova/logger v0.0.0-20181127235838-fd0d87064b06 // indirect

go.sum

@@ -97,6 +97,8 @@ github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/jsonschema-go v0.3.0 h1:6AH2TxVNtk3IlvkkhjrtbUc4S8AvO0Xii0DxIygDg+Q=
+github.com/google/jsonschema-go v0.3.0/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/mux v1.7.4/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So=
@@ -138,8 +140,6 @@ github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0V
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
-github.com/mark3labs/mcp-go v0.43.2 h1:21PUSlWWiSbUPQwXIJ5WKlETixpFpq+WBpbMGDSVy/I=
-github.com/mark3labs/mcp-go v0.43.2/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
 github.com/mattn/go-colorable v0.1.2 h1:/bC9yWikZXAL9uJdulbSfyVNIR3n3trXl+v8+1sx8mU=
 github.com/mattn/go-colorable v0.1.2/go.mod h1:U0ppj6V5qS13XJ6of8GYAs25YV2eR4EVcfRqFIhoBtE=
 github.com/mattn/go-isatty v0.0.8 h1:HLtExJ+uU2HOZ+wI0Tt5DtUDrx8yhUqDcp7fYERX4CE=
@@ -158,6 +158,8 @@ github.com/moby/sys/user v0.1.0 h1:WmZ93f5Ux6het5iituh9x2zAG7NFY9Aqi49jjE1PaQg=
 github.com/moby/sys/user v0.1.0/go.mod h1:fKJhFOnsCN6xZ5gSfbM6zaHGgDJMrqt9/reuj4T7MmU=
 github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
 github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
+github.com/modelcontextprotocol/go-sdk v1.2.0 h1:Y23co09300CEk8iZ/tMxIX1dVmKZkzoSBZOpJwUnc/s=
+github.com/modelcontextprotocol/go-sdk v1.2.0/go.mod h1:6fM3LCm3yV7pAs8isnKLn07oKtB0MP9LHd3DfAcKw10=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -286,8 +288,8 @@ golang.org/x/net v0.0.0-20200202094626-16171245cfb2/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20210726213435-c6fcb2dbf985/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
 golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
 golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
-golang.org/x/oauth2 v0.27.0 h1:da9Vo7/tDv5RH/7nZDz1eMGS/q1Vv1N/7FCrBhI9I3M=
-golang.org/x/oauth2 v0.27.0/go.mod h1:onh5ek6nERTohokkhCD/y2cV4Do3fxFHFuAejCkRWT8=
+golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
+golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
@@ -309,6 +311,8 @@ golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
 golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20190425150028-36563e24a262/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=
+golang.org/x/tools v0.38.0/go.mod h1:yEsQ/d/YK8cjh0L6rZlY8tgtlKiBNTL14pGDJPJpYQs=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/genproto v0.0.0-20241118233622-e639e219e697 h1:ToEetK57OidYuqD4Q5w+vfEnPvPpuTwedCNVohYJfNk=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20241223144023-3abc09e42ca8 h1:TqExAhdPaB60Ux47Cn0oLV07rGnxZzIsaRhQaqS666A=

go.work.sum

@@ -103,6 +103,8 @@ github.com/google/btree v1.0.0 h1:0udJVsspx3VBr5FwtLhQQtuAsVc79tTq0ocGIPAU6qo=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0 h1:A8PeW59pxE9IoFRqBp37U+mSNaQoZ46F1f0f863XSXw=
+github.com/google/jsonschema-go v0.3.0 h1:6AH2TxVNtk3IlvkkhjrtbUc4S8AvO0Xii0DxIygDg+Q=
+github.com/google/jsonschema-go v0.3.0/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no=
 github.com/google/martian/v3 v3.0.0 h1:pMen7vLs8nvgEYhywH3KDWJIJTeEr2ULsVWHWYHQyBs=
 github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99 h1:Ak8CrdlwwXwAZxzS66vgPt4U8yUZX7JwLvVR58FN5jM=

pkg/cmd/mcp/server.go

@@ -19,7 +19,6 @@ import (
 	stdlog "log"
 	"os"
 
-	"github.com/mark3labs/mcp-go/server"
 	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
 	"github.com/streamnative/streamnative-mcp-server/pkg/config"
@@ -30,7 +29,6 @@ import (
 
 func newMcpServer(_ context.Context, configOpts *ServerOptions, logrusLogger *logrus.Logger) (*mcp.Server, error) {
 	snConfig := configOpts.Options.LoadConfigOrDie()
-	var s *server.MCPServer
 	var mcpServer *mcp.Server
 	switch {
 	case snConfig.KeyFile != "":
@@ -46,16 +44,17 @@ func newMcpServer(_ context.Context, configOpts *ServerOptions, logrusLogger *lo
 			if err != nil {
 				return nil, errors.Wrap(err, "failed to create StreamNative Cloud session")
 			}
-			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, server.WithInstructions(mcp.GetStreamNativeCloudServerInstructions(userName, snConfig)))
+			instructions := mcp.GetStreamNativeCloudServerInstructions(userName, snConfig)
+			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, instructions)
 			mcpServer.SNCloudSession = session
 
-			s = mcpServer.MCPServer
-			mcp.RegisterPrompts(s)
+			// Register SNCloud-specific tools
+			mcp.RegisterPrompts(mcpServer.Server)
 			// Skip context tools if pulsar instance and cluster are provided via CLI
 			skipContextTools := snConfig.Context.PulsarInstance != "" && snConfig.Context.PulsarCluster != ""
-			mcp.RegisterContextTools(s, configOpts.Features, skipContextTools)
-			mcp.StreamNativeAddLogTools(s, configOpts.ReadOnly, configOpts.Features)
-			mcp.StreamNativeAddResourceTools(s, configOpts.ReadOnly, configOpts.Features)
+			mcp.RegisterContextTools(mcpServer.Server, configOpts.Features, skipContextTools)
+			mcp.StreamNativeAddLogTools(mcpServer.Server, configOpts.ReadOnly, configOpts.Features)
+			mcp.StreamNativeAddResourceTools(mcpServer.Server, configOpts.ReadOnly, configOpts.Features)
 		}
 	case snConfig.ExternalKafka != nil:
 		{
@@ -77,14 +76,14 @@ func newMcpServer(_ context.Context, configOpts *ServerOptions, logrusLogger *lo
 			if err != nil {
 				return nil, errors.Wrap(err, "failed to set external Kafka context")
 			}
-			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, server.WithInstructions(mcp.GetExternalKafkaServerInstructions(snConfig.ExternalKafka.BootstrapServers)))
+			instructions := mcp.GetExternalKafkaServerInstructions(snConfig.ExternalKafka.BootstrapServers)
+			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, instructions)
 			mcpServer.KafkaSession = ksession
-			s = mcpServer.MCPServer
 		}
 	case snConfig.ExternalPulsar != nil:
 		{
-			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, server.WithInstructions(mcp.GetExternalPulsarServerInstructions(snConfig.ExternalPulsar.WebServiceURL)))
-			s = mcpServer.MCPServer
+			instructions := mcp.GetExternalPulsarServerInstructions(snConfig.ExternalPulsar.WebServiceURL)
+			mcpServer = mcp.NewServer("streamnative-mcp-server", "0.0.1", logrusLogger, instructions)
 
 			// Only create global PulsarSession if not in multi-session mode
 			// In multi-session mode, each request must provide its own token via Authorization header
@@ -114,6 +113,8 @@ func newMcpServer(_ context.Context, configOpts *ServerOptions, logrusLogger *lo
 		}
 	}
 
+	// Register all tools
+	s := mcpServer.Server
 	mcp.PulsarAdminAddBrokersTools(s, configOpts.ReadOnly, configOpts.Features)
 	mcp.PulsarAdminAddBrokerStatsTools(s, configOpts.ReadOnly, configOpts.Features)
 	mcp.PulsarAdminAddClusterTools(s, configOpts.ReadOnly, configOpts.Features)