scout_apm_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94c095f06ab792c7e66a4a3d7893a0476308730d1d346f661ba34d52be5b665b
+  data.tar.gz: c1823c4b464ab833663a3026ff3f1c1d90de4c6c3b832f57257ce1f495c161e3
+SHA512:
+  metadata.gz: adba47ba7ab8d8838e42c236afe334243425f38701da5467e78badd91195ed029dfe4f5c3b308903c67f118ef10778a5e14dbd4dd4f8feb9801a3778da4d20d0
+  data.tar.gz: 657457f4239d0531bf7cac76fcd15e5ac9416947fd24d9ce83e38a74c47d0583a41b8194ae526d915ab540c0a3fb56c50cb0c111a22e5f9a23197c725550031a

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# CHANGELOG
+
+## 0.1.0 (2025-11-20)
+
+- Initial release
+- ScoutAPM API client with full endpoint coverage (applications, metrics, endpoints, traces, errors, insights, OpenAPI)
+- MCP server integration for Cursor IDE with executable `bundle exec scout_apm_mcp`
+- Helper methods for API key management and URL parsing (`Helpers.get_api_key`, `Helpers.parse_scout_url`, `Helpers.decode_endpoint_id`)
+- Support for environment variables and 1Password integration (via optional `opdotenv` gem)
+- Complete RBS type signatures for all public APIs
+- Comprehensive test suite with RSpec
+- Requires Ruby 3.0 or higher
+- All dependencies use latest compatible versions with pessimistic versioning for security

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,322 @@
+# scout_apm_mcp
+
+[![Gem Version](https://badge.fury.io/rb/scout_apm_mcp.svg)](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.
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>
+
+## Requirements
+
+- **Ruby 3.1 or higher** (Ruby 3.0 and earlier are not supported)
+
+## Quick Start
+
+1. In scoutapm create API key under Organization settings: https://scoutapm.com/settings
+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)
+
+### Cursor IDE Configuration
+
+For Cursor IDE, create or update `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "scout-apm": {
+      "command": "bundle",
+      "args": ["exec", "scout_apm_mcp"],
+      "env": {
+        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "scout-apm": {
+      "command": "scout_apm_mcp",
+      "env": {
+        "OP_ENV_ENTRY_PATH": "op://Vault Name/Item Name"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop Configuration
+
+For Claude Desktop, edit the MCP configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "scout-apm": {
+      "command": "bundle",
+      "args": ["exec", "scout_apm_mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "scout-apm": {
+      "command": "scout_apm_mcp"
+    }
+  }
+}
+```
+
+**Note**: After updating the configuration, restart Claude Desktop for changes to take effect.
+
+### Security Best Practice
+
+Do not store API keys or tokens in MCP configuration files. Instead, use one of these methods:
+
+1. **1Password Integration**: Set `OP_ENV_ENTRY_PATH` environment variable (e.g., `op://Vault/Item`) to automatically load credentials via opdotenv
+2. **1Password CLI**: The gem will automatically fall back to 1Password CLI if opdotenv is not available
+3. **Environment Variables**: Set `API_KEY` or `SCOUT_APM_API_KEY` in your shell environment (not recommended for production - use secret vault for in-memory provisioning)
+
+The gem will automatically detect and use credentials from your environment or 1Password integration.
+
+### Testing with MCP Inspector
+
+You can test the MCP server using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tool:
+
+```bash
+# Set your 1Password entry path (or use API_KEY/SCOUT_APM_API_KEY)
+export OP_ENV_ENTRY_PATH="op://Vault/Scout APM"
+
+# Run the MCP inspector with the server
+npx @modelcontextprotocol/inspector bundle exec scout_apm_mcp
+```
+
+The inspector will:
+1. Start a proxy server and open a browser interface
+2. Connect to your MCP server via STDIO
+3. Allow you to test all available tools interactively
+4. Display request/response messages and any errors
+
+This is useful for:
+- Testing tool functionality before integrating with MCP clients
+- Debugging MCP protocol communication
+- Verifying API key configuration
+- Exploring available tools and their parameters
+
+### Running the MCP Server manually
+
+After installation, you can start the MCP server immediately:
+
+```bash
+# With bundler
+gem install scout_apm_mcp && bundle exec scout_apm_mcp
+
+# Or if installed globally
+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).
+
+## 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
+- **Comprehensive API Coverage**: Supports all ScoutAPM API endpoints (apps, metrics, endpoints, traces, errors, insights)
+
+## Basic Usage
+
+### API Client
+
+```ruby
+require "scout_apm_mcp"
+
+# Get API key (from environment or 1Password)
+api_key = ScoutApmMcp::Helpers.get_api_key
+
+# Create client
+client = ScoutApmMcp::Client.new(api_key: api_key)
+
+# List applications
+apps = client.list_apps
+
+# Get application details
+app = client.get_app(123)
+
+# List endpoints
+endpoints = client.list_endpoints(123)
+
+# Fetch trace
+trace = client.fetch_trace(123, 456)
+
+# Get metrics
+metrics = client.get_metric(123, "response_time", from: "2025-01-01T00:00:00Z", to: "2025-01-02T00:00:00Z")
+
+# List error groups
+errors = client.list_error_groups(123, from: "2025-01-01T00:00:00Z", to: "2025-01-02T00:00:00Z")
+
+# Get insights
+insights = client.get_all_insights(123, limit: 20)
+```
+
+### URL Parsing
+
+```ruby
+# Parse a ScoutAPM trace URL
+url = "https://scoutapm.com/apps/123/endpoints/.../trace/456"
+parsed = ScoutApmMcp::Helpers.parse_scout_url(url)
+# => { app_id: 123, endpoint_id: "...", trace_id: 456, decoded_endpoint: "...", query_params: {...} }
+```
+
+### API Key Management
+
+The gem supports multiple methods for API key retrieval (checked in order):
+
+1. **Direct parameter**: Pass `api_key:` when calling `Helpers.get_api_key`
+2. **Environment variable**: Set `API_KEY` or `SCOUT_APM_API_KEY`
+3. **1Password via OP_ENV_ENTRY_PATH**: Set `OP_ENV_ENTRY_PATH` environment variable (e.g., `op://Vault/Item`)
+4. **1Password via opdotenv**: Automatically loads from 1Password if `opdotenv` gem is available and `op_vault`/`op_item` are provided
+5. **1Password CLI**: Falls back to direct `op` CLI command
+
+```ruby
+# From environment variable (recommended: use in-memory vault or shell environment)
+# Set API_KEY or SCOUT_APM_API_KEY in your environment
+api_key = ScoutApmMcp::Helpers.get_api_key
+
+# From 1Password using OP_ENV_ENTRY_PATH (recommended for 1Password users)
+# Set OP_ENV_ENTRY_PATH in your environment (e.g., op://Vault/Item)
+ENV["OP_ENV_ENTRY_PATH"] = "op://YourVault/YourItem"
+api_key = ScoutApmMcp::Helpers.get_api_key
+
+# From 1Password with explicit vault/item (requires opdotenv gem or op CLI)
+api_key = ScoutApmMcp::Helpers.get_api_key(
+  op_vault: "YourVault",
+  op_item: "Your ScoutAPM API",
+  op_field: "API_KEY"
+)
+```
+
+**Security Note**: Never hardcode API keys in your code or configuration files. Always use environment variables, in-memory vaults, or secure credential management systems like 1Password.
+
+## API Methods
+
+### Applications
+
+- `list_apps` - List all applications
+- `get_app(app_id)` - Get application details
+
+### Metrics
+
+- `list_metrics(app_id)` - List available metric types
+- `get_metric(app_id, metric_type, from:, to:)` - Get time-series metric data
+
+### 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
+
+### Traces
+
+- `fetch_trace(app_id, trace_id)` - Fetch detailed trace information
+
+### Errors
+
+- `list_error_groups(app_id, from:, to:, endpoint:)` - List error groups
+- `get_error_group(app_id, error_id)` - Get error group details
+- `get_error_group_errors(app_id, error_id)` - Get errors within a group
+
+### Insights
+
+- `get_all_insights(app_id, limit:)` - Get all insight types
+- `get_insight_by_type(app_id, insight_type, limit:)` - Get specific insight type
+- `get_insights_history(app_id, from:, to:, limit:, pagination_cursor:, pagination_direction:, pagination_page:)` - Get historical insights
+- `get_insights_history_by_type(app_id, insight_type, from:, to:, limit:, pagination_cursor:, pagination_direction:, pagination_page:)` - Get historical insights by type
+
+### OpenAPI Schema
+
+- `fetch_openapi_schema` - Fetch the ScoutAPM OpenAPI schema
+
+## MCP Server Integration
+
+This gem includes a ready-to-use MCP server that can be run directly:
+
+```bash
+# After installing the gem
+bundle exec scout_apm_mcp
+```
+
+Or if installed globally:
+
+```bash
+gem install scout_apm_mcp
+scout_apm_mcp
+```
+
+The server will communicate via STDIN/STDOUT using the MCP protocol. Configure it in your MCP client (e.g., Cursor IDE, Claude Desktop, or other MCP-enabled tools).
+
+## Error Handling
+
+The client raises exceptions for API errors:
+
+- `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
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run tests across multiple Ruby versions
+bundle exec appraisal install
+bundle exec appraisal rspec
+
+# Run linting
+bundle exec standardrb --fix
+
+# Validate RBS type signatures
+bundle exec rbs validate
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/amkisko/scout_apm_mcp.rb.
+
+Contribution policy:
+- New features are not necessarily added to the gem
+- Pull request should have test coverage for affected parts
+- Pull request should have changelog entry
+
+Review policy:
+- It might take up to 2 calendar weeks to review and merge critical fixes
+- It might take up to 6 calendar months to review and merge pull request
+- It might take up to 1 calendar year to review an issue
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.md).
+

data/bin/scout_apm_mcp

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Suppress all output to prevent breaking JSON parsing in MCP clients
+# STDOUT is used for MCP protocol communication (JSON-RPC), so we must not output anything
+# STDERR is also suppressed to prevent any error messages from breaking JSON parsing
+unless ENV["DEBUG"]
+  require "stringio"
+  # Redirect stderr to StringIO to suppress all error output
+  $stderr = StringIO.new
+  $stderr.set_encoding("UTF-8")
+end
+
+require "scout_apm_mcp"
+require "scout_apm_mcp/server"
+
+ScoutApmMcp::Server.start
+

data/lib/scout_apm_mcp/client.rb

@@ -0,0 +1,302 @@
+require "uri"
+require "net/http"
+require "json"
+require "base64"
+
+module ScoutApmMcp
+  # ScoutAPM API client for making authenticated requests to the ScoutAPM API
+  #
+  # @example
+  #   api_key = ScoutApmMcp::Helpers.get_api_key
+  #   client = ScoutApmMcp::Client.new(api_key: api_key)
+  #   apps = client.list_apps
+  #   trace = client.fetch_trace(123, 456)
+  class Client
+    API_BASE = "https://scoutapm.com/api/v0"
+
+    # @param api_key [String] ScoutAPM API key
+    # @param api_base [String] API base URL (default: https://scoutapm.com/api/v0)
+    def initialize(api_key:, api_base: API_BASE)
+      @api_key = api_key
+      @api_base = api_base
+    end
+
+    # List all applications accessible with the provided API key
+    #
+    # @return [Hash] API response containing applications list
+    def list_apps
+      uri = URI("#{@api_base}/apps")
+      make_request(uri)
+    end
+
+    # Get application details for a specific application
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @return [Hash] API response containing application details
+    def get_app(app_id)
+      uri = URI("#{@api_base}/apps/#{app_id}")
+      make_request(uri)
+    end
+
+    # List available metric types for an application
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @return [Hash] API response containing available metrics
+    def list_metrics(app_id)
+      uri = URI("#{@api_base}/apps/#{app_id}/metrics")
+      make_request(uri)
+    end
+
+    # Get time-series data for a specific metric type
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @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)
+      uri = URI("#{@api_base}/apps/#{app_id}/metrics/#{metric_type}")
+      uri.query = build_query_string(from: from, to: to)
+      make_request(uri)
+    end
+
+    # List all endpoints for an application
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @return [Hash] API response containing endpoints list
+    def list_endpoints(app_id, from: nil, to: nil)
+      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)
+    end
+
+    # Get metric data for a specific endpoint
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param endpoint_id [String] Endpoint ID (base64 URL-encoded)
+    # @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}")
+      uri.query = build_query_string(from: from, to: to)
+      make_request(uri)
+    end
+
+    # List traces for a specific endpoint (max 100, within 7 days)
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @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")
+      uri.query = build_query_string(from: from, to: to)
+      make_request(uri)
+    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
+    def fetch_trace(app_id, trace_id)
+      uri = URI("#{@api_base}/apps/#{app_id}/traces/#{trace_id}")
+      make_request(uri)
+    end
+
+    # List error groups for an application (max 100, within 30 days)
+    #
+    # @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 endpoint [String, nil] Base64 URL-encoded endpoint filter (optional)
+    # @return [Hash] API response containing error groups list
+    def list_error_groups(app_id, from: nil, to: nil, endpoint: nil)
+      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)
+    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
+    def get_error_group(app_id, error_id)
+      uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}")
+      make_request(uri)
+    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
+    def get_error_group_errors(app_id, error_id)
+      uri = URI("#{@api_base}/apps/#{app_id}/error_groups/#{error_id}/errors")
+      make_request(uri)
+    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
+    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)
+    end
+
+    # Get data for a specific insight type
+    #
+    # @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
+    def get_insight_by_type(app_id, insight_type, limit: nil)
+      uri = URI("#{@api_base}/apps/#{app_id}/insights/#{insight_type}")
+      uri.query = "limit=#{limit}" if limit
+      make_request(uri)
+    end
+
+    # Get historical insights data with cursor-based pagination
+    #
+    # @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 limit [Integer, nil] Maximum number of items per page (default: 10)
+    # @param pagination_cursor [Integer, nil] Cursor for pagination (insight ID)
+    # @param pagination_direction [String, nil] Pagination direction (forward, backward)
+    # @param pagination_page [Integer, nil] Page number for pagination (default: 1)
+    # @return [Hash] API response containing historical insights
+    def get_insights_history(app_id, from: nil, to: nil, limit: nil, pagination_cursor: nil, pagination_direction: nil, pagination_page: nil)
+      uri = URI("#{@api_base}/apps/#{app_id}/insights/history")
+      params = {}
+      params["from"] = from if from
+      params["to"] = to if to
+      params["limit"] = limit if limit
+      params["pagination_cursor"] = pagination_cursor if pagination_cursor
+      params["pagination_direction"] = pagination_direction if pagination_direction
+      params["pagination_page"] = pagination_page if pagination_page
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      make_request(uri)
+    end
+
+    # Get historical insights data filtered by insight type with cursor-based pagination
+    #
+    # @param app_id [Integer] ScoutAPM application ID
+    # @param insight_type [String] Insight type (n_plus_one, memory_bloat, slow_query)
+    # @param from [String, nil] Start time in ISO 8601 format
+    # @param to [String, nil] End time in ISO 8601 format
+    # @param limit [Integer, nil] Maximum number of items per page (default: 10)
+    # @param pagination_cursor [Integer, nil] Cursor for pagination (insight ID)
+    # @param pagination_direction [String, nil] Pagination direction (forward, backward)
+    # @param pagination_page [Integer, nil] Page number for pagination (default: 1)
+    # @return [Hash] API response containing historical insights
+    def get_insights_history_by_type(app_id, insight_type, from: nil, to: nil, limit: nil, pagination_cursor: nil, pagination_direction: nil, pagination_page: nil)
+      uri = URI("#{@api_base}/apps/#{app_id}/insights/history/#{insight_type}")
+      params = {}
+      params["from"] = from if from
+      params["to"] = to if to
+      params["limit"] = limit if limit
+      params["pagination_cursor"] = pagination_cursor if pagination_cursor
+      params["pagination_direction"] = pagination_direction if pagination_direction
+      params["pagination_page"] = pagination_page if pagination_page
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      make_request(uri)
+    end
+
+    # Fetch the ScoutAPM OpenAPI schema
+    #
+    # @return [Hash] Hash containing :content, :content_type, and :status
+    def fetch_openapi_schema
+      uri = URI("https://scoutapm.com/api/v0/openapi.yaml")
+      http = build_http_client(uri)
+
+      request = Net::HTTP::Get.new(uri)
+      request["X-SCOUT-API"] = @api_key
+      request["Accept"] = "application/x-yaml, application/yaml, text/yaml, */*"
+
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        {
+          content: response.body,
+          content_type: response.content_type,
+          status: response.code.to_i
+        }
+      when Net::HTTPUnauthorized
+        raise "Authentication failed. Check your API key."
+      else
+        raise "API request failed: #{response.code} #{response.message}"
+      end
+    end
+
+    private
+
+    # Build HTTP client
+    #
+    # @param uri [URI] URI object for the request
+    # @return [Net::HTTP] Configured HTTP client
+    def build_http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 10
+      http.open_timeout = 10
+      http
+    end
+
+    def build_query_string(from: nil, to: nil)
+      params = {}
+      params["from"] = from if from
+      params["to"] = to if to
+      return nil if params.empty?
+      URI.encode_www_form(params)
+    end
+
+    def make_request(uri)
+      http = build_http_client(uri)
+
+      request = Net::HTTP::Get.new(uri)
+      request["X-SCOUT-API"] = @api_key
+      request["Accept"] = "application/json"
+
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPUnauthorized
+        raise "Authentication failed. Check your API key. Response: #{response.body}"
+      when Net::HTTPNotFound
+        raise "Resource not found. Response: #{response.body}"
+      else
+        raise "API request failed: #{response.code} #{response.message}\n#{response.body}"
+      end
+    end
+  end
+end