scout_apm_mcp 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2bbad61c1acff6ae4c31b52a7e820acdc64449be4ae998a574c1937ac4775c
-  data.tar.gz: a2c68cf35aa37975a99cf98b68fa29a91673c449f983bbb96547b6403df8401f
+  metadata.gz: 24de549e2d8e310ce563f8a9c380f642aabdd528259785ed17ae062c8b8e59aa
+  data.tar.gz: 5a9c147401b3136be74f5197ec757b4f1d357c1ad5483f12c0813315f6d6d9e8
 SHA512:
-  metadata.gz: e591d27a417285348f7257f150aeb11a9fa4390227893fc996fadf65d08dd856fd4121f3780e7d5403ecb3e985d5c3f2389dce5a99c3d4f57ad9f47bb4123876
-  data.tar.gz: 6112164513df8a51d4e0c039f9245621869ea4533a54ad493df3ec3e4aa67b738fd4952a0507c740a35a1c8568705ed72f8c2cf9d927603bd85fb9080b671f46
+  metadata.gz: 509eeae8882791a33706ceda9a71a4095ef6e99abda4e7401082435d0d6e055882ebced248e176c74154bfa28db09eb965e49c5df88e8fa3c581f0f1e9dac782
+  data.tar.gz: 33143a776cb940411007c14be1a34691a5569275fa8c3c507b2eca92846c8585bcfa438906b135dd31f986c6fbbd0ff7a98c7be74e27491242aa9f751b410202

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## 0.1.3 (2025-11-21)
+
+- Custom exception classes (`ScoutApmMcp::Error`, `ScoutApmMcp::AuthError`, `ScoutApmMcp::APIError`) for better error handling
+- Input validation for metric types (`VALID_METRICS` constant) and insight types (`VALID_INSIGHTS` constant)
+- Time range validation (ensures from_time < to_time and range doesn't exceed 2 weeks)
+- Trace age validation (ensures trace queries aren't older than 7 days)
+- Client methods now return extracted data instead of full API response structure
+- Time/Duration helpers (`Helpers.format_time`, `Helpers.parse_time`, `Helpers.make_duration`)
+- Endpoint ID extraction helper (`Helpers.get_endpoint_id`)
+- User-Agent header (`scout-apm-mcp-rb/VERSION`) on all API requests
+- `active_since` parameter to `list_apps` method for filtering apps by last reported time
+- API-level error parsing - checks for `header.status.code` in response body
+- Error handling now uses custom exception classes instead of generic `RuntimeError`
+- MCP `ListAppsTool` now supports optional `active_since` parameter
+- Error responses now properly parse API-level error codes from response body
+- Invalid metric types, insight types, and time ranges are now validated before API calls
+
 ## 0.1.2 (2025-11-21)
 
 - Enhanced SSL certificate handling with support for `SSL_CERT_FILE` environment variable and automatic fallback to system certificates

data/README.md

@@ -113,12 +113,18 @@ The server will start and communicate via STDIN/STDOUT using the MCP protocol. M
 - **MCP Server Integration**: Ready-to-use MCP server compatible with Cursor IDE, Claude Desktop, and other MCP-enabled tools
 - **API Key Management**: Supports environment variables and 1Password integration (via optional `opdotenv` gem)
 - **URL Parsing**: Helper methods to parse ScoutAPM URLs and extract IDs
+- **Time Utilities**: Helper methods for formatting, parsing, and working with ISO 8601 time strings
+- **Input Validation**: Validates metric types, insight types, and time ranges before API calls
+- **Custom Error Handling**: Dedicated exception classes for better error handling and debugging
 - **Comprehensive API Coverage**: Supports all ScoutAPM API endpoints (apps, metrics, endpoints, traces, errors, insights)
+- **Data Extraction**: Client methods return extracted data instead of full API response structure for easier usage
 
 ## Basic Usage
 
 ### API Client
 
+**Note**: As of version 0.1.3, all client methods return extracted data (arrays, hashes) instead of the full API response structure. This is a breaking change from previous versions.
+
 ```ruby
 require "scout_apm_mcp"
 
@@ -128,10 +134,13 @@ api_key = ScoutApmMcp::Helpers.get_api_key
 # Create client
 client = ScoutApmMcp::Client.new(api_key: api_key)
 
-# List applications
+# List applications (returns Array<Hash>)
 apps = client.list_apps
 
-# Get application details
+# List applications filtered by active_since
+apps = client.list_apps(active_since: "2025-11-01T00:00:00Z")
+
+# Get application details (returns Hash)
 app = client.get_app(123)
 
 # List endpoints
@@ -140,7 +149,7 @@ endpoints = client.list_endpoints(123)
 # Fetch trace
 trace = client.fetch_trace(123, 456)
 
-# Get metrics
+# Get metrics (returns Hash with series data)
 metrics = client.get_metric(123, "response_time", from: "2025-01-01T00:00:00Z", to: "2025-01-02T00:00:00Z")
 
 # List error groups
@@ -159,6 +168,26 @@ parsed = ScoutApmMcp::Helpers.parse_scout_url(url)
 # => { app_id: 123, endpoint_id: "...", trace_id: 456, decoded_endpoint: "...", query_params: {...} }
 ```
 
+### Time and Duration Helpers
+
+```ruby
+# Format Time object to ISO 8601 string
+time_str = ScoutApmMcp::Helpers.format_time(Time.now)
+# => "2025-11-21T12:00:00Z"
+
+# Parse ISO 8601 string to Time object
+time = ScoutApmMcp::Helpers.parse_time("2025-11-21T12:00:00Z")
+# => #<Time: 2025-11-21 12:00:00 UTC>
+
+# Create duration hash from two ISO 8601 strings
+duration = ScoutApmMcp::Helpers.make_duration("2025-11-21T00:00:00Z", "2025-11-21T12:00:00Z")
+# => { start: #<Time: ...>, end: #<Time: ...> }
+
+# Extract endpoint ID from endpoint hash
+endpoint_id = ScoutApmMcp::Helpers.get_endpoint_id(endpoint_hash)
+# => "base64-encoded-endpoint-id"
+```
+
 ### API Key Management
 
 The gem supports multiple methods for API key retrieval (checked in order):
@@ -193,7 +222,7 @@ api_key = ScoutApmMcp::Helpers.get_api_key(
 
 ### Applications
 
-- `list_apps` - List all applications
+- `list_apps(active_since:)` - List all applications (optionally filtered by last reported time)
 - `get_app(app_id)` - Get application details
 
 ### Metrics
@@ -249,11 +278,32 @@ The server will communicate via STDIN/STDOUT using the MCP protocol. Configure i
 
 ## Error Handling
 
-The client raises exceptions for API errors:
+The client uses custom exception classes for better error handling:
+
+- `ScoutApmMcp::Error` - Base exception class for all ScoutAPM SDK errors
+- `ScoutApmMcp::AuthError` - Raised when authentication fails (401 Unauthorized)
+- `ScoutApmMcp::APIError` - Raised for API errors (includes `status_code` and `response_data` attributes)
 
-- `RuntimeError` with message containing "Authentication failed" for 401 Unauthorized
-- `RuntimeError` with message containing "Resource not found" for 404 Not Found
-- `RuntimeError` with message containing "API request failed" for other HTTP errors
+The client also validates input parameters and raises `ArgumentError` for:
+- Invalid metric types (must be one of: `apdex`, `response_time`, `response_time_95th`, `errors`, `throughput`, `queue_time`)
+- Invalid insight types (must be one of: `n_plus_one`, `memory_bloat`, `slow_query`)
+- Invalid time ranges (from_time must be before to_time, and range cannot exceed 2 weeks)
+- Trace queries older than 7 days (for `list_endpoint_traces`)
+
+```ruby
+begin
+  client.get_metric(123, "invalid_metric", from: "2025-01-01T00:00:00Z", to: "2025-01-02T00:00:00Z")
+rescue ScoutApmMcp::AuthError => e
+  puts "Authentication failed: #{e.message}"
+rescue ScoutApmMcp::APIError => e
+  puts "API error (#{e.status_code}): #{e.message}"
+  puts "Response data: #{e.response_data}"
+rescue ArgumentError => e
+  puts "Invalid parameter: #{e.message}"
+rescue ScoutApmMcp::Error => e
+  puts "Error: #{e.message}"
+end
+```
 
 ## Development
 

data/lib/scout_apm_mcp/client.rb

@@ -3,6 +3,10 @@ require "net/http"
 require "openssl"
 require "json"
 require "base64"
+require "time"
+
+require_relative "errors"
+require_relative "version"
 
 module ScoutApmMcp
   # ScoutAPM API client for making authenticated requests to the ScoutAPM API
@@ -15,37 +19,63 @@ module ScoutApmMcp
   class Client
     API_BASE = "https://scoutapm.com/api/v0"
 
+    # Valid metric types
+    VALID_METRICS = %w[apdex response_time response_time_95th errors throughput queue_time].freeze
+
+    # Valid insight types
+    VALID_INSIGHTS = %w[n_plus_one memory_bloat slow_query].freeze
+
     # @param api_key [String] ScoutAPM API key
     # @param api_base [String] API base URL (default: https://scoutapm.com/api/v0)
     def initialize(api_key:, api_base: API_BASE)
       @api_key = api_key
       @api_base = api_base
+      @user_agent = "scout-apm-mcp-rb/#{VERSION}"
     end
 
     # List all applications accessible with the provided API key
     #
-    # @return [Hash] API response containing applications list
-    def list_apps
+    # @param active_since [String, nil] ISO 8601 datetime string to filter apps active since that time (default: 30 days ago)
+    # @return [Array<Hash>] Array of application hashes
+    def list_apps(active_since: nil)
       uri = URI("#{@api_base}/apps")
-      make_request(uri)
+      response = make_request(uri)
+      apps = response.dig("results", "apps") || []
+
+      # Filter by active_since if provided
+      if active_since
+        active_time = Helpers.parse_time(active_since)
+        apps = apps.select do |app|
+          reported_at = app["last_reported_at"]
+          if reported_at && !reported_at.empty?
+            Helpers.parse_time(reported_at) >= active_time
+          else
+            false
+          end
+        end
+      end
+
+      apps
     end
 
     # Get application details for a specific application
     #
     # @param app_id [Integer] ScoutAPM application ID
-    # @return [Hash] API response containing application details
+    # @return [Hash] Application details hash
     def get_app(app_id)
       uri = URI("#{@api_base}/apps/#{app_id}")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "app") || {}
     end
 
     # List available metric types for an application
     #
     # @param app_id [Integer] ScoutAPM application ID
-    # @return [Hash] API response containing available metrics
+    # @return [Array<String>] Array of available metric type names
     def list_metrics(app_id)
       uri = URI("#{@api_base}/apps/#{app_id}/metrics")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "availableMetrics") || []
     end
 
     # Get time-series data for a specific metric type
@@ -54,11 +84,13 @@ module ScoutApmMcp
     # @param metric_type [String] Metric type (apdex, response_time, response_time_95th, errors, throughput, queue_time)
     # @param from [String, nil] Start time in ISO 8601 format
     # @param to [String, nil] End time in ISO 8601 format
-    # @return [Hash] API response containing metric data
+    # @return [Hash] Hash containing metric series data
     def get_metric(app_id, metric_type, from: nil, to: nil)
+      validate_metric_params(metric_type, from, to)
       uri = URI("#{@api_base}/apps/#{app_id}/metrics/#{metric_type}")
       uri.query = build_query_string(from: from, to: to)
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "series") || {}
     end
 
     # List all endpoints for an application
@@ -66,22 +98,25 @@ module ScoutApmMcp
     # @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
-    # @return [Hash] API response containing endpoints list
+    # @return [Array<Hash>] Array of endpoint hashes
     def list_endpoints(app_id, from: nil, to: nil)
+      validate_time_range(from, to) if from && to
       uri = URI("#{@api_base}/apps/#{app_id}/endpoints")
       uri.query = build_query_string(from: from, to: to)
-      make_request(uri)
+      response = make_request(uri)
+      response["results"] || []
     end
 
     # Get endpoint details
     #
     # @param app_id [Integer] ScoutAPM application ID
     # @param endpoint_id [String] Endpoint ID (base64 URL-encoded)
-    # @return [Hash] API response containing endpoint details
+    # @return [Hash] Endpoint details hash
     def get_endpoint(app_id, endpoint_id)
       encoded_endpoint_id = URI.encode_www_form_component(endpoint_id)
       uri = URI("#{@api_base}/apps/#{app_id}/endpoints/#{encoded_endpoint_id}")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "endpoint") || response["results"] || {}
     end
 
     # Get metric data for a specific endpoint
@@ -91,12 +126,15 @@ module ScoutApmMcp
     # @param metric_type [String] Metric type (apdex, response_time, response_time_95th, errors, throughput, queue_time)
     # @param from [String, nil] Start time in ISO 8601 format
     # @param to [String, nil] End time in ISO 8601 format
-    # @return [Hash] API response containing endpoint metrics
+    # @return [Array] Array of metric data points for the specified metric type
     def get_endpoint_metrics(app_id, endpoint_id, metric_type, from: nil, to: nil)
+      validate_metric_params(metric_type, from, to)
       encoded_endpoint_id = URI.encode_www_form_component(endpoint_id)
       uri = URI("#{@api_base}/apps/#{app_id}/endpoints/#{encoded_endpoint_id}/metrics/#{metric_type}")
       uri.query = build_query_string(from: from, to: to)
-      make_request(uri)
+      response = make_request(uri)
+      series = response.dig("results", "series") || {}
+      series[metric_type] || []
     end
 
     # List traces for a specific endpoint (max 100, within 7 days)
@@ -105,22 +143,33 @@ module ScoutApmMcp
     # @param endpoint_id [String] Endpoint ID (base64 URL-encoded)
     # @param from [String, nil] Start time in ISO 8601 format
     # @param to [String, nil] End time in ISO 8601 format
-    # @return [Hash] API response containing traces list
+    # @return [Array<Hash>] Array of trace hashes
     def list_endpoint_traces(app_id, endpoint_id, from: nil, to: nil)
+      validate_time_range(from, to) if from && to
+      if from && to
+        # Validate that from_time is not older than 7 days
+        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
       encoded_endpoint_id = URI.encode_www_form_component(endpoint_id)
       uri = URI("#{@api_base}/apps/#{app_id}/endpoints/#{encoded_endpoint_id}/traces")
       uri.query = build_query_string(from: from, to: to)
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "traces") || []
     end
 
     # Fetch detailed trace information
     #
     # @param app_id [Integer] ScoutAPM application ID
     # @param trace_id [Integer] Trace identifier
-    # @return [Hash] API response containing trace details
+    # @return [Hash] Trace details hash
     def fetch_trace(app_id, trace_id)
       uri = URI("#{@api_base}/apps/#{app_id}/traces/#{trace_id}")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "trace") || {}
     end
 
     # List error groups for an application (max 100, within 30 days)
@@ -129,46 +178,51 @@ module ScoutApmMcp
     # @param from [String, nil] Start time in ISO 8601 format
     # @param to [String, nil] End time in ISO 8601 format
     # @param endpoint [String, nil] Base64 URL-encoded endpoint filter (optional)
-    # @return [Hash] API response containing error groups list
+    # @return [Array<Hash>] Array of error group hashes
     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")
       params = {}
       params["from"] = from if from
       params["to"] = to if to
       params["endpoint"] = endpoint if endpoint
       uri.query = URI.encode_www_form(params) unless params.empty?
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "error_groups") || []
     end
 
     # Get details for a specific error group
     #
     # @param app_id [Integer] ScoutAPM application ID
     # @param error_id [Integer] Error group identifier
-    # @return [Hash] API response containing error group details
+    # @return [Hash] Error group details hash
     def get_error_group(app_id, error_id)
       uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "error_group") || {}
     end
 
     # Get individual errors within an error group (max 100)
     #
     # @param app_id [Integer] ScoutAPM application ID
     # @param error_id [Integer] Error group identifier
-    # @return [Hash] API response containing errors list
+    # @return [Array<Hash>] Array of error hashes
     def get_error_group_errors(app_id, error_id)
       uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}/errors")
-      make_request(uri)
+      response = make_request(uri)
+      response.dig("results", "errors") || []
     end
 
     # Get all insight types for an application (cached for 5 minutes)
     #
     # @param app_id [Integer] ScoutAPM application ID
     # @param limit [Integer, nil] Maximum number of items per insight type (default: 20)
-    # @return [Hash] API response containing all insights
+    # @return [Hash] Hash containing all insight types
     def get_all_insights(app_id, limit: nil)
       uri = URI("#{@api_base}/apps/#{app_id}/insights")
       uri.query = "limit=#{limit}" if limit
-      make_request(uri)
+      response = make_request(uri)
+      response["results"] || {}
     end
 
     # Get data for a specific insight type
@@ -176,11 +230,15 @@ module ScoutApmMcp
     # @param app_id [Integer] ScoutAPM application ID
     # @param insight_type [String] Insight type (n_plus_one, memory_bloat, slow_query)
     # @param limit [Integer, nil] Maximum number of items (default: 20)
-    # @return [Hash] API response containing insights
+    # @return [Hash] Hash containing insight data
     def get_insight_by_type(app_id, insight_type, limit: nil)
+      unless VALID_INSIGHTS.include?(insight_type)
+        raise ArgumentError, "Invalid insight_type. Must be one of: #{VALID_INSIGHTS.join(", ")}"
+      end
       uri = URI("#{@api_base}/apps/#{app_id}/insights/#{insight_type}")
       uri.query = "limit=#{limit}" if limit
-      make_request(uri)
+      response = make_request(uri)
+      response["results"] || {}
     end
 
     # Get historical insights data with cursor-based pagination
@@ -239,6 +297,7 @@ module ScoutApmMcp
 
       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, */*"
 
       response = http.request(request)
@@ -251,14 +310,16 @@ module ScoutApmMcp
           status: response.code.to_i
         }
       when Net::HTTPUnauthorized
-        raise "Authentication failed. Check your API key."
+        raise AuthError, "Authentication failed. Check your API key."
       else
-        raise "API request failed: #{response.code} #{response.message}"
+        raise APIError.new("API request failed: #{response.code} #{response.message}", status_code: response.code.to_i)
       end
     rescue OpenSSL::SSL::SSLError => e
-      raise "SSL verification failed: #{e.message}. This may be due to system certificate configuration issues."
+      raise Error, "SSL verification failed: #{e.message}. This may be due to system certificate configuration issues."
+    rescue Error
+      raise
     rescue => e
-      raise "Request failed: #{e.class} - #{e.message}"
+      raise Error, "Request failed: #{e.class} - #{e.message}"
     end
 
     private
@@ -303,24 +364,97 @@ module ScoutApmMcp
 
       request = Net::HTTP::Get.new(uri)
       request["X-SCOUT-API"] = @api_key
+      request["User-Agent"] = @user_agent
       request["Accept"] = "application/json"
 
       response = http.request(request)
+      response_data = handle_response_errors(response)
+
+      # Check for API-level errors in response body
+      if response_data.is_a?(Hash)
+        header = response_data["header"]
+        if header && header["status"]
+          status_code = header["status"]["code"]
+          if status_code && status_code >= 400
+            error_msg = header["status"]["message"] || "Unknown API error"
+            raise APIError.new(error_msg, status_code: status_code, response_data: response_data)
+          end
+        end
+      end
 
+      response_data
+    rescue OpenSSL::SSL::SSLError => e
+      raise Error, "SSL verification failed: #{e.message}. This may be due to system certificate configuration issues."
+    rescue Error
+      raise
+    rescue => e
+      raise Error, "Request failed: #{e.class} - #{e.message}"
+    end
+
+    # Handle common response errors and parse JSON
+    #
+    # @param response [Net::HTTPResponse] HTTP response object
+    # @return [Hash, Array] Parsed JSON response
+    # @raise [AuthError] When authentication fails
+    # @raise [APIError] When the API returns an error response
+    def handle_response_errors(response)
+      # Try to parse JSON response
+      begin
+        data = JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise APIError.new("Invalid JSON response: #{response.body}", status_code: response.code.to_i)
+      end
+
+      # Check for HTTP-level errors
       case response
       when Net::HTTPSuccess
-        JSON.parse(response.body)
+        data
       when Net::HTTPUnauthorized
-        raise "Authentication failed. Check your API key. Response: #{response.body}"
+        raise AuthError, "Authentication failed - check your API key"
       when Net::HTTPNotFound
-        raise "Resource not found. Response: #{response.body}"
+        raise APIError.new("Resource not found", status_code: 404, response_data: data)
       else
-        raise "API request failed: #{response.code} #{response.message}\n#{response.body}"
+        error_msg = "API request failed"
+        if data.is_a?(Hash) && data.dig("header", "status", "message")
+          error_msg = data.dig("header", "status", "message")
+        end
+        raise APIError.new(error_msg, status_code: response.code.to_i, response_data: data)
+      end
+    end
+
+    # Validate metric parameters
+    #
+    # @param metric_type [String] Metric type to validate
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @raise [ArgumentError] If validation fails
+    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
+
+    # Validate time ranges
+    #
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @raise [ArgumentError] If validation fails
+    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
+
+      # Validate time range (2 week maximum)
+      max_duration = 14 * 24 * 60 * 60 # 14 days in seconds
+      if (to_time - from_time) > max_duration
+        raise ArgumentError, "Time range cannot exceed 2 weeks"
       end
-    rescue OpenSSL::SSL::SSLError => e
-      raise "SSL verification failed: #{e.message}. This may be due to system certificate configuration issues."
-    rescue => e
-      raise "Request failed: #{e.class} - #{e.message}"
     end
   end
 end

data/lib/scout_apm_mcp/errors.rb

@@ -0,0 +1,18 @@
+module ScoutApmMcp
+  # Base exception for Scout APM SDK errors
+  class Error < StandardError; end
+
+  # Raised when authentication fails
+  class AuthError < Error; end
+
+  # Raised when the API returns an error response
+  class APIError < Error
+    attr_reader :status_code, :response_data
+
+    def initialize(message, status_code: nil, response_data: nil)
+      super(message)
+      @status_code = status_code
+      @response_data = response_data
+    end
+  end
+end

data/lib/scout_apm_mcp/helpers.rb

@@ -1,8 +1,9 @@
 require "uri"
 require "base64"
+require "time"
 
 module ScoutApmMcp
-  # Helper module for API key management and URL parsing
+  # Helper module for API key management, URL parsing, and time utilities
   module Helpers
     # Get API key from environment or 1Password
     #
@@ -151,5 +152,53 @@ module ScoutApmMcp
       # If decoding raises an exception, return original string
       endpoint_id.dup.force_encoding(Encoding::UTF_8)
     end
+
+    # Get a unique identifier for an endpoint from an endpoint dictionary
+    #
+    # This is provided by the API implicitly in the 'link' field.
+    #
+    # @param endpoint [Hash] Endpoint dictionary from the API
+    # @return [String] Endpoint ID extracted from the link field, or empty string if not found
+    def self.get_endpoint_id(endpoint)
+      link = endpoint["link"] || endpoint[:link] || ""
+      return "" if link.empty?
+
+      # Extract the endpoint ID from the link (last path segment)
+      link.split("/").last || ""
+    end
+
+    # Format datetime to ISO 8601 string for API
+    #
+    # Relies on UTC timezone. Converts the time to UTC if it's not already.
+    #
+    # @param time [Time] Time object to format
+    # @return [String] ISO 8601 formatted time string (e.g., "2025-01-01T00:00:00Z")
+    def self.format_time(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+
+    # Parse ISO 8601 time string to Time object
+    #
+    # Handles both 'Z' suffix and timezone offsets.
+    #
+    # @param time_str [String] ISO 8601 time string (e.g., "2025-01-01T00:00:00Z")
+    # @return [Time] Time object in UTC
+    def self.parse_time(time_str)
+      # Replace Z with +00:00 for Ruby's Time parser
+      normalized = time_str.sub(/Z\z/i, "+00:00")
+      Time.parse(normalized).utc
+    end
+
+    # Create a Duration object from ISO 8601 strings
+    #
+    # @param from_str [String] Start time in ISO 8601 format
+    # @param to_str [String] End time in ISO 8601 format
+    # @return [Hash] Hash with :start and :end Time objects
+    def self.make_duration(from_str, to_str)
+      {
+        start: parse_time(from_str),
+        end: parse_time(to_str)
+      }
+    end
   end
 end

data/lib/scout_apm_mcp/server.rb

@@ -166,14 +166,14 @@ module ScoutApmMcp
 
     # Applications Tools
     class ListAppsTool < BaseTool
-      description "List all applications accessible with the provided API key"
+      description "List all applications accessible with the provided API key. Provide an optional active_since ISO 8601 to filter to only apps that have reported data since that time. Defaults to the metric retention period of thirty days."
 
       arguments do
-        # No arguments required
+        optional(:active_since).maybe(:string).description("ISO 8601 datetime string to filter apps active since that time")
       end
 
-      def call
-        get_client.list_apps
+      def call(active_since: nil)
+        get_client.list_apps(active_since: active_since)
       end
     end
 
@@ -468,9 +468,15 @@ module ScoutApmMcp
             result[:data] = {trace: trace_data}
 
             if include_endpoint && parsed[:endpoint_id]
-              endpoint_data = client.get_endpoint(parsed[:app_id], parsed[:endpoint_id])
-              result[:data][:endpoint] = endpoint_data
-              result[:data][:decoded_endpoint] = parsed[:decoded_endpoint]
+              begin
+                endpoint_data = client.get_endpoint(parsed[:app_id], parsed[:endpoint_id])
+                result[:data][:endpoint] = endpoint_data
+                result[:data][:decoded_endpoint] = parsed[:decoded_endpoint]
+              rescue => e
+                # Endpoint fetch failed, but we still have trace data
+                result[:data][:endpoint_error] = "Failed to fetch endpoint: #{e.message}"
+                result[:data][:decoded_endpoint] = parsed[:decoded_endpoint]
+              end
             end
           else
             raise "Invalid trace URL: missing app_id or trace_id"

data/lib/scout_apm_mcp/version.rb

@@ -1,3 +1,3 @@
 module ScoutApmMcp
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/scout_apm_mcp.rb

@@ -2,6 +2,7 @@ require "uri"
 require "base64"
 
 require_relative "scout_apm_mcp/version"
+require_relative "scout_apm_mcp/errors"
 require_relative "scout_apm_mcp/client"
 require_relative "scout_apm_mcp/helpers"
 # Server is loaded on-demand when running the executable

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scout_apm_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Andrei Makarov
@@ -233,6 +233,7 @@ files:
 - bin/scout_apm_mcp
 - lib/scout_apm_mcp.rb
 - lib/scout_apm_mcp/client.rb
+- lib/scout_apm_mcp/errors.rb
 - lib/scout_apm_mcp/helpers.rb
 - lib/scout_apm_mcp/server.rb
 - lib/scout_apm_mcp/version.rb