scout_apm_mcp 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d91170a4429338139e7e846a48e093665085269fa1c230dbdd8c06507acafa81
-  data.tar.gz: cc4767697140de54fc4ed7d5e08b3c097b7a1d6e89b5d945882c4490926c2670
+  metadata.gz: 3e4f9717b9ae8caf19fa92e364acc8fd7183a27ca686b8c587748ec017bb1764
+  data.tar.gz: 7c8261b3a2f17d320d69051c67e152d851e0fe701c93fca62cd68c92f069475b
 SHA512:
-  metadata.gz: a96e42d3f8a07f71bc339ea551cc6eb8eb5b1179492c596843a8aebd10a857d04dae8a04b810e78aea08c12a23462ec0987bccd42f66f548d7d468d416240b19
-  data.tar.gz: 885b0d0d1feae986a0f054aa4138d2525ea730d77476480c3b8d0af9f24b66acd49fd8f97d1d6669e7565712e7e235265c8e138701df34a4a9f17463f47d67e9
+  metadata.gz: ba2f1f24479d17fb119c08c1ca14b22a2059e9ee0f3ca5047fc47c2a57b8eece7e2fb6541036434a8e623fb8781c2eeb95a9b91ce3dfe576ae615a8a1ba6bf5e
+  data.tar.gz: 94291c406ff5d7d5755349de80e03e6ca7001201c8d3642d613404ec2e1a0dcb0d96641439fca0ef5442a2738f5f20168fbee38219de6578ffe7551edf398c6e

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## 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.
+- Refreshed bundled OpenAPI fixture from Scout’s live schema (includes jobs paths).
+- Extracted MCP JSON-RPC error-id monkey patch into `lib/scout_apm_mcp/mcp_error_id_patch.rb` (excluded from coverage metrics).
+- Expanded test suite: `Server.start`, `NullLogger`, batch tool dispatch, `FetchScoutURLTool` / `FetchOpenAPISchemaTool` branches, and list endpoints/jobs timeframe edge cases
+
 ## 0.1.5 (2026-02-10)
 
 - Fix range handling in calculate_range method

data/bin/scout_apm_mcp

@@ -1,6 +1,4 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
-
 # Suppress all output to prevent breaking JSON parsing in MCP clients
 # STDOUT is used for MCP protocol communication (JSON-RPC), so we must not output anything
 # STDERR is also suppressed to prevent any error messages from breaking JSON parsing

data/lib/scout_apm_mcp/client.rb

@@ -25,6 +25,9 @@ module ScoutApmMcp
     # Valid insight types
     VALID_INSIGHTS = %w[n_plus_one memory_bloat slow_query].freeze
 
+    # Valid job metric types (distinct from application endpoint metrics)
+    VALID_JOB_METRICS = %w[throughput execution_time latency errors allocations].freeze
+
     # @param api_key [String] ScoutAPM API key
     # @param api_base [String] API base URL (default: https://scoutapm.com/api/v0)
     # @raise [ArgumentError] if api_key is nil or empty
@@ -191,6 +194,106 @@ module ScoutApmMcp
       response.dig("results", "traces") || []
     end
 
+    # List background jobs for an application
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @param range [String, nil] Quick time range (e.g., "30min", "1day", "3days", "7days"). If provided, calculates from/to automatically.
+    # @return [Array<Hash>] Array of job hashes
+    def list_jobs(app_id, from: nil, to: nil, range: nil)
+      if from.nil? && to.nil? && range.nil?
+        range = "7days"
+      end
+
+      if range
+        calculated = Helpers.calculate_range(range: range, to: to)
+        from = calculated[:from]
+        to = calculated[:to]
+      end
+
+      now = Time.now.utc
+      if from.nil? && to
+        calculated = Helpers.calculate_range(range: "7days", to: to)
+        from = calculated[:from]
+      elsif from && to.nil?
+        to = Helpers.format_time(now)
+      end
+
+      validate_time_range(from, to) if from && to
+      uri = URI("#{@api_base}/apps/#{app_id}/jobs")
+      uri.query = build_query_string(from: from, to: to)
+      response = make_request(uri)
+      response["results"] || []
+    end
+
+    # List available metric types for a background job
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param job_id [String] Job ID (base64 URL-encoded, as returned by list_jobs)
+    # @return [Array<String>] Metric type names
+    def list_job_metrics(app_id, job_id)
+      uri = URI(@api_base)
+      uri.path = File.join(uri.path, "apps", app_id.to_s, "jobs", job_id, "metrics")
+      response = make_request(uri)
+      response.dig("results", "availableMetrics") || []
+    end
+
+    # Get time-series data for a job metric
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param job_id [String] Job ID (base64 URL-encoded)
+    # @param metric_type [String] One of throughput, execution_time, latency, errors, allocations
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @param range [String, nil] Quick time range; if provided, calculates from/to automatically.
+    # @return [Array] Data points for the metric
+    def get_job_metrics(app_id, job_id, metric_type, from: nil, to: nil, range: nil)
+      if range
+        calculated = Helpers.calculate_range(range: range, to: to)
+        from = calculated[:from]
+        to = calculated[:to]
+      end
+
+      validate_job_metric_params(metric_type, from, to)
+      uri = URI(@api_base)
+      uri.path = File.join(uri.path, "apps", app_id.to_s, "jobs", job_id, "metrics", metric_type)
+      uri.query = build_query_string(from: from, to: to)
+      response = make_request(uri)
+      series = response.dig("results", "series") || {}
+      series[metric_type] || []
+    end
+
+    # List traces for a background job (max 100, within 7 days)
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param job_id [String] Job ID (base64 URL-encoded)
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @param range [String, nil] Quick time range; if provided, calculates from/to automatically.
+    # @return [Array<Hash>] Array of trace hashes
+    def list_job_traces(app_id, job_id, from: nil, to: nil, range: nil)
+      if range
+        calculated = Helpers.calculate_range(range: range, to: to)
+        from = calculated[:from]
+        to = calculated[:to]
+      end
+
+      validate_time_range(from, to) if from && to
+      if 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
+      uri = URI(@api_base)
+      uri.path = File.join(uri.path, "apps", app_id.to_s, "jobs", job_id, "traces")
+      uri.query = build_query_string(from: from, to: to)
+      response = make_request(uri)
+      response.dig("results", "traces") || []
+    end
+
     # Fetch detailed trace information
     #
     # @param app_id [Integer] ScoutAPM application ID
@@ -460,6 +563,13 @@ module ScoutApmMcp
       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
+
     # Validate time ranges
     #
     # @param from [String, nil] Start time in ISO 8601 format

data/lib/scout_apm_mcp/helpers.rb

@@ -64,7 +64,7 @@ module ScoutApmMcp
     # @param url [String] Full ScoutAPM URL
     # @return [Hash] Hash containing resource type and extracted IDs
     #   Possible keys: :url_type, :app_id, :endpoint_id, :trace_id, :error_id, :insight_type,
-    #   :query_params, :decoded_endpoint
+    #   :job_id, :query_params, :decoded_endpoint, :decoded_job
     def self.parse_scout_url(url)
       uri = URI.parse(url)
       path_parts = uri.path.split("/").reject(&:empty?)
@@ -78,7 +78,7 @@ module ScoutApmMcp
 
       # Detect URL type and extract IDs
       # Pattern: /apps/{app_id}/endpoints/{endpoint_id}/trace/{trace_id}
-      if path_parts.include?("trace")
+      if path_parts.include?("trace") && path_parts.include?("endpoints")
         result[:url_type] = :trace
         endpoints_index = path_parts.index("endpoints")
         trace_index = path_parts.index("trace")
@@ -86,6 +86,24 @@ module ScoutApmMcp
           result[:endpoint_id] = path_parts[endpoints_index + 1]
           result[:trace_id] = path_parts[trace_index + 1].to_i
         end
+      # Pattern: /apps/{app_id}/jobs/{job_id}/trace/{trace_id} or /apps/{app_id}/jobs/{job_id}
+      elsif path_parts.include?("jobs")
+        jobs_index = path_parts.index("jobs")
+        if jobs_index && path_parts[jobs_index + 1]
+          result[:job_id] = path_parts[jobs_index + 1]
+          if path_parts.include?("trace")
+            trace_index = path_parts.index("trace")
+            if trace_index && path_parts[trace_index + 1]
+              result[:url_type] = :job_trace
+              result[:trace_id] = path_parts[trace_index + 1].to_i
+            else
+              result[:url_type] = :job
+            end
+          else
+            result[:url_type] = :job
+          end
+          result[:decoded_job] = decode_endpoint_id(result[:job_id])
+        end
       # Pattern: /apps/{app_id}/endpoints/{endpoint_id}
       elsif path_parts.include?("endpoints")
         result[:url_type] = :endpoint
@@ -161,6 +179,14 @@ module ScoutApmMcp
       link.split("/").last || ""
     end
 
+    # Job ID from a job hash returned by the jobs API
+    #
+    # @param job [Hash] Job dictionary from list_jobs
+    # @return [String] job_id for path parameters, or empty string
+    def self.get_job_id(job)
+      job["job_id"] || job[:job_id] || ""
+    end
+
     # Format datetime to ISO 8601 string for API
     #
     # Relies on UTC timezone. Converts the time to UTC if it's not already.
@@ -226,8 +252,10 @@ module ScoutApmMcp
         value * 60 * 60
       when /^day/
         value * 24 * 60 * 60
+        # :nocov:
       else
         raise ArgumentError, "Unknown time unit: #{unit}"
+        # :nocov:
       end
     end
 

data/lib/scout_apm_mcp/mcp_error_id_patch.rb

@@ -0,0 +1,29 @@
+require "securerandom"
+
+# Monkey-patch fast-mcp so JSON-RPC error responses always include a non-nil id (strict MCP clients).
+# Loaded from server only; excluded.from SimpleCov — see spec_helper.
+module MCP
+  module Transports
+    class StdioTransport
+      if method_defined?(:send_error)
+        alias_method :original_send_error, :send_error
+
+        def send_error(code, message, id = nil)
+          id = "error_#{SecureRandom.hex(8)}" if id.nil?
+          original_send_error(code, message, id)
+        end
+      end
+    end
+  end
+
+  class Server
+    if method_defined?(:send_error)
+      alias_method :original_send_error, :send_error
+
+      def send_error(code, message, id = nil)
+        id = "error_#{SecureRandom.hex(8)}" if id.nil?
+        original_send_error(code, message, id)
+      end
+    end
+  end
+end

data/lib/scout_apm_mcp/server.rb

@@ -1,48 +1,13 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
-
 require "fast_mcp"
 require "scout_apm_mcp"
 require "logger"
 require "stringio"
-require "securerandom"
+require_relative "mcp_error_id_patch"
 
 # Alias MCP to FastMcp for compatibility
 FastMcp = MCP unless defined?(FastMcp)
 
-# Monkey-patch fast-mcp to ensure error responses always have a valid id
-# JSON-RPC 2.0 allows id: null for notifications, but MCP clients (Cursor/Inspector)
-# use strict Zod validation that requires id to be a string or number
-module MCP
-  module Transports
-    class StdioTransport
-      if method_defined?(:send_error)
-        alias_method :original_send_error, :send_error
-
-        def send_error(code, message, id = nil)
-          # Use placeholder id if nil to satisfy strict MCP client validation
-          # JSON-RPC 2.0 allows null for notifications, but MCP clients require valid id
-          id = "error_#{SecureRandom.hex(8)}" if id.nil?
-          original_send_error(code, message, id)
-        end
-      end
-    end
-  end
-
-  class Server
-    if method_defined?(:send_error)
-      alias_method :original_send_error, :send_error
-
-      def send_error(code, message, id = nil)
-        # Use placeholder id if nil to satisfy strict MCP client validation
-        # JSON-RPC 2.0 allows null for notifications, but MCP clients require valid id
-        id = "error_#{SecureRandom.hex(8)}" if id.nil?
-        original_send_error(code, message, id)
-      end
-    end
-  end
-end
-
 module ScoutApmMcp
   # MCP Server for ScoutAPM integration
   #
@@ -135,6 +100,10 @@ module ScoutApmMcp
       server.register_tool(ListEndpointsTool)
       server.register_tool(GetEndpointMetricsTool)
       server.register_tool(ListEndpointTracesTool)
+      server.register_tool(ListJobsTool)
+      server.register_tool(ListJobMetricsTool)
+      server.register_tool(GetJobMetricsTool)
+      server.register_tool(ListJobTracesTool)
       server.register_tool(FetchTraceTool)
       server.register_tool(ListErrorGroupsTool)
       server.register_tool(GetErrorGroupTool)
@@ -363,6 +332,83 @@ module ScoutApmMcp
       end
     end
 
+    class ListJobsTool < BaseTool
+      description <<~DESC
+        List background jobs for an application with performance metrics (throughput, execution time, etc.).
+
+        Time range: same as ListEndpointsTool — use range and/or from/to. If none are given, defaults to the last 7 days.
+
+        Each job includes a `job_id` (base64) for ListJobMetricsTool, GetJobMetricsTool, and ListJobTracesTool.
+      DESC
+
+      arguments do
+        required(:app_id).filled(:integer).description("ScoutAPM application ID")
+        optional(:range).maybe(:string).description("Quick time range: 30min, 60min, 3hrs, 6hrs, 12hrs, 1day, 3days, 7days")
+        optional(:from).maybe(:string).description("Start time ISO 8601. Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time ISO 8601; anchor for range if range is provided.")
+      end
+
+      def call(app_id:, range: nil, from: nil, to: nil)
+        get_client.list_jobs(app_id, from: from, to: to, range: range)
+      end
+    end
+
+    class ListJobMetricsTool < BaseTool
+      description "List available metric types for a specific background job (throughput, execution_time, latency, errors, allocations)"
+
+      arguments do
+        required(:app_id).filled(:integer).description("ScoutAPM application ID")
+        required(:job_id).filled(:string).description("Job ID (base64 URL-encoded) from list_jobs results")
+      end
+
+      def call(app_id:, job_id:)
+        get_client.list_job_metrics(app_id, job_id)
+      end
+    end
+
+    class GetJobMetricsTool < BaseTool
+      description <<~DESC
+        Get time-series data for a background job metric.
+
+        Metric types: throughput, execution_time, latency, errors, allocations (not the same set as HTTP endpoint metrics).
+
+        Use range or explicit from/to, same as GetEndpointMetricsTool.
+      DESC
+
+      arguments do
+        required(:app_id).filled(:integer).description("ScoutAPM application ID")
+        required(:job_id).filled(:string).description("Job ID (base64 URL-encoded)")
+        required(:metric_type).filled(:string).description("Job metric: throughput, execution_time, latency, errors, allocations")
+        optional(:range).maybe(:string).description("Quick time range template")
+        optional(:from).maybe(:string).description("Start time ISO 8601. Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time ISO 8601.")
+      end
+
+      def call(app_id:, job_id:, metric_type:, range: nil, from: nil, to: nil)
+        get_client.get_job_metrics(app_id, job_id, metric_type, from: from, to: to, range: range)
+      end
+    end
+
+    class ListJobTracesTool < BaseTool
+      description <<~DESC
+        List traces for a background job (max 100, within 7 days). Same time constraints as ListEndpointTracesTool.
+
+        Use FetchTraceTool with a trace id from results for full span detail.
+      DESC
+
+      arguments do
+        required(:app_id).filled(:integer).description("ScoutAPM application ID")
+        required(:job_id).filled(:string).description("Job ID (base64 URL-encoded)")
+        optional(:range).maybe(:string).description("Quick time range template")
+        optional(:from).maybe(:string).description("Start time ISO 8601; must be within last 7 days if used with to.")
+        optional(:to).maybe(:string).description("End time ISO 8601.")
+      end
+
+      def call(app_id:, job_id:, range: nil, from: nil, to: nil)
+        get_client.list_job_traces(app_id, job_id, from: from, to: to, range: range)
+      end
+    end
+
     class FetchTraceTool < BaseTool
       description "Fetch detailed trace information from ScoutAPM API"
 
@@ -522,10 +568,12 @@ module ScoutApmMcp
         Useful for extracting IDs before making other API requests.
 
         Returns a hash with:
-        - url_type: :endpoint, :trace, :error_group, :insight, :app, or :unknown
+        - url_type: :endpoint, :trace, :job, :job_trace, :error_group, :insight, :app, or :unknown
         - app_id: Application ID (integer)
         - endpoint_id: Base64 URL-encoded endpoint ID (if present)
+        - job_id: Base64 URL-encoded job ID (if present)
         - trace_id: Trace ID (if present)
+        - decoded_job: Human-readable queue/job name (if job_id present)
         - error_id: Error group ID (if present)
         - insight_type: Insight type (if present)
         - decoded_endpoint: Human-readable endpoint path (if endpoint_id present)
@@ -551,7 +599,9 @@ module ScoutApmMcp
         This tool automatically parses ScoutAPM URLs and fetches the corresponding data.
         Supported URL types:
         - Endpoint URLs: /apps/{app_id}/endpoints/{endpoint_id} (fetches from endpoint list)
+        - Job URLs: /apps/{app_id}/jobs/{job_id} (fetches from job list)
         - Trace URLs: /apps/{app_id}/endpoints/{endpoint_id}/trace/{trace_id}
+        - Job trace URLs: /apps/{app_id}/jobs/{job_id}/trace/{trace_id}
         - Error group URLs: /apps/{app_id}/error_groups/{error_id}
         - Insight URLs: /apps/{app_id}/insights or /apps/{app_id}/insights/{insight_type}
         - App URLs: /apps/{app_id}
@@ -561,12 +611,12 @@ module ScoutApmMcp
         - https://scoutapm.com/apps/123/endpoints/ABC123.../trace/456 (trace)
         - https://scoutapm.com/apps/123/error_groups/789 (error group)
 
-        For trace URLs, set include_endpoint=true to also fetch endpoint context.
+        For endpoint or job trace URLs, set include_endpoint=true to also fetch endpoint or job summary from the last 7 days.
       DESC
 
       arguments do
         required(:url).filled(:string).description("Full ScoutAPM URL")
-        optional(:include_endpoint).filled(:bool).description("For trace URLs, also fetch endpoint details for context (default: false)")
+        optional(:include_endpoint).filled(:bool).description("For trace URLs, also fetch endpoint or job context from recent list (default: false)")
       end
 
       def call(url:, include_endpoint: false)
@@ -604,6 +654,46 @@ module ScoutApmMcp
           else
             raise "Invalid trace URL: missing app_id or trace_id"
           end
+        when :job_trace
+          if parsed[:app_id] && parsed[:trace_id]
+            trace_data = client.fetch_trace(parsed[:app_id], parsed[:trace_id])
+            result[:data] = {trace: trace_data}
+
+            if include_endpoint && parsed[:job_id]
+              begin
+                jobs = client.list_jobs(parsed[:app_id], range: "7days")
+                job_data = jobs.find { |j| Helpers.get_job_id(j) == parsed[:job_id] }
+
+                if job_data
+                  result[:data][:job] = job_data
+                else
+                  result[:data][:job_error] = "Job not found in the last 7 days"
+                end
+                result[:data][:decoded_job] = parsed[:decoded_job]
+              rescue => e
+                result[:data][:job_error] = "Failed to fetch job: #{e.message}"
+                result[:data][:decoded_job] = parsed[:decoded_job]
+              end
+            end
+          else
+            raise "Invalid job trace URL: missing app_id or trace_id"
+          end
+        when :job
+          if parsed[:app_id] && parsed[:job_id]
+            jobs = client.list_jobs(parsed[:app_id], range: "7days")
+            job_data = jobs.find { |j| Helpers.get_job_id(j) == parsed[:job_id] }
+
+            if job_data
+              result[:data] = {
+                job: job_data,
+                decoded_job: parsed[:decoded_job]
+              }
+            else
+              raise "Job not found in the last 7 days. Try using ListJobsTool with a longer time range."
+            end
+          else
+            raise "Invalid job URL: missing app_id or job_id"
+          end
         when :endpoint
           if parsed[:app_id] && parsed[:endpoint_id]
             endpoints = client.list_endpoints(parsed[:app_id], range: "7days")

data/lib/scout_apm_mcp/version.rb

@@ -1,3 +1,3 @@
 module ScoutApmMcp
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/sig/scout_apm_mcp.rbs

@@ -5,6 +5,7 @@ module ScoutApmMcp
     def self.get_api_key: (?api_key: String?, ?op_vault: String, ?op_item: String, ?op_field: String) -> String
     def self.parse_scout_url: (String url) -> Hash[Symbol, untyped]
     def self.decode_endpoint_id: (String endpoint_id) -> String
+    def self.get_job_id: (Hash[String, untyped] | Hash[Symbol, untyped] job) -> String
   end
 
   class Client
@@ -18,6 +19,10 @@ module ScoutApmMcp
     def list_endpoints: (Integer app_id, ?from: String?, ?to: String?) -> Hash[String, untyped]
     def get_endpoint_metrics: (Integer app_id, String endpoint_id, String metric_type, ?from: String?, ?to: String?) -> Hash[String, untyped]
     def list_endpoint_traces: (Integer app_id, String endpoint_id, ?from: String?, ?to: String?) -> Hash[String, untyped]
+    def list_jobs: (Integer app_id, ?from: String?, ?to: String?, ?range: String?) -> untyped
+    def list_job_metrics: (Integer app_id, String job_id) -> untyped
+    def get_job_metrics: (Integer app_id, String job_id, String metric_type, ?from: String?, ?to: String?, ?range: String?) -> untyped
+    def list_job_traces: (Integer app_id, String job_id, ?from: String?, ?to: String?, ?range: String?) -> untyped
     def fetch_trace: (Integer app_id, Integer trace_id) -> Hash[String, untyped]
     def list_error_groups: (Integer app_id, ?from: String?, ?to: String?, ?endpoint: String?) -> Hash[String, untyped]
     def get_error_group: (Integer app_id, Integer error_id) -> Hash[String, untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scout_apm_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Andrei Makarov
@@ -305,6 +305,7 @@ files:
 - lib/scout_apm_mcp/client.rb
 - lib/scout_apm_mcp/errors.rb
 - lib/scout_apm_mcp/helpers.rb
+- lib/scout_apm_mcp/mcp_error_id_patch.rb
 - lib/scout_apm_mcp/server.rb
 - lib/scout_apm_mcp/version.rb
 - sig/scout_apm_mcp.rbs