scout_apm_mcp 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24de549e2d8e310ce563f8a9c380f642aabdd528259785ed17ae062c8b8e59aa
-  data.tar.gz: 5a9c147401b3136be74f5197ec757b4f1d357c1ad5483f12c0813315f6d6d9e8
+  metadata.gz: ce6703433e4f11c4cf2769a636135ed7a429707a84a09e196e7151b43cb368b2
+  data.tar.gz: 2ddf028b1023a364f4eb5d6afc8f1693549ce4ace041f7d12487719f4513ef3d
 SHA512:
-  metadata.gz: 509eeae8882791a33706ceda9a71a4095ef6e99abda4e7401082435d0d6e055882ebced248e176c74154bfa28db09eb965e49c5df88e8fa3c581f0f1e9dac782
-  data.tar.gz: 33143a776cb940411007c14be1a34691a5569275fa8c3c507b2eca92846c8585bcfa438906b135dd31f986c6fbbd0ff7a98c7be74e27491242aa9f751b410202
+  metadata.gz: 1f1ff860d8e236a1338d4f1ceb62a0a6620ff667dc266cc528a7ffd8eceaaf5f4a874612fcc7e8fe45b64a83c446d42af6eca639d13b4ee5cf71b76ce7e7b6b6
+  data.tar.gz: 3cadb0d9852c1e661630c69148cfdb2d9c85076094e4672f5b0358448015ade8d13bc800c04a67c1b105ddf66b1ca842ac056c8e38b12b158c3c6290a289daa7

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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

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,6 +119,22 @@ 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
@@ -233,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

data/lib/scout_apm_mcp/client.rb

@@ -27,8 +27,12 @@ module ScoutApmMcp
 
     # @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
@@ -42,7 +46,6 @@ module ScoutApmMcp
       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|
@@ -84,8 +87,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
+    # @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)
+    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)
@@ -98,8 +108,27 @@ 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
+    # @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)
+    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)
@@ -107,18 +136,6 @@ module ScoutApmMcp
       response["results"] || []
     end
 
-    # Get endpoint details
-    #
-    # @param app_id [Integer] ScoutAPM application ID
-    # @param endpoint_id [String] Endpoint ID (base64 URL-encoded)
-    # @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}")
-      response = make_request(uri)
-      response.dig("results", "endpoint") || response["results"] || {}
-    end
-
     # Get metric data for a specific endpoint
     #
     # @param app_id [Integer] ScoutAPM application ID
@@ -126,11 +143,18 @@ 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
+    # @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)
+    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)
-      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 = 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)
       response = make_request(uri)
       series = response.dig("results", "series") || {}
@@ -143,19 +167,25 @@ 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
+    # @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)
+    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
-        # 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 = 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)
       response = make_request(uri)
       response.dig("results", "traces") || []
@@ -370,7 +400,6 @@ module ScoutApmMcp
       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"]
@@ -391,21 +420,17 @@ module ScoutApmMcp
       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
         data

data/lib/scout_apm_mcp/helpers.rb

@@ -14,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
@@ -55,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
 
@@ -135,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
@@ -200,5 +194,59 @@ module ScoutApmMcp
         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,10 +165,23 @@ module ScoutApmMcp
 
     # Applications Tools
     class ListAppsTool < BaseTool
-      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."
+      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
-        optional(:active_since).maybe(:string).description("ISO 8601 datetime string to filter apps active since that time")
+        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(active_since: nil)
@@ -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
 
@@ -469,11 +587,16 @@ module ScoutApmMcp
 
             if include_endpoint && parsed[:endpoint_id]
               begin
-                endpoint_data = client.get_endpoint(parsed[:app_id], parsed[:endpoint_id])
-                result[:data][:endpoint] = endpoint_data
+                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
-                # 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
@@ -483,11 +606,17 @@ module ScoutApmMcp
           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.3"
+  VERSION = "0.1.4"
 end

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.3
+  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