scout_apm_mcp 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe2bbad61c1acff6ae4c31b52a7e820acdc64449be4ae998a574c1937ac4775c
-  data.tar.gz: a2c68cf35aa37975a99cf98b68fa29a91673c449f983bbb96547b6403df8401f
+  metadata.gz: ce6703433e4f11c4cf2769a636135ed7a429707a84a09e196e7151b43cb368b2
+  data.tar.gz: 2ddf028b1023a364f4eb5d6afc8f1693549ce4ace041f7d12487719f4513ef3d
 SHA512:
-  metadata.gz: e591d27a417285348f7257f150aeb11a9fa4390227893fc996fadf65d08dd856fd4121f3780e7d5403ecb3e985d5c3f2389dce5a99c3d4f57ad9f47bb4123876
-  data.tar.gz: 6112164513df8a51d4e0c039f9245621869ea4533a54ad493df3ec3e4aa67b738fd4952a0507c740a35a1c8568705ed72f8c2cf9d927603bd85fb9080b671f46
+  metadata.gz: 1f1ff860d8e236a1338d4f1ceb62a0a6620ff667dc266cc528a7ffd8eceaaf5f4a874612fcc7e8fe45b64a83c446d42af6eca639d13b4ee5cf71b76ce7e7b6b6
+  data.tar.gz: 3cadb0d9852c1e661630c69148cfdb2d9c85076094e4672f5b0358448015ade8d13bc800c04a67c1b105ddf66b1ca842ac056c8e38b12b158c3c6290a289daa7

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # CHANGELOG
 
+## 0.1.4 (2025-12-08)
+
+- Enhanced API client and documentation for improved endpoint management
+- Refactored RSpec test suite with improved organization and clarity (split into focused spec files by component)
+- Added RuboCop configuration (replacing Standard) with custom rules for RSpec and strict linting
+- Updated trunk configuration to use RuboCop instead of Standard
+- Added Code of Conduct, Governance, and Security Guidelines documents
+- Updated MCP server configuration to use `gem exec` command with Ruby version specification
+- Updated GitHub Actions workflow dependencies
+- Updated bundler dependencies for improved compatibility
+
+## 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

@@ -1,6 +1,6 @@
 # scout_apm_mcp
 
-[![Gem Version](https://badge.fury.io/rb/scout_apm_mcp.svg?v=0.1.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)
+[![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)
 
 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.
 
@@ -20,6 +20,12 @@ Sponsored by [Kisko Labs](https://www.kiskolabs.com).
 2. In 1Password create an item with the name "Scout APM API" and store the API key in a new field named API_KEY
 3. Configure your favorite service to use local MCP server, ensure OP_ENV_ENTRY_PATH has correct vault and item names (both are visible in 1Password UI)
 
+### Installation
+
+```bash
+gem install scout_apm_mcp
+```
+
 ### Cursor IDE Configuration
 
 For Cursor IDE, create or update `.cursor/mcp.json` in your project:
@@ -28,15 +34,19 @@ For Cursor IDE, create or update `.cursor/mcp.json` in your project:
 {
   "mcpServers": {
     "scout-apm": {
-      "command": "scout_apm_mcp",
+      "command": "gem",
+      "args": ["exec", "scout_apm_mcp"],
       "env": {
-        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
+        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name",
+        "RUBY_VERSION": "3.4.7"
       }
     }
   }
 }
 ```
 
+**Note**: Using `gem exec` ensures the correct Ruby version is used. If you're using a Ruby version manager like [mise](https://mise.jdx.dev/) or [rbenv](https://github.com/rbenv/rbenv), set the `RUBY_VERSION` environment variable to match your desired Ruby version. The `gem exec` command will automatically use the correct Ruby version based on your version manager configuration.
+
 ### Claude Desktop Configuration
 
 For Claude Desktop, edit the MCP configuration file:
@@ -48,16 +58,18 @@ For Claude Desktop, edit the MCP configuration file:
 {
   "mcpServers": {
     "scout-apm": {
-      "command": "scout_apm_mcp",
+      "command": "gem",
+      "args": ["exec", "scout_apm_mcp"],
       "env": {
-        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
+        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name",
+        "RUBY_VERSION": "3.4.7"
       }
     }
   }
 }
 ```
 
-**Note**: After updating the configuration, restart Claude Desktop for changes to take effect.
+**Note**: After updating the configuration, restart Claude Desktop for changes to take effect. Using `gem exec` ensures the correct Ruby version is used. If you're using a Ruby version manager like [mise](https://mise.jdx.dev/) or [rbenv](https://github.com/rbenv/rbenv), set the `RUBY_VERSION` environment variable to match your desired Ruby version. The `gem exec` command will automatically use the correct Ruby version based on your version manager configuration.
 
 ### Security Best Practice
 
@@ -107,18 +119,40 @@ scout_apm_mcp
 
 The server will start and communicate via STDIN/STDOUT using the MCP protocol. Make sure you have your ScoutAPM API key configured (see API Key Management section below).
 
+## Upgrading
+
+To upgrade to the latest version of the gem:
+
+```bash
+gem update scout_apm_mcp
+```
+
+If you're using Bundler, update your `Gemfile.lock`:
+
+```bash
+bundle update scout_apm_mcp
+```
+
+**Note**: As of version 0.1.3, client methods return extracted data (arrays, hashes) instead of full API response structures. This is a breaking change from previous versions. See the [CHANGELOG.md](CHANGELOG.md) for details on breaking changes and new features.
+
 ## Features
 
 - **ScoutAPM API Client**: Full-featured client for ScoutAPM REST API
 - **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 +162,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 +177,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 +196,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 +250,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
@@ -204,10 +261,11 @@ api_key = ScoutApmMcp::Helpers.get_api_key(
 ### Endpoints
 
 - `list_endpoints(app_id, from:, to:)` - List all endpoints
-- `get_endpoint(app_id, endpoint_id)` - Get endpoint details
 - `get_endpoint_metrics(app_id, endpoint_id, metric_type, from:, to:)` - Get endpoint metrics
 - `list_endpoint_traces(app_id, endpoint_id, from:, to:)` - List endpoint traces
 
+Note: The API doesn't provide a direct endpoint detail endpoint. Use `list_endpoints` and filter by endpoint_id to get specific endpoint information.
+
 ### Traces
 
 - `fetch_trace(app_id, trace_id)` - Fetch detailed trace information
@@ -249,11 +307,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,66 @@ 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)
+    # @raise [ArgumentError] if api_key is nil or empty
     def initialize(api_key:, api_base: API_BASE)
-      @api_key = api_key
+      if api_key.nil? || api_key.to_s.strip.empty?
+        raise ArgumentError, "API key is required and cannot be nil or empty"
+      end
+      @api_key = api_key.to_s
       @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") || []
+
+      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 +87,20 @@ 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
-    def get_metric(app_id, metric_type, from: nil, to: nil)
+    # @param range [String, nil] Quick time range (e.g., "30min", "1day", "3days", "7days"). If provided, calculates from/to automatically.
+    # @return [Hash] Hash containing metric series data
+    def get_metric(app_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_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 +108,32 @@ 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
-    def list_endpoints(app_id, from: nil, to: nil)
+    # @param range [String, nil] Quick time range (e.g., "30min", "1day", "3days", "7days"). If provided, calculates from/to automatically.
+    # @return [Array<Hash>] Array of endpoint hashes
+    def list_endpoints(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}/endpoints")
       uri.query = build_query_string(from: from, to: to)
-      make_request(uri)
-    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
-    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["results"] || []
     end
 
     # Get metric data for a specific endpoint
@@ -91,12 +143,22 @@ 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
-    def get_endpoint_metrics(app_id, endpoint_id, metric_type, from: nil, to: nil)
-      encoded_endpoint_id = URI.encode_www_form_component(endpoint_id)
-      uri = URI("#{@api_base}/apps/#{app_id}/endpoints/#{encoded_endpoint_id}/metrics/#{metric_type}")
+    # @param range [String, nil] Quick time range (e.g., "30min", "1day", "3days", "7days"). If provided, calculates from/to automatically.
+    # @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, range: nil)
+      if range
+        calculated = Helpers.calculate_range(range: range, to: to)
+        from = calculated[:from]
+        to = calculated[:to]
+      end
+
+      validate_metric_params(metric_type, from, to)
+      uri = URI(@api_base)
+      uri.path = File.join(uri.path, "apps", app_id.to_s, "endpoints", 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 +167,39 @@ 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
-    def list_endpoint_traces(app_id, endpoint_id, from: nil, to: nil)
-      encoded_endpoint_id = URI.encode_www_form_component(endpoint_id)
-      uri = URI("#{@api_base}/apps/#{app_id}/endpoints/#{encoded_endpoint_id}/traces")
+    # @param range [String, nil] Quick time range (e.g., "30min", "1day", "3days", "7days"). If provided, calculates from/to automatically.
+    # @return [Array<Hash>] Array of trace hashes
+    def list_endpoint_traces(app_id, endpoint_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, "endpoints", 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 +208,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 +260,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 +327,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 +340,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 +394,92 @@ 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)
+
+      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
+
+    # @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)
+      begin
+        data = JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise APIError.new("Invalid JSON response: #{response.body}", status_code: response.code.to_i)
+      end
 
       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
     #
@@ -13,14 +14,10 @@ module ScoutApmMcp
     # @return [String] API key
     # @raise [RuntimeError] if API key cannot be found
     def self.get_api_key(api_key: nil, op_vault: nil, op_item: nil, op_field: "API_KEY")
-      # Use provided API key if available
       return api_key if api_key && !api_key.empty?
 
-      # Check environment variable (may have been set by opdotenv loaded early in server startup)
       api_key = ENV["API_KEY"] || ENV["SCOUT_APM_API_KEY"]
       return api_key if api_key && !api_key.empty?
-
-      # Try direct 1Password CLI as fallback (opdotenv was already tried in server startup)
       op_env_entry_path = ENV["OP_ENV_ENTRY_PATH"]
       if op_env_entry_path && !op_env_entry_path.empty?
         begin
@@ -54,7 +51,6 @@ module ScoutApmMcp
           api_key = `op read "op://#{op_vault}/#{op_item}/#{op_field}" 2>/dev/null`.strip
           return api_key if api_key && !api_key.empty?
         rescue
-          # Silently fail
         end
       end
 
@@ -134,7 +130,6 @@ module ScoutApmMcp
     # @return [String] Decoded endpoint ID
     def self.decode_endpoint_id(endpoint_id)
       decoded = Base64.urlsafe_decode64(endpoint_id)
-      # Check if decoded result is valid UTF-8
       if decoded.force_encoding(Encoding::UTF_8).valid_encoding?
         decoded.force_encoding(Encoding::UTF_8)
       else
@@ -151,5 +146,107 @@ 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
+
+    # Parse a time range string into seconds
+    #
+    # Supports formats like: "30min", "60min", "3hrs", "6hrs", "12hrs", "1day", "3days", "7days"
+    # Case-insensitive, supports singular and plural forms
+    #
+    # @param range_str [String] Time range string (e.g., "30min", "1day", "7days")
+    # @return [Integer] Duration in seconds
+    # @raise [ArgumentError] If the range string format is invalid
+    def self.parse_range(range_str)
+      return nil if range_str.nil? || range_str.empty?
+
+      # Normalize: lowercase, remove spaces, handle singular/plural
+      normalized = range_str.downcase.strip.gsub(/\s+/, "")
+
+      # Match pattern: number followed by unit
+      match = normalized.match(/\A(\d+)(min|mins?|hr|hrs?|hour|hours|day|days)\z/)
+      unless match
+        valid_ranges = %w[30min 60min 3hrs 6hrs 12hrs 1day 3days 7days]
+        raise ArgumentError, "Invalid range format: #{range_str}. Valid formats: #{valid_ranges.join(", ")}"
+      end
+
+      value = match[1].to_i
+      unit = match[2]
+
+      case unit
+      when /^min/
+        value * 60
+      when /^hr/, /^hour/
+        value * 60 * 60
+      when /^day/
+        value * 24 * 60 * 60
+      else
+        raise ArgumentError, "Unknown time unit: #{unit}"
+      end
+    end
+
+    # Calculate from/to times based on a range string
+    #
+    # @param range [String, nil] Time range string (e.g., "30min", "1day", "3days")
+    # @param to [String, nil] End time in ISO 8601 format (defaults to now if not provided)
+    # @return [Hash] Hash with :from and :to as ISO 8601 strings
+    def self.calculate_range(range:, to: nil)
+      return {from: nil, to: to} if range.nil? || range.empty?
+
+      end_time = to ? parse_time(to) : Time.now.utc
+      duration_seconds = parse_range(range)
+      start_time = end_time - duration_seconds
+
+      {
+        from: format_time(start_time),
+        to: format_time(end_time)
+      }
+    end
   end
 end

data/lib/scout_apm_mcp/server.rb

@@ -133,7 +133,6 @@ module ScoutApmMcp
       server.register_tool(ListMetricsTool)
       server.register_tool(GetMetricTool)
       server.register_tool(ListEndpointsTool)
-      server.register_tool(FetchEndpointTool)
       server.register_tool(GetEndpointMetricsTool)
       server.register_tool(ListEndpointTracesTool)
       server.register_tool(FetchTraceTool)
@@ -166,14 +165,27 @@ module ScoutApmMcp
 
     # Applications Tools
     class ListAppsTool < BaseTool
-      description "List all applications accessible with the provided API key"
+      description <<~DESC
+        List all applications accessible with the provided API key.
+
+        Returns an array of applications with details like name, ID, and last reported time.
+        Use the app_id from the results to make subsequent API calls.
+
+        Optional filtering:
+        - active_since: Only return apps that have reported data since this time (ISO 8601 format)
+        - Default behavior: Returns all apps (no filtering by default, but API may filter to last 30 days)
+
+        Example:
+        - List all apps: call without parameters
+        - List apps active in last 7 days: provide active_since="2025-01-08T00:00:00Z"
+      DESC
 
       arguments do
-        # No arguments required
+        optional(:active_since).maybe(:string).description("ISO 8601 datetime string to filter apps active since that time (e.g., 2025-01-08T00:00:00Z)")
       end
 
-      def call
-        get_client.list_apps
+      def call(active_since: nil)
+        get_client.list_apps(active_since: active_since)
       end
     end
 
@@ -203,80 +215,151 @@ module ScoutApmMcp
     end
 
     class GetMetricTool < BaseTool
-      description "Get time-series data for a specific metric type"
+      description <<~DESC
+        Get time-series data for a specific metric type.
+
+        Available metric types:
+        - apdex: Application Performance Index (0-1, higher is better)
+        - response_time: Average response time in milliseconds
+        - response_time_95th: 95th percentile response time in milliseconds
+        - errors: Number of errors
+        - throughput: Requests per second
+        - queue_time: Time spent in queue in milliseconds
+
+        You can specify time ranges using:
+        1. Quick range templates: range="30min", "1day", "3days", "7days", etc.
+        2. Explicit times: from and to with ISO 8601 timestamps
+
+        Examples:
+        - Get response time for last hour: metric_type="response_time", range="1hr"
+        - Get error count for last day: metric_type="errors", range="1day"
+        - Get metrics for specific range: metric_type="apdex", from="2025-01-15T10:00:00Z", to="2025-01-15T12:00:00Z"
+      DESC
 
       arguments do
         required(:app_id).filled(:integer).description("ScoutAPM application ID")
         required(:metric_type).filled(:string).description("Metric type: apdex, response_time, response_time_95th, errors, throughput, queue_time")
-        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z)")
-        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z)")
+        optional(:range).maybe(:string).description("Quick time range template: 30min, 60min, 3hrs, 6hrs, 12hrs, 1day, 3days, 7days. If provided, calculates from/to automatically.")
+        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z). Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z). Used as end point for range if range is provided.")
       end
 
-      def call(app_id:, metric_type:, from: nil, to: nil)
-        get_client.get_metric(app_id, metric_type, from: from, to: to)
+      def call(app_id:, metric_type:, range: nil, from: nil, to: nil)
+        get_client.get_metric(app_id, metric_type, from: from, to: to, range: range)
       end
     end
 
     # Endpoints Tools
     class ListEndpointsTool < BaseTool
-      description "List all endpoints for an application"
+      description <<~DESC
+        List all endpoints for an application.
+
+        The API requires timeframe parameters. You can specify time ranges in two ways:
+        1. Quick range templates: Use the 'range' parameter (e.g., "30min", "1day", "3days", "7days")
+        2. Explicit times: Use 'from' and 'to' parameters with ISO 8601 timestamps
+
+        If neither from/to nor range are provided, defaults to the last 7 days.
+
+        Quick range templates (case-insensitive):
+        - "30min" or "30mins" - Last 30 minutes
+        - "60min" or "60mins" or "1hr" or "1hour" - Last 60 minutes
+        - "3hrs" or "3hours" - Last 3 hours
+        - "6hrs" or "6hours" - Last 6 hours
+        - "12hrs" or "12hours" - Last 12 hours
+        - "1day" or "1days" - Last 24 hours
+        - "3days" - Last 3 days
+        - "7days" - Last 7 days (default)
+
+        Examples:
+        - List endpoints for last 30 minutes: range="30min"
+        - List endpoints for last day: range="1day"
+        - List endpoints for a specific range: from="2025-01-15T10:00:00Z", to="2025-01-15T12:00:00Z"
+        - List endpoints from a specific time to now: from="2025-01-15T10:00:00Z"
+        - List endpoints for 1 day ending at specific time: range="1day", to="2025-01-15T12:00:00Z"
+      DESC
 
       arguments do
         required(:app_id).filled(:integer).description("ScoutAPM application ID")
-        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z)")
-        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z)")
+        optional(:range).maybe(:string).description("Quick time range template: 30min, 60min, 3hrs, 6hrs, 12hrs, 1day, 3days, 7days. If provided, calculates from/to automatically.")
+        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z). Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z). Used as end point for range if range is provided, otherwise defaults to now.")
       end
 
-      def call(app_id:, from: nil, to: nil)
-        get_client.list_endpoints(app_id, from: from, to: to)
+      def call(app_id:, range: nil, from: nil, to: nil)
+        get_client.list_endpoints(app_id, from: from, to: to, range: range)
       end
     end
 
-    class FetchEndpointTool < BaseTool
-      description "Fetch endpoint details from ScoutAPM API"
+    class GetEndpointMetricsTool < BaseTool
+      description <<~DESC
+        Get metric data for a specific endpoint.
 
-      arguments do
-        required(:app_id).filled(:integer).description("ScoutAPM application ID")
-        required(:endpoint_id).filled(:string).description("Endpoint ID (base64 URL-encoded)")
-      end
+        Available metric types:
+        - apdex: Application Performance Index (0-1, higher is better)
+        - response_time: Average response time in milliseconds
+        - response_time_95th: 95th percentile response time in milliseconds
+        - errors: Number of errors
+        - throughput: Requests per second
+        - queue_time: Time spent in queue in milliseconds
 
-      def call(app_id:, endpoint_id:)
-        client = get_client
-        {
-          endpoint: client.get_endpoint(app_id, endpoint_id),
-          decoded_endpoint: Helpers.decode_endpoint_id(endpoint_id)
-        }
-      end
-    end
+        You can specify time ranges using:
+        1. Quick range templates: range="30min", "1day", "3days", "7days", etc.
+        2. Explicit times: from and to with ISO 8601 timestamps
 
-    class GetEndpointMetricsTool < BaseTool
-      description "Get metric data for a specific endpoint"
+        Returns time-series data points for the specified metric type.
+
+        Examples:
+        - Get response time for last hour: metric_type="response_time", range="1hr"
+        - Get error count for last day: metric_type="errors", range="1day"
+        - Get metrics for specific range: metric_type="apdex", from="2025-01-15T10:00:00Z", to="2025-01-15T12:00:00Z"
+      DESC
 
       arguments do
         required(:app_id).filled(:integer).description("ScoutAPM application ID")
-        required(:endpoint_id).filled(:string).description("Endpoint ID (base64 URL-encoded)")
+        required(:endpoint_id).filled(:string).description("Endpoint ID (base64 URL-encoded). Extract from ScoutAPM URLs or use ParseScoutURLTool.")
         required(:metric_type).filled(:string).description("Metric type: apdex, response_time, response_time_95th, errors, throughput, queue_time")
-        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z)")
-        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z)")
+        optional(:range).maybe(:string).description("Quick time range template: 30min, 60min, 3hrs, 6hrs, 12hrs, 1day, 3days, 7days. If provided, calculates from/to automatically.")
+        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z). Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z). Used as end point for range if range is provided.")
       end
 
-      def call(app_id:, endpoint_id:, metric_type:, from: nil, to: nil)
-        get_client.get_endpoint_metrics(app_id, endpoint_id, metric_type, from: from, to: to)
+      def call(app_id:, endpoint_id:, metric_type:, range: nil, from: nil, to: nil)
+        get_client.get_endpoint_metrics(app_id, endpoint_id, metric_type, from: from, to: to, range: range)
       end
     end
 
     class ListEndpointTracesTool < BaseTool
-      description "List traces for a specific endpoint (max 100, within 7 days)"
+      description <<~DESC
+        List traces for a specific endpoint (max 100, within 7 days).
+
+        Traces are individual request executions that can be analyzed for performance issues.
+        Returns up to 100 traces for the specified endpoint within the last 7 days.
+
+        You can specify time ranges using:
+        1. Quick range templates: range="30min", "1day", "3days", "7days", etc.
+        2. Explicit times: from and to with ISO 8601 timestamps
+
+        Time range constraints:
+        - If from is provided, it must be within the last 7 days
+        - Maximum 100 traces returned per request
+        - Use the trace_id from results with FetchTraceTool for detailed analysis
+
+        Examples:
+        - List traces from last hour: range="1hr"
+        - List traces from last day: range="1day"
+        - List traces for specific range: from="2025-01-15T10:00:00Z", to="2025-01-15T12:00:00Z"
+      DESC
 
       arguments do
         required(:app_id).filled(:integer).description("ScoutAPM application ID")
-        required(:endpoint_id).filled(:string).description("Endpoint ID (base64 URL-encoded)")
-        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z)")
-        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z)")
+        required(:endpoint_id).filled(:string).description("Endpoint ID (base64 URL-encoded). Extract from ScoutAPM URLs or use ParseScoutURLTool.")
+        optional(:range).maybe(:string).description("Quick time range template: 30min, 60min, 3hrs, 6hrs, 12hrs, 1day, 3days, 7days. If provided, calculates from/to automatically.")
+        optional(:from).maybe(:string).description("Start time in ISO 8601 format (e.g., 2025-11-17T15:25:35Z). Must be within last 7 days. Ignored if range is provided.")
+        optional(:to).maybe(:string).description("End time in ISO 8601 format (e.g., 2025-11-18T15:25:35Z). Used as end point for range if range is provided.")
       end
 
-      def call(app_id:, endpoint_id:, from: nil, to: nil)
-        get_client.list_endpoint_traces(app_id, endpoint_id, from: from, to: to)
+      def call(app_id:, endpoint_id:, range: nil, from: nil, to: nil)
+        get_client.list_endpoint_traces(app_id, endpoint_id, from: from, to: to, range: range)
       end
     end
 
@@ -432,10 +515,28 @@ module ScoutApmMcp
 
     # Utility Tools
     class ParseScoutURLTool < BaseTool
-      description "Parse a ScoutAPM URL and extract resource information (app_id, endpoint_id, trace_id, etc.)"
+      description <<~DESC
+        Parse a ScoutAPM URL and extract resource information (app_id, endpoint_id, trace_id, etc.).
+
+        This tool extracts structured information from ScoutAPM URLs without making API calls.
+        Useful for extracting IDs before making other API requests.
+
+        Returns a hash with:
+        - url_type: :endpoint, :trace, :error_group, :insight, :app, or :unknown
+        - app_id: Application ID (integer)
+        - endpoint_id: Base64 URL-encoded endpoint ID (if present)
+        - trace_id: Trace ID (if present)
+        - error_id: Error group ID (if present)
+        - insight_type: Insight type (if present)
+        - decoded_endpoint: Human-readable endpoint path (if endpoint_id present)
+
+        Example:
+        - Input: "https://scoutapm.com/apps/123/endpoints/ABC123.../trace/456"
+        - Output: {url_type: :trace, app_id: 123, endpoint_id: "ABC123...", trace_id: 456, decoded_endpoint: "Controller/Action"}
+      DESC
 
       arguments do
-        required(:url).filled(:string).description("Full ScoutAPM URL (e.g., https://scoutapm.com/apps/123/endpoints/.../trace/456)")
+        required(:url).filled(:string).description("Full ScoutAPM URL")
       end
 
       def call(url:)
@@ -444,10 +545,27 @@ module ScoutApmMcp
     end
 
     class FetchScoutURLTool < BaseTool
-      description "Fetch data from a ScoutAPM URL by automatically detecting the resource type and fetching the appropriate data"
+      description <<~DESC
+        Fetch data from a ScoutAPM URL by automatically detecting the resource type and fetching the appropriate data.
+
+        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)
+        - Trace URLs: /apps/{app_id}/endpoints/{endpoint_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}
+
+        Examples:
+        - https://scoutapm.com/apps/123/endpoints/ABC123... (endpoint)
+        - 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.
+      DESC
 
       arguments do
-        required(:url).filled(:string).description("Full ScoutAPM URL (e.g., https://scoutapm.com/apps/123/endpoints/.../trace/456)")
+        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)")
       end
 
@@ -468,20 +586,37 @@ 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
+                endpoints = client.list_endpoints(parsed[:app_id], range: "7days")
+                endpoint_data = endpoints.find { |ep| Helpers.get_endpoint_id(ep) == parsed[:endpoint_id] }
+
+                if endpoint_data
+                  result[:data][:endpoint] = endpoint_data
+                else
+                  result[:data][:endpoint_error] = "Endpoint not found in the last 7 days"
+                end
+                result[:data][:decoded_endpoint] = parsed[:decoded_endpoint]
+              rescue => e
+                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]
-            }
+            endpoints = client.list_endpoints(parsed[:app_id], range: "7days")
+            endpoint_data = endpoints.find { |ep| Helpers.get_endpoint_id(ep) == parsed[:endpoint_id] }
+
+            if endpoint_data
+              result[:data] = {
+                endpoint: endpoint_data,
+                decoded_endpoint: parsed[:decoded_endpoint]
+              }
+            else
+              raise "Endpoint not found in the last 7 days. Try using ListEndpointsTool with a longer time range."
+            end
           else
             raise "Invalid endpoint URL: missing app_id or endpoint_id"
           end

data/lib/scout_apm_mcp/version.rb

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

data/sig/scout_apm_mcp.rbs

@@ -16,7 +16,6 @@ module ScoutApmMcp
     def list_metrics: (Integer app_id) -> Hash[String, untyped]
     def get_metric: (Integer app_id, String metric_type, ?from: String?, ?to: String?) -> Hash[String, untyped]
     def list_endpoints: (Integer app_id, ?from: String?, ?to: String?) -> Hash[String, untyped]
-    def get_endpoint: (Integer app_id, String endpoint_id) -> 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 fetch_trace: (Integer app_id, Integer trace_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.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Andrei Makarov
@@ -47,22 +47,22 @@ dependencies:
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
-    - - ">="
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 2.2.0
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: opdotenv
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +175,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.52'
+- !ruby/object:Gem::Dependency
+  name: standard-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: standard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -233,6 +275,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