scout_apm_mcp 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e4f9717b9ae8caf19fa92e364acc8fd7183a27ca686b8c587748ec017bb1764
-  data.tar.gz: 7c8261b3a2f17d320d69051c67e152d851e0fe701c93fca62cd68c92f069475b
+  metadata.gz: fe458cddc45b80969f47263d81bbe57f2050d3202b905a55afa60369aa9ed6d7
+  data.tar.gz: de2e96c9019de8727d7752134e84f6e19a2d66dc14247cd34b8d6ee7df125983
 SHA512:
-  metadata.gz: ba2f1f24479d17fb119c08c1ca14b22a2059e9ee0f3ca5047fc47c2a57b8eece7e2fb6541036434a8e623fb8781c2eeb95a9b91ce3dfe576ae615a8a1ba6bf5e
-  data.tar.gz: 94291c406ff5d7d5755349de80e03e6ca7001201c8d3642d613404ec2e1a0dcb0d96641439fca0ef5442a2738f5f20168fbee38219de6578ffe7551edf398c6e
+  metadata.gz: 34116b86965f6e2f15dd857a1e271e40966ccd92bb4a6d782c3d8a87bf58098b41129ef4caff286f91fe4857127b0a24b2b354988735e0faab5afaeebb0d2cda
+  data.tar.gz: 0b53a613b27315899f3f416fd589327b57969758ed5c0db5923c644b3f50788765b6b4264146e4668ee50901c79923f8c20295f130fb2e7b5dab2c46130e8e74

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## Unreleased
+
+## 0.2.0 (2026-07-05)
+
+- Add `list_anomaly_events` and `get_anomaly_event` client methods and MCP tools.
+- Add `sort_by`, `limit`, and `offset` to `list_endpoints` for paginated endpoint listings.
+- Return extracted `results` from `get_insights_history` and `get_insights_history_by_type`; validate `insight_type` on history-by-type requests.
+- Retry transient ScoutAPM GET failures (5xx and network timeouts) with bounded exponential backoff.
+- Fix `FetchTraceTool` `include_endpoint` so `trace_metric_name` is read from the extracted trace payload.
+- Fix MCP JSON-RPC error responses for strict MCP clients.
+- Reuse one ScoutAPM API client per MCP server process instead of creating a client per tool call.
+
 ## 0.1.6 (2026-03-29)
 
 - Background jobs API support: `list_jobs`, `list_job_metrics`, `get_job_metrics`, `list_job_traces` on the client, matching MCP tools, and URL parsing / `FetchScoutURLTool` handling for job and job-trace links.

data/README.md

@@ -1,15 +1,9 @@
 # scout_apm_mcp
 
-[![Gem Version](https://badge.fury.io/rb/scout_apm_mcp.svg?v=0.1.3)](https://badge.fury.io/rb/scout_apm_mcp) [![Test Status](https://github.com/amkisko/scout_apm_mcp.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/scout_apm_mcp.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/scout_apm_mcp.rb/graph/badge.svg?token=HVWDDNLEO5)](https://codecov.io/gh/amkisko/scout_apm_mcp.rb)
+[![Gem Version](https://badge.fury.io/rb/scout_apm_mcp.svg?v=0.2.0)](https://badge.fury.io/rb/scout_apm_mcp) [![Test Status](https://github.com/amkisko/scout_apm_mcp.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/scout_apm_mcp.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/scout_apm_mcp.rb/graph/badge.svg?token=HVWDDNLEO5)](https://codecov.io/gh/amkisko/scout_apm_mcp.rb)
 
 Ruby gem providing ScoutAPM API client and MCP (Model Context Protocol) server tools for fetching traces, endpoints, metrics, errors, and insights. Integrates with MCP-compatible clients like Cursor IDE, Claude Desktop, and other MCP-enabled tools.
 
-Sponsored by [Kisko Labs](https://www.kiskolabs.com).
-
-<a href="https://www.kiskolabs.com">
-  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
-</a>
-
 ## Requirements
 
 - **Ruby 3.1 or higher** (Ruby 3.0 and earlier are not supported)
@@ -378,3 +372,10 @@ If you discover a security vulnerability, please report it responsibly. See [SEC
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
+## Sponsors
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>

data/lib/scout_apm_mcp/client/api.rb

@@ -0,0 +1,221 @@
+module ScoutApmMcp
+  class Client
+    module Api
+      module Apps
+        def list_apps(active_since: nil)
+          uri = URI("#{@api_base}/apps")
+          response = make_request(uri)
+          apps = response.dig("results", "apps") || []
+          return apps unless active_since
+
+          active_time = Helpers.parse_time(active_since)
+          apps.select do |app|
+            reported_at = app["last_reported_at"]
+            reported_at && !reported_at.empty? && Helpers.parse_time(reported_at) >= active_time
+          end
+        end
+
+        def get_app(app_id)
+          uri = URI("#{@api_base}/apps/#{app_id}")
+          response = make_request(uri)
+          response.dig("results", "app") || {}
+        end
+      end
+
+      module Metrics
+        def list_metrics(app_id)
+          uri = URI("#{@api_base}/apps/#{app_id}/metrics")
+          response = make_request(uri)
+          response.dig("results", "availableMetrics") || []
+        end
+
+        def get_metric(app_id, metric_type, from: nil, to: nil, range: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_metric_params(metric_type, times[:from], times[:to])
+          uri = URI("#{@api_base}/apps/#{app_id}/metrics/#{metric_type}")
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          response.dig("results", "series") || {}
+        end
+      end
+
+      module Endpoints
+        def list_endpoints(app_id, from: nil, to: nil, range: nil, sort_by: nil, limit: nil, offset: nil)
+          times = resolve_listing_time_range(from: from, to: to, range: range)
+          validate_sort_by!(sort_by)
+
+          uri = URI("#{@api_base}/apps/#{app_id}/endpoints")
+          assign_query(uri, from: times[:from], to: times[:to], sort_by: sort_by, limit: limit, offset: offset)
+          response = make_request(uri)
+          endpoint_listing_results(response, sort_by: sort_by, limit: limit, offset: offset)
+        end
+
+        def get_endpoint_metrics(app_id, endpoint_id, metric_type, from: nil, to: nil, range: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_metric_params(metric_type, times[:from], times[:to])
+          uri = api_uri("apps", app_id, "endpoints", endpoint_id, "metrics", metric_type)
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          series = response.dig("results", "series") || {}
+          series[metric_type] || []
+        end
+
+        def list_endpoint_traces(app_id, endpoint_id, from: nil, to: nil, range: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_trace_time_range(times[:from], times[:to])
+          uri = api_uri("apps", app_id, "endpoints", endpoint_id, "traces")
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          response.dig("results", "traces") || []
+        end
+
+        private
+
+        def endpoint_listing_results(response, sort_by:, limit:, offset:)
+          results = response["results"]
+          paginated = !sort_by.nil? || !limit.nil? || !offset.nil?
+          paginated ? (results || {}) : (results || [])
+        end
+      end
+
+      module Jobs
+        def list_jobs(app_id, from: nil, to: nil, range: nil)
+          times = resolve_listing_time_range(from: from, to: to, range: range)
+          uri = URI("#{@api_base}/apps/#{app_id}/jobs")
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          response["results"] || []
+        end
+
+        def list_job_metrics(app_id, job_id)
+          uri = api_uri("apps", app_id, "jobs", job_id, "metrics")
+          response = make_request(uri)
+          response.dig("results", "availableMetrics") || []
+        end
+
+        def get_job_metrics(app_id, job_id, metric_type, from: nil, to: nil, range: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_job_metric_params(metric_type, times[:from], times[:to])
+          uri = api_uri("apps", app_id, "jobs", job_id, "metrics", metric_type)
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          series = response.dig("results", "series") || {}
+          series[metric_type] || []
+        end
+
+        def list_job_traces(app_id, job_id, from: nil, to: nil, range: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_trace_time_range(times[:from], times[:to])
+          uri = api_uri("apps", app_id, "jobs", job_id, "traces")
+          assign_query(uri, from: times[:from], to: times[:to])
+          response = make_request(uri)
+          response.dig("results", "traces") || []
+        end
+      end
+
+      module Traces
+        def fetch_trace(app_id, trace_id)
+          uri = URI("#{@api_base}/apps/#{app_id}/traces/#{trace_id}")
+          response = make_request(uri)
+          response.dig("results", "trace") || {}
+        end
+      end
+
+      module ErrorGroups
+        def list_error_groups(app_id, from: nil, to: nil, endpoint: nil)
+          validate_time_range(from, to) if from && to
+          uri = URI("#{@api_base}/apps/#{app_id}/error_groups")
+          assign_query(uri, from: from, to: to, endpoint: endpoint)
+          response = make_request(uri)
+          response.dig("results", "error_groups") || []
+        end
+
+        def get_error_group(app_id, error_id)
+          uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}")
+          response = make_request(uri)
+          response.dig("results", "error_group") || {}
+        end
+
+        def get_error_group_errors(app_id, error_id)
+          uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}/errors")
+          response = make_request(uri)
+          response.dig("results", "errors") || []
+        end
+      end
+
+      module AnomalyEvents
+        def list_anomaly_events(app_id, from: nil, to: nil, range: nil, state: nil, metric: nil, endpoint: nil)
+          times = resolve_range_times(from: from, to: to, range: range)
+          validate_time_range(times[:from], times[:to]) if times[:from] && times[:to]
+          validate_anomaly_state!(state)
+
+          uri = URI("#{@api_base}/apps/#{app_id}/anomaly_events")
+          assign_query(uri, from: times[:from], to: times[:to], state: state, metric: metric, endpoint: endpoint)
+          response = make_request(uri)
+          response.dig("results", "anomaly_events") || []
+        end
+
+        def get_anomaly_event(app_id, anomaly_event_id)
+          uri = URI("#{@api_base}/apps/#{app_id}/anomaly_events/#{anomaly_event_id}")
+          response = make_request(uri)
+          response.dig("results", "anomaly_event") || {}
+        end
+      end
+
+      module Insights
+        def get_all_insights(app_id, limit: nil)
+          uri = URI("#{@api_base}/apps/#{app_id}/insights")
+          assign_query(uri, limit: limit)
+          response = make_request(uri)
+          response["results"] || {}
+        end
+
+        def get_insight_by_type(app_id, insight_type, limit: nil)
+          validate_insight_type(insight_type)
+          uri = URI("#{@api_base}/apps/#{app_id}/insights/#{insight_type}")
+          assign_query(uri, limit: limit)
+          response = make_request(uri)
+          response["results"] || {}
+        end
+
+        def get_insights_history(app_id, from: nil, to: nil, limit: nil, pagination_cursor: nil, pagination_direction: nil, pagination_page: nil)
+          uri = URI("#{@api_base}/apps/#{app_id}/insights/history")
+          assign_query(
+            uri,
+            from: from,
+            to: to,
+            limit: limit,
+            pagination_cursor: pagination_cursor,
+            pagination_direction: pagination_direction,
+            pagination_page: pagination_page
+          )
+          response = make_request(uri)
+          response["results"] || {}
+        end
+
+        def get_insights_history_by_type(app_id, insight_type, from: nil, to: nil, limit: nil, pagination_cursor: nil, pagination_direction: nil, pagination_page: nil)
+          validate_insight_type(insight_type)
+          uri = URI("#{@api_base}/apps/#{app_id}/insights/history/#{insight_type}")
+          assign_query(
+            uri,
+            from: from,
+            to: to,
+            limit: limit,
+            pagination_cursor: pagination_cursor,
+            pagination_direction: pagination_direction,
+            pagination_page: pagination_page
+          )
+          response = make_request(uri)
+          response["results"] || {}
+        end
+      end
+
+      module OpenApi
+        def fetch_openapi_schema
+          uri = URI("https://scoutapm.com/api/v0/openapi.yaml")
+          fetch_openapi_schema_response(uri)
+        end
+      end
+    end
+  end
+end

data/lib/scout_apm_mcp/client/http_transport.rb

@@ -0,0 +1,174 @@
+module ScoutApmMcp
+  class Client
+    module HttpTransport
+      private
+
+      def build_http_client(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.read_timeout = 10
+        http.open_timeout = 10
+        configure_ssl(http, uri) if uri.scheme == "https"
+        http
+      end
+
+      def make_request(uri)
+        attempt = 0
+
+        loop do
+          attempt += 1
+          return perform_request(uri)
+        rescue APIError => error
+          retry_api_error!(error, attempt)
+        rescue OpenSSL::SSL::SSLError => error
+          raise_ssl_error(error)
+        rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT => error
+          retry_connection_error!(error, attempt)
+        rescue Error
+          raise
+        rescue => error
+          raise Error, "Request failed: #{error.class} - #{error.message}"
+        end
+      end
+
+      def perform_request(uri)
+        http = build_http_client(uri)
+        request = build_json_request(uri)
+        response = http.request(request)
+        response_data = handle_response_errors(response)
+        validate_api_status_header(response_data)
+        response_data
+      end
+
+      def handle_response_errors(response)
+        data = parse_response_body(response)
+
+        case response
+        when Net::HTTPSuccess
+          data
+        when Net::HTTPUnauthorized
+          raise AuthError, "Authentication failed - check your API key"
+        when Net::HTTPNotFound
+          raise APIError.new("Resource not found", status_code: 404, response_data: data)
+        else
+          raise_api_error(response, data)
+        end
+      end
+
+      def fetch_openapi_schema_response(uri)
+        http = build_http_client(uri)
+        request = build_openapi_request(uri)
+        response = http.request(request)
+        handle_openapi_response(response)
+      rescue OpenSSL::SSL::SSLError => error
+        raise_ssl_error(error)
+      rescue Error
+        raise
+      rescue => error
+        raise Error, "Request failed: #{error.class} - #{error.message}"
+      end
+
+      def configure_ssl(http, uri)
+        return unless uri.scheme == "https"
+
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        ca_file = ssl_certificate_file
+        http.ca_file = ca_file if ca_file
+      end
+
+      def ssl_certificate_file
+        if ENV["SSL_CERT_FILE"] && File.file?(ENV["SSL_CERT_FILE"])
+          ENV["SSL_CERT_FILE"]
+        elsif File.exist?(OpenSSL::X509::DEFAULT_CERT_FILE)
+          OpenSSL::X509::DEFAULT_CERT_FILE
+        end
+      end
+
+      def build_json_request(uri)
+        request = Net::HTTP::Get.new(uri)
+        request["X-SCOUT-API"] = @api_key
+        request["User-Agent"] = @user_agent
+        request["Accept"] = "application/json"
+        request
+      end
+
+      def build_openapi_request(uri)
+        request = Net::HTTP::Get.new(uri)
+        request["X-SCOUT-API"] = @api_key
+        request["User-Agent"] = @user_agent
+        request["Accept"] = "application/x-yaml, application/yaml, text/yaml, */*"
+        request
+      end
+
+      def parse_response_body(response)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise APIError.new("Invalid JSON response: #{response.body}", status_code: response.code.to_i)
+      end
+
+      def validate_api_status_header(response_data)
+        return unless response_data.is_a?(Hash)
+
+        header = response_data["header"]
+        return unless header && header["status"]
+
+        status_code = header["status"]["code"]
+        return unless status_code && status_code >= 400
+
+        error_message = header["status"]["message"] || "Unknown API error"
+        raise APIError.new(error_message, status_code: status_code, response_data: response_data)
+      end
+
+      def raise_api_error(response, data)
+        error_message = "API request failed"
+        if data.is_a?(Hash) && data.dig("header", "status", "message")
+          error_message = data.dig("header", "status", "message")
+        end
+        raise APIError.new(error_message, status_code: response.code.to_i, response_data: data)
+      end
+
+      def handle_openapi_response(response)
+        case response
+        when Net::HTTPSuccess
+          {
+            content: response.body,
+            content_type: response.content_type,
+            status: response.code.to_i
+          }
+        when Net::HTTPUnauthorized
+          raise AuthError, "Authentication failed. Check your API key."
+        else
+          raise APIError.new("API request failed: #{response.code} #{response.message}", status_code: response.code.to_i)
+        end
+      end
+
+      def raise_ssl_error(error)
+        raise Error, "SSL verification failed: #{error.message}. This may be due to system certificate configuration issues."
+      end
+
+      def raise_connection_error(error)
+        raise Error, "Request failed: #{error.class} - #{error.message}"
+      end
+
+      def retryable_api_error?(error)
+        error.is_a?(APIError) && error.status_code && RETRYABLE_HTTP_STATUS_CODES.include?(error.status_code)
+      end
+
+      def retry_api_error!(error, attempt)
+        raise unless retryable_api_error?(error) && attempt < MAX_REQUEST_ATTEMPTS
+
+        sleep(retry_backoff_seconds(attempt))
+      end
+
+      def retry_connection_error!(error, attempt)
+        raise_connection_error(error) if attempt >= MAX_REQUEST_ATTEMPTS
+
+        sleep(retry_backoff_seconds(attempt))
+      end
+
+      def retry_backoff_seconds(attempt)
+        RETRY_BASE_DELAY_SECONDS * (2**(attempt - 1))
+      end
+    end
+  end
+end

data/lib/scout_apm_mcp/client/query_params.rb

@@ -0,0 +1,31 @@
+module ScoutApmMcp
+  class Client
+    module QueryParams
+      private
+
+      def build_query_string(from: nil, to: nil)
+        encode_query_params("from" => from, "to" => to)
+      end
+
+      def encode_query_params(params)
+        filtered = params.each_with_object({}) do |(key, value), hash|
+          hash[key] = value unless value.nil?
+        end
+        return nil if filtered.empty?
+
+        URI.encode_www_form(filtered)
+      end
+
+      def assign_query(uri, **params)
+        query = encode_query_params(params.transform_keys(&:to_s))
+        uri.query = query if query
+      end
+
+      def api_uri(*path_segments)
+        uri = URI(@api_base)
+        uri.path = File.join(uri.path, *path_segments.map(&:to_s))
+        uri
+      end
+    end
+  end
+end

data/lib/scout_apm_mcp/client/validation.rb

@@ -0,0 +1,90 @@
+module ScoutApmMcp
+  class Client
+    module Validation
+      private
+
+      def validate_insight_type(insight_type)
+        return if VALID_INSIGHTS.include?(insight_type)
+
+        raise ArgumentError, "Invalid insight_type. Must be one of: #{VALID_INSIGHTS.join(", ")}"
+      end
+
+      def validate_metric_params(metric_type, from, to)
+        unless VALID_METRICS.include?(metric_type)
+          raise ArgumentError, "Invalid metric_type. Must be one of: #{VALID_METRICS.join(", ")}"
+        end
+        validate_time_range(from, to) if from && to
+      end
+
+      def validate_job_metric_params(metric_type, from, to)
+        unless VALID_JOB_METRICS.include?(metric_type)
+          raise ArgumentError, "Invalid metric_type. Must be one of: #{VALID_JOB_METRICS.join(", ")}"
+        end
+        validate_time_range(from, to) if from && to
+      end
+
+      def validate_time_range(from, to)
+        return unless from && to
+
+        from_time = Helpers.parse_time(from)
+        to_time = Helpers.parse_time(to)
+
+        if from_time >= to_time
+          raise ArgumentError, "from_time must be before to_time"
+        end
+
+        max_duration = 14 * 24 * 60 * 60
+        if (to_time - from_time) > max_duration
+          raise ArgumentError, "Time range cannot exceed 2 weeks"
+        end
+      end
+
+      def resolve_range_times(from:, to:, range:)
+        return {from: from, to: to} unless range
+
+        Helpers.calculate_range(range: range, to: to)
+      end
+
+      def resolve_listing_time_range(from:, to:, range:, default_range: "7days")
+        range = default_range if listing_range_unset?(from, to, range)
+        times = resolve_range_times(from: from, to: to, range: range)
+        from, to = normalize_listing_bounds(times[:from], times[:to])
+        validate_time_range(from, to) if from && to
+        {from: from, to: to}
+      end
+
+      def listing_range_unset?(from, to, range)
+        from.nil? && to.nil? && range.nil?
+      end
+
+      def normalize_listing_bounds(from, to)
+        from = Helpers.calculate_range(range: "7days", to: to)[:from] if from.nil? && to
+        to = Helpers.format_time(Time.now.utc) if from && to.nil?
+        [from, to]
+      end
+
+      def validate_trace_time_range(from, to)
+        validate_time_range(from, to) if from && to
+        return unless from && to
+
+        from_time = Helpers.parse_time(from)
+        seven_days_ago = Time.now.utc - (7 * 24 * 60 * 60)
+        if from_time < seven_days_ago
+          raise ArgumentError, "from_time cannot be older than 7 days"
+        end
+      end
+
+      def validate_sort_by!(sort_by)
+        return if sort_by.nil? || VALID_ENDPOINT_SORT_BY.include?(sort_by)
+
+        raise ArgumentError, "Invalid sort_by. Must be one of: #{VALID_ENDPOINT_SORT_BY.join(", ")}"
+      end
+
+      def validate_anomaly_state!(state)
+        return if state.nil? || VALID_ANOMALY_STATES.include?(state)
+
+        raise ArgumentError, "Invalid state. Must be one of: #{VALID_ANOMALY_STATES.join(", ")}"
+      end
+    end
+  end
+end