capabilityadvisor

Documentation

Overview

Package capabilityadvisor asks MCPHub for a bounded capability route without granting the recommendation any execution authority.

Index

• type Activity
• type Advisor
  • func New(registry Registry) *Advisor
  • func (a *Advisor) Advise(ctx context.Context, request Request) Result
  • func (a *Advisor) InvalidateAll()
  • func (a *Advisor) InvalidateCatalog(revision string)
• type Hint
  • func (h Hint) NeedsDescription() bool
  • func (h Hint) Truncated() bool
• type Registry
• type Request
• type Result
• type Status

Types

type Activity

type Activity struct {
	Objective           string
	Phase               string
	CurrentActivity     string
	DesiredOutcome      string
	AvailableInputKinds []string
	// IntentTags are locally classified, allowlisted semantic labels such as
	// "symbols", "observability", or "repository". They preserve useful
	// routing signal without sending the user's prompt or arbitrary wording.
	IntentTags []string
}

Activity is the bounded, host-authored summary sent to MCPHub. These fields must describe the activity, never contain raw files, tool output, secrets, credentials, or actual input values. AvailableInputKinds contains labels such as "url", "workspace", "database", or "artifact_id" only.

type Advisor

type Advisor struct {
	// contains filtered or unexported fields
}

Advisor owns only ephemeral deduplication state. It does not persist raw inputs or outputs, reconnect servers, modify MCP scope, or execute a recommended downstream tool.

func New

func New(registry Registry) *Advisor

New returns a capability advisor backed by registry. A nil registry is allowed and degrades every eligible request to StatusUnavailable.

func (*Advisor) Advise

func (a *Advisor) Advise(ctx context.Context, request Request) Result

Advise resolves the current non-trivial activity at most once for its cache key. It never returns an error and never calls the recommended tool.

func (*Advisor) InvalidateAll

func (a *Advisor) InvalidateAll()

InvalidateAll drops every in-memory recommendation. Call when the host observes a catalog generation change (MCP reconnect, pin change, or an MCPHub catalog_revision advance) so the next Advise cannot reuse a stale route. Inflight calls are left alone; they still complete for their waiters.

func (*Advisor) InvalidateCatalog

func (a *Advisor) InvalidateCatalog(revision string)

InvalidateCatalog drops cache entries that were stored under a different catalog generation than revision. When revision is empty, this is a no-op so hosts without a revision feed do not thrash the cache.

type Hint

type Hint struct {
	Namespaced                string
	Server                    string
	Tool                      string
	RequiredFields            []string
	Alternatives              []string
	Ambiguous                 bool
	MetadataTruncated         bool
	ArgumentTemplateTruncated bool
	AlternativesTruncated     bool
}

Hint is the complete allowlisted projection of a resolver recommendation. Argument values, schemas, descriptions, scores, matched terms, and resolver prose are intentionally absent. An ambiguous hint is still useful model context, but must not be treated as a selected or executed tool.

func (Hint) NeedsDescription

func (h Hint) NeedsDescription() bool

NeedsDescription reports whether MCPHub omitted part of the argument shape and mcphub_describe_tool should precede any model-authored downstream call.

func (Hint) Truncated

func (h Hint) Truncated() bool

Truncated reports whether any resolver list or recommendation metadata was bounded. The individual flags remain available so a caller can distinguish an incomplete argument shape from merely compact presentation metadata.

type Registry

type Registry interface {
	ResolveToolName(remoteName string) (string, bool)
	CallTool(ctx context.Context, exposedName string, args map[string]any) (*mcp.ToolResult, error)
}

Registry is the narrow MCP surface used by the host-owned advisor. The advisor only calls mcphub_resolve_tool; recommended tools remain model-owned calls through the normal authority and execution paths.

type Request

type Request struct {
	GoalID             string
	NonTrivial         bool
	Reconsider         bool
	CatalogRevision    string
	CacheDiscriminator [32]byte
	Activity           Activity
}

Request carries host control metadata separately from the activity sent to MCPHub. GoalID and CacheDiscriminator participate only in an in-memory hashed cache key and are never included in the resolver query or durable state. NonTrivial fails closed: a false value skips resolution. Reconsider bypasses a previous successful recommendation or no-match result after a downstream failure or an explicit user request. CatalogRevision is optional, opaque host-owned metadata. When available, it separates cache generations without ever entering the resolver query.

type Result

type Result struct {
	Status          Status
	Hint            *Hint
	CatalogRevision string
	Attempted       bool
	Cached          bool
}

Result is deliberately non-error-bearing. Resolver failures must not fail a user turn; callers continue without Hint when Status is unavailable or invalid. Attempted means this invocation dispatched an MCP resolver call. Cached means no MCP call was needed because this phase/activity was already resolved successfully (including a valid ambiguous or no-match result). CatalogRevision is an optional bounded opaque revision returned by MCPHub.

type Status

type Status string

Status is a bounded host conclusion. It intentionally carries no remote error text or arbitrary resolver output.

const (
	StatusSkipped     Status = "skipped"
	StatusResolved    Status = "resolved"
	StatusAmbiguous   Status = "ambiguous"
	StatusNoMatch     Status = "no_match"
	StatusUnavailable Status = "unavailable"
	StatusInvalid     Status = "invalid"
)