diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index 1d2acc7ba..dca92d8f4 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -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) @@ -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( diff --git a/internal/agent/runtime.go b/internal/agent/runtime.go index 8cdcd2eec..3d033fe64 100644 --- a/internal/agent/runtime.go +++ b/internal/agent/runtime.go @@ -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. diff --git a/internal/agent/tools_integration_test.go b/internal/agent/tools_integration_test.go index af20774f5..d4d1e408b 100644 --- a/internal/agent/tools_integration_test.go +++ b/internal/agent/tools_integration_test.go @@ -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 } @@ -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) @@ -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") + } } diff --git a/internal/api/auth_middleware.go b/internal/api/auth_middleware.go index b0bf49004..b4981e035 100644 --- a/internal/api/auth_middleware.go +++ b/internal/api/auth_middleware.go @@ -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 diff --git a/internal/api/auth_test.go b/internal/api/auth_test.go index 5b946ebd5..9d6e4b5c2 100644 --- a/internal/api/auth_test.go +++ b/internal/api/auth_test.go @@ -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}, diff --git a/internal/api/intelligence.go b/internal/api/intelligence.go new file mode 100644 index 000000000..5bc32f5d4 --- /dev/null +++ b/internal/api/intelligence.go @@ -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) +} diff --git a/internal/api/intelligence_test.go b/internal/api/intelligence_test.go new file mode 100644 index 000000000..05318ff58 --- /dev/null +++ b/internal/api/intelligence_test.go @@ -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) + } +} diff --git a/internal/mcp/describe.go b/internal/mcp/describe.go index 7190fe365..fe380db49 100644 --- a/internal/mcp/describe.go +++ b/internal/mcp/describe.go @@ -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 @@ -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. // @@ -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() diff --git a/internal/mcp/describe_test.go b/internal/mcp/describe_test.go index 934a32281..6c6a30d28 100644 --- a/internal/mcp/describe_test.go +++ b/internal/mcp/describe_test.go @@ -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 { @@ -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) { diff --git a/internal/mcp/server.go b/internal/mcp/server.go index eb025959a..dfbdd1626 100644 --- a/internal/mcp/server.go +++ b/internal/mcp/server.go @@ -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" ) @@ -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) @@ -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"` @@ -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", @@ -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() @@ -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) { diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go index 0d57e7072..ce650af43 100644 --- a/internal/mcp/server_test.go +++ b/internal/mcp/server_test.go @@ -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" @@ -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 { @@ -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") diff --git a/site/src/content/docs/reference/http-routes.mdx b/site/src/content/docs/reference/http-routes.mdx index 2155b25a4..dd2bcaa71 100644 --- a/site/src/content/docs/reference/http-routes.mdx +++ b/site/src/content/docs/reference/http-routes.mdx @@ -90,6 +90,7 @@ Capabilities map to roles in [roles](/reference/roles). | `GET` | `/api/dashboards/:id` | `dashboards:manage-own` | | `PUT` | `/api/dashboards/:id` | `dashboards:manage-own` | | `GET` | `/api/health` | none | +| `GET` | `/api/intelligence` | `telemetry:read` | | `Any` | `/api/mcp` | `telemetry:read` | | `GET` | `/api/observability/logs` | `telemetry:read` | | `GET` | `/api/observability/overview` | `telemetry:read` | diff --git a/site/src/content/docs/reference/mcp-tools.mdx b/site/src/content/docs/reference/mcp-tools.mdx index 641fa7791..b4b85c459 100644 --- a/site/src/content/docs/reference/mcp-tools.mdx +++ b/site/src/content/docs/reference/mcp-tools.mdx @@ -1,7 +1,7 @@ --- title: "MCP tools" description: "Every tool a Fanout instance exposes over MCP, with its inputs and whether it changes anything." -summary: "Nine tools served at /mcp, each with its inputs and mutation semantics, taken from the server's own tools/list answer." +summary: "Ten tools served at /mcp, each with its inputs and mutation semantics, taken from the server's own tools/list answer." read_when: - "You are connecting an agent and want to know what it can call." - "You need to know which tools mutate state and which cannot." @@ -13,7 +13,7 @@ generated: true tool list rather than reading the registrations. Edit the generator, not this page. */} -A Fanout instance serves MCP at `/mcp`. Nine tools, listed below exactly as the +A Fanout instance serves MCP at `/mcp`. Ten tools, listed below exactly as the server reports them to a connecting client. Every tool is **closed-world**: it reads or writes what this instance holds @@ -25,6 +25,7 @@ and reaches nothing else. | [`dashboard_get`](#dashboard_get) | No — read-only | | [`dashboard_list`](#dashboard_list) | No — read-only | | [`dashboard_update`](#dashboard_update) | **Yes — replaces existing state** | +| [`intelligence_snapshot`](#intelligence_snapshot) | No — read-only | | [`observability_overview`](#observability_overview) | No — read-only | | [`search_logs`](#search_logs) | No — read-only | | [`service_performance`](#service_performance) | No — read-only | @@ -74,6 +75,14 @@ Takes no arguments. | `state` | `object` | **yes** | Complete replacement widget registry, 12-column layout, and shared filters | | `description` | `string` | no | Concise purpose of this dashboard | +## intelligence_snapshot + +**Latest detected anomalies** — Return the latest precomputed health score, anomalies, insights, and recurring warning or error log patterns. + +Read-only. Calling it changes nothing. + +Takes no arguments. + ## observability_overview **System health overview** — Summarize service health for a bounded telemetry window. Start here for incident triage.