@last9/mcp-server 0.1.13 → 0.1.15

package/README.md

@@ -28,7 +28,7 @@ IDEs. Implements the following MCP
 
 **Prometheus/PromQL Tools:**
 
-- `promptheus_range_query`: Execute PromQL range queries for metrics data.
+- `prometheus_range_query`: Execute PromQL range queries for metrics data.
 - `prometheus_instant_query`: Execute PromQL instant queries for metrics data.
 - `prometheus_label_values`: Get label values for PromQL queries.
 - `prometheus_labels`: Get available labels for PromQL queries.
@@ -41,10 +41,16 @@ IDEs. Implements the following MCP
 - `add_drop_rule`: Create a drop rule for logs at
   [Last9 Control Plane](https://last9.io/control-plane)
 - `get_service_logs`: Get raw log entries for a specific service over a time range. Can apply filters on severity and body.
+- `get_log_attributes`: Get available log attributes (labels) for a specified time window.
 
 **Traces Management:**
 
 - `get_service_traces`: Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes.
+- `get_trace_attributes`: Get available trace attributes (series) for a specified time window.
+
+**Change Events:**
+
+- `get_change_events`: Get change events from the last9_change_events prometheus metric over a given time range.
 
 **Alert Management:**
 
@@ -123,7 +129,7 @@ Parameters:
 - `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
 - `env` (string, optional): Environment to filter by. Defaults to 'prod'.
 
-### promptheus_range_query
+### prometheus_range_query
 
 Perform a Prometheus range query to get metrics data over a specified time range. Recommended to check available labels first using `prometheus_labels` tool.
 
@@ -268,6 +274,22 @@ Examples:
 - service_name="api" + severity_filters=["error"] + body_filters=["timeout"] → finds error logs containing "timeout"
 - service_name="web" + body_filters=["timeout", "failed", "error 500"] → finds logs containing any of these patterns
 
+### get_log_attributes
+
+Get available log attributes (labels) for a specified time window. This tool retrieves all attribute names that exist in logs during the specified time range, which can be used for filtering and querying logs.
+
+Parameters:
+
+- `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
+- `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
+
+Returns:
+- List of log attributes grouped into two categories:
+  - Log Attributes: Standard log fields like service, severity, body, level, etc.
+  - Resource Attributes: Resource-related fields prefixed with "resource_" like resource_k8s.pod.name, resource_service.name, etc.
+
 ### get_service_traces
 
 Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes. This tool retrieves distributed tracing data for debugging performance issues, understanding request flows, and analyzing service interactions.
@@ -294,11 +316,59 @@ Examples:
 - service_name="api" + span_kind=["server"] + status_code=["error"] → finds failed server-side traces
 - service_name="payment" + span_name="process_payment" + lookback_minutes=30 → finds payment processing traces from last 30 minutes
 
+### get_trace_attributes
+
+Get available trace attributes (series) for a specified time window. This tool retrieves all attribute names that exist in traces during the specified time range, which can be used for filtering and querying traces.
+
+Parameters:
+
+- `lookback_minutes` (integer, optional): Number of minutes to look back from now for the time window. Default: 15. Examples: 15, 30, 60.
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
+- `region` (string, optional): AWS region to query. Leave empty to use default from configuration. Examples: ap-south-1, us-east-1, eu-west-1.
+
+Returns:
+- An alphabetically sorted list of all available trace attributes (e.g., http.method, http.status_code, db.name, resource_service.name, duration, etc.)
+
+### get_change_events
+
+Get change events from the last9_change_events prometheus metric over a given time range. Returns change events that occurred in the specified time window, including deployments, configuration changes, and other system modifications.
+
+Parameters:
+
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
+- `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
+- `service` (string, optional): Name of the service to filter change events for.
+- `environment` (string, optional): Environment to filter by.
+- `event_name` (string, optional): Name of the change event to filter by (use available_event_names to see valid values).
+
+Returns:
+- `available_event_names`: List of all available event types that can be used for filtering
+- `change_events`: Array of timeseries data with metric labels and timestamp-value pairs
+- `count`: Total number of change events returned
+- `time_range`: Start and end time of the query window
+
+Each change event includes:
+- `metric`: Map of metric labels (service_name, env, event_type, message, etc.)
+- `values`: Array of timestamp-value pairs representing the timeseries data
+
+Common event types include: deployment, config_change, rollback, scale_up/scale_down, restart, upgrade/downgrade, maintenance, backup/restore, health_check, certificate, database.
+
+Best practices:
+1. First call without event_name to get available_event_names
+2. Use exact event name from available_event_names for the event_name parameter
+3. Combine with other filters (service, environment, time) for precise results
+
 ## Installation
 
-You can install the Last9 Observability MCP server using either:
+You can install and run the Last9 Observability MCP server in several ways:
+
+### Local Installation
 
-### Homebrew
+For local development and traditional STDIO usage:
+
+#### Homebrew
 
 ```bash
 # Add the Last9 tap
@@ -308,7 +378,7 @@ brew tap last9/tap
 brew install last9-mcp
 ```
 
-### NPM
+#### NPM
 
 ```bash
 # Install globally
@@ -332,6 +402,8 @@ The Last9 MCP server requires the following environment variables:
   for accessing control plane APIs from
   [API Access](https://app.last9.io/settings/api-access)
 
+## Usage
+
 ## Usage with Claude Desktop
 
 Configure the Claude app to use the MCP server:

package/dist/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2024-present Last9
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/dist/README.md

@@ -18,6 +18,7 @@ IDEs. Implements the following MCP
 [tools](https://modelcontextprotocol.io/docs/concepts/tools):
 
 **Observability & APM Tools:**
+
 - `get_exceptions`: Get the list of exceptions.
 - `get_service_summary`: Get service summary with throughput, error rate, and response time.
 - `get_service_environments`: Get available environments for services.
@@ -26,19 +27,27 @@ IDEs. Implements the following MCP
 - `get_service_dependency_graph`: Get service dependency graph showing incoming/outgoing dependencies.
 
 **Prometheus/PromQL Tools:**
+
 - `promptheus_range_query`: Execute PromQL range queries for metrics data.
 - `prometheus_instant_query`: Execute PromQL instant queries for metrics data.
 - `prometheus_label_values`: Get label values for PromQL queries.
 - `prometheus_labels`: Get available labels for PromQL queries.
 
 **Logs Management:**
+
 - `get_logs`: Get logs filtered by service name and/or severity level.
 - `get_drop_rules`: Get drop rules for logs that determine what logs get
   filtered out at [Last9 Control Plane](https://last9.io/control-plane)
 - `add_drop_rule`: Create a drop rule for logs at
   [Last9 Control Plane](https://last9.io/control-plane)
+- `get_service_logs`: Get raw log entries for a specific service over a time range. Can apply filters on severity and body.
+
+**Traces Management:**
+
+- `get_service_traces`: Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes.
 
 **Alert Management:**
+
 - `get_alert_config`: Get alert configurations (alert rules) from Last9.
 - `get_alerts`: Get currently active alerts from Last9 monitoring system.
 
@@ -156,20 +165,19 @@ Parameters:
 
 ### get_logs
 
-Gets logs filtered by optional service name and/or severity level within a
-specified time range.
+Gets logs filtered by service name and/or severity level within a specified time range. This tool now uses the advanced v2 logs API with physical index optimization for better performance.
+
+**Note**: This tool now requires a `service_name` parameter and internally uses the same advanced infrastructure as `get_service_logs`.
 
 Parameters:
 
-- `service` (string, optional): Name of the service to get logs for.
-- `severity` (string, optional): Severity of the logs to get.
-- `lookback_minutes` (integer, recommended): Number of minutes to look back from
-  now. Default: 60. Examples: 60, 30, 15.
-- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD
-  HH:MM:SS). Leave empty to use lookback_minutes.
-- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD
-  HH:MM:SS). Leave empty to default to current time.
+- `service_name` (string, required): Name of the service to get logs for.
+- `severity` (string, optional): Severity of the logs to get (automatically converted to severity_filters format).
+- `lookback_minutes` (integer, recommended): Number of minutes to look back from now. Default: 60. Examples: 60, 30, 15.
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to use lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
 - `limit` (integer, optional): Maximum number of logs to return. Default: 20.
+- `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
 
 ### get_drop_rules
 
@@ -237,13 +245,62 @@ Returns information about:
 - Metric degradation information
 - Group labels and annotations for each instance
 
+### get_service_logs
+
+Get raw log entries for a specific service over a time range. This tool retrieves actual log entries including log messages, timestamps, severity levels, and other metadata. Useful for debugging issues, monitoring service behavior, and analyzing specific log patterns.
+
+Parameters:
+
+- `service_name` (string, required): Name of the service to get logs for.
+- `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
+- `limit` (integer, optional): Maximum number of log entries to return. Default: 20.
+- `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
+- `severity_filters` (array, optional): Array of severity patterns to filter logs (e.g., ["error", "warn"]). Uses OR logic.
+- `body_filters` (array, optional): Array of message content patterns to filter logs (e.g., ["timeout", "failed"]). Uses OR logic.
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
+
+Filtering behavior:
+- Multiple filter types are combined with AND logic (service AND severity AND body)
+- Each filter array uses OR logic (matches any pattern in the array)
+
+Examples:
+- service_name="api" + severity_filters=["error"] + body_filters=["timeout"] → finds error logs containing "timeout"
+- service_name="web" + body_filters=["timeout", "failed", "error 500"] → finds logs containing any of these patterns
+
+### get_service_traces
+
+Query traces for a specific service with filtering options for span kinds, status codes, and other trace attributes. This tool retrieves distributed tracing data for debugging performance issues, understanding request flows, and analyzing service interactions.
+
+Parameters:
+
+- `service_name` (string, required): Name of the service to get traces for.
+- `lookback_minutes` (integer, optional): Number of minutes to look back from now. Default: 60 minutes. Examples: 60, 30, 15.
+- `limit` (integer, optional): Maximum number of traces to return. Default: 10.
+- `env` (string, optional): Environment to filter by. Use "get_service_environments" tool to get available environments.
+- `span_kind` (array, optional): Filter by span types (server, client, internal, consumer, producer).
+- `span_name` (string, optional): Filter by specific span name.
+- `status_code` (array, optional): Filter by trace status (ok, error, unset, success).
+- `order` (string, optional): Field to order traces by. Default: "Duration". Options: Duration, Timestamp.
+- `direction` (string, optional): Sort direction. Default: "backward". Options: forward, backward.
+- `start_time_iso` (string, optional): Start time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to now - lookback_minutes.
+- `end_time_iso` (string, optional): End time in ISO format (YYYY-MM-DD HH:MM:SS). Leave empty to default to current time.
+
+Filtering options:
+- Combine multiple filters to narrow down specific traces of interest
+- Use time range filters with lookback_minutes or explicit start/end times
+
+Examples:
+- service_name="api" + span_kind=["server"] + status_code=["error"] → finds failed server-side traces
+- service_name="payment" + span_name="process_payment" + lookback_minutes=30 → finds payment processing traces from last 30 minutes
+
 ## Installation
 
 You can install the Last9 Observability MCP server using either:
 
 ### Homebrew
 
-```
+```bash
 # Add the Last9 tap
 brew tap last9/tap
 
@@ -285,6 +342,7 @@ Configure the Claude app to use the MCP server:
 4. Copy and paste the server config to your existing file, then save
 5. Restart Claude
 
+### If installed via Homebrew:
 ```json
 {
   "mcpServers": {
@@ -300,6 +358,23 @@ Configure the Claude app to use the MCP server:
 }
 ```
 
+### If installed via NPM:
+```json
+{
+  "mcpServers": {
+    "last9": {
+      "command": "npx",
+      "args": ["-y", "@last9/mcp-server"],
+      "env": {
+        "LAST9_BASE_URL": "<last9_otlp_host>",
+        "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
+        "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
+      }
+    }
+  }
+}
+```
+
 ## Usage with Cursor
 
 Configure Cursor to use the MCP server:
@@ -310,6 +385,7 @@ Configure Cursor to use the MCP server:
 4. Copy and paste the server config to your existing file, then save
 5. Restart Cursor
 
+### If installed via Homebrew:
 ```json
 {
   "mcpServers": {
@@ -325,6 +401,23 @@ Configure Cursor to use the MCP server:
 }
 ```
 
+### If installed via NPM:
+```json
+{
+  "mcpServers": {
+    "last9": {
+      "command": "npx",
+      "args": ["-y", "@last9/mcp-server"],
+      "env": {
+        "LAST9_BASE_URL": "<last9_otlp_host>",
+        "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
+        "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
+      }
+    }
+  }
+}
+```
+
 ## Usage with Windsurf
 
 Configure Windsurf to use the MCP server:
@@ -335,6 +428,7 @@ Configure Windsurf to use the MCP server:
 4. Copy and paste the server config to your existing file, then save
 5. Restart Windsurf
 
+### If installed via Homebrew:
 ```json
 {
   "mcpServers": {
@@ -350,17 +444,35 @@ Configure Windsurf to use the MCP server:
 }
 ```
 
+### If installed via NPM:
+```json
+{
+  "mcpServers": {
+    "last9": {
+      "command": "npx",
+      "args": ["-y", "@last9/mcp-server"],
+      "env": {
+        "LAST9_BASE_URL": "<last9_otlp_host>",
+        "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
+        "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
+      }
+    }
+  }
+}
+```
+
 ## Usage with VS Code
 
 > Note: MCP support in VS Code is available starting v1.99 and is currently in
 > preview. For advanced configuration options and alternative setup methods,
 > [view the VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
 
-1.  Open VS Code, go to Settings, select the User tab, then Features, then Chat
-2.  Click "Edit settings.json"
-3.  Copy and paste the server config to your existing file, then save
-4.  Restart VS Code
+1. Open VS Code, go to Settings, select the User tab, then Features, then Chat
+2. Click "Edit settings.json"
+3. Copy and paste the server config to your existing file, then save
+4. Restart VS Code
 
+### If installed via Homebrew:
 ```json
 {
   "mcp": {
@@ -379,6 +491,114 @@ Configure Windsurf to use the MCP server:
 }
 ```
 
+### If installed via NPM:
+```json
+{
+  "mcp": {
+    "servers": {
+      "last9": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "@last9/mcp-server"],
+        "env": {
+          "LAST9_BASE_URL": "<last9_otlp_host>",
+          "LAST9_AUTH_TOKEN": "<last9_otlp_auth_token>",
+          "LAST9_REFRESH_TOKEN": "<last9_write_refresh_token>"
+        }
+      }
+    }
+  }
+}
+```
+
+## Development
+
+For local development and testing, you can run the MCP server in HTTP mode which makes it easier to debug requests and responses.
+
+### Running in HTTP Mode
+
+Set the `HTTP_MODE` environment variable to enable HTTP server mode:
+
+```bash
+# Export required environment variables
+export LAST9_API_TOKEN="your_api_token"
+export LAST9_BASE_URL="https://your-last9-endpoint"  # Your Last9 endpoint
+export HTTP_MODE=true
+export HTTP_PORT=8080  # Optional, defaults to 8080
+
+# Run the server
+./last9-mcp-server
+```
+
+The server will start on `http://localhost:8080/mcp` and you can test it with curl:
+
+### Testing with curl
+
+```bash
+# Test get_service_logs
+curl -X POST http://localhost:8080/mcp \
+    -H "Content-Type: application/json" \
+    -H "Mcp-Session-Id: session_$(date +%s)000000000" \
+    -d '{
+      "jsonrpc": "2.0",
+      "id": 1,
+      "method": "tools/call",
+      "params": {
+        "name": "get_service_logs",
+        "arguments": {
+          "service_name": "your-service-name",
+          "lookback_minutes": 30,
+          "limit": 10
+        }
+      }
+    }'
+
+# Test get_service_traces
+curl -X POST http://localhost:8080/mcp \
+    -H "Content-Type: application/json" \
+    -H "Mcp-Session-Id: session_$(date +%s)000000000" \
+    -d '{
+      "jsonrpc": "2.0",
+      "id": 2,
+      "method": "tools/call",
+      "params": {
+        "name": "get_service_traces",
+        "arguments": {
+          "service_name": "your-service-name",
+          "lookback_minutes": 60,
+          "limit": 5
+        }
+      }
+    }'
+
+# List available tools
+curl -X POST http://localhost:8080/mcp \
+    -H "Content-Type: application/json" \
+    -H "Mcp-Session-Id: session_$(date +%s)000000000" \
+    -d '{
+      "jsonrpc": "2.0",
+      "id": 3,
+      "method": "tools/list",
+      "params": {}
+    }'
+```
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/last9/last9-mcp-server.git
+cd last9-mcp-server
+
+# Build the binary
+go build -o last9-mcp-server
+
+# Run in development mode
+HTTP_MODE=true ./last9-mcp-server
+```
+
+**Note**: HTTP mode is for development and testing only. When integrating with Claude Desktop or other MCP clients, use the default STDIO mode (without `HTTP_MODE=true`).
+
 ## Badges
 
 [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/last9-last9-mcp-server-badge.png)](https://mseep.ai/app/last9-last9-mcp-server)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@last9/mcp-server",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Last9 MCP Server - Model Context Protocol server implementation for Last9",
   "bin": {
     "last9-mcp": "./bin/cli.js"