toolannotations

package
v0.70.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package toolannotations is the single source of truth for MCP tool-annotation filter semantics (Spec 035 F4, Spec 094 FR-004).

It is a leaf package: it depends only on internal/config for the annotation shape and performs no I/O whatsoever. It was extracted from internal/server/mcp_annotations.go so that lower-level consumers — notably the Spec 098 preflight evaluator — can classify a tool against the same filters the retrieve_tools handler applies, without importing internal/server (which would be an import cycle) and without re-implementing the semantics (which would let the two drift).

The behavior is byte-identical to the pre-extraction implementation; the server package now delegates to these functions.

Index

Constants

View Source
const (
	FilterKeyReadOnlyOnly     = "read_only_only"
	FilterKeyExcludeDestruct  = "exclude_destructive"
	FilterKeyExcludeOpenWorld = "exclude_open_world"
)

Filter parameter names, used as the diagnostics map keys (Spec 094 FR-003) and interpolated literally into the suggestion string (FR-006).

Variables

This section is empty.

Functions

func ExcludeReason

func ExcludeReason(annotations *config.ToolAnnotations, readOnlyOnly, excludeDestructive, excludeOpenWorld bool) (filterKey string, explicit, excluded bool)

ExcludeReason decides whether a tool is excluded and, when it is, which filter is responsible and why (Spec 094 FR-004). It is the single source of truth for the filter semantics — ShouldExclude delegates to it, so the diagnostics can never describe a different filter than the one that ran.

Filters are evaluated read-only → destructive → open-world and the FIRST one that excludes the tool owns the omission, which keeps per-filter counts summable (no double counting). `explicit` distinguishes an omission caused by an explicitly unsafe hint (remediation: none, the filter is working) from one caused by absent/unset annotations (remediation: fix upstream metadata).

func ExcludeReasonFor

func ExcludeReasonFor(annotations *config.ToolAnnotations, f Filters) (filterKey string, explicit, excluded bool)

ExcludeReasonFor is the Filters-typed form of ExcludeReason, for callers that already carry a Filters value.

func ShouldExclude

func ShouldExclude(annotations *config.ToolAnnotations, readOnlyOnly, excludeDestructive, excludeOpenWorld bool) bool

ShouldExclude returns true if a tool should be excluded based on its annotations and the active filters.

Types

type Filters

type Filters struct {
	ReadOnlyOnly       bool
	ExcludeDestructive bool
	ExcludeOpenWorld   bool
}

Filters is the set of annotation filters a caller activated. The zero value means "no filtering", for which every tool passes.

func (Filters) Any

func (f Filters) Any() bool

Any reports whether at least one filter is active.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL