Server handlers implementation for auto-completion (#679)

* Define other types for completion

* Define CompletionProvider and default implementation

* Implement and generate handler for completion

* Define tests for handleComplete

* Follow interface segregation

* Fix completions not reported to client

* Refactor completion provider for context

* Refactor "everything" example for completion

* Add quick guide for auto completion in README

* Simplify auto-completion README section

* Prevent nil pointer dereference on mcp.Completion and return INVALID_REQUEST to match marshal error behavior

Author: ezraisw

README.md

@@ -778,3 +778,114 @@ go generate ./...
 You need `go` installed and the `goimports` tool available. The generator runs
 `goimports` automatically to format and fix imports.
 
+### Auto-completions
+
+When users are filling in argument values for a specific prompt (identified by name) or resource template (identified by URI), servers can provide contextual suggestions.
+To enable completion support, use the `server.WithCompletions()` option when creating your server.
+
+#### Completion Providers
+
+You can provide completion logic for both prompt arguments and resource template arguments by implementing the respective interfaces and passing them to the server as options.
+
+<details>
+<summary>Show Completion Provider Examples</summary>
+
+```go
+type MyPromptCompletionProvider struct{}
+
+func (p *MyPromptCompletionProvider) CompletePromptArgument(
+    ctx context.Context,
+    promptName string,
+    argument mcp.CompleteArgument,
+    context mcp.CompleteContext,
+) (*mcp.Completion, error) {
+    // Example: provide style suggestions for a "code_review" prompt
+    if promptName == "code_review" && argument.Name == "style" {
+        styles := []string{"formal", "casual", "technical", "creative"}
+        var suggestions []string
+        
+        // Filter based on current input
+        for _, style := range styles {
+            if strings.HasPrefix(style, argument.Value) {
+                suggestions = append(suggestions, style)
+            }
+        }
+        
+        return &mcp.Completion{
+            Values: suggestions,
+        }, nil
+    }
+    
+    // Return empty suggestions for unhandled cases
+    return &mcp.Completion{Values: []string{}}, nil
+}
+
+type MyResourceCompletionProvider struct{}
+
+func (p *MyResourceCompletionProvider) CompleteResourceArgument(
+    ctx context.Context,
+    uri string,
+    argument mcp.CompleteArgument,
+    context mcp.CompleteContext,
+) (*mcp.Completion, error) {
+    // Example: provide file path completions
+    if uri == "file:///{path}" && argument.Name == "path" {
+        // You can access previously completed arguments from context.Arguments
+        // context.Arguments is a map[string]string of already-resolved arguments
+        
+        paths := getMatchingPaths(argument.Value) // Your custom logic
+        
+        return &mcp.Completion{
+            Values:  paths[:min(len(paths), 100)], // Max 100 items
+            Total:   len(paths),                    // Total available matches
+            HasMore: len(paths) > 100,              // More results available
+        }, nil
+    }
+    
+    return &mcp.Completion{Values: []string{}}, nil
+}
+
+// Register the provider
+mcpServer := server.NewMCPServer(
+    "my-server",
+    "1.0.0",
+    server.WithCompletions(),
+    server.WithPromptCompletionProvider(&MyPromptCompletionProvider{}),
+    server.WithResourceCompletionProvider(&MyResourceCompletionProvider{}),
+)
+```
+
+</details>
+
+#### Completion Context
+
+For prompts or resource templates with multiple arguments, the `CompleteContext` parameter provides access to previously completed arguments. This allows you to provide contextual suggestions based on earlier choices.
+
+<details>
+<summary>Show Completion Context Example</summary>
+
+```go
+func (p *MyProvider) CompleteResourceArgument(
+    ctx context.Context,
+    uri string,
+    argument mcp.CompleteArgument,
+    context mcp.CompleteContext,
+) (*mcp.Completion, error) {
+    // Access previously completed arguments
+    if previousValue, ok := context.Arguments["previous_arg"]; ok {
+        // Provide suggestions based on previous_arg value
+        return getSuggestionsFor(argument.Value, previousValue), nil
+    }
+    
+    return &mcp.Completion{Values: []string{}}, nil
+}
+```
+
+</details>
+
+#### Response Constraints
+
+When returning completion results:
+- Maximum 100 items per response
+- Use `Total` to indicate the total number of available matches
+- Use `HasMore` to signal if additional results exist beyond the returned values

examples/everything/id.go

@@ -0,0 +1,42 @@
+package main
+
+import "strconv"
+
+func pow(n int, p int) int {
+	result := 1
+	for p > 0 {
+		if (p & 1) == 1 {
+			result *= n
+		}
+		n *= n
+		p >>= 1
+	}
+	return result
+}
+
+// n < 10000 is 4 digits
+var maxDigits = 4
+var maxId = pow(10, maxDigits)
+
+func isIdInRange(num int) bool {
+	return num >= 0 && num < maxId
+}
+
+// getIdSuggestions returns 10 suggestions for a given number.
+// It returns the current argument value appended with 0-9.
+func getIdSuggestions(num int) []string {
+	suggestions := make([]string, 0, 10)
+	for i := range 10 {
+		suggestions = append(suggestions, strconv.Itoa(num*10+i))
+	}
+	return suggestions
+}
+
+func getTotalIds(digits int) int {
+	// Leftover digits represent the total number of choices.
+	return pow(10, maxDigits-digits)
+}
+
+func hasMoreIds(digits int) bool {
+	return digits < maxDigits-1
+}

examples/everything/main.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"log"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/mark3labs/mcp-go/mcp"
@@ -69,6 +70,9 @@ func NewMCPServer() *server.MCPServer {
 		server.WithToolCapabilities(true),
 		server.WithLogging(),
 		server.WithHooks(hooks),
+		server.WithCompletions(),
+		server.WithPromptCompletionProvider(&promptCompletionProvider{}),
+		server.WithResourceCompletionProvider(&resourceCompletionProvider{}),
 	)
 
 	mcpServer.AddResource(mcp.NewResource("test://static/resource",
@@ -501,13 +505,80 @@ func handleGetTinyImageTool(
 	}, nil
 }
 
+var styles = []string{"formal", "casual", "technical", "creative"}
+
 func handleNotification(
 	ctx context.Context,
 	notification mcp.JSONRPCNotification,
 ) {
 	log.Printf("Received notification: %s", notification.Method)
 }
 
+type promptCompletionProvider struct{}
+
+func (p *promptCompletionProvider) CompletePromptArgument(ctx context.Context, promptName string, argument mcp.CompleteArgument, context mcp.CompleteContext) (*mcp.Completion, error) {
+	switch promptName {
+	case string(COMPLEX):
+		if argument.Name == "style" {
+			var suggestions []string
+			for _, style := range styles {
+				if argument.Value == "" || strings.HasPrefix(style, argument.Value) {
+					suggestions = append(suggestions, style)
+				}
+			}
+			return &mcp.Completion{
+				Values: suggestions,
+			}, nil
+		}
+		fallthrough
+	default:
+		return &mcp.Completion{
+			Values: []string{},
+		}, nil
+	}
+}
+
+type resourceCompletionProvider struct{}
+
+// CompleteResourceArgument here is implemented to return suggestions for "test://dynamic/resource/{id}" template, specifically for the "id" argument.
+func (p *resourceCompletionProvider) CompleteResourceArgument(ctx context.Context, uri string, argument mcp.CompleteArgument, context mcp.CompleteContext) (*mcp.Completion, error) {
+	if uri == "test://dynamic/resource/{id}" && argument.Name == "id" {
+		if len(argument.Value) == 0 {
+			return &mcp.Completion{
+				Values:  getIdSuggestions(0),
+				Total:   maxId,
+				HasMore: true,
+			}, nil
+		}
+
+		// If the input is not a number, return empty suggestion.
+		intArgVal, err := strconv.Atoi(argument.Value)
+		if err != nil {
+			return &mcp.Completion{
+				Values: []string{},
+			}, nil
+		}
+
+		digits := len(argument.Value)
+
+		// If the input is out of range, return empty suggestion.
+		if !isIdInRange(intArgVal) {
+			return &mcp.Completion{
+				Values: []string{},
+			}, nil
+		}
+
+		return &mcp.Completion{
+			Values:  getIdSuggestions(intArgVal),
+			Total:   getTotalIds(digits),
+			HasMore: hasMoreIds(digits),
+		}, nil
+	}
+	return &mcp.Completion{
+		Values: []string{},
+	}, nil
+}
+
 func main() {
 	var transport string
 	flag.StringVar(&transport, "t", "stdio", "Transport type (stdio or http)")

mcp/types.go

@@ -103,6 +103,10 @@ const (
 	// MethodNotificationTasksStatus notifies when a task's status changes.
 	// https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks
 	MethodNotificationTasksStatus = "notifications/tasks/status"
+
+	// MethodCompletionComplete returns completion suggestions for a given argument
+	// https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion
+	MethodCompletionComplete MCPMethod = "completion/complete"
 )
 
 type URITemplate struct {
@@ -556,6 +560,8 @@ type ServerCapabilities struct {
 	Roots *struct{} `json:"roots,omitempty"`
 	// Present if the server supports task-based execution.
 	Tasks *TasksCapability `json:"tasks,omitempty"`
+	// Present if the server supports completions requests to the client.
+	Completions *struct{} `json:"completions,omitempty"`
 }
 
 // Icon represents a visual identifier for MCP entities.
@@ -1202,29 +1208,81 @@ type CompleteRequest struct {
 	Header http.Header    `json:"-"`
 }
 
+// CompleteParams are the parameters for a completion/complete request
 type CompleteParams struct {
-	Ref      any `json:"ref"` // Can be PromptReference or ResourceReference
-	Argument struct {
-		// The name of the argument
-		Name string `json:"name"`
-		// The value of the argument to use for completion matching.
-		Value string `json:"value"`
-	} `json:"argument"`
+	Ref      any              `json:"ref"` // Can be PromptReference or ResourceReference
+	Argument CompleteArgument `json:"argument"`
+	Context  CompleteContext  `json:"context"`
+}
+
+func (p *CompleteParams) UnmarshalJSON(data []byte) error {
+	// Use a temporary type to avoid infinite recursion on UnmarshalJSON
+	type Alias CompleteParams
+	aux := &struct {
+		// Use RawMessage to delay unmarshalling until after the type is known
+		Ref json.RawMessage `json:"ref"`
+		*Alias
+	}{
+		Alias: (*Alias)(p),
+	}
+	if err := json.Unmarshal(data, aux); err != nil {
+		return err
+	}
+	// Use a temporary "type peek" struct to determine the type
+	var typePeek struct {
+		Type string `json:"type"`
+	}
+	if err := json.Unmarshal(aux.Ref, &typePeek); err != nil {
+		return err
+	}
+	switch typePeek.Type {
+	case "ref/prompt":
+		var prompt PromptReference
+		if err := json.Unmarshal(aux.Ref, &prompt); err != nil {
+			return err
+		}
+		p.Ref = prompt
+	case "ref/resource":
+		var resource ResourceReference
+		if err := json.Unmarshal(aux.Ref, &resource); err != nil {
+			return err
+		}
+		p.Ref = resource
+	default:
+		return fmt.Errorf("unknown reference type: %s", typePeek.Type)
+	}
+	return nil
 }
 
 // CompleteResult is the server's response to a completion/complete request
 type CompleteResult struct {
 	Result
-	Completion struct {
-		// An array of completion values. Must not exceed 100 items.
-		Values []string `json:"values"`
-		// The total number of completion options available. This can exceed the
-		// number of values actually sent in the response.
-		Total int `json:"total,omitempty"`
-		// Indicates whether there are additional completion options beyond those
-		// provided in the current response, even if the exact total is unknown.
-		HasMore bool `json:"hasMore,omitempty"`
-	} `json:"completion"`
+	Completion Completion `json:"completion"`
+}
+
+// CompleteArgument is an argument to a completion request
+type CompleteArgument struct {
+	// The name of the argument
+	Name string `json:"name"`
+	// The value of the argument to use for completion matching.
+	Value string `json:"value"`
+}
+
+// CompleteContext is the context about already-resolved arguments
+type CompleteContext struct {
+	Arguments map[string]string `json:"arguments"`
+}
+
+// Completion is the server's response to a completion/complete request
+type Completion struct {
+	// An array of completion values. Must not exceed 100 items.
+	Values []string `json:"values"`
+	// The total number of completion options available. This can exceed the
+	// number of values actually sent in the response.
+	Total int `json:"total,omitempty"`
+	// Indicates whether there are additional completion options beyond those
+	// provided in the current response, even if the exact total is unknown.
+	HasMore bool `json:"hasMore,omitempty"`
 }
 
 // ResourceReference is a reference to a resource or resource template definition.