cubeapm-mcp 1.1.0 → 1.2.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.
 
@@ -159,12 +160,16 @@ You can now ask Claude questions like:
 | `search_traces` | Search traces by service, environment, or custom query |
 | `get_trace` | Fetch complete trace details by trace ID |
 
-**Search Parameters:**
-- `query` - Optional search query
-- `env` - Environment filter (e.g., `production`)
-- `service` - Service name filter
-- `start` / `end` - Time range
+**Search Parameters (Required):**
+- `query` - Search query (default: `*` for wildcard)
+- `env` - Environment filter (default: `UNSET`)
+- `service` - Service name filter (**required**, case-sensitive)
+- `start` / `end` - Time range (RFC3339 or Unix timestamp)
+
+**Search Parameters (Optional):**
 - `limit` - Maximum results (default: 20)
+- `spanKind` - Filter by span type: `server`, `client`, `consumer`, `producer`
+- `sortBy` - Sort by: `duration` (useful for finding slow traces)
 
 **Get Trace Parameters:**
 - `trace_id` - Hex-encoded trace ID
@@ -176,6 +181,30 @@ 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

package/dist/index.js

@@ -200,28 +200,42 @@ histogram_quantiles("phi", 0.95, sum by (vmrange, service) (increase(cube_apm_la
 // ============================================
 server.tool("search_traces", `Search for traces in CubeAPM matching the specified criteria. Returns trace snippets with key spans.
 
-Tips for effective trace searches:
+IMPORTANT - Required Parameters:
+- query, env, service, start, end are ALL REQUIRED by CubeAPM API
+- Use query="*" for wildcard search
+- Use env="UNSET" if environment is not configured
 - Service names are case-sensitive (e.g., "Kratos-Prod" not "kratos")
-- Use the service parameter to filter by service name
-- Use the env parameter to filter by environment
-- Time range is required (start/end in RFC3339 or Unix timestamp)
+
+Optional filters:
+- 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"})`, {
-    query: z.string().optional().describe("The traces search query"),
-    env: z.string().optional().describe("Environment name to filter by"),
-    service: z.string().optional().describe("Service name to filter by"),
+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"`, {
+    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)"),
     start: z.string().describe("Start timestamp in RFC3339 format or Unix seconds"),
     end: z.string().describe("End timestamp in RFC3339 format or Unix seconds"),
     limit: z.number().optional().default(20).describe("Maximum number of traces to return"),
-}, async ({ query, env, service, start, end, limit }) => {
-    const params = new URLSearchParams({ start, end, limit: String(limit) });
-    if (query)
-        params.append("query", query);
-    if (env)
-        params.append("env", env);
-    if (service)
-        params.append("service", service);
+    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 }) => {
+    const params = new URLSearchParams({
+        query,
+        env,
+        service,
+        start,
+        end,
+        limit: String(limit)
+    });
+    if (spanKind)
+        params.append("spanKind", spanKind);
+    if (sortBy)
+        params.append("sortBy", sortBy);
     const response = await fetch(`${queryBaseUrl}/api/traces/api/v1/search?${params.toString()}`, { method: "GET" });
     if (!response.ok) {
         return {
@@ -305,6 +319,166 @@ 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
+
+## Metrics 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:
+
+\`\`\`promql
+# P95 Latency
+histogram_quantiles("phi", 0.95, sum by (vmrange, service) (
+  increase(cube_apm_latency_bucket{service="MyService", span_kind="server"}[5m])
+))
+\`\`\`
+
+Note: Latency values are in SECONDS (0.05 = 50ms)
+
+## Logs (LogsQL)
+- Use \`*\` to discover available labels
+- Lambda logs: \`{faas.name="my-function"}\`
+- Service logs: \`{service_name="my-service"}\`
+
+## Traces
+- query, env, service are REQUIRED parameters
+- Use \`sortBy=duration\` to find slow traces
+- Filter by spanKind: server, client, consumer, producer
+`,
+            },
+        ],
+    };
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

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