🚀 Comprehensive Testing & Production-Ready Improvements (#5)

This PR transforms the MCP server framework into a production-ready solution with comprehensive test coverage (42 tests), complete functionality implementation, enhanced documentation, and improved Docker container configuration.

Author: aatchison

.github/workflows/ci.yml

@@ -33,14 +33,25 @@ jobs:
         restore-keys: |
           ${{ runner.os }}-go-
 
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+
+    - name: Install Python dependencies
+      run: pip install requests
+
     - name: Download dependencies
-      run: go mod download
+      run: make deps
 
-    - name: Run tests
-      run: go test -v -race -coverprofile=coverage.out ./...
+    - name: Run unit tests
+      run: make test
+
+    - name: Run integration tests
+      run: make test-integration
 
     - name: Generate coverage report
-      run: go tool cover -html=coverage.out -o coverage.html
+      run: make test-coverage
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v3
@@ -100,13 +111,7 @@ jobs:
       env:
         GOOS: ${{ matrix.goos }}
         GOARCH: ${{ matrix.goarch }}
-      run: |
-        mkdir -p dist
-        if [ "$GOOS" = "windows" ]; then
-          go build -ldflags="-s -w" -o dist/mcp-server-${{ matrix.goos }}-${{ matrix.goarch }}.exe cmd/mcp-server/main.go
-        else
-          go build -ldflags="-s -w" -o dist/mcp-server-${{ matrix.goos }}-${{ matrix.goarch }} cmd/mcp-server/main.go
-        fi
+      run: make build-all
 
     - name: Upload build artifacts
       uses: actions/upload-artifact@v4

.golangci.yml

@@ -82,14 +82,7 @@ linters:
     - unused
     - whitespace
 
-  disable:
-    - maligned
-    - deadcode
-    - golint
-    - interfacer
-    - scopelint
-    - structcheck
-    - varcheck
+  disable: []
 
 issues:
   exclude-rules:

Dockerfile

@@ -48,4 +48,4 @@ EXPOSE 8080
 ENTRYPOINT ["./mcp-server"]
 
 # Default arguments (can be overridden)
-CMD ["-transport=stdio"]
+CMD ["-transport=sse", "-addr=8080"]

Makefile

@@ -1,6 +1,6 @@
 # Variables
 BINARY_NAME=mcp-server
-PACKAGE=github.com/openhands/mcp-server-framework
+PACKAGE=github.com/protobomb/mcp-server-framework
 VERSION?=$(shell git describe --tags --always --dirty)
 BUILD_TIME=$(shell date -u '+%Y-%m-%d_%H:%M:%S')
 LDFLAGS=-ldflags "-s -w -X main.version=$(VERSION) -X main.buildTime=$(BUILD_TIME)"
@@ -46,19 +46,23 @@ clean: ## Clean build artifacts
 	rm -rf dist/
 	rm -f coverage.out coverage.html
 
-test: ## Run tests
-	$(GOTEST) -v -race ./pkg/... ./internal/... ./cmd/...
+test: ## Run unit tests
+	$(GOTEST) -v -race ./pkg/...
 
 test-coverage: ## Run tests with coverage
-	$(GOTEST) -v -race -coverprofile=coverage.out ./pkg/... ./internal/... ./cmd/...
+	$(GOTEST) -v -race -coverprofile=coverage.out ./pkg/...
 	$(GOCMD) tool cover -html=coverage.out -o coverage.html
 
 coverage: test-coverage ## Generate coverage report
 	$(GOCMD) tool cover -func=coverage.out
 
 lint: ## Run linter
 	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest)
-	golangci-lint run
+	@if command -v golangci-lint >/dev/null 2>&1; then \
+		golangci-lint run; \
+	else \
+		$(shell go env GOPATH)/bin/golangci-lint run; \
+	fi
 
 fmt: ## Format code
 	$(GOCMD) fmt ./...
@@ -79,7 +83,7 @@ docker: ## Build Docker image
 	docker build -t $(BINARY_NAME):$(VERSION) .
 
 docker-run: ## Run Docker container
-	docker run -it --rm -p 8080:8080 $(BINARY_NAME):latest -transport=sse -addr=:8080
+	docker run -it --rm -p 8080:8080 $(BINARY_NAME):latest -transport=sse -addr=8080
 
 docker-run-stdio: ## Run Docker container with STDIO
 	docker run -it --rm $(BINARY_NAME):latest
@@ -91,7 +95,7 @@ run: build ## Build and run the server
 	./$(BINARY_NAME)
 
 run-sse: build ## Build and run the server with SSE transport
-	./$(BINARY_NAME) -transport=sse -addr=:8080
+	./$(BINARY_NAME) -transport=sse -addr=8080
 
 run-client: build-client ## Build and run the test client
 	./mcp-client -help
@@ -109,6 +113,18 @@ dev: ## Run in development mode with hot reload
 	@which air > /dev/null || (echo "Installing air..." && go install github.com/cosmtrek/air@latest)
 	air
 
+test-integration: build ## Run integration tests
+	@echo "Running integration tests..."
+	@./$(BINARY_NAME) -transport=sse -addr=8081 > /dev/null 2>&1 & \
+	SERVER_PID=$$!; \
+	sleep 2; \
+	python3 scripts/test_sse_integration.py 8081; \
+	TEST_RESULT=$$?; \
+	kill $$SERVER_PID 2>/dev/null || true; \
+	exit $$TEST_RESULT
+
+test-all: test test-integration ## Run all tests (unit + integration)
+
 benchmark: ## Run benchmarks
 	$(GOTEST) -bench=. -benchmem ./...
 
@@ -123,7 +139,7 @@ mod-why: ## Show why a module is needed
 	@read -p "Enter module name: " module; \
 	$(GOMOD) why $$module
 
-check: deps fmt vet lint test ## Run all checks
+check: deps fmt vet lint test-all ## Run all checks
 
 ci: check build ## Run CI pipeline locally
 

README.md

@@ -22,7 +22,7 @@ A simple, reusable Model Context Protocol (MCP) server framework written in Go.
 go run cmd/mcp-server/main.go
 
 # SSE transport
-go run cmd/mcp-server/main.go -transport=sse -addr=:8080
+go run cmd/mcp-server/main.go -transport=sse -addr=8080
 ```
 
 ### As a Library
@@ -35,8 +35,8 @@ import (
     "encoding/json"
     "log"
 
-    "github.com/openhands/mcp-server-framework/internal/transport"
-    "github.com/openhands/mcp-server-framework/pkg/mcp"
+    "github.com/protobomb/mcp-server-framework/pkg/transport"
+    "github.com/protobomb/mcp-server-framework/pkg/mcp"
 )
 
 func main() {
@@ -158,7 +158,12 @@ go get github.com/openhands/mcp-server-framework
 
 ```bash
 docker pull ghcr.io/openhands/mcp-server-framework:latest
-docker run -p 8080:8080 ghcr.io/openhands/mcp-server-framework:latest -transport=sse
+
+# Run with SSE transport (default)
+docker run -p 8080:8080 ghcr.io/openhands/mcp-server-framework:latest
+
+# Run with STDIO transport
+docker run -i ghcr.io/openhands/mcp-server-framework:latest -transport=stdio
 ```
 
 ## API Reference
@@ -265,47 +270,91 @@ transport := transport.NewSSETransport(":8080")
 ```
 
 SSE endpoints:
-- `GET /events` - SSE event stream
-- `POST /send` - Send messages to server
+- `GET /sse` - SSE event stream (with optional ?sessionId parameter)
+- `POST /message` - Send messages to server (requires ?sessionId parameter)
 - `GET /health` - Health check
 
 ## Built-in Handlers
 
-The framework includes these built-in handlers:
+The framework includes these built-in MCP handlers:
 
-- `initialize` - MCP initialization
+- `initialize` - MCP initialization handshake
 - `initialized` - MCP initialization complete notification
+- `tools/list` - List available tools
+- `tools/call` - Call a specific tool
 
-## Example Handlers
+## Built-in Tools
 
-The standalone server includes example handlers:
+The framework includes these example tools:
 
-- `echo` - Echo back the input message
-- `add` - Add two numbers
-- `listMethods` - List available methods
-- `ping` - Ping notification handler
+- `echo` - Echo back the provided message
+  - Parameters: `message` (string) - The message to echo back
+  - Returns: Text content with "Echo: {message}"
 
 ## Testing
 
+The framework includes comprehensive testing with both unit and integration tests.
+
+### Quick Testing
+
 ```bash
-# Run all tests
+# Run all tests (unit + integration)
+make test-all
+
+# Run only unit tests
 make test
 
+# Run only integration tests
+make test-integration
+
 # Run tests with coverage
 make test-coverage
 
+# Run all checks (format, lint, test)
+make check
+```
+
+### Test Coverage
+
+The framework has **42 comprehensive test cases** covering:
+
+- **SSE Transport**: 14 tests covering session management, message handling, CORS, error handling
+- **STDIO Transport**: 9 tests covering transport lifecycle and message handling  
+- **MCP Server**: 13 tests covering handlers, tools, capabilities, and protocol compliance
+- **MCP Client**: 14 tests covering client operations, timeouts, and error handling
+
+### Integration Testing
+
+Integration tests automatically:
+1. Start the MCP server with SSE transport
+2. Test complete MCP protocol flow (initialize → initialized → tools/list → tools/call)
+3. Verify request/response matching and notification handling
+4. Clean up server process
+
+### Manual Testing
+
+```bash
+# Manual unit testing
+go test ./pkg/...
+go test -v -race ./pkg/...
+go test -cover ./pkg/...
+
+# Test with mcp-cli (requires Node.js)
+./mcp-server -transport=sse -addr=8080 &
+npx @modelcontextprotocol/cli connect sse http://localhost:8080/sse
+
 # Test client with STDIO server
 make test-client-stdio
 
 # Test client with HTTP server  
 make test-client-http
-
-# Manual testing
-go test ./...
-go test -cover ./...
-go test -v ./...
 ```
 
+### Test Scripts
+
+- `scripts/test_sse_integration.py` - Python-based SSE integration test
+- `scripts/test-examples.sh` - Bash-based endpoint testing script
+
 ## Building
 
 ```bash
@@ -340,11 +389,14 @@ GOOS=darwin GOARCH=amd64 go build -o mcp-server-darwin cmd/mcp-server/main.go
 # Build Docker image
 docker build -t mcp-server-framework .
 
-# Run with STDIO
-docker run -i mcp-server-framework
+# Run with SSE transport (default)
+docker run -p 8080:8080 mcp-server-framework
+
+# Run with STDIO transport
+docker run -i mcp-server-framework -transport=stdio
 
-# Run with SSE
-docker run -p 8080:8080 mcp-server-framework -transport=sse -addr=:8080
+# Run with custom SSE address
+docker run -p 9090:9090 mcp-server-framework -addr=9090
 ```
 
 ## Examples
@@ -356,7 +408,7 @@ docker run -p 8080:8080 mcp-server-framework -transport=sse -addr=:8080
 ./mcp-client -transport=stdio -command='./mcp-server'
 
 # Test with HTTP server (start server first)
-./mcp-server -transport=sse -addr=:8080 &
+./mcp-server -transport=sse -addr=8080 &
 ./mcp-client -transport=http -addr=http://localhost:8080
 
 # Interactive demo
@@ -372,16 +424,19 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./mcp-server
 ### SSE Client Example
 
 ```javascript
+// Generate or get session ID
+const sessionId = 'your-session-id'; // or generate one
+
 // Connect to SSE endpoint
-const eventSource = new EventSource('http://localhost:8080/events');
+const eventSource = new EventSource(`http://localhost:8080/sse?sessionId=${sessionId}`);
 
 eventSource.onmessage = function(event) {
     const data = JSON.parse(event.data);
     console.log('Received:', data);
 };
 
 // Send a message
-fetch('http://localhost:8080/send', {
+fetch(`http://localhost:8080/message?sessionId=${sessionId}`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({