chore: import upstream snapshot with attribution

2026-07-13 12:37:57 +08:00
commit e30f8ba47c
533 changed files with 115926 additions and 0 deletions
@@ -0,0 +1,256 @@
+// Package toolvalidation provides source-level (AST) validators for MCP tool
+// registrations. It is intended to be consumed from _test.go files in any
+// package that registers mcp.Tool literals (including downstream repositories
+// such as github-mcp-server-remote) so the same guardrails apply everywhere
+// without duplicating the parsing logic.
+package toolvalidation
+
+import (
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// MCPImportPath is the canonical module path of the MCP go-sdk. Source files
+// that import this path under any alias (including the default `mcp`) are
+// candidates for tool-literal validation.
+const MCPImportPath = "github.com/modelcontextprotocol/go-sdk/mcp"
+
+// ReadOnlyHintViolation describes a single mcp.Tool composite literal that
+// failed the ReadOnlyHint check.
+type ReadOnlyHintViolation struct {
+	// File is the path to the offending source file, made relative to the
+	// scan directory when possible.
+	File string
+	// Line is the 1-indexed line number of the offending literal.
+	Line int
+	// ToolName is the value of the Name field on the mcp.Tool literal, or
+	// "<unknown>" when it cannot be statically extracted.
+	ToolName string
+	// Reason is a human-readable explanation of why the literal failed.
+	Reason string
+}
+
+// String renders a violation in the format used by FormatReadOnlyHintViolations:
+// "<file>:<line> tool=<name>: <reason>".
+func (v ReadOnlyHintViolation) String() string {
+	return fmt.Sprintf("%s:%d tool=%s: %s", v.File, v.Line, v.ToolName, v.Reason)
+}
+
+// ScanReadOnlyHint parses every non-test .go file in dir (a single package
+// directory) and returns a violation for each mcp.Tool composite literal that
+// does not explicitly set Annotations.ReadOnlyHint.
+//
+// The Go runtime cannot distinguish an unset bool field from one explicitly
+// set to false, so this AST-level check exists to prevent future tool
+// registrations from silently defaulting ReadOnlyHint to false — which has
+// triggered downstream agents to prompt for human approval on safe read
+// operations.
+//
+// Callers typically invoke this from a _test.go file:
+//
+//	dir, _ := os.Getwd()
+//	violations, err := toolvalidation.ScanReadOnlyHint(dir)
+func ScanReadOnlyHint(dir string) ([]ReadOnlyHintViolation, error) {
+	fset := token.NewFileSet()
+	pkgs, err := parser.ParseDir(fset, dir, func(info os.FileInfo) bool {
+		// Skip test files: they are allowed to construct mcp.Tool literals
+		// for fixtures or mocks where ReadOnlyHint is not meaningful.
+		return !strings.HasSuffix(info.Name(), "_test.go")
+	}, parser.ParseComments)
+	if err != nil {
+		return nil, fmt.Errorf("parse package directory %q: %w", dir, err)
+	}
+
+	var violations []ReadOnlyHintViolation
+	for _, pkg := range pkgs {
+		for filename, file := range pkg.Files {
+			aliases := mcpAliasesFor(file)
+			if len(aliases) == 0 {
+				continue
+			}
+			rel, relErr := filepath.Rel(dir, filename)
+			if relErr != nil || rel == "" {
+				rel = filepath.Base(filename)
+			}
+			ast.Inspect(file, func(n ast.Node) bool {
+				cl, ok := n.(*ast.CompositeLit)
+				if !ok {
+					return true
+				}
+				if !isQualifiedType(cl.Type, aliases, "Tool") {
+					return true
+				}
+				violations = append(violations, checkToolLiteral(cl, aliases, rel, fset.Position(cl.Pos()).Line)...)
+				return true
+			})
+		}
+	}
+	return violations, nil
+}
+
+// FormatReadOnlyHintViolations renders a single multi-line error message
+// suitable for passing to t.Fatal. Returns "" when violations is empty.
+func FormatReadOnlyHintViolations(violations []ReadOnlyHintViolation) string {
+	if len(violations) == 0 {
+		return ""
+	}
+	var msg strings.Builder
+	msg.WriteString("Found tool registrations that do not explicitly set ReadOnlyHint:\n")
+	for _, v := range violations {
+		msg.WriteString("  - ")
+		msg.WriteString(v.String())
+		msg.WriteByte('\n')
+	}
+	msg.WriteString("\nEvery mcp.Tool registration must declare Annotations.ReadOnlyHint explicitly ")
+	msg.WriteString("(true for read-only tools, false for tools with side effects). ")
+	msg.WriteString("See pkg/toolvalidation.ScanReadOnlyHint.")
+	return msg.String()
+}
+
+func checkToolLiteral(cl *ast.CompositeLit, aliases map[string]struct{}, file string, line int) []ReadOnlyHintViolation {
+	toolName := extractToolName(cl)
+	if toolName == "" {
+		toolName = "<unknown>"
+	}
+	mk := func(reason string) ReadOnlyHintViolation {
+		return ReadOnlyHintViolation{File: file, Line: line, ToolName: toolName, Reason: reason}
+	}
+
+	if hasUnkeyedFields(cl) {
+		return []ReadOnlyHintViolation{mk("mcp.Tool literal uses positional (unkeyed) fields; this check requires keyed fields so Annotations.ReadOnlyHint can be verified")}
+	}
+
+	annotations := findFieldValue(cl, "Annotations")
+	if annotations == nil {
+		return []ReadOnlyHintViolation{mk("mcp.Tool literal is missing an Annotations field")}
+	}
+
+	annoLit := unwrapAnnotationsLiteral(annotations, aliases)
+	if annoLit == nil {
+		return []ReadOnlyHintViolation{mk("Annotations is not an &mcp.ToolAnnotations{...} literal; ReadOnlyHint cannot be statically verified")}
+	}
+
+	if hasUnkeyedFields(annoLit) {
+		return []ReadOnlyHintViolation{mk("mcp.ToolAnnotations literal uses positional (unkeyed) fields; use keyed fields so ReadOnlyHint can be verified")}
+	}
+
+	if findFieldValue(annoLit, "ReadOnlyHint") == nil {
+		return []ReadOnlyHintViolation{mk("ToolAnnotations literal does not explicitly set ReadOnlyHint")}
+	}
+	return nil
+}
+
+// mcpAliasesFor returns the set of local identifiers under which the given
+// file imports the MCP go-sdk (MCPImportPath). The default unaliased import
+// resolves to the package name "mcp". Blank (`_`) and dot (`.`) imports are
+// skipped because tool literals cannot meaningfully be qualified through them.
+func mcpAliasesFor(file *ast.File) map[string]struct{} {
+	aliases := map[string]struct{}{}
+	for _, imp := range file.Imports {
+		path, err := strconv.Unquote(imp.Path.Value)
+		if err != nil || path != MCPImportPath {
+			continue
+		}
+		if imp.Name != nil {
+			if imp.Name.Name == "_" || imp.Name.Name == "." {
+				continue
+			}
+			aliases[imp.Name.Name] = struct{}{}
+			continue
+		}
+		aliases["mcp"] = struct{}{}
+	}
+	return aliases
+}
+
+// isQualifiedType reports whether expr is a SelectorExpr of the form
+// <alias>.<typeName> where alias is in the provided alias set.
+func isQualifiedType(expr ast.Expr, aliases map[string]struct{}, typeName string) bool {
+	sel, ok := expr.(*ast.SelectorExpr)
+	if !ok {
+		return false
+	}
+	ident, ok := sel.X.(*ast.Ident)
+	if !ok {
+		return false
+	}
+	if _, ok := aliases[ident.Name]; !ok {
+		return false
+	}
+	return sel.Sel != nil && sel.Sel.Name == typeName
+}
+
+// hasUnkeyedFields reports whether the composite literal has any positional
+// (non-key/value) elements. The static check cannot reliably map positional
+// fields without full type information, so such literals are rejected with a
+// dedicated diagnostic rather than producing false "missing field" violations.
+func hasUnkeyedFields(cl *ast.CompositeLit) bool {
+	for _, elt := range cl.Elts {
+		if _, ok := elt.(*ast.KeyValueExpr); !ok {
+			return true
+		}
+	}
+	return false
+}
+
+// findFieldValue returns the value expression for the named keyed field of a
+// composite literal, or nil if the field is absent.
+func findFieldValue(cl *ast.CompositeLit, name string) ast.Expr {
+	for _, elt := range cl.Elts {
+		kv, ok := elt.(*ast.KeyValueExpr)
+		if !ok {
+			continue
+		}
+		key, ok := kv.Key.(*ast.Ident)
+		if !ok {
+			continue
+		}
+		if key.Name == name {
+			return kv.Value
+		}
+	}
+	return nil
+}
+
+// unwrapAnnotationsLiteral attempts to extract the *ast.CompositeLit for
+// &mcp.ToolAnnotations{...} or mcp.ToolAnnotations{...} from an expression,
+// resolving the MCP package's local alias per file.
+func unwrapAnnotationsLiteral(expr ast.Expr, aliases map[string]struct{}) *ast.CompositeLit {
+	if u, ok := expr.(*ast.UnaryExpr); ok && u.Op == token.AND {
+		expr = u.X
+	}
+	cl, ok := expr.(*ast.CompositeLit)
+	if !ok {
+		return nil
+	}
+	if !isQualifiedType(cl.Type, aliases, "ToolAnnotations") {
+		return nil
+	}
+	return cl
+}
+
+// extractToolName returns the literal value of the Name field of an mcp.Tool
+// composite literal, or empty string if the value is not a basic string literal.
+// Interpreted ("...") and raw (`...`) string literals are handled via
+// strconv.Unquote so embedded escapes are decoded correctly; the raw
+// literal value is returned as a best-effort fallback if unquoting fails.
+func extractToolName(cl *ast.CompositeLit) string {
+	v := findFieldValue(cl, "Name")
+	if v == nil {
+		return ""
+	}
+	bl, ok := v.(*ast.BasicLit)
+	if !ok || bl.Kind != token.STRING {
+		return ""
+	}
+	if unq, err := strconv.Unquote(bl.Value); err == nil {
+		return unq
+	}
+	return bl.Value
+}