Merge branch 'main' into addCompletion

Author: samthanawalla

.github/workflows/readme-check.yml

@@ -0,0 +1,38 @@
+name: README Check
+on:
+  workflow_dispatch:  
+  pull_request:
+    paths:
+      - 'internal/readme/**'
+      - 'README.md'
+  
+permissions:
+  contents: read
+
+jobs:
+  readme-check:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Go
+      uses: actions/setup-go@v5
+    - name: Check out code
+      uses: actions/checkout@v4
+    - name: Check README is up-to-date
+      run: |
+        cd internal/readme
+        make
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "ERROR: README.md is not up-to-date!"
+          echo ""
+          echo "The README.md file differs from what would be generated by running 'make' in internal/readme/."
+          echo "Please update internal/readme/README.src.md instead of README.md directly,"
+          echo "then run 'make' in the internal/readme/ directory to regenerate README.md."
+          echo ""
+          echo "Changes:"
+          git status --porcelain
+          echo ""
+          echo "Diff:"
+          git diff
+          exit 1
+        fi
+        echo "README.md is up-to-date"

.github/workflows/test.yml

@@ -8,8 +8,25 @@ on:
 
 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: 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"
+  
   test:
     runs-on: ubuntu-latest
     strategy:

CONTRIBUTING.md

@@ -68,6 +68,15 @@ This process is similar to the [Go proposal
 process](https://github.com/golang/proposal), but is necessarily lighter weight
 to accommodate the greater rate of change expected for the SDK.
 
+### Design discussion
+
+For open ended design discussion (anything that doesn't fall into the issue
+categories above), use [GitHub
+Discussions](https://github.com/modelcontextprotocol/go-sdk/discussions).
+Ideally, each discussion should be focused on one aspect of the design. For
+example: Tool Binding and Session APIs would be two separate discussions.
+When discussions reach a consensus, they should be promoted into proposals.
+
 ## Contributing code
 
 The project uses GitHub pull requests (PRs) to review changes.
@@ -96,6 +105,19 @@ copyright header following the format below:
 // license that can be found in the LICENSE file.
 ```
 
+### Updating the README
+
+The top-level `README.md` file is generated from `internal/readme/README.src.md`
+and should not be edited directly. To update the README:
+
+1. Make your changes to `internal/readme/README.src.md`
+2. Run `make` in the `internal/readme/` directory to regenerate `README.md`
+3. Commit both files together
+
+The CI system will automatically check that the README is up-to-date by running
+`make` and verifying no changes result. If you see a CI failure about the
+README being out of sync, follow the steps above to regenerate it.
+
 ## Code of conduct
 
 This project follows the [Go Community Code of Conduct](https://go.dev/conduct).

README.md

@@ -1,10 +1,7 @@
 <!-- Autogenerated by weave; DO NOT EDIT -->
 # MCP Go SDK
 
-<!-- TODO: update pkgsite links here to point to the modelcontextprotocol
-module, once it exists. -->
-
-[![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
+[![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).
@@ -15,6 +12,18 @@ 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.
 
+## Design
+
+The design doc for this SDK is at [design.md](./design/design.md), which was
+initially reviewed at
+[modelcontextprotocol/discussions/364](https://github.com/orgs/modelcontextprotocol/discussions/364).
+
+Further design discussion should occur in
+[issues](https://github.com/modelcontextprotocol/go-sdk/issues) (for concrete
+proposals) or
+[discussions](https://github.com/modelcontextprotocol/go-sdk/discussions) for
+open-ended discussion. See CONTRIBUTING.md for details.
+
 ## Package documentation
 
 The SDK consists of two importable packages:
@@ -95,14 +104,18 @@ type HiParams struct {
 
 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.Name}},
+		Content: []mcp.Content{&mcp.TextContent{Text: "Hi " + params.Arguments.Name}},
 	}, nil
 }
 
 func main() {
 	// Create a server with a single tool.
 	server := mcp.NewServer("greeter", "v1.0.0", nil)
-	server.AddTools(mcp.NewServerTool("greet", "say hi", SayHi))
+	server.AddTools(
+		mcp.NewServerTool("greet", "say hi", SayHi, mcp.Input(
+			mcp.Property("name", mcp.Description("the name of the person to greet")),
+		)),
+	)
 	// Run the server over stdin/stdout, until the client disconnects
 	if err := server.Run(context.Background(), mcp.NewStdioTransport()); err != nil {
 		log.Fatal(err)
@@ -112,15 +125,6 @@ func main() {
 
 The `examples/` directory contains more example clients and servers.
 
-## Design
-
-The design doc for this SDK is at [design.md](./design/design.md), which was
-initially reviewed at
-[modelcontextprotocol/discussions/364](https://github.com/orgs/modelcontextprotocol/discussions/364).
-
-Further design discussion should occur in GitHub issues. See CONTRIBUTING.md
-for details.
-
 ## Acknowledgements
 
 Several existing Go MCP SDKs inspired the development and design of this

design/design.md

@@ -470,6 +470,10 @@ server.AddReceivingMiddleware(withLogging)
 
 **Differences from mcp-go**: Version 0.26.0 of mcp-go defines 24 server hooks. Each hook consists of a field in the `Hooks` struct, a `Hooks.Add` method, and a type for the hook function. These are rarely used. The most common is `OnError`, which occurs fewer than ten times in open-source code.
 
+#### Rate Limiting
+
+Rate limiting can be configured using middleware. Please see [examples/rate-limiting](<https://github.com/modelcontextprotocol/go-sdk/tree/main/examples/rate-limiting>] for an example on how to implement this.
+
 ### Errors
 
 With the exception of tool handler errors, protocol errors are handled transparently as Go errors: errors in server-side feature handlers are propagated as errors from calls from the `ClientSession`, and vice-versa.
@@ -863,7 +867,7 @@ type ServerOptions struct {
 }
 ```
 
-#### Securty Considerations
+#### Security Considerations
 
 Implementors of the CompletionHandler MUST adhere to the following security guidelines:
 
@@ -952,7 +956,7 @@ In addition to the `List` methods, the SDK provides an iterator method for each
 
 # Governance and Community
 
-While the sections above propose an initial implementation of the Go SDK, MCP is evolving rapidly. SDKs need to keep pace, by implementing changes to the spec, fixing bugs, and accomodating new and emerging use-cases. This section proposes how the SDK project can be managed so that it can change safely and transparently.
+While the sections above propose an initial implementation of the Go SDK, MCP is evolving rapidly. SDKs need to keep pace, by implementing changes to the spec, fixing bugs, and accommodating new and emerging use-cases. This section proposes how the SDK project can be managed so that it can change safely and transparently.
 
 Initially, the Go SDK repository will be administered by the Go team and Anthropic, and they will be the Approvers (the set of people able to merge PRs to the SDK). The policies here are also intended to satisfy necessary constraints of the Go team's participation in the project.
 
@@ -980,7 +984,7 @@ A proposal is an issue that proposes a new API for the SDK, or a change to the s
 
 Proposals that are straightforward and uncontroversial may be approved based on GitHub discussion. However, proposals that are deemed to be sufficiently unclear or complicated will be deferred to a regular steering meeting (see below).
 
-This process is similar to the [Go proposal process](https://github.com/golang/proposal), but is necessarily lighter weight to accomodate the greater rate of change expected for the SDK.
+This process is similar to the [Go proposal process](https://github.com/golang/proposal), but is necessarily lighter weight to accommodate the greater rate of change expected for the SDK.
 
 ### Steering meetings
 

examples/hello/main.go

@@ -25,7 +25,7 @@ type HiArgs struct {
 func SayHi(ctx context.Context, ss *mcp.ServerSession, params *mcp.CallToolParamsFor[HiArgs]) (*mcp.CallToolResultFor[struct{}], error) {
 	return &mcp.CallToolResultFor[struct{}]{
 		Content: []mcp.Content{
-			&mcp.TextContent{Text: "Hi " + params.Name},
+			&mcp.TextContent{Text: "Hi " + params.Arguments.Name},
 		},
 	}, nil
 }

examples/rate-limiting/go.mod

@@ -0,0 +1,8 @@
+module github.com/modelcontextprotocol/go-sdk/examples/rate-limiting
+
+go 1.25
+
+require (
+	github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89
+	golang.org/x/time v0.12.0
+)

examples/rate-limiting/go.sum

@@ -0,0 +1,8 @@
+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/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89 h1:kUGBYP25FTv3ZRBhLT4iQvtx4FDl7hPkWe3isYrMxyo=
+github.com/modelcontextprotocol/go-sdk v0.0.0-20250625185707-09181c2c2e89/go.mod h1:DcXfbr7yl7e35oMpzHfKw2nUYRjhIGS2uou/6tdsTB0=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+golang.org/x/tools v0.34.0 h1:qIpSLOxeCYGg9TrcJokLBG4KFA6d795g0xkBkiESGlo=
+golang.org/x/tools v0.34.0/go.mod h1:pAP9OwEaY1CAW3HOmg3hLZC5Z0CCmzjAF2UQMSqNARg=

examples/rate-limiting/main.go

@@ -0,0 +1,54 @@
+// 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 main
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"golang.org/x/time/rate"
+)
+
+// GlobalRateLimiterMiddleware creates a middleware that applies a global rate limit.
+// Every request attempting to pass through will try to acquire a token.
+// If a token cannot be acquired immediately, the request will be rejected.
+func GlobalRateLimiterMiddleware[S mcp.Session](limiter *rate.Limiter) mcp.Middleware[S] {
+	return func(next mcp.MethodHandler[S]) mcp.MethodHandler[S] {
+		return func(ctx context.Context, session S, method string, params mcp.Params) (mcp.Result, error) {
+			if !limiter.Allow() {
+				return nil, errors.New("JSON RPC overloaded")
+			}
+			return next(ctx, session, method, params)
+		}
+	}
+}
+
+// PerMethodRateLimiterMiddleware creates a middleware that applies rate limiting
+// on a per-method basis.
+// Methods not specified in limiters will not be rate limited by this middleware.
+func PerMethodRateLimiterMiddleware[S mcp.Session](limiters map[string]*rate.Limiter) mcp.Middleware[S] {
+	return func(next mcp.MethodHandler[S]) mcp.MethodHandler[S] {
+		return func(ctx context.Context, session S, method string, params mcp.Params) (mcp.Result, error) {
+			if limiter, ok := limiters[method]; ok {
+				if !limiter.Allow() {
+					return nil, errors.New("JSON RPC overloaded")
+				}
+			}
+			return next(ctx, session, method, params)
+		}
+	}
+}
+
+func main() {
+	server := mcp.NewServer("greeter1", "v0.0.1", nil)
+	server.AddReceivingMiddleware(GlobalRateLimiterMiddleware[*mcp.ServerSession](rate.NewLimiter(rate.Every(time.Second/5), 10)))
+	server.AddReceivingMiddleware(PerMethodRateLimiterMiddleware[*mcp.ServerSession](map[string]*rate.Limiter{
+		"callTool":  rate.NewLimiter(rate.Every(time.Second), 5),  // once a second with a burst up to 5
+		"listTools": rate.NewLimiter(rate.Every(time.Minute), 20), // once a minute with a burst up to 20
+	}))
+	// Run Server logic.
+}

examples/sse/main.go

@@ -22,7 +22,7 @@ type SayHiParams struct {
 func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[SayHiParams]) (*mcp.CallToolResultFor[any], error) {
 	return &mcp.CallToolResultFor[any]{
 		Content: []mcp.Content{
-			&mcp.TextContent{Text: "Hi " + params.Name},
+			&mcp.TextContent{Text: "Hi " + params.Arguments.Name},
 		},
 	}, nil
 }