cubeapm-mcp 1.1.1 → 1.3.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/cubeapm-mcp.svg)](https://www.npmjs.com/package/cubeapm-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Server](https://lobehub.com/badge/mcp/technicalrhino-cubeapm-mcp)](https://lobehub.com/mcp/technicalrhino-cubeapm-mcp)
 
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [CubeAPM](https://cubeapm.com) - enabling AI assistants like Claude to query your observability data including traces, metrics, and logs.
 
@@ -180,9 +181,33 @@ You can now ask Claude questions like:
 |------|-------------|
 | `ingest_metrics_prometheus` | Send metrics in Prometheus text exposition format |
 
+## Prompts
+
+Pre-defined templates for common observability tasks:
+
+| Prompt | Description |
+|--------|-------------|
+| `investigate-service` | Comprehensive service investigation - checks errors, latency, and traces |
+| `check-latency` | Get P50, P95, P99 latency percentiles for a service |
+| `find-slow-traces` | Find slowest traces to identify performance bottlenecks |
+
+**Usage Example:**
+```
+Use the investigate-service prompt for Kratos-Prod
+```
+
+## Resources
+
+Readable resources exposing CubeAPM data and configuration:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `cubeapm://config` | Current CubeAPM connection configuration |
+| `cubeapm://query-patterns` | Query patterns and naming conventions reference |
+
 ## CubeAPM Query Patterns
 
-### Metrics Naming Conventions
+### Metrics (PromQL / MetricsQL)
 
 CubeAPM uses specific naming conventions that differ from standard OpenTelemetry:
 
@@ -192,7 +217,7 @@ CubeAPM uses specific naming conventions that differ from standard OpenTelemetry
 | Service label | `service` (NOT `server` or `service_name`) |
 | Common labels | `env`, `service`, `span_kind`, `status_code`, `http_code` |
 
-### Histogram Queries (P50, P90, P95, P99)
+#### Histogram Queries (P50, P90, P95, P99)
 
 CubeAPM uses **VictoriaMetrics-style histograms** with `vmrange` labels instead of Prometheus `le` buckets:
 
@@ -208,7 +233,9 @@ histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))
 
 > **Note:** Latency values are returned in **seconds** (0.05 = 50ms)
 
-### Logs Label Discovery
+### Logs (LogsQL)
+
+#### Stream Selectors
 
 Log labels vary by source. Use `*` query first to discover available labels:
 
@@ -224,17 +251,92 @@ Log labels vary by source. Use `*` query first to discover available labels:
 # Lambda function logs
 {faas.name="my-lambda-prod"}
 
-# Search with text filter
-{faas.name=~".*-prod"} AND "error"
+# Regex match
+{faas.name=~".*-prod"}
+
+# Text filter with boolean operators
+{faas.name=~".*"} AND "error" AND NOT "retry"
+```
+
+#### Pipe Operators
+
+Chain after any query with `|`:
+
+| Pipe | Syntax | Description |
+|------|--------|-------------|
+| `copy` | `\| copy src AS dst` | Copy field value |
+| `drop` | `\| drop field1, field2` | Remove fields from output |
+| `extract_regexp` | `\| extract_regexp "(?P<name>re)"` | Extract via named capture groups |
+| `join` | `\| join by (field) (...subquery...)` | Join with subquery results |
+| `keep` | `\| keep field1, field2` | Keep only specified fields |
+| `limit` | `\| limit N` | Return at most N results |
+| `math` | `\| math result = f1 + f2` | Arithmetic (+, -, *, /, %) |
+| `rename` | `\| rename src AS dst` | Rename a field |
+| `replace` | `\| replace (field, "old", "new")` | Substring replacement |
+| `replace_regexp` | `\| replace_regexp (field, "re", "repl")` | Regex replacement |
+| `sort` | `\| sort by (field) [asc\|desc]` | Sort results |
+| `stats` | `\| stats <func> as alias [by (fields)]` | Aggregate results |
+| `unpack_json` | `\| unpack_json` | Extract fields from JSON body |
+
+#### Stats Functions
+
+Used with the `| stats` pipe:
+
+| Function | Description |
+|----------|-------------|
+| `avg(field)` | Arithmetic mean |
+| `count()` | Total matching entries |
+| `count_empty(field)` | Entries where field is empty |
+| `count_uniq(field)` | Distinct values |
+| `max(field)` | Maximum value |
+| `median(field)` | Median (50th percentile) |
+| `min(field)` | Minimum value |
+| `quantile(p, field)` | p-th quantile (e.g., `quantile(0.95, duration)`) |
+| `sum(field)` | Sum of values |
+
+#### Example Log Queries
+
+```logsql
+# Count errors per Lambda function
+{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)
+
+# Top 10 slowest requests
+{service_name="my-service"} | sort by (duration) desc | limit 10
+
+# Extract and aggregate from JSON logs
+{service_name="api"} | unpack_json | stats avg(response_time) as avg_rt by (endpoint)
+```
+
+### Traces
+
+Trace queries use the same pipe syntax as logs: `{stream_selector} | pipe1 | pipe2`
+
+**Important notes:**
+- `query`, `env`, `service` are REQUIRED parameters
+- Duration is in **milliseconds** (not seconds like metrics)
+- `p95` is NOT a valid stats function — use `quantile(0.95, duration)`
+- Service names are case-sensitive (e.g., `"Kratos-Prod"` not `"kratos"`)
+
+#### Example Trace Queries
+
+```
+# P95 latency for a service
+{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms
+
+# Error count by endpoint
+{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)
+
+# Slowest spans
+{service="Kratos-Prod"} | sort by (duration) desc | limit 20
 ```
 
-## Example Queries
+## Example Natural Language Queries
 
 ### Logs
 ```
 "Show me logs from webhook-lambda-prod"
 "Find all logs containing 'timeout' in the last hour"
-"Query logs from Lambda functions in production"
+"Count errors per Lambda function in the last 24h"
 ```
 
 ### Metrics
@@ -246,7 +348,7 @@ Log labels vary by source. Use `*` query first to discover available labels:
 
 ### Traces
 ```
-"Find slow traces (>2s) from the order-service"
+"Find the P95 latency for Kratos-Prod using trace stats"
 "Show me traces with errors in the production environment"
 "Get the full waterfall for trace ID abc123"
 ```

package/dist/index.js

@@ -41,11 +41,39 @@ LogsQL Query Syntax:
 - Negation: {faas.name!="unwanted-service"}
 - Combine filters: {env="UNSET", faas.name=~".*-lambda.*"}
 
+PIPE OPERATORS — chain after query with "|":
+  | copy src_field AS dst_field       — copy field value
+  | drop field1, field2               — remove fields from output
+  | extract_regexp "(?P<name>regex)"  — extract fields via named capture groups
+  | join by (field) (...subquery...)   — join with subquery results
+  | keep field1, field2               — keep only specified fields
+  | limit N                           — return at most N results
+  | math result = field1 + field2     — compute derived fields (+, -, *, /, %)
+  | rename src AS dst                 — rename a field
+  | replace (field, "old", "new")     — replace substring in field
+  | replace_regexp (field, "re", "replacement") — regex replacement
+  | sort by (field) [asc|desc]        — sort results
+  | stats <func> as alias [by (group_fields)] — aggregate results
+  | unpack_json                       — extract fields from JSON log body
+
+STATS FUNCTIONS (use with | stats pipe):
+  avg(field)            — arithmetic mean
+  count()               — total number of matching entries
+  count_empty(field)    — count entries where field is empty
+  count_uniq(field)     — count distinct values
+  max(field)            — maximum value
+  median(field)         — median (50th percentile)
+  min(field)            — minimum value
+  quantile(p, field)    — p-th quantile (e.g., quantile(0.95, duration))
+  sum(field)            — sum of values
+
 Example queries:
 - All logs (discover structure): *
 - Lambda logs: {faas.name="webhook-lambda-prod"}
 - Search errors: {faas.name=~".*"} AND "error"
-- By environment: {env="production"}`, {
+- By environment: {env="production"}
+- Count errors per function: {faas.name=~".*"} AND "error" | stats count() as error_count by (faas.name)
+- Top 10 slowest: {service_name="my-service"} | sort by (duration) desc | limit 10`, {
     query: z.string().describe("The log search query including stream filters (LogsQL syntax)"),
     start: z.string().describe("Start time in RFC3339 format (e.g., 2024-01-01T00:00:00Z) or Unix timestamp in seconds"),
     end: z.string().describe("End time in RFC3339 format or Unix timestamp in seconds"),
@@ -206,15 +234,45 @@ IMPORTANT - Required Parameters:
 - Use env="UNSET" if environment is not configured
 - Service names are case-sensitive (e.g., "Kratos-Prod" not "kratos")
 
-Optional filters:
+TRACE QUERY SYNTAX:
+The query parameter supports pipe syntax similar to LogsQL:
+  {stream_selector} | pipe1 | pipe2
+
+Stream selectors filter spans:
+  {service="Kratos-Prod"}
+  {service="Kratos-Prod", span_kind="server"}
+  {http_code=~"5.."}
+
+PIPE OPERATORS — same as LogsQL pipes:
+  | copy, | drop, | extract_regexp, | join, | keep, | limit,
+  | math, | rename, | replace, | replace_regexp, | sort,
+  | stats <func> as alias [by (group_fields)], | unpack_json
+
+STATS FUNCTIONS (for aggregate trace analysis):
+  avg(field)            — arithmetic mean
+  count()               — total matching spans
+  count_uniq(field)     — distinct values
+  max(field)            — maximum value
+  median(field)         — median value
+  min(field)            — minimum value
+  quantile(p, field)    — p-th quantile (e.g., quantile(0.95, duration))
+  sum(field)            — sum of values
+
+IMPORTANT: Duration in traces is in MILLISECONDS.
+IMPORTANT: "p95" is NOT a valid function — use quantile(0.95, duration).
+
+Example queries:
+  Wildcard: query="*"
+  P95 latency: query='{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_latency'
+  Error count by endpoint: query='{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)'
+  Slow spans: query='{service="Kratos-Prod"} | sort by (duration) desc | limit 20'
+
+Optional filters (applied in addition to query):
 - spanKind: server, client, consumer, producer
 - sortBy: duration (to find slow traces)
 
 To discover available service names, first query metrics:
-count by (service) (cube_apm_calls_total{env="UNSET"})
-
-Example: Find slow server spans in Shopify-Prod
-  query="*", env="UNSET", service="Shopify-Prod", spanKind="server", sortBy="duration"`, {
+count by (service) (cube_apm_calls_total{env="UNSET"})`, {
     query: z.string().default("*").describe("The traces search query (use * for wildcard)"),
     env: z.string().default("UNSET").describe("Environment name (use UNSET if not configured)"),
     service: z.string().describe("Service name to filter by (REQUIRED, case-sensitive)"),
@@ -224,13 +282,16 @@ Example: Find slow server spans in Shopify-Prod
     spanKind: z.string().optional().describe("Filter by span kind: server, client, consumer, producer"),
     sortBy: z.string().optional().describe("Sort results by: duration"),
 }, async ({ query, env, service, start, end, limit, spanKind, sortBy }) => {
+    // Generate a random index value for the API call
+    const index = Math.random().toString(36).substring(2, 15);
     const params = new URLSearchParams({
         query,
         env,
         service,
         start,
         end,
-        limit: String(limit)
+        limit: String(limit),
+        index
     });
     if (spanKind)
         params.append("spanKind", spanKind);
@@ -319,6 +380,254 @@ server.tool("ingest_metrics_prometheus", "Send metrics to CubeAPM in Prometheus
         ],
     };
 });
+// ============================================
+// PROMPTS - Pre-defined templates for common tasks
+// ============================================
+server.prompt("investigate-service", "Investigate issues with a specific service - checks errors, latency, and recent traces", {
+    service: z.string().describe("The service name to investigate (case-sensitive)"),
+    timeRange: z.string().optional().default("1h").describe("Time range to look back (e.g., 1h, 6h, 24h)"),
+}, async ({ service, timeRange }) => {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Please investigate the ${service} service for the last ${timeRange}:
+
+1. First, check the error rate using metrics:
+   - Query: sum(increase(cube_apm_calls_total{service="${service}", status_code="ERROR"}[${timeRange}])) / sum(increase(cube_apm_calls_total{service="${service}"}[${timeRange}])) * 100
+
+2. Check P95 latency:
+   - Query: histogram_quantiles("phi", 0.95, sum by (vmrange) (increase(cube_apm_latency_bucket{service="${service}", span_kind="server"}[5m])))
+
+3. Search for error traces:
+   - Use search_traces with service="${service}", query="status_code=ERROR"
+
+4. Check recent logs if available:
+   - Query logs with {service_name="${service}"} or discover labels first with *
+
+Summarize any issues found and provide recommendations.`,
+                },
+            },
+        ],
+    };
+});
+server.prompt("check-latency", "Check P50, P95, and P99 latency percentiles for a service", {
+    service: z.string().describe("The service name (case-sensitive)"),
+}, async ({ service }) => {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Check the latency percentiles for ${service} service:
+
+Use query_metrics_instant with these queries:
+
+1. P50 (median):
+   histogram_quantiles("phi", 0.5, sum by (vmrange, service) (increase(cube_apm_latency_bucket{service="${service}", span_kind="server"}[5m])))
+
+2. P95:
+   histogram_quantiles("phi", 0.95, sum by (vmrange, service) (increase(cube_apm_latency_bucket{service="${service}", span_kind="server"}[5m])))
+
+3. P99:
+   histogram_quantiles("phi", 0.99, sum by (vmrange, service) (increase(cube_apm_latency_bucket{service="${service}", span_kind="server"}[5m])))
+
+Note: Latency values are in SECONDS (multiply by 1000 for milliseconds).
+
+Present the results in a clear table format.`,
+                },
+            },
+        ],
+    };
+});
+server.prompt("find-slow-traces", "Find the slowest traces for a service to identify performance bottlenecks", {
+    service: z.string().describe("The service name (case-sensitive)"),
+    minDuration: z.string().optional().default("1s").describe("Minimum duration to filter (e.g., 500ms, 1s, 2s)"),
+}, async ({ service, minDuration }) => {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Find slow traces for ${service} service (minimum duration: ${minDuration}):
+
+1. Search for traces using search_traces with:
+   - service: "${service}"
+   - sortBy: "duration"
+   - spanKind: "server"
+   - limit: 10
+
+2. For the slowest trace found, use get_trace to fetch the full trace details
+
+3. Analyze the trace waterfall to identify:
+   - Which span took the longest
+   - Any external dependencies causing delays
+   - Database queries or API calls that are slow
+
+Provide a summary of performance bottlenecks and recommendations.`,
+                },
+            },
+        ],
+    };
+});
+// ============================================
+// RESOURCES - Expose CubeAPM data as readable resources
+// ============================================
+server.resource("config", "cubeapm://config", {
+    description: "Current CubeAPM connection configuration",
+    mimeType: "application/json",
+}, async () => {
+    return {
+        contents: [
+            {
+                uri: "cubeapm://config",
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    queryUrl: queryBaseUrl,
+                    ingestUrl: ingestBaseUrl,
+                    usingFullUrl: !!CUBEAPM_URL,
+                    host: CUBEAPM_HOST,
+                    queryPort: CUBEAPM_QUERY_PORT,
+                    ingestPort: CUBEAPM_INGEST_PORT,
+                }, null, 2),
+            },
+        ],
+    };
+});
+server.resource("query-patterns", "cubeapm://query-patterns", {
+    description: "CubeAPM-specific query patterns and naming conventions",
+    mimeType: "text/markdown",
+}, async () => {
+    return {
+        contents: [
+            {
+                uri: "cubeapm://query-patterns",
+                mimeType: "text/markdown",
+                text: `# CubeAPM Query Patterns — Full Reference
+
+## Metrics (PromQL / MetricsQL)
+
+### Naming Conventions
+- Prefix: \`cube_apm_*\` (e.g., cube_apm_calls_total, cube_apm_latency_bucket)
+- Service label: \`service\` (NOT "server" or "service_name")
+- Common labels: env, service, span_kind, status_code, http_code
+
+### Histogram Queries (Percentiles)
+CubeAPM uses VictoriaMetrics-style histograms with \`vmrange\` label (NOT Prometheus \`le\` buckets):
+
+\`\`\`promql
+# ✅ Correct — use histogram_quantiles() with vmrange
+histogram_quantiles("phi", 0.95, sum by (vmrange, service) (
+  increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])
+))
+
+# ❌ Wrong — standard Prometheus syntax won't work
+histogram_quantile(0.95, sum by (le) (rate(http_request_duration_bucket[5m])))
+\`\`\`
+
+Latency values are in SECONDS (0.05 = 50ms).
+
+---
+
+## Logs (LogsQL)
+
+### Stream Selectors
+- \`*\` — wildcard, discover all labels
+- \`{faas.name="my-function"}\` — exact match
+- \`{faas.name=~".*-prod"}\` — regex match
+- \`{faas.name!="unwanted"}\` — negation
+- \`{env="production", faas.name=~".*"}\` — combine filters
+
+### Text Filters
+- \`{stream} AND "error"\` — text search
+- \`{stream} AND "timeout" AND NOT "retry"\` — boolean operators
+
+### Pipe Operators
+Chain after query with \`|\`:
+
+| Pipe | Syntax | Description |
+|------|--------|-------------|
+| copy | \`copy src AS dst\` | Copy field value |
+| drop | \`drop field1, field2\` | Remove fields from output |
+| extract_regexp | \`extract_regexp "(?P<name>re)"\` | Extract via named capture groups |
+| join | \`join by (field) (...subquery...)\` | Join with subquery |
+| keep | \`keep field1, field2\` | Keep only specified fields |
+| limit | \`limit N\` | Return at most N results |
+| math | \`math result = f1 + f2\` | Arithmetic (+, -, *, /, %) |
+| rename | \`rename src AS dst\` | Rename a field |
+| replace | \`replace (field, "old", "new")\` | Substring replacement |
+| replace_regexp | \`replace_regexp (field, "re", "repl")\` | Regex replacement |
+| sort | \`sort by (field) [asc/desc]\` | Sort results |
+| stats | \`stats <func> as alias [by (fields)]\` | Aggregate results |
+| unpack_json | \`unpack_json\` | Extract fields from JSON body |
+
+### Stats Functions
+Used with \`| stats\` pipe:
+
+| Function | Description |
+|----------|-------------|
+| \`avg(field)\` | Arithmetic mean |
+| \`count()\` | Total matching entries |
+| \`count_empty(field)\` | Entries where field is empty |
+| \`count_uniq(field)\` | Distinct values |
+| \`max(field)\` | Maximum value |
+| \`median(field)\` | Median (50th percentile) |
+| \`min(field)\` | Minimum value |
+| \`quantile(p, field)\` | p-th quantile (e.g., quantile(0.95, duration)) |
+| \`sum(field)\` | Sum of values |
+
+### Example Log Queries
+\`\`\`logsql
+# Discover labels
+*
+
+# Count errors per Lambda function
+{faas.name=~".*"} AND "error" | stats count() as errors by (faas.name)
+
+# Top 10 slowest requests
+{service_name="my-service"} | sort by (duration) desc | limit 10
+\`\`\`
+
+---
+
+## Traces
+
+### Query Syntax
+Trace queries use the same pipe syntax:
+\`{stream_selector} | pipe1 | pipe2\`
+
+### Stream Selectors
+- \`{service="Kratos-Prod"}\`
+- \`{service="Kratos-Prod", span_kind="server"}\`
+- \`{http_code=~"5.."}\`
+
+### Important Notes
+- query, env, service are REQUIRED parameters
+- Duration is in MILLISECONDS (not seconds like metrics)
+- \`p95\` is NOT a valid function — use \`quantile(0.95, duration)\`
+- Use \`sortBy=duration\` param to find slow traces
+- Filter by spanKind: server, client, consumer, producer
+
+### Example Trace Queries
+\`\`\`
+# P95 latency for a service
+{service="Kratos-Prod", span_kind="server"} | stats quantile(0.95, duration) as p95_ms
+
+# Error count by endpoint
+{service="Kratos-Prod", status_code="ERROR"} | stats count() as errors by (http_route)
+
+# Slowest spans
+{service="Kratos-Prod"} | sort by (duration) desc | limit 20
+\`\`\`
+`,
+            },
+        ],
+    };
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeapm-mcp",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "MCP server for CubeAPM - Query traces, metrics, and logs from your observability platform using AI assistants",
   "type": "module",
   "main": "dist/index.js",