mcpaggregate

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

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.

func New

func New(opts Options) http.Handler

New returns the http.Handler mounted at apiurl.PathPrefixMCPServer. The handler expects the prefix to have been stripped, so it sees /{cluster}/apis/faros.sh/v1alpha1/mcpservers/{name}/mcp.

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

type ProviderTarget struct {
	Name        string
	DisplayName string
	MCPURL      string
}

ProviderTarget is one federation target: a Ready provider and the URL of its own MCP endpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL