Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion cmd/fanout/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,7 @@ func main() {
// raw *sql.DB here bypassed the DuckLake maintenance-race protection.
queries := observability.New(q)
api.NewObservabilityHandler(queries).Register(e.Group("/api/observability", api.RequireCapability(api.ReadTelemetry)))
api.RegisterIntelligenceRoutes(e, detector)
dashboards := dashboard.New(sqlite.DB)
api.RegisterDashboardRoutes(e, dashboards)

Expand Down Expand Up @@ -366,7 +367,7 @@ func main() {
// The model executes the same standard MCP tools exposed to external clients.
// The internal connection is in-memory, so the single binary has no HTTP
// self-call, shared secret, or sidecar runtime.
mcpServer := mcp.New(queries, dashboards, version)
mcpServer := mcp.NewWithIntelligence(queries, dashboards, detector, version)
if cfg.MCPEnabled {
mcpResourceURL := cfg.MCPResourceURL()
mcpAuthorization, err := api.NewMCPAuthorization(
Expand Down
2 changes: 1 addition & 1 deletion internal/agent/runtime.go
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import (
appid "github.com/labstack/fanout/internal/id"
)

const systemPrompt = `You are Fanout's observability assistant. Use observability_overview first for broad health questions, service_topology for dependencies, service_performance for activity/latency/endpoints/comparisons, trace_detail for trace or root-cause inspection, and search_logs for log questions. Treat structured outputs as authoritative. You can also list, inspect, create, and update the user's named dashboards. When asked to create a dashboard, compose a useful complete layout using overview, topology, activity, performance, trace, logs, and assistant widgets; use unique stable widget IDs, valid non-overlapping 12-column positions, and the requested time window. Creating is additive. Only update an existing dashboard after the user explicitly asks to change or replace it; inspect it first and preserve unrelated views. State the time window you used, distinguish missing data from healthy behavior, and never invent services, metrics, or causal claims. Keep answers concise because attached views provide interactive details. Never expose implementation details to the user: do not mention protocol names, tool names, schemas, query IDs, data-source names, storage engines, providers, or internal execution steps. Refer to attached interactive content simply as a view.`
const systemPrompt = `You are Fanout's observability assistant. Use observability_overview first for broad health questions, intelligence_snapshot for the latest precomputed anomalies and recurring log patterns, service_topology for dependencies, service_performance for activity/latency/endpoints/comparisons, trace_detail for trace or root-cause inspection, and search_logs for log questions. Treat structured outputs as authoritative. You can also list, inspect, create, and update the user's named dashboards. When asked to create a dashboard, compose a useful complete layout using overview, topology, activity, performance, trace, logs, and assistant widgets; use unique stable widget IDs, valid non-overlapping 12-column positions, and the requested time window. Creating is additive. Only update an existing dashboard after the user explicitly asks to change or replace it; inspect it first and preserve unrelated views. State the time window you used, distinguish missing data from healthy behavior, and never invent services, metrics, or causal claims. Keep answers concise because attached views provide interactive details. Never expose implementation details to the user: do not mention protocol names, tool names, schemas, query IDs, data-source names, storage engines, providers, or internal execution steps. Refer to attached interactive content simply as a view.`

// Error categories used to pick a client-safe RUN_ERROR message; the raw
// error (which can include provider response bodies) stays server-side.
Expand Down
19 changes: 18 additions & 1 deletion internal/agent/tools_integration_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,19 @@ import (
"context"
"testing"

"github.com/labstack/fanout/internal/intelligence"
fanoutmcp "github.com/labstack/fanout/internal/mcp"
"github.com/labstack/fanout/internal/observability"
)

type registryQueries struct{}

type registryIntelligence struct{}

func (registryIntelligence) LatestSnapshot() *intelligence.IntelligenceSnapshot {
return &intelligence.IntelligenceSnapshot{Summary: "healthy", HealthScore: 100}
}

func (registryQueries) Overview(context.Context, observability.Scope, int) (observability.Result[observability.Overview], error) {
return observability.Result[observability.Overview]{}, nil
}
Expand All @@ -31,7 +38,7 @@ func (registryQueries) Logs(context.Context, observability.Scope, string, string
}

func TestToolRegistryNegotiatesMCPApps(t *testing.T) {
server := fanoutmcp.New(registryQueries{}, nil, "test")
server := fanoutmcp.NewWithIntelligence(registryQueries{}, nil, registryIntelligence{}, "test")
registry, err := NewToolRegistry(context.Background(), server.MCP())
if err != nil {
t.Fatalf("NewToolRegistry: %v", err)
Expand All @@ -57,4 +64,14 @@ func TestToolRegistryNegotiatesMCPApps(t *testing.T) {
t.Errorf("app URI for %s = %q, want %q", tool, got, resourceURI)
}
}
foundIntelligence := false
for _, definition := range registry.Definitions() {
if definition.Name == "intelligence_snapshot" {
foundIntelligence = true
break
}
}
if !foundIntelligence {
t.Fatal("intelligence_snapshot was not registered for the agent")
}
}
2 changes: 2 additions & 0 deletions internal/api/auth_middleware.go
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,8 @@ func classifyRoute(method, path string) (routePolicy, bool) {
return routePolicy{kind: routePolicyCapability, capability: ReadOperations}, read || method == http.MethodPost
case strings.HasPrefix(path, "/api/observability/"):
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, read
case path == "/api/intelligence":
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, read
case path == "/api/alerts" || path == "/api/alerts/summary" || path == "/api/rules":
if read {
return routePolicy{kind: routePolicyCapability, capability: ReadTelemetry}, true
Expand Down
1 change: 1 addition & 0 deletions internal/api/auth_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ func TestRoutePolicyClassification(t *testing.T) {
{http.MethodGet, "/api/auth/oauth/authorize", routePolicyAuthenticated, ""},
{http.MethodPost, "/api/auth/oauth/authorize", routePolicyAuthenticated, ""},
{http.MethodGet, "/api/observability/overview", routePolicyCapability, ReadTelemetry},
{http.MethodGet, "/api/intelligence", routePolicyCapability, ReadTelemetry},
{http.MethodGet, "/api/alerts", routePolicyCapability, ReadTelemetry},
{http.MethodPost, "/api/rules", routePolicyCapability, ManageAlerts},
{http.MethodPut, "/api/rules/rule-1", routePolicyCapability, ManageAlerts},
Expand Down
36 changes: 36 additions & 0 deletions internal/api/intelligence.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
package api

import (
"net/http"

"github.com/labstack/echo/v5"
"github.com/labstack/fanout/internal/intelligence"
)

// IntelligenceSnapshots is the read side of the detector used by HTTP and
// other consumers. Keeping the interface narrow makes the endpoint independent
// of how snapshots are generated or retained.
type IntelligenceSnapshots interface {
LatestSnapshot() *intelligence.IntelligenceSnapshot
}

// RegisterIntelligenceRoutes exposes the detector's latest completed snapshot.
func RegisterIntelligenceRoutes(e *echo.Echo, snapshots IntelligenceSnapshots) {
h := &intelligenceHandler{snapshots: snapshots}
e.GET("/api/intelligence", h.latest, RequireCapability(ReadTelemetry))
}

type intelligenceHandler struct {
snapshots IntelligenceSnapshots
}

func (h *intelligenceHandler) latest(c *echo.Context) error {
if h.snapshots == nil {
return echo.NewHTTPError(http.StatusServiceUnavailable, "intelligence snapshot is not ready")
}
snapshot := h.snapshots.LatestSnapshot()
if snapshot == nil {
return echo.NewHTTPError(http.StatusServiceUnavailable, "intelligence snapshot is not ready")
}
return c.JSON(http.StatusOK, snapshot)
}
60 changes: 60 additions & 0 deletions internal/api/intelligence_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
package api

import (
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"time"

"github.com/labstack/echo/v5"
"github.com/labstack/fanout/internal/intelligence"
)

type fakeIntelligenceSnapshots struct {
snapshot *intelligence.IntelligenceSnapshot
}

func (f fakeIntelligenceSnapshots) LatestSnapshot() *intelligence.IntelligenceSnapshot {
return f.snapshot
}

func TestIntelligenceLatestReturnsSnapshot(t *testing.T) {
want := &intelligence.IntelligenceSnapshot{
GeneratedAt: time.Date(2026, 8, 26, 12, 0, 0, 0, time.UTC),
Timeframe: "last_15m",
Summary: "System healthy (98/100).",
HealthScore: 98,
Insights: []intelligence.Insight{},
Patterns: []intelligence.Pattern{},
Anomalies: []intelligence.Anomaly{},
}
e := echo.New()
h := &intelligenceHandler{snapshots: fakeIntelligenceSnapshots{snapshot: want}}
e.GET("/api/intelligence", h.latest)

rec := httptest.NewRecorder()
e.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/intelligence", nil))
if rec.Code != http.StatusOK {
t.Fatalf("status = %d, body = %s", rec.Code, rec.Body.String())
}
var got intelligence.IntelligenceSnapshot
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
t.Fatalf("decode response: %v", err)
}
if got.GeneratedAt != want.GeneratedAt || got.Timeframe != want.Timeframe || got.HealthScore != want.HealthScore || got.Summary != want.Summary {
t.Fatalf("snapshot = %#v, want %#v", got, *want)
}
}

func TestIntelligenceLatestReportsNotReady(t *testing.T) {
e := echo.New()
h := &intelligenceHandler{snapshots: fakeIntelligenceSnapshots{}}
e.GET("/api/intelligence", h.latest)

rec := httptest.NewRecorder()
e.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/intelligence", nil))
if rec.Code != http.StatusServiceUnavailable {
t.Fatalf("status = %d, want %d", rec.Code, http.StatusServiceUnavailable)
}
}
7 changes: 6 additions & 1 deletion internal/mcp/describe.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
"github.com/modelcontextprotocol/go-sdk/mcp"

"github.com/labstack/fanout/internal/dashboard"
"github.com/labstack/fanout/internal/intelligence"
)

// This file exists so the MCP reference can be generated from the server itself
Expand Down Expand Up @@ -58,6 +59,10 @@ type ToolInput struct {
Required bool
}

type describeIntelligence struct{}

func (describeIntelligence) LatestSnapshot() *intelligence.IntelligenceSnapshot { return nil }

// DescribeTools reports every tool this server exposes, as the server itself
// reports them over MCP.
//
Expand All @@ -73,7 +78,7 @@ func DescribeTools(ctx context.Context) ([]ToolDoc, error) {
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

server := New(nil, dashboard.New(nil), "docgen")
server := NewWithIntelligence(nil, dashboard.New(nil), describeIntelligence{}, "docgen")

serverTransport, clientTransport := mcp.NewInMemoryTransports()

Expand Down
18 changes: 17 additions & 1 deletion internal/mcp/describe_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ func TestDescribeToolsMatchesWhatAClientIsServed(t *testing.T) {
t.Fatalf("DescribeTools: %v", err)
}

server := New(nil, dashboard.New(nil), "test")
server := NewWithIntelligence(nil, dashboard.New(nil), describeIntelligence{}, "test")
session := connectTestClient(t, server, nil)
listed, err := session.ListTools(context.Background(), nil)
if err != nil {
Expand Down Expand Up @@ -76,6 +76,22 @@ func TestDescribeToolsIncludesTheDashboardTools(t *testing.T) {
}
}

func TestDescribeToolsIncludesIntelligenceSnapshot(t *testing.T) {
docs, err := DescribeTools(context.Background())
if err != nil {
t.Fatalf("DescribeTools: %v", err)
}
for _, doc := range docs {
if doc.Name == "intelligence_snapshot" {
if !doc.ReadOnly || doc.OpenWorld {
t.Fatalf("intelligence_snapshot annotations = %+v", doc)
}
return
}
}
t.Fatal("intelligence_snapshot is registered but absent from DescribeTools")
}

// Every tool must arrive with the facts the page is built from. A blank cell
// reads as "nothing to say" rather than "not generated".
func TestDescribeToolsReportsCompleteMetadata(t *testing.T) {
Expand Down
47 changes: 39 additions & 8 deletions internal/mcp/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
"time"

"github.com/labstack/fanout/internal/dashboard"
"github.com/labstack/fanout/internal/intelligence"
"github.com/labstack/fanout/internal/observability"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
Expand All @@ -17,7 +18,7 @@ const mcpUIExtension = "io.modelcontextprotocol/ui"

const staticCatalogTTLMs = 5 * 60 * 1000

const serverInstructions = "Start with observability_overview for system health, service_topology for dependencies, service_performance for latency and errors, trace_detail for one trace, and search_logs for application events. Treat schema, timestamps, provenance, and bounded time windows as authoritative. Dashboard tools are scoped to the authenticated user: list or get a dashboard before changing it, create only when asked, and replace an existing dashboard only with explicit user intent."
const serverInstructions = "Start with observability_overview for system health, use intelligence_snapshot for the latest precomputed anomalies and log patterns, service_topology for dependencies, service_performance for latency and errors, trace_detail for one trace, and search_logs for application events. Treat schema, timestamps, provenance, and bounded time windows as authoritative. Dashboard tools are scoped to the authenticated user: list or get a dashboard before changing it, create only when asked, and replace an existing dashboard only with explicit user intent."

type Observability interface {
Overview(context.Context, observability.Scope, int) (observability.Result[observability.Overview], error)
Expand All @@ -27,6 +28,10 @@ type Observability interface {
Logs(context.Context, observability.Scope, string, string, string, int) (observability.Result[observability.Logs], error)
}

type IntelligenceSnapshots interface {
LatestSnapshot() *intelligence.IntelligenceSnapshot
}

type QueryInput struct {
Window string `json:"window,omitempty" jsonschema:"Time window such as 15m, 1h, or 24h; defaults to 1h"`
Namespace string `json:"namespace,omitempty" jsonschema:"OpenTelemetry service namespace; empty queries all namespaces"`
Expand Down Expand Up @@ -58,13 +63,22 @@ type LogsInput struct {
}

type Server struct {
mcp *mcp.Server
queries Observability
dashboards *dashboard.Service
now func() time.Time
mcp *mcp.Server
queries Observability
intelligence IntelligenceSnapshots
dashboards *dashboard.Service
now func() time.Time
}

func New(queries Observability, dashboards *dashboard.Service, version string) *Server {
return newServer(queries, dashboards, nil, version)
}

func NewWithIntelligence(queries Observability, dashboards *dashboard.Service, snapshots IntelligenceSnapshots, version string) *Server {
return newServer(queries, dashboards, snapshots, version)
}

func newServer(queries Observability, dashboards *dashboard.Service, snapshots IntelligenceSnapshots, version string) *Server {
s := &Server{
mcp: mcp.NewServer(&mcp.Implementation{
Name: "fanout",
Expand All @@ -78,9 +92,10 @@ func New(queries Observability, dashboards *dashboard.Service, version string) *
Tools: &mcp.ToolCapabilities{},
Resources: &mcp.ResourceCapabilities{},
}}),
queries: queries,
dashboards: dashboards,
now: time.Now,
queries: queries,
intelligence: snapshots,
dashboards: dashboards,
now: time.Now,
}
s.registerTools()
s.registerDashboardTools()
Expand Down Expand Up @@ -225,6 +240,22 @@ func (s *Server) registerTools() {
Annotations: readOnly,
Meta: appToolMeta(logsAppURI),
}, s.logs)
if s.intelligence != nil {
mcp.AddTool(s.mcp, &mcp.Tool{
Name: "intelligence_snapshot",
Title: "Latest detected anomalies",
Description: "Return the latest precomputed health score, anomalies, insights, and recurring warning or error log patterns.",
Annotations: readOnly,
}, s.intelligenceSnapshot)
}
}

func (s *Server) intelligenceSnapshot(_ context.Context, _ *mcp.CallToolRequest, _ struct{}) (*mcp.CallToolResult, intelligence.IntelligenceSnapshot, error) {
snapshot := s.intelligence.LatestSnapshot()
if snapshot == nil {
return nil, intelligence.IntelligenceSnapshot{}, fmt.Errorf("intelligence snapshot is not ready")
}
return summary(snapshot.Summary), *snapshot, nil
}

func (s *Server) overview(ctx context.Context, _ *mcp.CallToolRequest, input QueryInput) (*mcp.CallToolResult, observability.Result[observability.Overview], error) {
Expand Down
40 changes: 40 additions & 0 deletions internal/mcp/server_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"time"

"github.com/labstack/fanout/internal/dashboard"
"github.com/labstack/fanout/internal/intelligence"
"github.com/labstack/fanout/internal/observability"
controlstore "github.com/labstack/fanout/internal/store"
mcpgoauth "github.com/modelcontextprotocol/go-sdk/auth"
Expand All @@ -17,6 +18,14 @@ type fakeObservability struct {
scope observability.Scope
}

type fakeIntelligence struct {
snapshot *intelligence.IntelligenceSnapshot
}

func (f fakeIntelligence) LatestSnapshot() *intelligence.IntelligenceSnapshot {
return f.snapshot
}

func TestDashboardToolsUseAuthenticatedOwner(t *testing.T) {
database, err := controlstore.NewSQLite(":memory:")
if err != nil {
Expand Down Expand Up @@ -152,6 +161,37 @@ func TestInvalidWindowIsToolError(t *testing.T) {
}
}

func TestIntelligenceSnapshotReturnsStructuredOutput(t *testing.T) {
want := &intelligence.IntelligenceSnapshot{
GeneratedAt: time.Date(2026, 8, 26, 12, 0, 0, 0, time.UTC),
Timeframe: "last_15m",
Summary: "One anomaly requires attention.",
HealthScore: 75,
Anomalies: []intelligence.Anomaly{{
Type: intelligence.AnomalyLatencyDegradation,
ServiceName: "checkout",
}},
}
s := NewWithIntelligence(&fakeObservability{}, nil, fakeIntelligence{snapshot: want}, "test")
result, output, err := s.intelligenceSnapshot(context.Background(), nil, struct{}{})
if err != nil {
t.Fatalf("intelligence snapshot: %v", err)
}
if output.GeneratedAt != want.GeneratedAt || output.HealthScore != want.HealthScore || len(output.Anomalies) != 1 {
t.Fatalf("output = %#v, want %#v", output, *want)
}
if len(result.Content) != 1 {
t.Fatalf("content = %#v", result.Content)
}
}

func TestIntelligenceSnapshotReportsNotReady(t *testing.T) {
s := NewWithIntelligence(&fakeObservability{}, nil, fakeIntelligence{}, "test")
if _, _, err := s.intelligenceSnapshot(context.Background(), nil, struct{}{}); err == nil {
t.Fatal("expected not-ready error")
}
}

func TestToolsAdvertiseReadableMCPApps(t *testing.T) {
t.Run("negotiated client", func(t *testing.T) {
server := New(&fakeObservability{}, nil, "test")
Expand Down
Loading
Loading