toolkit

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"`
}

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
}

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
}

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

type ConnectionLister interface {
	ListConnections() []ConnectionDetail
}

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

type ResourceAddress struct {
	// Scope and ScopeID name the library. An empty scope means the caller's
	// own, which is the one library every authenticated caller may write.
	Scope   string
	ScopeID string
	// Path is the folder chain inside the library, for example
	// "datasets/media-manager".
	Path string
	// Filename is the file's name within that folder, and the last segment of
	// the canonical URI.
	Filename string
}

type ResourceDestination struct {
	// Scope and ScopeID name the library the file is filed in. An empty scope
	// means the caller's own library, which is the one place every
	// authenticated caller may write.
	Scope   string `json:"scope,omitempty"`
	ScopeID string `json:"scope_id,omitempty"`
	// Path is the folder chain inside the library, for example
	// "datasets/media-manager". It is required: a managed resource is filed in
	// a folder, and the folder is half of the address this destination is.
	Path string `json:"path,omitempty"`
	// Filename is the file's name within that folder, and the last segment of
	// the canonical mcp:// URI. Together with the library and the path it is
	// the destination's whole address.
	Filename string `json:"filename,omitempty"`
	// ChangeSummary is what the version history shows beside the revision a
	// replacement records. Empty takes the platform's default.
	ChangeSummary string `json:"change_summary,omitempty"`

	// DisplayName, Description and Tags label the file, and are deliberately
	// NOT wire fields: every export tool already takes a name, a description
	// and tags for the asset it would otherwise write, and those are what label
	// the resource. One set of labels per call, rather than two that can
	// disagree about what the same bytes are called.
	//
	// They are recorded on a create and left alone by a replacement: a file
	// people have since renamed or re-tagged in the portal is not re-labeled
	// by the next scheduled refresh of its contents.
	DisplayName string   `json:"-"`
	Description string   `json:"-"`
	Tags        []string `json:"-"`
}

type ResourceLander interface {
	// Check validates the destination and the caller's authority to write
	// there, writing nothing. A nil error means Land will not refuse the
	// address.
	CheckResourceDestination(ctx context.Context, dest ResourceDestination) error
	// LandResource streams content into the destination, creating the resource
	// or recording a new version of the one already at that address. The
	// contentType is what the producer says the bytes are; the destination's
	// filename refines it where the producer could only say "text".
	LandResource(
		ctx context.Context, dest ResourceDestination, content io.Reader, contentType string,
	) (*ResourceLanding, error)
}

type ResourceLanding struct {
	ResourceID string `json:"resource_id"`
	// Reference is the mcp:resource:<id> form every tool that takes a
	// reference accepts.
	Reference string `json:"reference"`
	// URI is the canonical mcp:// address, which is what save_asset's
	// 'references' argument takes.
	URI         string `json:"uri"`
	Filename    string `json:"filename"`
	Scope       string `json:"scope"`
	ScopeID     string `json:"scope_id,omitempty"`
	Path        string `json:"path"`
	ContentType string `json:"content_type"`
	SizeBytes   int64  `json:"size_bytes"`
	// Version is the version number the content was recorded as: 1 for a
	// create, and the next number for every replacement after it.
	Version int `json:"version"`
	// Created distinguishes the two halves of create-or-replace, because they
	// mean different things to the caller: a create is a new address to wire
	// something up to, a replacement is an address that already has readers.
	Created bool `json:"created"`
	// TableChanges is one sentence per table registered over the file, saying
	// it followed onto the new version or is pinned and now behind it (#1536).
	// Absent when no table is registered over the file. It reports what this
	// write did, so it is named apart from the `tables` a fetched reference
	// carries, which are the rows a caller queries (#1666).
	TableChanges []string `json:"table_changes,omitempty"`
	Message      string   `json:"message"`
}

type ResourceQuery struct {
	// Scope and ScopeID name the library. An empty scope is every library the
	// caller can see, which is deliberately wider than a write's default: a
	// listing answers "what is filed here", and someone browsing has no reason
	// to be shown only their own library when they can see three.
	Scope   string
	ScopeID string
	// Path is the folder the listing is rooted at, and it is a prefix: the
	// answer holds what is beneath it at every depth, which is what makes a
	// folder count mean anything. Empty is the whole library.
	Path string
	// Limit and Offset page the answer. A non-positive limit takes the
	// implementation's default.
	Limit  int
	Offset int
}