Documentation
¶
Overview ¶
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
This is a base-layer capability of the hub: the endpoint is mounted unconditionally at apiurl.PathPrefixMCPServer and always answers, even when no providers are registered (it just serves an empty tool list). It never depends on edges — edges are a first-class provider that federates its tools in exactly like every other provider (kuery, code, infrastructure, …).
Per request the handler parses the tenant cluster + MCPServer name out of the path, authenticates the caller's bearer, builds a fresh stateless mcp.Server, federates every Ready provider's own /mcp endpoint into it, and serves the MCP protocol over streamable HTTP.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var PathPrefix = apiurl.PathPrefixMCPServer
PathPrefix is the router prefix this handler mounts under. Re-exported for the hub server wiring so the prefix and the handler live together.
Functions ¶
func FederatedInstructions ¶
func FederatedInstructions(ctx context.Context, targets []ProviderTarget, bearerToken, cluster string) string
FederatedInstructions fetches each provider's server-level MCP instructions (from `initialize`) in parallel and returns a merged block to append to the aggregate's own instructions — so operator-authored provider guidance (e.g. a Home Assistant Service's spec.instructions describing its entity layout) reaches the model connecting to the aggregate, not just the provider's direct endpoint. Providers with no instructions or an error contribute nothing. Enumeration order is preserved for deterministic output.
Types ¶
type FederatedProvider ¶
type FederatedProvider struct {
Name string `json:"name"`
DisplayName string `json:"displayName,omitempty"`
MCPURL string `json:"mcpURL"`
Reachable bool `json:"reachable"`
Error string `json:"error,omitempty"`
Tools []FederatedTool `json:"tools"`
// contains filtered or unexported fields
}
FederatedProvider is the introspection view of one federation target: a Ready provider, whether its MCP endpoint answered, and the tools it advertised. It is what the portal renders so a user can see what the aggregate is federating live, without connecting an MCP client.
func DiscoverFederation ¶
func DiscoverFederation(ctx context.Context, targets []ProviderTarget, bearerToken, cluster string) []FederatedProvider
DiscoverFederation runs the same concurrent tools/list discovery the aggregate performs at request-build time, but returns a structured snapshot instead of registering proxy tools. It never fails as a whole: an unreachable provider is reported with Reachable=false and a populated Error, so the UI can show partial state. Providers are returned in enumeration order (deterministic).
type FederatedTool ¶
type FederatedTool struct {
Name string `json:"name"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
}
FederatedTool is one tool advertised by a federated provider. Names are the provider-local names; the aggregate prefixes them "<provider>__" when it proxies, but introspection shows the raw names the provider reports.
type Options ¶
type Options struct {
// Providers enumerates the live Ready providers to federate. Required.
Providers ProviderEnumerator
// ExternalURL is the hub's externally reachable base URL, used only to
// self-describe the endpoint in the faros://about resource. Optional.
ExternalURL string
// Logger is used for federation diagnostics. Optional.
Logger logr.Logger
}
Options configures the aggregate handler.
type ProviderEnumerator ¶
type ProviderEnumerator func(ctx context.Context) []ProviderTarget
ProviderEnumerator returns the live set of Ready providers exposing an MCP endpoint. Called once per MCP request from registerProviderTools.
type ProviderTarget ¶
ProviderTarget is one federation target: a Ready provider and the URL of its own MCP endpoint.