mcp

type Annotations struct {
	ReadOnlyHint    bool `json:"readOnlyHint"`
	DestructiveHint bool `json:"destructiveHint"`
}

type Catalogue interface {
	All() []usecase.Descriptor
	ByMCPTool(tool string) (usecase.Descriptor, bool)
	Invoke(ctx context.Context, name string, actor appshared.ActorContext, in usecase.Input) (usecase.Output, error)
}

type ErrPromptArguments struct{ Reason string }

type ErrURI struct{ Reason string }

type PromptArgument struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
}

type PromptSummary struct {
	Name        string           `json:"name"`
	Title       string           `json:"title"`
	Description string           `json:"description"`
	Arguments   []PromptArgument `json:"arguments"`
}

type Prompts interface {
	// Published is the prompts written for an agent rather than for this product's own provider.
	Published() []aiprovider.Prompt
	Get(id string) (aiprovider.Prompt, error)
}

type Resource struct {
	URI         string `json:"uri"`
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType"`
}

type ResourceKind struct {
	// Segment is what follows the scheme: `items`, `containers`, `views`.
	Segment string
	// UseCase is the catalogue name of the read.
	UseCase string
	// Field is the input the identifier is bound to.
	Field string
	// Title is what a client shows for the *kind* in `resources/templates/list`. Protocol
	// documentation like a tool's description, not display text (ADR-0011): what a person sees in
	// their own language is rendered by their own client from their own catalogue.
	Title string
	// Description says what the content is and what reading it costs.
	Description string
	// NameField is the key of the read's own output that names one instance. Most resources here
	// are named by `name` and an entry by its `title`; the field is in the table rather than
	// assumed, so that a kind whose read calls it something else needs no second code path.
	NameField string
	// ListUseCase is the catalogue read that enumerates this kind, or empty where the kind cannot
	// be enumerated. Entries are the empty one, and deliberately so (ADR-0051 decision 3): no
	// unanchored item list exists in this product, and one built for `resources/list` would be a
	// tenant asking for everything.
	ListUseCase string
	// Paged says whether that list answers a page with a cursor rather than a bare list.
	//
	// Exactly one kind may be paged, and `list` relies on it: the MCP cursor is that kind's own
	// cursor passed through, and two paged kinds would need a composite cursor this package would
	// have to invent and sign itself. A test holds the invariant, so a second one is caught here
	// rather than by an agent walking a page twice.
	Paged bool
}

type ResourceTemplate struct {
	URITemplate string `json:"uriTemplate"`
	Name        string `json:"name"`
	Title       string `json:"title"`
	Description string `json:"description"`
	MimeType    string `json:"mimeType"`
}

type Server struct {
	Catalogue Catalogue
	// Prompts is the store the outbound adapters read, published here. Nil is an
	// installation running without it, and then the prompts capability is not declared and the two
	// methods answer "method not found": a capability is claimed only where something serves it.
	Prompts Prompts
	// Sessions mints and checks the `Mcp-Session-Id` a handshake hands out. Nil is an
	// installation running without the streaming half: no session is issued, none is checked, and
	// `GET /mcp` is not served.
	Sessions Sessions
	// Streams bounds the server-initiated connections, and it is the *same* registry the change
	// stream uses: an agent's stream is not a different kind of connection from a browser's and
	// must not have a different kind of limit.
	Streams *stream.Registry
	// Wakeups tells an open stream that a workspace changed, so a `listChanged` notification is
	// sent because something happened rather than because a timer fired.
	Wakeups Wakeups
	Signals StreamSignals
	// Clock is injectable so the tests do not have to wait. Nil means the system clock.
	Clock func() time.Time
	// Name and Version identify the server on initialize.
	Name    string
	Version string
}

type Sessions interface {
	Issue(tenantID, accountID shared.ID, now time.Time) string
	Validate(session string, tenantID, accountID shared.ID, now time.Time) error
}

type StreamSignals interface {
	StreamOpened(ctx context.Context)
	StreamClosed(ctx context.Context, seconds float64)
	StreamRefused(ctx context.Context, reason string)
}

type Tool struct {
	Name string `json:"name"`
	// Description carries the preconditions and side effects an agent needs in order to decide
	// whether to call the tool (ai-first.md §1.1). It is protocol documentation like an OpenAPI
	// description, not display text - what a user sees is rendered from a message code.
	Description string         `json:"description"`
	InputSchema map[string]any `json:"inputSchema"`
	Annotations Annotations    `json:"annotations"`
}

type Wakeups interface {
	Subscribe(tenantID shared.ID) (<-chan struct{}, func())
}