merge with main

Author: jba

.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

@@ -3,7 +3,7 @@ on:
   # Manual trigger
   workflow_dispatch:
   push:
-    branches: main
+    branches: [main]
   pull_request:
 
 permissions:
@@ -13,43 +13,51 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - name: Check out code
-      uses: actions/checkout@v4
-    - name: Set up Go
-      uses: actions/setup-go@v5
-    - name: Check formatting
-      run: |
-        unformatted=$(gofmt -l .)
-        if [ -n "$unformatted" ]; then
-          echo "The following files are not properly formatted:"
-          echo "$unformatted"
-          exit 1
-        fi
-        echo "All Go files are properly formatted"
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "^1.23"
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "The following files are not properly formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+          echo "All Go files are properly formatted"
+      - name: Run Go vet
+        run: go vet ./...
+      - name: Run staticcheck
+        uses: dominikh/staticcheck-action@v1
+        with:
+          version: "latest"
 
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.23', '1.24', '1.25.0-rc.2' ]
+        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: Test
-      run: go test -v ./...
+      - name: Check out code
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+      - 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 ./...
+      - 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

@@ -1,25 +1,23 @@
 <!-- Autogenerated by weave; DO NOT EDIT -->
-# MCP Go SDK v0.2.0
+# MCP Go SDK v0.3.0
 
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/modelcontextprotocol/go-sdk)
 
 ***BREAKING CHANGES***
 
 This version contains breaking changes.
 See the [release notes](
-https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.2.0) for details.
+https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.3.0) for details.
 
 [![PkgGoDev](https://pkg.go.dev/badge/github.com/modelcontextprotocol/go-sdk)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
 
 This repository contains an unreleased implementation of the official Go
 software development kit (SDK) for the Model Context Protocol (MCP).
 
 > [!WARNING]
-> The SDK should be considered unreleased, and is currently unstable
-> and subject to breaking changes. Please test it out and file bug reports or API
-> proposals, but don't use it in real projects. See the issue tracker for known
-> issues and missing features. We aim to release a stable version of the SDK in
-> August, 2025.
+> The SDK is not yet at v1.0.0 and may still be subject to incompatible API
+> changes. We aim to tag v1.0.0 in September, 2025. See
+> https://github.com/modelcontextprotocol/go-sdk/issues/328 for details.
 
 ## Design
 
@@ -73,8 +71,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)
 	}
@@ -115,10 +113,10 @@ type HiParams struct {
 	Name string `json:"name" jsonschema:"the name of the person to greet"`
 }
 
-func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[HiParams]) (*mcp.CallToolResultFor[any], error) {
-	return &mcp.CallToolResultFor[any]{
-		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + params.Arguments.Name}},
-	}, nil
+func SayHi(ctx context.Context, req *mcp.CallToolRequest, args HiParams) (*mcp.CallToolResult, any, error) {
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + args.Name}},
+	}, nil, nil
 }
 
 func main() {
@@ -127,7 +125,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,115 @@
+// 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"
+)
+
+// TokenInfo holds information from a bearer token.
+type TokenInfo struct {
+	Scopes     []string
+	Expiration time.Time
+	// TODO: add standard JWT fields
+	Extra map[string]any
+}
+
+// The error that a TokenVerifier should return if the token cannot be verified.
+var ErrInvalidToken = errors.New("invalid token")
+
+// A TokenVerifier checks the validity of a bearer token, and extracts information
+// from it. If verification fails, it should return an error that unwraps to ErrInvalidToken.
+type TokenVerifier func(ctx context.Context, token string) (*TokenInfo, error)
+
+// RequireBearerTokenOptions are options for [RequireBearerToken].
+type RequireBearerTokenOptions struct {
+	// The URL for the resource server metadata OAuth flow, to be returned as part
+	// of the WWW-Authenticate header.
+	ResourceMetadataURL string
+	// The required scopes.
+	Scopes []string
+}
+
+type tokenInfoKey struct{}
+
+// TokenInfoFromContext returns the [TokenInfo] stored in ctx, or nil if none.
+func TokenInfoFromContext(ctx context.Context) *TokenInfo {
+	ti := ctx.Value(tokenInfoKey{})
+	if ti == nil {
+		return nil
+	}
+	return ti.(*TokenInfo)
+}
+
+// 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. All must be present.
+	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
+}