source

type MultiSource ¶

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

MultiSource composes an ORDERED list of Sources into one, with a defined precedence on name collisions and aggregated diagnostics. It is what makes "keep adding sources" easy: future sources implement Source and slot into the ordered list — the consumer (registerMCP) is unchanged.

PRECEDENCE (collision rule): EARLIER sources win. When two sources both produce a server with the same ServerConfig.Name, the one from the earlier source is kept and the later one is SHADOWED — dropped, with a SkipError "shadowed by a higher-precedence source" notice so the operator can see it happened. Callers order the slice highest-precedence-first; the conventional resolver (ResolveSources) builds it as static (explicit --mcp-server) > ToolHive.

Diagnostics from every source are concatenated in source order, with each shadow notice appended at the point the collision is detected. A fatal error from ANY source is returned immediately (with the diagnostics gathered so far) — a source that genuinely could not be consulted is a fault worth surfacing, unlike a merely-absent one which its own implementation reports as "no servers".

func NewMultiSource(sources ...Source) MultiSource

func (MultiSource) Name() string

func (m MultiSource) Servers(ctx context.Context) ([]mcp.ServerConfig, []SkipError, error)

type ResolveOptions ¶

type ResolveOptions struct {
	// StaticServers are the operator-configured --mcp-server entries, already
	// parsed. Highest precedence.
	StaticServers []mcp.ServerConfig
	// ToolHiveEnabled adds the live ToolHive workload source (lower precedence than
	// the static list). Default-on is decided by the composition root's flag, not
	// here.
	ToolHiveEnabled bool
	// ToolHiveGroup is the ToolHive group to filter to. Empty -> the effective
	// "default" group. Only consulted when ToolHiveEnabled.
	ToolHiveGroup string
}

ResolveOptions configures the conventional MCP-source resolver. The zero value resolves NOTHING (no static servers, ToolHive disabled), so MCP stays opt-in unless the operator configured a server or left ToolHive on.

type ServerInfo ¶

type ServerInfo struct {
	Name      string
	URL       string
	Transport string
	Group     string
}

ServerInfo is one resolved MCP server candidate (post-merge, post-shadow).

type SkipError ¶

type SkipError struct {
	// Server is the server name (or source label) the problem concerns.
	Server string
	// Reason is a short, human-readable description of the problem.
	Reason string
}

SkipError records one non-fatal diagnostic: a server a Source saw but excluded, or a server dropped because a higher-precedence source already claimed its name (a SHADOW notice). It is collected and surfaced by the composition root; it is NEVER returned as a Source's fatal error.

func (e SkipError) Error() string

type Source ¶

type Source interface {
	Servers(ctx context.Context) ([]mcp.ServerConfig, []SkipError, error)
	// Name identifies the source for diagnostics, e.g. "static",
	// "toolhive(default)", "toolhive(<group>)".
	Name() string
}

Source produces MCP server configs for the composition root to connect.

Servers(ctx) returns:

• the server configs this source knows about (each a candidate connection),
• non-fatal per-server diagnostics (SkipError) for servers the source saw but deliberately excluded (wrong transport, bad name, …),
• a non-nil error ONLY for a hard INFRA fault that prevented consultation entirely. An ABSENT source (e.g. no container runtime, no configured servers) is "zero servers", NOT an error — MCP is opt-in and fail-soft.

func ResolveSources(opts ResolveOptions) []Source

static (explicit --mcp-server, in flag order)   [highest]
  > toolhive(<group or 'default'>) when enabled  [lowest]

type SourceInfo ¶

type SourceInfo struct {
	// Name is the source's Name(), e.g. "static" or "toolhive(default)".
	Name string
	// Kind is the coarse source kind: "static" or "toolhive".
	Kind string
	// Enabled reports whether this source was active in the resolution.
	Enabled bool
	// Group is the ToolHive group (empty for the static source).
	Group string
	// Servers are the configs this source contributed (before cross-source
	// shadowing — these are the source's own view).
	Servers []ServerInfo
	// Diagnostics are this source's per-server skip reasons.
	Diagnostics []string
}

SourceInfo is the inventory for one resolved Source: its identity, the servers it contributed, and any diagnostics it raised. The name is deliberate (Stage C, the gRPC adapter, consumes source.SourceInfo) even though it reads as a stutter.

func InspectSources(ctx context.Context, sources []Source, _ ResolveOptions) []SourceInfo

type StaticSource ¶

type StaticSource struct {
	// Servers is the pre-parsed config list (empty is fine — yields zero servers).
	Configs []mcp.ServerConfig
}

StaticSource is the Source backing the operator-configured --mcp-server entries (already parsed into mcp.ServerConfig by the flag). It is the simplest possible Source: it just hands back the pre-parsed configs verbatim, with no diagnostics and no fatal error. It is the highest-precedence source in the conventional resolver so an explicit --mcp-server always wins a name collision against a discovered ToolHive workload.

func (StaticSource) Name() string

func (s StaticSource) Servers(context.Context) ([]mcp.ServerConfig, []SkipError, error)

type ToolHiveSource ¶

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

ToolHiveSource discovers MCP servers from the running ToolHive workloads in a group, reading each workload's already-populated HTTP proxy URL. Construction of the underlying ToolHive manager is LAZY (first Servers call) and ERROR-GUARDED: if no container runtime is reachable the source degrades to zero servers plus a single diagnostic, NOT a fatal error, so a developer without Podman/Docker can still run the harness.

func NewToolHiveSource(group string) ToolHiveSource

func (s ToolHiveSource) Name() string

func (s ToolHiveSource) Servers(ctx context.Context) ([]mcp.ServerConfig, []SkipError, error)