toolkit

type AnnotationConfig ¶ added in v1.101.0

type AnnotationConfig struct {
	ReadOnlyHint    *bool `yaml:"read_only_hint"`
	DestructiveHint *bool `yaml:"destructive_hint"`
	IdempotentHint  *bool `yaml:"idempotent_hint"`
	OpenWorldHint   *bool `yaml:"open_world_hint"`
}

AnnotationConfig is the YAML-configurable set of MCP tool annotation hints shared by every toolkit. Each field is a pointer so an unset hint (inherit the tool's built-in default) is distinct from an explicit false.

type ConnectionDetail ¶

type ConnectionDetail struct {
	Name           string
	Description    string
	IsDefault      bool
	CatalogID      string
	OperationCount int
	// Health is optional per-connection reachability, populated by gateway
	// kinds that hold a live upstream session (so an evicted or dead upstream
	// is observable from list_connections instead of only when a downstream
	// tool call fails). Nil for toolkits that do not track reachability.
	Health *ConnectionHealth
}

ConnectionDetail provides information about a single connection within a toolkit.

CatalogID and OperationCount are optional and only populated by toolkits where they have meaning (today: apigateway). They exist on this shared struct so list_connections can surface what's actually bound at runtime rather than only what's stored in the DB. The two disagreed in the past when a config update reached the store but never reached the in-memory toolkit, and the missing fields here made the divergence invisible from the MCP surface.

type ConnectionHealth ¶ added in v1.82.0

type ConnectionHealth struct {
	// Reachable is true when the connection has a live session and its most
	// recent forwarded call did not end in an unrecovered transport error.
	Reachable bool
	// LastSuccessUnix is the unix-seconds time of the last successful
	// forwarded call (or the initial connect). Zero when none has succeeded.
	LastSuccessUnix int64
	// LastError is the most recent call or connect failure, empty when healthy.
	LastError string
}

ConnectionHealth is the runtime reachability of a gateway upstream.

Reachability is observed passively from forwarded traffic, not from an active background probe: a transport error or timeout on a forwarded call marks the connection unreachable, and it is cleared by the next successful call (or a re-dial). So an idle connection that saw one transient failure can read unreachable until traffic resumes, even though its session is alive. A tool-level error (e.g. bad arguments) is NOT a transport failure and does not affect reachability.

func (h *ConnectionHealth) Wire() *ConnectionHealthWire

type ConnectionHealthWire ¶ added in v1.83.0

type ConnectionHealthWire struct {
	Reachable   bool   `json:"reachable"`
	LastSuccess string `json:"last_success,omitempty"`
	LastError   string `json:"last_error,omitempty"`
}

ConnectionHealthWire is the JSON wire shape for ConnectionHealth, shared by every operator surface (the list_connections MCP tool and the admin connections API) so they report identical reachability for the same connection by construction rather than by two copies happening to agree.

type ConnectionLister ¶

type ConnectionLister interface {
	ListConnections() []ConnectionDetail
}

ConnectionLister is an optional interface for toolkits that manage multiple connections internally. Toolkits implementing this interface expose all their connections for discovery via the list_connections tool.

type ConnectionManager ¶ added in v1.48.0

type ConnectionManager interface {
	AddConnection(name string, config map[string]any) error
	RemoveConnection(name string) error
	HasConnection(name string) bool
}

ConnectionManager is an optional interface for toolkits that support adding and removing backend connections at runtime without restart. Used by the admin API to make DB-managed connections live immediately.