mcpserver

package
v0.4.4 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const DefaultWindowDurationMs = 60000 // 1 minute

DefaultWindowDurationMs is the default window duration for activity summary.

View Source
const MaxMetricPeekNames = 20

MaxMetricPeekNames is the maximum number of metric names allowed in a peek request.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActivityErrorSummary

type ActivityErrorSummary struct {
	TraceID   string `json:"trace_id" jsonschema:"Trace ID"`
	Service   string `json:"service" jsonschema:"Service name"`
	SpanName  string `json:"span_name" jsonschema:"Span name where error occurred"`
	ErrorMsg  string `json:"error_msg" jsonschema:"Error message"`
	Timestamp uint64 `json:"timestamp_unix_nano" jsonschema:"Error timestamp (Unix nanoseconds)"`
}

type ActivityMetricPeek

type ActivityMetricPeek struct {
	Name        string             `json:"name" jsonschema:"Metric name"`
	Type        string             `json:"type" jsonschema:"Metric type"`
	Value       *float64           `json:"value,omitempty" jsonschema:"Current value (Gauge/Sum)"`
	Count       *uint64            `json:"count,omitempty" jsonschema:"Count (Histogram)"`
	Sum         *float64           `json:"sum,omitempty" jsonschema:"Sum (Histogram)"`
	Min         *float64           `json:"min,omitempty" jsonschema:"Min value (Histogram)"`
	Max         *float64           `json:"max,omitempty" jsonschema:"Max value (Histogram)"`
	Percentiles map[string]float64 `json:"percentiles,omitempty" jsonschema:"Percentiles: p50, p95, p99 (Histogram)"`
}

type ActivityThroughput

type ActivityThroughput struct {
	TotalSpans   uint64 `json:"total_spans" jsonschema:"Total spans received"`
	TotalLogs    uint64 `json:"total_logs" jsonschema:"Total logs received"`
	TotalMetrics uint64 `json:"total_metrics" jsonschema:"Total metrics received"`
}

type ActivityTraceSummary

type ActivityTraceSummary struct {
	TraceID    string  `json:"trace_id" jsonschema:"Trace ID"`
	Service    string  `json:"service" jsonschema:"Service name"`
	RootSpan   string  `json:"root_span" jsonschema:"Root span name (or first span seen)"`
	Status     string  `json:"status" jsonschema:"Status: OK, ERROR, or UNSET"`
	DurationMs float64 `json:"duration_ms" jsonschema:"Duration in milliseconds"`
	ErrorMsg   string  `json:"error_msg,omitempty" jsonschema:"Error message if status is ERROR"`
}

type AddOTLPPortInput

type AddOTLPPortInput struct {
	Port int `json:"port" jsonschema:"Port to add (1-65535)"`
}

type AddOTLPPortOutput

type AddOTLPPortOutput struct {
	Endpoints []string `json:"endpoints" jsonschema:"All active OTLP endpoint addresses"`
	Success   bool     `json:"success" jsonschema:"Whether port addition succeeded"`
	Message   string   `json:"message,omitempty" jsonschema:"Additional information or error message"`
}

type ClearDataInput

type ClearDataInput struct{}

type ClearDataOutput

type ClearDataOutput struct {
	Message string `json:"message" jsonschema:"Confirmation message"`
}

type CreateSnapshotInput

type CreateSnapshotInput struct {
	Name string `json:"name" jsonschema:"Snapshot name (e.g. 'before-deploy', 'test-start')"`
}

type CreateSnapshotOutput

type CreateSnapshotOutput struct {
	Name      string `json:"name" jsonschema:"Snapshot name"`
	TracePos  int    `json:"trace_position" jsonschema:"Current trace buffer position"`
	LogPos    int    `json:"log_position" jsonschema:"Current log buffer position"`
	MetricPos int    `json:"metric_position" jsonschema:"Current metric buffer position"`
	Message   string `json:"message" jsonschema:"Success message"`
}

type DataSummary

type DataSummary struct {
	TraceCount    int            `json:"trace_count" jsonschema:"Number of spans"`
	LogCount      int            `json:"log_count" jsonschema:"Number of logs"`
	MetricCount   int            `json:"metric_count" jsonschema:"Number of metrics"`
	Services      []string       `json:"services" jsonschema:"Distinct services"`
	TraceIDs      []string       `json:"trace_ids" jsonschema:"Distinct trace IDs"`
	LogSeverities map[string]int `json:"log_severities" jsonschema:"Log severity counts"`
	MetricNames   []string       `json:"metric_names" jsonschema:"Distinct metric names"`
}

type FileSourceInfo

type FileSourceInfo struct {
	Directory    string   `json:"directory" jsonschema:"Directory path"`
	WatchedDirs  []string `json:"watched_dirs" jsonschema:"Subdirectories being watched"`
	FilesTracked int      `json:"files_tracked" jsonschema:"Number of files being tracked"`
}

type GetOTLPEndpointInput

type GetOTLPEndpointInput struct{}

type GetOTLPEndpointOutput

type GetOTLPEndpointOutput struct {
	Endpoint        string            `json:"endpoint" jsonschema:"OTLP gRPC endpoint address (accepts traces, logs, and metrics)"`
	Protocol        string            `json:"protocol" jsonschema:"Protocol type (grpc)"`
	EnvironmentVars map[string]string `json:"environment_vars" jsonschema:"Suggested environment variables for configuring applications"`
}

type GetSnapshotDataInput

type GetSnapshotDataInput struct {
	StartSnapshot string `json:"start_snapshot" jsonschema:"Start snapshot name"`
	EndSnapshot   string `json:"end_snapshot,omitempty" jsonschema:"End snapshot name (empty = current)"`
}

type GetSnapshotDataOutput

type GetSnapshotDataOutput struct {
	StartSnapshot string          `json:"start_snapshot" jsonschema:"Start snapshot name"`
	EndSnapshot   string          `json:"end_snapshot" jsonschema:"End snapshot name"`
	TimeRange     TimeRange       `json:"time_range" jsonschema:"Time window of the data"`
	Traces        []TraceSummary  `json:"traces" jsonschema:"All traces in time range"`
	Logs          []LogSummary    `json:"logs" jsonschema:"All logs in time range"`
	Metrics       []MetricSummary `json:"metrics" jsonschema:"All metrics in time range"`
	Summary       DataSummary     `json:"summary" jsonschema:"Data summary"`
}

type GetStatsInput

type GetStatsInput struct{}

type GetStatsOutput

type GetStatsOutput struct {
	Traces    StorageStats       `json:"traces" jsonschema:"Trace storage statistics"`
	Logs      LogStorageStats    `json:"logs" jsonschema:"Log storage statistics"`
	Metrics   MetricStorageStats `json:"metrics" jsonschema:"Metric storage statistics"`
	Snapshots int                `json:"snapshot_count" jsonschema:"Number of snapshots"`
}

type ListFileSourcesInput

type ListFileSourcesInput struct{}

type ListFileSourcesOutput

type ListFileSourcesOutput struct {
	Sources []FileSourceInfo `json:"sources" jsonschema:"Active file sources"`
	Count   int              `json:"count" jsonschema:"Number of active file sources"`
}

type LogStorageStats

type LogStorageStats struct {
	LogCount     int            `json:"log_count" jsonschema:"Current number of logs"`
	Capacity     int            `json:"capacity" jsonschema:"Maximum logs capacity"`
	TraceCount   int            `json:"trace_count" jsonschema:"Logs linked to traces"`
	ServiceCount int            `json:"service_count" jsonschema:"Distinct services"`
	Severities   map[string]int `json:"severities" jsonschema:"Severity level counts"`
}

type LogSummary

type LogSummary struct {
	TraceID     string         `json:"trace_id,omitempty" jsonschema:"Associated trace ID (hex)"`
	SpanID      string         `json:"span_id,omitempty" jsonschema:"Associated span ID (hex)"`
	ServiceName string         `json:"service_name" jsonschema:"Service name"`
	Severity    string         `json:"severity" jsonschema:"Severity text (INFO, ERROR, etc)"`
	SeverityNum int32          `json:"severity_number" jsonschema:"Severity number"`
	Body        string         `json:"body" jsonschema:"Log message body"`
	Timestamp   uint64         `json:"timestamp_unix_nano" jsonschema:"Timestamp (Unix nanoseconds)"`
	Attributes  map[string]any `json:"attributes,omitempty" jsonschema:"Log attributes"`
}

type ManageSnapshotsInput

type ManageSnapshotsInput struct {
	Action string `json:"action" jsonschema:"Action: 'list', 'delete', or 'clear'"`
	Name   string `json:"name,omitempty" jsonschema:"Snapshot name (required for 'delete')"`
}

type ManageSnapshotsOutput

type ManageSnapshotsOutput struct {
	Action    string   `json:"action" jsonschema:"Action performed"`
	Snapshots []string `json:"snapshots,omitempty" jsonschema:"List of snapshot names (for 'list')"`
	Message   string   `json:"message" jsonschema:"Status message"`
}

type MetricStorageStats

type MetricStorageStats struct {
	MetricCount  int            `json:"metric_count" jsonschema:"Current number of metrics"`
	Capacity     int            `json:"capacity" jsonschema:"Maximum metrics capacity"`
	UniqueNames  int            `json:"unique_names" jsonschema:"Distinct metric names"`
	ServiceCount int            `json:"service_count" jsonschema:"Distinct services"`
	TypeCounts   map[string]int `json:"type_counts" jsonschema:"Counts by metric type"`
}

type MetricSummary

type MetricSummary struct {
	MetricName  string   `json:"metric_name" jsonschema:"Metric name"`
	ServiceName string   `json:"service_name" jsonschema:"Service name"`
	MetricType  string   `json:"metric_type" jsonschema:"Metric type (Gauge, Sum, Histogram, etc)"`
	Timestamp   uint64   `json:"timestamp_unix_nano" jsonschema:"Timestamp (Unix nanoseconds)"`
	Value       *float64 `json:"value,omitempty" jsonschema:"Numeric value (for Gauge/Sum)"`
	Count       *uint64  `json:"count,omitempty" jsonschema:"Count (for Histogram)"`
	Sum         *float64 `json:"sum,omitempty" jsonschema:"Sum (for Histogram)"`
	DataPoints  int      `json:"data_point_count" jsonschema:"Number of data points"`
}

type QueryInput

type QueryInput struct {
	// Basic filters
	ServiceName   string   `json:"service_name,omitempty" jsonschema:"Filter by service name"`
	TraceID       string   `json:"trace_id,omitempty" jsonschema:"Filter by trace ID (hex format)"`
	SpanName      string   `json:"span_name,omitempty" jsonschema:"Filter by span operation name"`
	LogSeverity   string   `json:"log_severity,omitempty" jsonschema:"Filter logs by severity (INFO, WARN, ERROR, etc)"`
	MetricNames   []string `json:"metric_names,omitempty" jsonschema:"Filter metrics by names"`
	StartSnapshot string   `json:"start_snapshot,omitempty" jsonschema:"Start of time range (snapshot name)"`
	EndSnapshot   string   `json:"end_snapshot,omitempty" jsonschema:"End of time range (snapshot name, empty = current)"`
	Limit         int      `json:"limit,omitempty" jsonschema:"Maximum results per signal type (0 = no limit)"`

	// Status filters (NEW)
	ErrorsOnly bool   `json:"errors_only,omitempty" jsonschema:"Only return spans with error status (shortcut for span_status=ERROR)"`
	SpanStatus string `json:"span_status,omitempty" jsonschema:"Filter by span status: OK, ERROR, or UNSET"`

	// Duration filters in nanoseconds (NEW)
	MinDurationNs *uint64 `json:"min_duration_ns,omitempty" jsonschema:"Minimum span duration in nanoseconds (e.g., 500000000 for 500ms)"`
	MaxDurationNs *uint64 `json:"max_duration_ns,omitempty" jsonschema:"Maximum span duration in nanoseconds"`

	// Attribute filters (NEW)
	HasAttribute    string            `json:"has_attribute,omitempty" jsonschema:"Filter spans/logs that have this attribute key (e.g., 'http.status_code')"`
	AttributeEquals map[string]string `json:"attribute_equals,omitempty" jsonschema:"Filter by attribute key-value pairs (e.g., {'http.status_code': '500'})"`
}

type QueryOutput

type QueryOutput struct {
	Traces  []TraceSummary  `json:"traces" jsonschema:"Matching trace spans"`
	Logs    []LogSummary    `json:"logs" jsonschema:"Matching log records"`
	Metrics []MetricSummary `json:"metrics" jsonschema:"Matching metrics"`
	Summary QuerySummary    `json:"summary" jsonschema:"Query result summary"`
}

type QuerySummary

type QuerySummary struct {
	TraceCount  int      `json:"trace_count" jsonschema:"Number of spans returned"`
	LogCount    int      `json:"log_count" jsonschema:"Number of logs returned"`
	MetricCount int      `json:"metric_count" jsonschema:"Number of metrics returned"`
	Services    []string `json:"services" jsonschema:"Distinct services in results"`
	TraceIDs    []string `json:"trace_ids" jsonschema:"Distinct trace IDs in results"`
}

type RecentActivityInput

type RecentActivityInput struct {
	MetricNames []string `json:"metric_names,omitempty" jsonschema:"Metric names to peek (max 20, empty = none)"`
}

type RecentActivityOutput

type RecentActivityOutput struct {
	RecentTraces     []ActivityTraceSummary `json:"recent_traces" jsonschema:"Most recent 5 traces"`
	RecentErrors     []ActivityErrorSummary `json:"recent_errors" jsonschema:"Most recent 5 errors (separate from traces)"`
	Throughput       ActivityThroughput     `json:"throughput" jsonschema:"Throughput counters (caller computes rates)"`
	MetricsPeek      []ActivityMetricPeek   `json:"metrics_peek,omitempty" jsonschema:"Current values for requested metrics"`
	WindowDurationMs int64                  `json:"window_duration_ms" jsonschema:"Window duration in milliseconds"`
}

type RemoveFileSourceInput

type RemoveFileSourceInput struct {
	Directory string `json:"directory" jsonschema:"Directory to stop watching"`
}

type RemoveFileSourceOutput

type RemoveFileSourceOutput struct {
	Directory string `json:"directory" jsonschema:"Directory that was removed"`
	Success   bool   `json:"success" jsonschema:"Whether removal succeeded"`
	Message   string `json:"message,omitempty" jsonschema:"Additional information"`
}

type RemoveOTLPPortInput

type RemoveOTLPPortInput struct {
	Port int `json:"port" jsonschema:"Port to remove (1-65535)"`
}

type RemoveOTLPPortOutput

type RemoveOTLPPortOutput struct {
	Endpoints []string `json:"endpoints" jsonschema:"Remaining active OTLP endpoint addresses"`
	Success   bool     `json:"success" jsonschema:"Whether port removal succeeded"`
	Message   string   `json:"message,omitempty" jsonschema:"Additional information or error message"`
}

type Server

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

Server wraps the MCP server with observability storage and OTLP receiver. It provides snapshot-first tools for agents to query telemetry data across all signal types.

func NewServer

func NewServer(obsStorage *storage.ObservabilityStorage, otlpReceiver *otlpreceiver.UnifiedServer, opts ...ServerOptions) (*Server, error)

NewServer creates a new MCP server that exposes snapshot-first observability tools. The otlpReceiver provides the OTLP endpoint and enables dynamic port rebinding.

func (*Server) AddFileSource

func (s *Server) AddFileSource(ctx context.Context, directory string, activeOnly bool) error

AddFileSource adds a new file source that reads OTLP JSONL from a directory. When activeOnly is true, only active files (e.g., traces.jsonl) are loaded, skipping rotated archives (e.g., traces-2025-12-09T13-10-56.jsonl). Returns an error if the directory is already being watched.

func (*Server) FileSourceStats

func (s *Server) FileSourceStats() []filereader.Stats

FileSourceStats returns stats for all file sources.

func (*Server) ListFileSources

func (s *Server) ListFileSources() []string

ListFileSources returns all active file source directories.

func (*Server) MCPServer

func (s *Server) MCPServer() *mcp.Server

MCPServer returns the underlying mcp.Server for use with alternative transports. This enables the server to be used with StreamableHTTPHandler for HTTP transport.

func (*Server) RemoveFileSource

func (s *Server) RemoveFileSource(directory string) error

RemoveFileSource stops and removes a file source. The source is removed from the map under the lock, then stopped outside the lock so fs.Stop cannot block other operations.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run starts the MCP server on stdio transport. This method blocks until the context is cancelled or EOF is received on stdin.

func (*Server) Shutdown

func (s *Server) Shutdown()

Shutdown performs cleanup when using non-stdio transports. For stdio transport, this cleanup is handled by Run() automatically.

type ServerOptions

type ServerOptions struct {
	Verbose bool // Enable verbose logging
}

ServerOptions configures the MCP server.

type SetFileSourceInput

type SetFileSourceInput struct {
	Directory string `` /* 153-byte string literal not displayed */
	// ActiveOnly when true (default) only loads active files like traces.jsonl,
	// skipping rotated archives like traces-2025-12-09T13-10-56.jsonl.
	// Set to false to load all files including archives.
	ActiveOnly *bool `json:"active_only,omitempty" jsonschema:"Only load active files, skip rotated archives (default: true)"`
}

type SetFileSourceOutput

type SetFileSourceOutput struct {
	Directory   string   `json:"directory" jsonschema:"Directory being watched"`
	WatchedDirs []string `json:"watched_dirs" jsonschema:"Subdirectories being watched (traces, logs, metrics)"`
	Success     bool     `json:"success" jsonschema:"Whether setup succeeded"`
	Message     string   `json:"message,omitempty" jsonschema:"Additional information"`
}

type StatusInput

type StatusInput struct{}

type StatusOutput

type StatusOutput struct {
	SpansReceived    uint64  `json:"spans_received" jsonschema:"Total spans received since startup"`
	LogsReceived     uint64  `json:"logs_received" jsonschema:"Total logs received since startup"`
	MetricsReceived  uint64  `json:"metrics_received" jsonschema:"Total metrics received since startup"`
	RecentErrorCount int     `json:"recent_error_count" jsonschema:"Number of recent errors tracked (max 100)"`
	Generation       uint64  `json:"generation" jsonschema:"Change counter - incremented on any telemetry receipt"`
	UptimeSeconds    float64 `json:"uptime_seconds" jsonschema:"Server uptime in seconds"`
}

type StorageStats

type StorageStats struct {
	SpanCount  int `json:"span_count" jsonschema:"Current number of spans"`
	Capacity   int `json:"capacity" jsonschema:"Maximum spans capacity"`
	TraceCount int `json:"trace_count" jsonschema:"Number of distinct traces"`
}

type TimeRange

type TimeRange struct {
	StartTime string `json:"start_time" jsonschema:"Start time (RFC3339)"`
	EndTime   string `json:"end_time" jsonschema:"End time (RFC3339)"`
	Duration  string `json:"duration" jsonschema:"Duration as string"`
}

type TraceSummary

type TraceSummary struct {
	TraceID      string         `json:"trace_id" jsonschema:"Trace ID (hex)"`
	SpanID       string         `json:"span_id" jsonschema:"Span ID (hex)"`
	ParentSpanID string         `json:"parent_span_id,omitempty" jsonschema:"Parent span ID (hex, empty for root)"`
	ServiceName  string         `json:"service_name" jsonschema:"Service name"`
	SpanName     string         `json:"span_name" jsonschema:"Span operation name"`
	StartTime    uint64         `json:"start_time_unix_nano" jsonschema:"Start time (Unix nanoseconds)"`
	EndTime      uint64         `json:"end_time_unix_nano" jsonschema:"End time (Unix nanoseconds)"`
	Status       string         `json:"status,omitempty" jsonschema:"Span status code"`
	Attributes   map[string]any `json:"attributes,omitempty" jsonschema:"Span attributes"`
}

Jump to

Keyboard shortcuts

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