Stateless

.github/pull_request_template.md

@@ -1,12 +1,28 @@
-### PR Tips
+### PR Guideline
 
 Typically, PRs should consist of a single commit, and so should generally follow
-the [rules for Go commit messages](https://go.dev/wiki/CommitMessage), with the following
-changes and additions:
+the [rules for Go commit messages](https://go.dev/wiki/CommitMessage).
 
-- Markdown is allowed.
+You **must** follow the form:
 
-- For a pervasive change, use "all" in the title instead of a package name.
+```
+net/http: handle foo when bar
+
+[longer description here in the body]
+
+Fixes #12345
+```
+Notably, for the subject (the first line of description):
 
+- the name of the package affected by the change goes before the colon
+- the part after the colon uses the verb tense + phrase that completes the blank in, “this change modifies this package to ___________”
+- the verb after the colon is lowercase
+- there is no trailing period
+- it should be kept as short as possible
+
+Additionally:
+
+- Markdown is allowed.
+- For a pervasive change, use "all" in the title instead of a package name.
 - The PR description should provide context (why this change?) and describe the changes
   at a high level. Changes that are obvious from the diffs don't need to be mentioned.

.github/workflows/test.yml

@@ -1,22 +1,22 @@
 name: Test
 on:
   # Manual trigger
-  workflow_dispatch:  
+  workflow_dispatch:
   push:
     branches: main
   pull_request:
-  
+
 permissions:
   contents: read
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - name: Set up Go
-      uses: actions/setup-go@v5
     - name: Check out code
       uses: actions/checkout@v4
+    - name: Set up Go
+      uses: actions/setup-go@v5
     - name: Check formatting
       run: |
         unformatted=$(gofmt -l .)
@@ -26,18 +26,30 @@ jobs:
           exit 1
         fi
         echo "All Go files are properly formatted"
-  
+
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.23', '1.24' ]
+        go: [ '1.23', '1.24', '1.25.0-rc.3' ]
     steps:
+    - name: Check out code
+      uses: actions/checkout@v4
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
         go-version: ${{ matrix.go }}
-    - name: Check out code
-      uses: actions/checkout@v4
     - name: Test
       run: go test -v ./...
+
+  race-test:
+    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: '1.24'
+    - name: Test with -race
+      run: go test -v -race ./...

.gitignore

@@ -0,0 +1,38 @@
+# Builds
+*.exe
+*.exe~
+dist/
+build/
+bin/
+*.tmp
+
+# IDE files
+.vscode/
+*.code-workspace
+.idea/
+*~
+
+# Go Specific
+*.prof
+*.pprof
+*.out
+*.coverage
+coverage.txt
+coverage.html
+
+# OS generated files
+# macOS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Windows
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+.nfs*

README.md

@@ -73,8 +73,8 @@ func main() {
 	client := mcp.NewClient(&mcp.Implementation{Name: "mcp-client", Version: "v1.0.0"}, nil)
 
 	// Connect to a server over stdin/stdout
-	transport := mcp.NewCommandTransport(exec.Command("myserver"))
-	session, err := client.Connect(ctx, transport)
+	transport := &mcp.CommandTransport{Command: exec.Command("myserver")}
+	session, err := client.Connect(ctx, transport, nil)
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -127,7 +127,7 @@ func main() {
 
 	mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
 	// Run the server over stdin/stdout, until the client disconnects
-	if err := server.Run(context.Background(), mcp.NewStdioTransport()); err != nil {
+	if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
 		log.Fatal(err)
 	}
 }

auth/auth.go

@@ -0,0 +1,96 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"slices"
+	"strings"
+	"time"
+)
+
+type TokenInfo struct {
+	Scopes     []string
+	Expiration time.Time
+}
+
+type TokenVerifier func(ctx context.Context, token string) (*TokenInfo, error)
+
+type RequireBearerTokenOptions struct {
+	Scopes              []string
+	ResourceMetadataURL string
+}
+
+var ErrInvalidToken = errors.New("invalid token")
+
+type tokenInfoKey struct{}
+
+// RequireBearerToken returns a piece of middleware that verifies a bearer token using the verifier.
+// If verification succeeds, the [TokenInfo] is added to the request's context and the request proceeds.
+// If verification fails, the request fails with a 401 Unauthenticated, and the WWW-Authenticate header
+// is populated to enable [protected resource metadata].
+//
+// [protected resource metadata]: https://datatracker.ietf.org/doc/rfc9728
+func RequireBearerToken(verifier TokenVerifier, opts *RequireBearerTokenOptions) func(http.Handler) http.Handler {
+	// Based on typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
+
+	return func(handler http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			tokenInfo, errmsg, code := verify(r.Context(), verifier, opts, r.Header.Get("Authorization"))
+			if code != 0 {
+				if code == http.StatusUnauthorized || code == http.StatusForbidden {
+					if opts != nil && opts.ResourceMetadataURL != "" {
+						w.Header().Add("WWW-Authenticate", "Bearer resource_metadata="+opts.ResourceMetadataURL)
+					}
+				}
+				http.Error(w, errmsg, code)
+				return
+			}
+			r = r.WithContext(context.WithValue(r.Context(), tokenInfoKey{}, tokenInfo))
+			handler.ServeHTTP(w, r)
+		})
+	}
+}
+
+func verify(ctx context.Context, verifier TokenVerifier, opts *RequireBearerTokenOptions, authHeader string) (_ *TokenInfo, errmsg string, code int) {
+	// Extract bearer token.
+	fields := strings.Fields(authHeader)
+	if len(fields) != 2 || strings.ToLower(fields[0]) != "bearer" {
+		return nil, "no bearer token", http.StatusUnauthorized
+	}
+
+	// Verify the token and get information from it.
+	tokenInfo, err := verifier(ctx, fields[1])
+	if err != nil {
+		if errors.Is(err, ErrInvalidToken) {
+			return nil, err.Error(), http.StatusUnauthorized
+		}
+		// TODO: the TS SDK distinguishes another error, OAuthError, and returns a 400.
+		// Investigate how that works.
+		// See typescript-sdk/src/server/auth/middleware/bearerAuth.ts.
+		return nil, err.Error(), http.StatusInternalServerError
+	}
+
+	// Check scopes.
+	if opts != nil {
+		// Note: quadratic, but N is small.
+		for _, s := range opts.Scopes {
+			if !slices.Contains(tokenInfo.Scopes, s) {
+				return nil, "insufficient scope", http.StatusForbidden
+			}
+		}
+	}
+
+	// Check expiration.
+	if tokenInfo.Expiration.IsZero() {
+		return nil, "token missing expiration", http.StatusUnauthorized
+	}
+	if tokenInfo.Expiration.Before(time.Now()) {
+		return nil, "token expired", http.StatusUnauthorized
+	}
+	return tokenInfo, "", 0
+}

auth/auth_test.go

@@ -0,0 +1,70 @@
+// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestVerify(t *testing.T) {
+	ctx := context.Background()
+	verifier := func(_ context.Context, token string) (*TokenInfo, error) {
+		switch token {
+		case "valid":
+			return &TokenInfo{Expiration: time.Now().Add(time.Hour)}, nil
+		case "invalid":
+			return nil, ErrInvalidToken
+		case "noexp":
+			return &TokenInfo{}, nil
+		case "expired":
+			return &TokenInfo{Expiration: time.Now().Add(-time.Hour)}, nil
+		default:
+			return nil, errors.New("unknown")
+		}
+	}
+
+	for _, tt := range []struct {
+		name     string
+		opts     *RequireBearerTokenOptions
+		header   string
+		wantMsg  string
+		wantCode int
+	}{
+		{
+			"valid", nil, "Bearer valid",
+			"", 0,
+		},
+		{
+			"bad header", nil, "Barer valid",
+			"no bearer token", 401,
+		},
+		{
+			"invalid", nil, "bearer invalid",
+			"invalid token", 401,
+		},
+		{
+			"no expiration", nil, "Bearer noexp",
+			"token missing expiration", 401,
+		},
+		{
+			"expired", nil, "Bearer expired",
+			"token expired", 401,
+		},
+		{
+			"missing scope", &RequireBearerTokenOptions{Scopes: []string{"s1"}}, "Bearer valid",
+			"insufficient scope", 403,
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			_, gotMsg, gotCode := verify(ctx, verifier, tt.opts, tt.header)
+			if gotMsg != tt.wantMsg || gotCode != tt.wantCode {
+				t.Errorf("got (%q, %d), want (%q, %d)", gotMsg, gotCode, tt.wantMsg, tt.wantCode)
+			}
+		})
+	}
+}