@kyrontha/lens-mcp 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# Kyrontha Lens MCP server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [Kyrontha Lens](https://lens.kyrontha.io). Lets Claude Desktop, Claude Code, Cursor, Windsurf, and other MCP clients query your Lens workspace — logs, traces, APM — without leaving the editor.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `search_logs` | Lucene query across your log stream. Returns matching lines with timestamp, level, source, log group, and a truncated message. |
+| `search_traces` | Search distributed traces. Filter by service, operation, status, min duration; sort by recent, slow, or errors. |
+| `get_trace` | Fetch every span in one trace (up to 100). Use after `search_traces` to drill in. |
+| `check_connection` | Health probe — verifies the API key works and shows which Lens workspace you're authenticated against. |
+
+All tools are read-only. Retention, plan limits, and PII redaction are enforced server-side; this package adds no business logic — it's a transport shim.
+
+## Install
+
+```bash
+npm install -g @kyrontha/lens-mcp
+```
+
+Or use `npx` directly in your MCP client config — no install needed.
+
+## Configure
+
+You need two things:
+
+1. **Lens base URL.** Defaults to `https://lens.kyrontha.io`. If you're on a private deployment, override with `LENS_URL`.
+2. **An API key.** Generate one in your Lens workspace under a connection's API keys, or in the admin panel. The format is `kl_…`.
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "kyrontha-lens": {
+      "command": "npx",
+      "args": ["-y", "@kyrontha/lens-mcp"],
+      "env": {
+        "LENS_URL": "https://lens.kyrontha.io",
+        "LENS_API_KEY": "kl_…"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask: *"Use kyrontha-lens to find any errors in the last hour."*
+
+### Claude Code
+
+```bash
+claude mcp add kyrontha-lens npx @kyrontha/lens-mcp \
+  -e LENS_URL=https://lens.kyrontha.io \
+  -e LENS_API_KEY=kl_…
+```
+
+### Cursor, Windsurf, etc.
+
+These read the same `mcpServers` config shape. Drop the JSON block above into the client's MCP config.
+
+## Try it
+
+After configuring, a few useful prompts:
+
+> *"In Lens, what were the top error sources in the last 24h?"*
+
+> *"Find any traces where checkout took over 2 seconds today. Pull the slowest one's full span tree."*
+
+> *"Grep my logs for 'connection refused' over the last 3 days, then check if there are matching traces."*
+
+The model decides which tools to call. With Lens's unified store backing it, a single conversation can pull from logs + traces in one investigation.
+
+## Troubleshooting
+
+**`LENS_API_KEY env var is required`** — the env block in your MCP config wasn't picked up. Restart the client and confirm the key is set under the `env` key, not at the top level.
+
+**`401 Invalid API key`** — the key is wrong or has been rotated. Regenerate in Lens and update the config.
+
+**Tools time out** — Lens API calls have a 30s timeout. If the workspace has multi-terabyte data, narrow `time_range` first (`1h` then `6h`) before widening.
+
+**Need verbose logs** — set `MCP_DEBUG=1` in the env block to see request/response detail on stderr.
+
+## Security
+
+- The API key is shipped through your MCP client's env config and never touches Lens's backend except as a Bearer header. Treat it like a password.
+- All tools are read-only. There's currently no MCP tool that writes data into Lens.
+- The server is a single Node.js process spawned by your MCP client; it terminates with the client.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kyrontha/lens-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Kyrontha Lens — lets Claude Desktop, Claude Code, Cursor, and other MCP clients query your logs, traces, and APM data.",
+  "type": "module",
+  "bin": {
+    "kyrontha-lens-mcp": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "observability",
+    "logs",
+    "traces",
+    "apm",
+    "kyrontha",
+    "lens"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/jblamba/Kyrontha%20Lens/_git/Kyrontha-Lens",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "author": "Kyrontha"
+}

package/src/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// Kyrontha Lens MCP server.
+//
+// Lets MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, etc.)
+// query the user's Lens workspace — logs, traces, APM — directly. Every
+// tool here is a thin shim around an HTTP endpoint on the Lens backend
+// (/v1/query/*) authenticated by the customer's API key. The shim adds
+// no business logic; retention clamping, redaction, plan limits all live
+// server-side so a leaked MCP package can't bypass them.
+//
+// Config (read once at startup from env):
+//   LENS_URL       Base URL of the Lens API. Default https://lens.kyrontha.io
+//   LENS_API_KEY   Customer's API key (kl_…). Required.
+//
+// Distribution:
+//   npx @kyrontha/lens-mcp
+//   - or -
+//   npm install -g @kyrontha/lens-mcp
+//   kyrontha-lens-mcp
+//
+// Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json
+// on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
+//   {
+//     "mcpServers": {
+//       "kyrontha-lens": {
+//         "command": "npx",
+//         "args": ["-y", "@kyrontha/lens-mcp"],
+//         "env": {
+//           "LENS_URL": "https://lens.kyrontha.io",
+//           "LENS_API_KEY": "kl_…"
+//         }
+//       }
+//     }
+//   }
+//
+// All log output goes to stderr so it can't pollute the stdio MCP wire
+// protocol on stdout. Claude Desktop surfaces stderr in its developer
+// settings if you need to debug.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const LENS_URL = (process.env.LENS_URL || 'https://lens.kyrontha.io').replace(/\/+$/, '');
+const LENS_API_KEY = process.env.LENS_API_KEY || '';
+
+if (!LENS_API_KEY) {
+  console.error(
+    '[kyrontha-lens-mcp] LENS_API_KEY env var is required.\n' +
+    '  Generate one at ' + LENS_URL + '/admin or your tenant\'s connection wizard,\n' +
+    '  then set it in your MCP client config (e.g. claude_desktop_config.json).');
+  process.exit(1);
+}
+
+// ── HTTP helpers ─────────────────────────────────────────────────────────────
+// One thin wrapper around fetch that:
+//   - injects the bearer token
+//   - timeouts the call (slow Lens shouldn't hang the MCP client forever)
+//   - surfaces structured errors to the model as text content so it can
+//     reason about the failure (vs throwing into the MCP stack)
+//
+// Returned shape is the MCP tool-result shape so call sites can return it
+// directly without an extra wrap.
+async function lensRequest(method, path, body) {
+  const url = LENS_URL + path;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 30_000);
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: 'Bearer ' + LENS_API_KEY,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let parsed;
+    try { parsed = JSON.parse(text); } catch { parsed = { raw: text }; }
+    if (!res.ok) {
+      const errMsg =
+        (parsed && parsed.error) ||
+        `Lens ${method} ${path} returned ${res.status}`;
+      return {
+        content: [{ type: 'text', text: `Error: ${errMsg}` }],
+        isError: true,
+      };
+    }
+    return {
+      content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }],
+    };
+  } catch (err) {
+    const msg = err.name === 'AbortError'
+      ? `Lens ${method} ${path} timed out after 30s`
+      : `Lens ${method} ${path} failed: ${err.message}`;
+    return {
+      content: [{ type: 'text', text: `Error: ${msg}` }],
+      isError: true,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Server setup ─────────────────────────────────────────────────────────────
+const server = new McpServer({
+  name: 'kyrontha-lens',
+  version: '0.1.0',
+});
+
+// Tool descriptions are read by the model to decide when to call them.
+// Be explicit about what each tool returns AND when to reach for it —
+// generic descriptions lead to over-calling (e.g. searching logs for
+// metrics-shaped questions) and burn tokens.
+
+server.registerTool(
+  'search_logs',
+  {
+    title: 'Search logs',
+    description:
+      'Search the customer\'s log stream and return matching lines. Use this for questions about log events, errors, ' +
+      'request patterns, or anything text-shaped. Query syntax is Lucene: `level:error AND source:api`, ' +
+      '`message:"connection refused"`, `log_group:/aws/lambda/* AND status_code:[500 TO 599]`, ' +
+      '`trace_id:"<hex>"`. Empty query returns every log line in the time range.',
+    inputSchema: {
+      query: z.string().describe(
+        'Lucene-style query. Empty string matches all logs in the time range.'),
+      time_range: z.enum(['1h', '6h', '24h', '3d', '7d']).optional()
+        .describe('How far back to search. Default 24h.'),
+      limit: z.number().int().min(1).max(50).optional()
+        .describe('Max log lines to return (1-50). Default 20.'),
+    },
+  },
+  async (input) => lensRequest('POST', '/v1/query/logs', input),
+);
+
+server.registerTool(
+  'search_traces',
+  {
+    title: 'Search distributed traces',
+    description:
+      'Search distributed traces (APM). Returns one row per trace summarising the root span. Filters match ANY ' +
+      'span in the trace (so service="email" finds traces with any email-service span). Use sort="slow" for the ' +
+      'slowest traces in the window, "errors" for traces with any error span, "recent" for most recent (default). ' +
+      'For a specific trace, call get_trace with its trace_id.',
+    inputSchema: {
+      query: z.string().optional()
+        .describe('Optional free-text filter — matches operation name + service.'),
+      service: z.string().optional()
+        .describe('Filter by service name (matches any span in the trace).'),
+      operation: z.string().optional()
+        .describe('Filter by root-span operation name.'),
+      status: z.enum(['ok', 'error']).optional()
+        .describe('Filter by trace status (any error span → error).'),
+      min_duration_ms: z.number().int().min(0).optional()
+        .describe('Only return traces longer than this many ms.'),
+      sort: z.enum(['recent', 'slow', 'errors']).optional()
+        .describe('Sort order. Default "recent".'),
+      time_range: z.enum(['1h', '6h', '24h', '3d', '7d']).optional()
+        .describe('How far back to search. Default 24h.'),
+      limit: z.number().int().min(1).max(50).optional()
+        .describe('Max traces to return (1-50). Default 20.'),
+    },
+  },
+  async (input) => lensRequest('POST', '/v1/query/traces', input),
+);
+
+server.registerTool(
+  'get_trace',
+  {
+    title: 'Get a single trace by ID',
+    description:
+      'Fetch every span in one trace, ordered. Use this after search_traces returns a trace_id you want to inspect ' +
+      'in detail. Caps at 100 spans — for huge traces, the `truncated` flag in the response tells you there\'s more. ' +
+      'Use this for "why is THIS trace slow" or "what was the dependency chain" questions.',
+    inputSchema: {
+      trace_id: z.string().regex(/^[0-9a-f]{16,32}$/i)
+        .describe('Hex-encoded trace ID (16 or 32 chars), as returned by search_traces.'),
+    },
+  },
+  async ({ trace_id }) =>
+    lensRequest('GET', '/v1/query/traces/' + encodeURIComponent(trace_id)),
+);
+
+// Health is exposed as a tool (not just an internal check) because users
+// often ask "is my Lens connection working" or "what workspace am I pointed
+// at" — and a clean tool keeps that out of MCP-protocol-noise territory.
+server.registerTool(
+  'check_connection',
+  {
+    title: 'Verify Lens connection + show authenticated workspace',
+    description:
+      'Confirms this MCP server can reach Lens with the configured API key and returns the authenticated tenant ' +
+      'name. Use this if other tools start failing — it isolates "auth/network broken" from "no matching data".',
+    inputSchema: {},
+  },
+  async () => lensRequest('GET', '/v1/query/health'),
+);
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // stderr only — stdout is owned by the MCP wire protocol.
+  console.error(`[kyrontha-lens-mcp] connected. lens=${LENS_URL}`);
+}
+
+main().catch((err) => {
+  console.error('[kyrontha-lens-mcp] fatal:', err);
+  process.exit(1);
+});