cubeapm-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TechnicalRhino
+
+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.

package/README.md

@@ -0,0 +1,239 @@
+# CubeAPM MCP Server
+
+[![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)
+
+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.
+
+## What is this?
+
+This MCP server connects AI assistants (like Claude) to your CubeAPM instance, allowing you to:
+
+- **Query logs** using natural language that gets translated to LogsQL
+- **Analyze metrics** with PromQL-compatible queries
+- **Search and inspect traces** to debug distributed systems
+- **Monitor your services** through conversational interfaces
+
+## Installation
+
+### From NPM (Recommended)
+
+```bash
+npm install -g cubeapm-mcp
+```
+
+### From Source
+
+```bash
+git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
+cd cubeapm-mcp
+npm install
+npm run build
+```
+
+## Quick Start
+
+### 1. Configure Claude Code
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "cubeapm": {
+      "command": "npx",
+      "args": ["-y", "cubeapm-mcp"],
+      "env": {
+        "CUBEAPM_HOST": "your-cubeapm-server.com"
+      }
+    }
+  }
+}
+```
+
+### 2. Restart Claude Code
+
+After updating the settings, restart Claude Code to load the MCP server.
+
+### 3. Start Querying
+
+You can now ask Claude questions like:
+
+- *"Show me error logs from the payment-service in the last hour"*
+- *"What's the p99 latency for the checkout API?"*
+- *"Find traces where duration > 5s in production"*
+- *"Get the full trace for trace ID abc123def456"*
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `CUBEAPM_HOST` | `localhost` | CubeAPM server hostname or IP |
+| `CUBEAPM_QUERY_PORT` | `3140` | Port for querying APIs (traces, metrics, logs) |
+| `CUBEAPM_INGEST_PORT` | `3130` | Port for ingestion APIs |
+
+### Example Configurations
+
+**Local Development:**
+```json
+{
+  "mcpServers": {
+    "cubeapm": {
+      "command": "npx",
+      "args": ["-y", "cubeapm-mcp"],
+      "env": {
+        "CUBEAPM_HOST": "localhost"
+      }
+    }
+  }
+}
+```
+
+**Production:**
+```json
+{
+  "mcpServers": {
+    "cubeapm": {
+      "command": "npx",
+      "args": ["-y", "cubeapm-mcp"],
+      "env": {
+        "CUBEAPM_HOST": "cubeapm.internal.company.com",
+        "CUBEAPM_QUERY_PORT": "3140"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Logs
+
+| Tool | Description |
+|------|-------------|
+| `query_logs` | Query logs using LogsQL syntax with time range and limit |
+
+**Parameters:**
+- `query` - LogsQL query string (e.g., `{service="api"} error`)
+- `start` - Start time (RFC3339 or Unix timestamp)
+- `end` - End time (RFC3339 or Unix timestamp)
+- `limit` - Maximum entries to return (default: 100)
+
+### Metrics
+
+| Tool | Description |
+|------|-------------|
+| `query_metrics_instant` | Execute a PromQL query at a single point in time |
+| `query_metrics_range` | Execute a PromQL query over a time range |
+
+**Instant Query Parameters:**
+- `query` - PromQL expression
+- `time` - Evaluation timestamp
+- `step` - Optional time window in seconds
+
+**Range Query Parameters:**
+- `query` - PromQL expression
+- `start` / `end` - Time range
+- `step` - Resolution in seconds
+
+### Traces
+
+| Tool | Description |
+|------|-------------|
+| `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
+- `limit` - Maximum results (default: 20)
+
+**Get Trace Parameters:**
+- `trace_id` - Hex-encoded trace ID
+- `start` / `end` - Time range to search within
+
+### Ingestion
+
+| Tool | Description |
+|------|-------------|
+| `ingest_metrics_prometheus` | Send metrics in Prometheus text exposition format |
+
+## Example Queries
+
+### Logs
+```
+"Find all ERROR logs from auth-service in the last 30 minutes"
+"Show me logs containing 'connection refused' from the database service"
+"Query logs where trace_id matches xyz123"
+```
+
+### Metrics
+```
+"What's the average request duration for the API gateway?"
+"Show me CPU usage for all services over the last 6 hours"
+"Graph the error rate for checkout-service with 1-minute resolution"
+```
+
+### Traces
+```
+"Find slow traces (>2s) from the order-service"
+"Show me traces with errors in the production environment"
+"Get the full waterfall for trace ID abc123"
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/TechnicalRhino/cubeapm-mcp.git
+cd cubeapm-mcp
+
+# Install dependencies
+npm install
+
+# Run in development mode (with hot reload)
+npm run dev
+
+# Build for production
+npm run build
+
+# Test the build
+npm start
+```
+
+## How It Works
+
+```
+┌─────────────────┐     MCP Protocol     ┌─────────────────┐     HTTP API     ┌─────────────────┐
+│  Claude / AI    │◄───────────────────►│  cubeapm-mcp    │◄────────────────►│    CubeAPM      │
+│   Assistant     │   (stdio transport)  │   MCP Server    │   (REST calls)   │    Server       │
+└─────────────────┘                      └─────────────────┘                  └─────────────────┘
+```
+
+The MCP server:
+1. Receives tool calls from the AI assistant via stdio
+2. Translates them to CubeAPM HTTP API requests
+3. Returns formatted results back to the assistant
+
+## Requirements
+
+- **Node.js** 18+
+- **CubeAPM** instance (self-hosted or cloud)
+- **Claude Code** or any MCP-compatible client
+
+## Related Links
+
+- [CubeAPM Documentation](https://docs.cubeapm.com)
+- [CubeAPM HTTP APIs](https://docs.cubeapm.com/http-apis)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Claude Code](https://claude.ai/code)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Configuration from environment variables
+const CUBEAPM_HOST = process.env.CUBEAPM_HOST || "localhost";
+const CUBEAPM_QUERY_PORT = process.env.CUBEAPM_QUERY_PORT || "3140";
+const CUBEAPM_INGEST_PORT = process.env.CUBEAPM_INGEST_PORT || "3130";
+const queryBaseUrl = `http://${CUBEAPM_HOST}:${CUBEAPM_QUERY_PORT}`;
+const ingestBaseUrl = `http://${CUBEAPM_HOST}:${CUBEAPM_INGEST_PORT}`;
+// Create the MCP server
+const server = new McpServer({
+    name: "cubeapm-mcp",
+    version: "1.0.0",
+});
+// ============================================
+// LOGS APIs
+// ============================================
+server.tool("query_logs", "Query logs from CubeAPM using LogsQL syntax. Returns log entries matching the query.", {
+    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"),
+    limit: z.number().optional().default(100).describe("Maximum log entries to return (default: 100)"),
+}, async ({ query, start, end, limit }) => {
+    const params = new URLSearchParams({
+        query,
+        start,
+        end,
+        limit: String(limit),
+    });
+    const response = await fetch(`${queryBaseUrl}/api/logs/select/logsql/query`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error querying logs: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const text = await response.text();
+    return {
+        content: [
+            {
+                type: "text",
+                text: text || "No logs found matching the query",
+            },
+        ],
+    };
+});
+// ============================================
+// METRICS APIs
+// ============================================
+server.tool("query_metrics_instant", "Execute an instant query against CubeAPM metrics at a single point in time. Uses PromQL-compatible syntax.", {
+    query: z.string().describe("The metrics query expression (PromQL syntax)"),
+    time: z.string().describe("Evaluation timestamp in RFC3339 format or Unix timestamp in seconds"),
+    step: z.number().optional().describe("Time window in seconds for processing data"),
+}, async ({ query, time, step }) => {
+    const params = new URLSearchParams({ query, time });
+    if (step)
+        params.append("step", String(step));
+    const response = await fetch(`${queryBaseUrl}/api/metrics/api/v1/query`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error querying metrics: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await response.json();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+server.tool("query_metrics_range", "Execute a range query against CubeAPM metrics over a time range. Returns time series data.", {
+    query: z.string().describe("The metrics query expression (PromQL syntax)"),
+    start: z.string().describe("Start timestamp in RFC3339 format or Unix timestamp"),
+    end: z.string().describe("End timestamp in RFC3339 format or Unix timestamp"),
+    step: z.number().describe("Resolution step width in seconds"),
+}, async ({ query, start, end, step }) => {
+    const params = new URLSearchParams({
+        query,
+        start,
+        end,
+        step: String(step),
+    });
+    const response = await fetch(`${queryBaseUrl}/api/metrics/api/v1/query_range`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: params.toString(),
+    });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error querying metrics range: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await response.json();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// ============================================
+// TRACES APIs
+// ============================================
+server.tool("search_traces", "Search for traces in CubeAPM matching the specified criteria. Returns trace snippets with key spans.", {
+    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"),
+    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);
+    const response = await fetch(`${queryBaseUrl}/api/traces/api/v1/search?${params.toString()}`, { method: "GET" });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error searching traces: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await response.json();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+server.tool("get_trace", "Fetch a complete trace by its ID from CubeAPM. Returns all spans in the trace with full details.", {
+    trace_id: z.string().describe("The hex-encoded trace ID to fetch"),
+    start: z.string().describe("Start timestamp in RFC3339 format or Unix seconds"),
+    end: z.string().describe("End timestamp in RFC3339 format or Unix seconds"),
+}, async ({ trace_id, start, end }) => {
+    const params = new URLSearchParams({ start, end });
+    const response = await fetch(`${queryBaseUrl}/api/traces/api/v1/traces/${trace_id}?${params.toString()}`, { method: "GET" });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching trace: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const data = await response.json();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+});
+// ============================================
+// INGESTION APIs (for sending data to CubeAPM)
+// ============================================
+server.tool("ingest_metrics_prometheus", "Send metrics to CubeAPM in Prometheus text exposition format.", {
+    metrics: z.string().describe("Metrics data in Prometheus text exposition format"),
+}, async ({ metrics }) => {
+    const response = await fetch(`${ingestBaseUrl}/api/metrics/v1/save`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/plain",
+        },
+        body: metrics,
+    });
+    if (!response.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error ingesting metrics: ${response.status} ${response.statusText}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Metrics ingested successfully",
+            },
+        ],
+    };
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("CubeAPM MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "cubeapm-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for CubeAPM - Query traces, metrics, and logs from your observability platform using AI assistants",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cubeapm-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TechnicalRhino/cubeapm-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TechnicalRhino/cubeapm-mcp/issues"
+  },
+  "homepage": "https://github.com/TechnicalRhino/cubeapm-mcp#readme",
+  "author": "TechnicalRhino",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cubeapm",
+    "observability",
+    "apm",
+    "traces",
+    "metrics",
+    "logs",
+    "claude",
+    "ai",
+    "monitoring",
+    "distributed-tracing",
+    "promql",
+    "logsql"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}