internal/mcp: implement resource templates

Provide support for resource templates on the client and server.

Adding, removing and listing resource templates looks just like those
operations on resources.

Although the spec provides no guidance on the unique ID for resource
templates, we follow most existing SDKs, as well as the parallel with
resources, and index on the URI template rather than the name.

As the spec recommends, the server verifies an incoming URI in a
ReadResource request against its list of resources and resource
templates, to make sure the URI came from one of them. The main
technical challenge here is the need to check that a URI template could
have produced a particular URI.

I wrote a very simplified version of this check. At some point
we should switch to github.com/yosida95/uritemplate/v3.

Change-Id: I1e34dd01c8f2171123c68c045ad62f5e85c05e7c
Reviewed-on: https://go-review.googlesource.com/c/tools/+/680158
Auto-Submit: Jonathan Amsterdam <jba@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>

Author: jba

internal/mcp/client.go

@@ -328,6 +328,11 @@ func (cs *ClientSession) ListResources(ctx context.Context, params *ListResource
 	return handleSend[*ListResourcesResult](ctx, cs, methodListResources, params)
 }
 
+// ListResourceTemplates lists the resource templates that are currently available on the server.
+func (cs *ClientSession) ListResourceTemplates(ctx context.Context, params *ListResourceTemplatesParams) (*ListResourceTemplatesResult, error) {
+	return handleSend[*ListResourceTemplatesResult](ctx, cs, methodListResourceTemplates, params)
+}
+
 // ReadResource ask the server to read a resource and return its contents.
 func (cs *ClientSession) ReadResource(ctx context.Context, params *ReadResourceParams) (*ReadResourceResult, error) {
 	return handleSend[*ReadResourceResult](ctx, cs, methodReadResource, params)

internal/mcp/generate.go

@@ -104,6 +104,11 @@ var declarations = config{
 		Fields: config{"Params": {Name: "ListResourcesParams"}},
 	},
 	"ListResourcesResult": {},
+	"ListResourceTemplatesRequest": {
+		Name:   "-",
+		Fields: config{"Params": {Name: "ListResourceTemplatesParams"}},
+	},
+	"ListResourceTemplatesResult": {},
 	"ListRootsRequest": {
 		Name:   "-",
 		Fields: config{"Params": {Name: "ListRootsParams"}},
@@ -152,6 +157,11 @@ var declarations = config{
 		Name:   "-",
 		Fields: config{"Params": {Name: "ResourceListChangedParams"}},
 	},
+	"ResourceTemplate": {},
+	"ResourceTemplateListChangedNotification": {
+		Name:   "-",
+		Fields: config{"Params": {Name: "ResourceTemplateListChangedParams"}},
+	},
 	"Role": {},
 	"Root": {},
 	"RootsListChangedNotification": {

internal/mcp/mcp_test.go

@@ -237,32 +237,53 @@ func TestEndToEnd(t *testing.T) {
 			t.Errorf("resources/list mismatch (-want, +got):\n%s", diff)
 		}
 
+		template := &ResourceTemplate{
+			Name:        "rt",
+			MIMEType:    "text/template",
+			URITemplate: "file:///{+filename}", // the '+' means that filename can contain '/'
+		}
+		st := &ServerResourceTemplate{ResourceTemplate: template, Handler: readHandler}
+		s.AddResourceTemplates(st)
+		tres, err := cs.ListResourceTemplates(ctx, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if diff := cmp.Diff([]*ResourceTemplate{template}, tres.ResourceTemplates); diff != "" {
+			t.Errorf("resources/list mismatch (-want, +got):\n%s", diff)
+		}
+
 		for _, tt := range []struct {
 			uri      string
 			mimeType string // "": not found; "text/plain": resource; "text/template": template
+			fail     bool   // non-nil error returned
 		}{
-			{"file:///info.txt", "text/plain"},
-			{"file:///fail.txt", ""},
-			// TODO(jba): add resource template cases when we implement them
+			{"file:///info.txt", "text/plain", false},
+			{"file:///fail.txt", "", false},
+			{"file:///template.txt", "text/template", false},
+			{"file:///../private.txt", "", true}, // not found: escaping disallowed
 		} {
 			rres, err := cs.ReadResource(ctx, &ReadResourceParams{URI: tt.uri})
 			if err != nil {
 				if code := errorCode(err); code == CodeResourceNotFound {
 					if tt.mimeType != "" {
 						t.Errorf("%s: not found but expected it to be", tt.uri)
 					}
-				} else {
-					t.Errorf("reading %s: %v", tt.uri, err)
+				} else if !tt.fail {
+					t.Errorf("%s: unexpected error %v", tt.uri, err)
 				}
-			} else if g, w := len(rres.Contents), 1; g != w {
-				t.Errorf("got %d contents, wanted %d", g, w)
 			} else {
-				c := rres.Contents[0]
-				if got := c.URI; got != tt.uri {
-					t.Errorf("got uri %q, want %q", got, tt.uri)
-				}
-				if got := c.MIMEType; got != tt.mimeType {
-					t.Errorf("%s: got MIME type %q, want %q", tt.uri, got, tt.mimeType)
+				if tt.fail {
+					t.Errorf("%s: unexpected success", tt.uri)
+				} else if g, w := len(rres.Contents), 1; g != w {
+					t.Errorf("got %d contents, wanted %d", g, w)
+				} else {
+					c := rres.Contents[0]
+					if got := c.URI; got != tt.uri {
+						t.Errorf("got uri %q, want %q", got, tt.uri)
+					}
+					if got := c.MIMEType; got != tt.mimeType {
+						t.Errorf("%s: got MIME type %q, want %q", tt.uri, got, tt.mimeType)
+					}
 				}
 			}
 		}

internal/mcp/protocol.go

@@ -13,6 +13,7 @@ import (
 	"net/url"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 
 	jsonrpc2 "golang.org/x/tools/internal/jsonrpc2_v2"
@@ -25,7 +26,14 @@ type ServerResource struct {
 	Handler  ResourceHandler
 }
 
+// A ServerResourceTemplate associates a ResourceTemplate with its handler.
+type ServerResourceTemplate struct {
+	ResourceTemplate *ResourceTemplate
+	Handler          ResourceHandler
+}
+
 // A ResourceHandler is a function that reads a resource.
+// It will be called when the client calls [ClientSession.ReadResource].
 // If it cannot find the resource, it should return the result of calling [ResourceNotFoundError].
 type ResourceHandler func(context.Context, *ServerSession, *ReadResourceParams) (*ReadResourceResult, error)
 
@@ -145,3 +153,69 @@ func fileRoot(root *Root) (_ string, err error) {
 	}
 	return fileRoot, nil
 }
+
+// Matches reports whether the receiver's uri template matches the uri.
+// TODO: use "github.com/yosida95/uritemplate/v3"
+func (sr *ServerResourceTemplate) Matches(uri string) bool {
+	re, err := uriTemplateToRegexp(sr.ResourceTemplate.URITemplate)
+	if err != nil {
+		return false
+	}
+	return re.MatchString(uri)
+}
+
+func uriTemplateToRegexp(uriTemplate string) (*regexp.Regexp, error) {
+	pat := uriTemplate
+	var b strings.Builder
+	b.WriteByte('^')
+	seen := map[string]bool{}
+	for len(pat) > 0 {
+		literal, rest, ok := strings.Cut(pat, "{")
+		b.WriteString(regexp.QuoteMeta(literal))
+		if !ok {
+			break
+		}
+		expr, rest, ok := strings.Cut(rest, "}")
+		if !ok {
+			return nil, errors.New("missing '}'")
+		}
+		pat = rest
+		if strings.ContainsRune(expr, ',') {
+			return nil, errors.New("can't handle commas in expressions")
+		}
+		if strings.ContainsRune(expr, ':') {
+			return nil, errors.New("can't handle prefix modifiers in expressions")
+		}
+		if len(expr) > 0 && expr[len(expr)-1] == '*' {
+			return nil, errors.New("can't handle explode modifiers in expressions")
+		}
+
+		// These sets of valid characters aren't accurate.
+		// See https://datatracker.ietf.org/doc/html/rfc6570.
+		var re, name string
+		first := byte(0)
+		if len(expr) > 0 {
+			first = expr[0]
+		}
+		switch first {
+		default:
+			// {var} doesn't match slashes. (It should also fail to match other characters,
+			// but this simplified implementation doesn't handle that.)
+			re = `[^/]*`
+			name = expr
+		case '+':
+			// {+var} matches anything, even slashes
+			re = `.*`
+			name = expr[1:]
+		case '#', '.', '/', ';', '?', '&':
+			return nil, fmt.Errorf("prefix character %c unsupported", first)
+		}
+		if seen[name] {
+			return nil, fmt.Errorf("can't handle duplicate name %q", name)
+		}
+		seen[name] = true
+		b.WriteString(re)
+	}
+	b.WriteByte('$')
+	return regexp.Compile(b.String())
+}

internal/mcp/resource.go

@@ -112,3 +112,25 @@ func TestReadFileResource(t *testing.T) {
 		t.Errorf("got %q, want %q", g, want)
 	}
 }
+
+func TestTemplateMatch(t *testing.T) {
+	uri := "file:///path/to/file"
+	for _, tt := range []struct {
+		template string
+		want     bool
+	}{
+		{"file:///{}/{a}/{b}", true},
+		{"file:///{a}/{b}", false},
+		{"file:///{+path}", true},
+		{"file:///{a}/{+path}", true},
+	} {
+		re, err := uriTemplateToRegexp(tt.template)
+		if err != nil {
+			t.Fatalf("%s: %v", tt.template, err)
+		}
+		got := re.MatchString(uri)
+		if got != tt.want {
+			t.Errorf("%s: got %t, want %t", tt.template, got, tt.want)
+		}
+	}
+}