github--github-mcp-server/pkg/toolvalidation/readonlyhint.go

// 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
}