scout_apm_mcp 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee786e2a50c8985e1423731c5acf85264c5dce178d366238a317685762170c57
-  data.tar.gz: 8fda9d886c840af02bc5caeb0375b4d963bfef95c4c9c12492f415256a21d361
+  metadata.gz: 24de549e2d8e310ce563f8a9c380f642aabdd528259785ed17ae062c8b8e59aa
+  data.tar.gz: 5a9c147401b3136be74f5197ec757b4f1d357c1ad5483f12c0813315f6d6d9e8
 SHA512:
-  metadata.gz: 3434d01dfa3783ba3a1364caadd17aae11deb0170557fba1277d3b9b72e3706cbb5eed30a984ca9b0222f85933caff79242a05b19d400693e27b1b0a8adc9a08
-  data.tar.gz: 87540aa4f25083d54b2aee4c9080c3b3544f3c87fe39462198949814ce12a82aae9dae266f73bbbf940ad0f643c78cf5435c40520a221d642b3859d8ab1b6683
+  metadata.gz: 509eeae8882791a33706ceda9a71a4095ef6e99abda4e7401082435d0d6e055882ebced248e176c74154bfa28db09eb965e49c5df88e8fa3c581f0f1e9dac782
+  data.tar.gz: 33143a776cb940411007c14be1a34691a5569275fa8c3c507b2eca92846c8585bcfa438906b135dd31f986c6fbbd0ff7a98c7be74e27491242aa9f751b410202

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
+- Improved error handling for SSL verification failures with clearer error messages
+- Extended `Helpers.parse_scout_url` to support parsing multiple URL types (endpoints, error_groups, insights, apps) beyond just traces
+- Added `FetchScoutURLTool` MCP tool for automatically detecting and fetching data from any ScoutAPM URL
+- Fixed MCP error handling to ensure error responses always have valid IDs for strict MCP client validation
+- Improved URL parsing to return `url_type` field for better resource type detection
+
 ## 0.1.1 (2025-11-21)
 
 - Fixed `NullLogger` missing `set_client_initialized` method that caused MCP initialization errors

data/README.md

@@ -24,22 +24,6 @@ Sponsored by [Kisko Labs](https://www.kiskolabs.com).
 
 For Cursor IDE, create or update `.cursor/mcp.json` in your project:
 
-```json
-{
-  "mcpServers": {
-    "scout-apm": {
-      "command": "bundle",
-      "args": ["exec", "scout_apm_mcp"],
-      "env": {
-        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
-      }
-    }
-  }
-}
-```
-
-Or if installed globally:
-
 ```json
 {
   "mcpServers": {
@@ -64,21 +48,10 @@ For Claude Desktop, edit the MCP configuration file:
 {
   "mcpServers": {
     "scout-apm": {
-      "command": "bundle",
-      "args": ["exec", "scout_apm_mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-Or if installed globally:
-
-```json
-{
-  "mcpServers": {
-    "scout-apm": {
-      "command": "scout_apm_mcp"
+      "command": "scout_apm_mcp",
+      "env": {
+        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
+      }
     }
   }
 }
@@ -140,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"
 
@@ -155,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
@@ -167,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
@@ -186,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):
@@ -220,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
@@ -276,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)
+
+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`)
 
-- `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
+```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

@@ -1,7 +1,12 @@
 require "uri"
 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
@@ -14,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
@@ -53,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
@@ -65,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
@@ -90,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)
@@ -104,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)
@@ -128,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
@@ -175,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
@@ -238,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)
@@ -250,10 +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 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
 
     private
@@ -264,9 +330,24 @@ module ScoutApmMcp
     # @return [Net::HTTP] Configured HTTP client
     def build_http_client(uri)
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
       http.read_timeout = 10
       http.open_timeout = 10
+
+      if uri.scheme == "https"
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+        # Set ca_file directly - this is the simplest and most reliable approach
+        # Try SSL_CERT_FILE first, then default cert file
+        ca_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
+
+        http.ca_file = ca_file if ca_file
+      end
+
       http
     end
 
@@ -283,19 +364,96 @@ 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
     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
     #
@@ -63,30 +64,55 @@ module ScoutApmMcp
             "or provide OP_ENV_ENTRY_PATH, or op_vault and op_item parameters for 1Password integration"
     end
 
-    # Parse a ScoutAPM trace URL and extract app_id, endpoint_id, and trace_id
+    # Parse a ScoutAPM URL and extract resource information
     #
-    # @param url [String] Full ScoutAPM trace URL
-    # @return [Hash] Hash containing :app_id, :endpoint_id, :trace_id, :query_params, and :decoded_endpoint
+    # @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
     def self.parse_scout_url(url)
       uri = URI.parse(url)
       path_parts = uri.path.split("/").reject(&:empty?)
 
-      # Extract from URL: /apps/{app_id}/endpoints/{endpoint_id}/trace/{trace_id}
+      result = {}
       app_index = path_parts.index("apps")
-      endpoints_index = path_parts.index("endpoints")
-      trace_index = path_parts.index("trace")
 
-      result = {}
+      return result unless app_index
+
+      result[:app_id] = path_parts[app_index + 1].to_i
 
-      if app_index && endpoints_index && trace_index
-        result[:app_id] = path_parts[app_index + 1].to_i
-        result[:endpoint_id] = path_parts[endpoints_index + 1]
-        result[:trace_id] = path_parts[trace_index + 1].to_i
+      # Detect URL type and extract IDs
+      # Pattern: /apps/{app_id}/endpoints/{endpoint_id}/trace/{trace_id}
+      if path_parts.include?("trace")
+        result[:url_type] = :trace
+        endpoints_index = path_parts.index("endpoints")
+        trace_index = path_parts.index("trace")
+        if endpoints_index && trace_index
+          result[:endpoint_id] = path_parts[endpoints_index + 1]
+          result[:trace_id] = path_parts[trace_index + 1].to_i
+        end
+      # Pattern: /apps/{app_id}/endpoints/{endpoint_id}
+      elsif path_parts.include?("endpoints")
+        result[:url_type] = :endpoint
+        endpoints_index = path_parts.index("endpoints")
+        result[:endpoint_id] = path_parts[endpoints_index + 1] if endpoints_index
+      # Pattern: /apps/{app_id}/error_groups/{error_id}
+      elsif path_parts.include?("error_groups")
+        result[:url_type] = :error_group
+        error_groups_index = path_parts.index("error_groups")
+        result[:error_id] = path_parts[error_groups_index + 1].to_i if error_groups_index
+      # Pattern: /apps/{app_id}/insights or /apps/{app_id}/insights/{insight_type}
+      elsif path_parts.include?("insights")
+        result[:url_type] = :insight
+        insights_index = path_parts.index("insights")
+        if insights_index && path_parts.length > insights_index + 1
+          result[:insight_type] = path_parts[insights_index + 1]
+        end
+      # Pattern: /apps/{app_id}
+      elsif path_parts.length == 2 && path_parts[0] == "apps"
+        result[:url_type] = :app
       else
-        # Fallback: try to extract by position
-        result[:app_id] = path_parts[1].to_i if path_parts[0] == "apps"
-        result[:endpoint_id] = path_parts[3] if path_parts[2] == "endpoints"
-        result[:trace_id] = path_parts[5].to_i if path_parts[4] == "trace"
+        result[:url_type] = :unknown
       end
 
       # Parse query parameters
@@ -126,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

@@ -16,6 +16,21 @@ FastMcp = MCP unless defined?(FastMcp)
 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)
@@ -26,17 +41,6 @@ module MCP
       end
     end
   end
-
-  class Server
-    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
 
 module ScoutApmMcp
@@ -141,6 +145,7 @@ module ScoutApmMcp
       server.register_tool(GetInsightsHistoryTool)
       server.register_tool(GetInsightsHistoryByTypeTool)
       server.register_tool(ParseScoutURLTool)
+      server.register_tool(FetchScoutURLTool)
       server.register_tool(FetchOpenAPISchemaTool)
     end
 
@@ -161,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
 
@@ -427,10 +432,10 @@ module ScoutApmMcp
 
     # Utility Tools
     class ParseScoutURLTool < BaseTool
-      description "Parse a ScoutAPM trace URL and extract app_id, endpoint_id, and trace_id"
+      description "Parse a ScoutAPM URL and extract resource information (app_id, endpoint_id, trace_id, etc.)"
 
       arguments do
-        required(:url).filled(:string).description("Full ScoutAPM trace URL (e.g., https://scoutapm.com/apps/123/endpoints/.../trace/456)")
+        required(:url).filled(:string).description("Full ScoutAPM URL (e.g., https://scoutapm.com/apps/123/endpoints/.../trace/456)")
       end
 
       def call(url:)
@@ -438,6 +443,90 @@ module ScoutApmMcp
       end
     end
 
+    class FetchScoutURLTool < BaseTool
+      description "Fetch data from a ScoutAPM URL by automatically detecting the resource type and fetching the appropriate data"
+
+      arguments do
+        required(:url).filled(:string).description("Full ScoutAPM URL (e.g., https://scoutapm.com/apps/123/endpoints/.../trace/456)")
+        optional(:include_endpoint).filled(:bool).description("For trace URLs, also fetch endpoint details for context (default: false)")
+      end
+
+      def call(url:, include_endpoint: false)
+        parsed = Helpers.parse_scout_url(url)
+        client = get_client
+
+        result = {
+          url: url,
+          parsed: parsed,
+          data: nil
+        }
+
+        case parsed[:url_type]
+        when :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[:endpoint_id]
+              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"
+          end
+        when :endpoint
+          if parsed[:app_id] && parsed[:endpoint_id]
+            endpoint_data = client.get_endpoint(parsed[:app_id], parsed[:endpoint_id])
+            result[:data] = {
+              endpoint: endpoint_data,
+              decoded_endpoint: parsed[:decoded_endpoint]
+            }
+          else
+            raise "Invalid endpoint URL: missing app_id or endpoint_id"
+          end
+        when :error_group
+          if parsed[:app_id] && parsed[:error_id]
+            error_data = client.get_error_group(parsed[:app_id], parsed[:error_id])
+            result[:data] = {error_group: error_data}
+          else
+            raise "Invalid error group URL: missing app_id or error_id"
+          end
+        when :insight
+          if parsed[:app_id]
+            if parsed[:insight_type]
+              insight_data = client.get_insight_by_type(parsed[:app_id], parsed[:insight_type])
+              result[:data] = {insight: insight_data, insight_type: parsed[:insight_type]}
+            else
+              insights_data = client.get_all_insights(parsed[:app_id])
+              result[:data] = {insights: insights_data}
+            end
+          else
+            raise "Invalid insight URL: missing app_id"
+          end
+        when :app
+          if parsed[:app_id]
+            app_data = client.get_app(parsed[:app_id])
+            result[:data] = {app: app_data}
+          else
+            raise "Invalid app URL: missing app_id"
+          end
+        when :unknown
+          raise "Unknown or unsupported ScoutAPM URL format: #{url}"
+        else
+          raise "Unable to determine URL type from: #{url}"
+        end
+
+        result
+      end
+    end
+
     class FetchOpenAPISchemaTool < BaseTool
       description "Fetch the ScoutAPM OpenAPI schema from the API and optionally validate it"
 

data/lib/scout_apm_mcp/version.rb

@@ -1,3 +1,3 @@
 module ScoutApmMcp
-  VERSION = "0.1.1"
+  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.1
+  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