@loguro/mcp 1.0.0 → 1.2.0

package/dist/index.js

@@ -19560,6 +19560,263 @@ class StdioServerTransport {
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+
+// src/docs-catalog.ts
+var DOCS_CATALOG = [
+  { path: "/docs/getting-started", title: "Getting Started", section: "General" },
+  { path: "/docs/query-syntax", title: "Query Syntax", section: "General" },
+  { path: "/docs/alerting", title: "Alerting", section: "General" },
+  { path: "/docs/integrations", title: "Integrations", section: "General" },
+  { path: "/docs/cli/install", title: "Install", section: "CLI" },
+  { path: "/docs/cli/getting-started", title: "Getting Started", section: "CLI" },
+  { path: "/docs/cli/auth", title: "Auth", section: "CLI" },
+  { path: "/docs/cli/project-link", title: "Project Link", section: "CLI" },
+  { path: "/docs/cli/commands", title: "Commands", section: "CLI" },
+  { path: "/docs/cli/querying", title: "Querying", section: "CLI" },
+  { path: "/docs/cli/query-syntax", title: "Query Syntax", section: "CLI" },
+  { path: "/docs/cli/investigate", title: "Investigate", section: "CLI" },
+  { path: "/docs/cli/visualizations", title: "Visualizations", section: "CLI" },
+  { path: "/docs/cli/replay", title: "Replay", section: "CLI" },
+  { path: "/docs/cli/alerts", title: "Alerts", section: "CLI" },
+  { path: "/docs/cli/integrations", title: "Integrations", section: "CLI" },
+  { path: "/docs/cli/share", title: "Share", section: "CLI" },
+  { path: "/docs/cli/account", title: "Account", section: "CLI" },
+  { path: "/docs/commands/count", title: "--count", section: "Commands" },
+  { path: "/docs/commands/top", title: "--top", section: "Commands" },
+  { path: "/docs/commands/unique", title: "--unique", section: "Commands" },
+  { path: "/docs/commands/rate", title: "--rate", section: "Commands" },
+  { path: "/docs/commands/diff", title: "--diff", section: "Commands" },
+  { path: "/docs/commands/downloads", title: "--downloads", section: "Commands" },
+  { path: "/docs/commands/replay", title: "--replay", section: "Commands" },
+  { path: "/docs/commands/live", title: "--live", section: "Commands" },
+  { path: "/docs/commands/group", title: "--group", section: "Commands" },
+  { path: "/docs/commands/alerts", title: "--alerts", section: "Commands" },
+  { path: "/docs/commands/views", title: "--views", section: "Commands" },
+  { path: "/docs/commands/keys", title: "--keys", section: "Commands" },
+  { path: "/docs/commands/channels", title: "--channels", section: "Commands" },
+  { path: "/docs/commands/embed-status", title: "--embed::status", section: "Commands" },
+  { path: "/docs/commands/billing", title: "--billing", section: "Commands" },
+  { path: "/docs/commands/usage", title: "--usage", section: "Commands" },
+  { path: "/docs/commands/integrations-config", title: "--integrations::config", section: "Commands" },
+  { path: "/docs/commands/send", title: "--send", section: "Commands" },
+  { path: "/docs/commands/tasks", title: "--task", section: "Commands" },
+  { path: "/docs/commands/slow", title: "--slow", section: "Commands" },
+  { path: "/docs/commands/sample", title: "--sample", section: "Commands" },
+  { path: "/docs/commands/memory", title: "--memory", section: "Commands" },
+  { path: "/docs/commands/chart", title: "--chart", section: "Commands" },
+  { path: "/docs/commands/timeline", title: "--timeline", section: "Commands" },
+  { path: "/docs/commands/notifications", title: "--notifications", section: "Commands" },
+  { path: "/docs/commands/severity", title: "--severity", section: "Commands" },
+  { path: "/docs/commands/separate-message", title: "--separate::message", section: "Commands" },
+  { path: "/docs/commands/no-group", title: "--no-group", section: "Commands" },
+  { path: "/docs/commands/hashtag", title: "#view", section: "Commands" },
+  { path: "/docs/commands/investigate", title: "--investigate", section: "Commands" },
+  { path: "/docs/commands/explain", title: "--explain", section: "Commands" },
+  { path: "/docs/commands/notes", title: "--notes", section: "Commands" },
+  { path: "/docs/commands/share", title: "--share:md", section: "Commands" },
+  { path: "/docs/commands/slack", title: "--slack", section: "Commands" },
+  { path: "/docs/commands/trace", title: "--trace:full", section: "Commands" },
+  { path: "/docs/features/saved-views", title: "Saved Views", section: "Features" },
+  { path: "/docs/features/log-export", title: "Log Export", section: "Features" },
+  { path: "/docs/features/embed-widgets", title: "Embed Widgets", section: "Features" },
+  { path: "/docs/features/replay", title: "Replay", section: "Features" },
+  { path: "/docs/features/issue-tracker", title: "Issue Tracker", section: "Features" },
+  { path: "/docs/features/messaging", title: "Messaging", section: "Features" },
+  { path: "/docs/features/heartbeat", title: "Heartbeat", section: "Features" },
+  { path: "/docs/features/memory", title: "Memory", section: "Features" },
+  { path: "/docs/mcp/setup", title: "Setup", section: "MCP" },
+  { path: "/docs/mcp/auth", title: "Auth", section: "MCP" },
+  { path: "/docs/mcp/config", title: "Config", section: "MCP" },
+  { path: "/docs/mcp/tools", title: "Tools", section: "MCP" },
+  { path: "/docs/mcp/clients", title: "Clients", section: "MCP" },
+  { path: "/docs/mcp/vs-cli", title: "MCP vs CLI", section: "MCP" },
+  { path: "/docs/tui/getting-started", title: "Getting Started", section: "TUI" },
+  { path: "/docs/tui/views", title: "Views", section: "TUI" },
+  { path: "/docs/tui/keymap", title: "Keymap", section: "TUI" },
+  { path: "/docs/tui/search", title: "Search", section: "TUI" },
+  { path: "/docs/tui/alerts", title: "Alerts", section: "TUI" },
+  { path: "/docs/tui/saved-views", title: "Saved Views", section: "TUI" },
+  { path: "/docs/tui/docs-browser", title: "Docs Browser", section: "TUI" },
+  { path: "/docs/tui/health-badge", title: "Health Badge", section: "TUI" },
+  { path: "/docs/tui/troubleshooting", title: "Troubleshooting", section: "TUI" },
+  { path: "/docs/web-analytics/getting-started", title: "Getting Started", section: "Web Analytics" },
+  { path: "/docs/web-analytics/install", title: "Install", section: "Web Analytics" },
+  { path: "/docs/web-analytics/events", title: "Events", section: "Web Analytics" },
+  { path: "/docs/web-analytics/pageviews", title: "Pageviews", section: "Web Analytics" },
+  { path: "/docs/web-analytics/identity", title: "Identity", section: "Web Analytics" },
+  { path: "/docs/web-analytics/privacy", title: "Privacy", section: "Web Analytics" },
+  { path: "/docs/web-analytics/api-reference", title: "API Reference", section: "Web Analytics" },
+  { path: "/docs/web-analytics/troubleshooting", title: "Troubleshooting", section: "Web Analytics" }
+];
+
+// src/docs.ts
+var DOCS_BASE_URL = (process.env.LOGURO_DOCS_BASE_URL ?? "https://logu.ro").replace(/\/$/, "");
+var CACHE_TTL_MS = 15 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 1e4;
+var USER_AGENT = `loguro-mcp-docs/1.0.0 (node/${process.version})`;
+var cache = new Map;
+var allFetchedAt = 0;
+function extractHeadings(md) {
+  const out = [];
+  for (const line of md.split(`
+`)) {
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (m)
+      out.push(m[2].trim());
+  }
+  return out;
+}
+function isFresh(entry) {
+  return Date.now() - entry.fetchedAt < CACHE_TTL_MS;
+}
+async function fetchDoc(path, force = false) {
+  const cached2 = cache.get(path);
+  if (!force && cached2 && isFresh(cached2))
+    return cached2;
+  const url = `${DOCS_BASE_URL}${path}.md`;
+  const res = await fetch(url, {
+    headers: { "User-Agent": USER_AGENT, Accept: "text/markdown,text/plain,*/*" },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${url}: HTTP ${res.status}`);
+  }
+  const body = await res.text();
+  const entry = {
+    path,
+    body,
+    headings: extractHeadings(body),
+    fetchedAt: Date.now()
+  };
+  cache.set(path, entry);
+  return entry;
+}
+async function fetchAllDocs() {
+  if (Date.now() - allFetchedAt < CACHE_TTL_MS)
+    return;
+  await Promise.all(DOCS_CATALOG.map((entry) => fetchDoc(entry.path).catch((err) => {
+    process.stderr.write(`docs: failed to fetch ${entry.path}: ${err.message}
+`);
+  })));
+  allFetchedAt = Date.now();
+}
+function listDocs(section) {
+  const filtered = section ? DOCS_CATALOG.filter((e) => e.section.toLowerCase() === section.toLowerCase()) : DOCS_CATALOG;
+  return filtered.map((e) => {
+    const cached2 = cache.get(e.path);
+    return cached2 ? { ...e, headings: cached2.headings } : { ...e };
+  });
+}
+function listSections() {
+  const counts = new Map;
+  for (const e of DOCS_CATALOG)
+    counts.set(e.section, (counts.get(e.section) ?? 0) + 1);
+  return [...counts.entries()].map(([section, count]) => ({ section, count }));
+}
+function tokens(s) {
+  return s.toLowerCase().split(/\s+/).filter(Boolean);
+}
+function countOccurrences(haystack, needle) {
+  if (!needle)
+    return 0;
+  let count = 0;
+  let i = 0;
+  const lc = haystack.toLowerCase();
+  while ((i = lc.indexOf(needle, i)) !== -1) {
+    count++;
+    i += needle.length;
+  }
+  return count;
+}
+function buildSnippet(body, query, max = 280) {
+  const lc = body.toLowerCase();
+  const idx = lc.indexOf(query.toLowerCase());
+  if (idx === -1) {
+    return body.slice(0, max).trim() + (body.length > max ? "…" : "");
+  }
+  const start = Math.max(0, idx - 80);
+  const end = Math.min(body.length, idx + query.length + 200);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < body.length ? "…" : "";
+  return prefix + body.slice(start, end).replace(/\s+/g, " ").trim() + suffix;
+}
+async function searchDocs(query, limit = 5) {
+  await fetchAllDocs();
+  const q = query.trim().toLowerCase();
+  const qTokens = tokens(q);
+  if (!q)
+    return [];
+  const hits = [];
+  for (const entry of DOCS_CATALOG) {
+    const cached2 = cache.get(entry.path);
+    const titleLc = entry.title.toLowerCase();
+    const sectionLc = entry.section.toLowerCase();
+    const matchedIn = new Set;
+    let score = 0;
+    const matchedHeadings = [];
+    if (titleLc.includes(q)) {
+      score += 50;
+      matchedIn.add("title");
+    } else {
+      for (const t of qTokens)
+        if (titleLc.includes(t)) {
+          score += 15;
+          matchedIn.add("title");
+        }
+    }
+    if (sectionLc.includes(q)) {
+      score += 10;
+      matchedIn.add("section");
+    }
+    if (cached2) {
+      for (const h of cached2.headings) {
+        const hLc = h.toLowerCase();
+        if (hLc.includes(q)) {
+          score += 20;
+          matchedIn.add("heading");
+          matchedHeadings.push(h);
+        } else {
+          for (const t of qTokens) {
+            if (hLc.includes(t)) {
+              score += 5;
+              matchedIn.add("heading");
+              if (!matchedHeadings.includes(h))
+                matchedHeadings.push(h);
+            }
+          }
+        }
+      }
+      const bodyOccurrences = countOccurrences(cached2.body, q);
+      if (bodyOccurrences > 0) {
+        score += Math.min(bodyOccurrences, 10);
+        matchedIn.add("body");
+      } else {
+        for (const t of qTokens) {
+          const occ = countOccurrences(cached2.body, t);
+          if (occ > 0) {
+            score += Math.min(occ, 5) * 0.5;
+            matchedIn.add("body");
+          }
+        }
+      }
+    }
+    if (score > 0) {
+      hits.push({
+        path: entry.path,
+        title: entry.title,
+        section: entry.section,
+        score,
+        matchedIn: [...matchedIn],
+        snippet: cached2 ? buildSnippet(cached2.body, q) : "",
+        matchedHeadings
+      });
+    }
+  }
+  hits.sort((a, b) => b.score - a.score);
+  return hits.slice(0, limit);
+}
+
+// src/index.ts
 function loadCliAuth() {
   const xdg = process.env.XDG_CONFIG_HOME;
   const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
@@ -19577,13 +19834,21 @@ var cliAuth = loadCliAuth();
 var TOKEN = process.env.LOGURO_TOKEN ?? cliAuth.token;
 var BASE_URL = (process.env.LOGURO_BASE_URL ?? cliAuth.baseUrl ?? "https://logu.ro").replace(/\/$/, "");
 var DEFAULT_PROJECT = process.env.LOGURO_PROJECT;
+var ENV_TRUNCATE_LIMIT = (() => {
+  const raw = process.env.LOGURO_TRUNCATE_LIMIT;
+  if (!raw)
+    return 500;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 500;
+})();
+var TRUNCATABLE_TOP_FIELDS = ["message", "stack", "stackTrace", "error", "errorMessage", "raw", "body"];
 if (!TOKEN) {
   process.stderr.write("Error: no PAT found. Run `loguro login` first, or set LOGURO_TOKEN env var.\n");
   process.exit(1);
 }
-var USER_AGENT = `loguro-mcp/1.0.0 (node/${process.version})`;
+var USER_AGENT2 = `loguro-mcp/1.0.0 (node/${process.version})`;
 var REQUEST_TIMEOUT_MS = 15000;
-async function logsRequest(project, params) {
+function buildQS(params) {
   const qs = new URLSearchParams;
   for (const [key, value] of Object.entries(params)) {
     if (value === undefined || value === null)
@@ -19595,11 +19860,34 @@ async function logsRequest(project, params) {
       qs.set(key, String(value));
     }
   }
-  const url = `${BASE_URL}/api/logs/${encodeURIComponent(project)}?${qs}`;
+  return qs;
+}
+async function logsRequest(project, params) {
+  const url = `${BASE_URL}/api/logs/${encodeURIComponent(project)}?${buildQS(params)}`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${TOKEN}`,
+      "User-Agent": USER_AGENT2,
+      Accept: "application/json"
+    },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Loguro API error ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+async function logsSubRequest(project, subPath, params, method = "GET") {
+  const sub = subPath.startsWith("/") ? subPath : "/" + subPath;
+  const qs = buildQS(params);
+  const hasQuery = Array.from(qs.keys()).length > 0;
+  const url = `${BASE_URL}/api/logs/${encodeURIComponent(project)}${sub}${method === "GET" && hasQuery ? `?${qs}` : ""}`;
   const res = await fetch(url, {
+    method,
     headers: {
       Authorization: `Bearer ${TOKEN}`,
-      "User-Agent": USER_AGENT,
+      "User-Agent": USER_AGENT2,
       Accept: "application/json"
     },
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
@@ -19610,6 +19898,30 @@ async function logsRequest(project, params) {
   }
   return res.json();
 }
+async function apiRequest(method, path, body) {
+  const url = `${BASE_URL}${path.startsWith("/") ? path : "/" + path}`;
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${TOKEN}`,
+      "User-Agent": USER_AGENT2,
+      Accept: "application/json",
+      ...body !== undefined ? { "Content-Type": "application/json" } : {}
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  const text = await res.text();
+  let data = text;
+  try {
+    data = text.length > 0 ? JSON.parse(text) : undefined;
+  } catch {}
+  if (!res.ok) {
+    const msg = data && data.error || data && data.message || text || `HTTP ${res.status}`;
+    throw new Error(`Loguro API error ${res.status}: ${msg}`);
+  }
+  return data;
+}
 function jsonResult(data, summary) {
   const content = [];
   if (summary)
@@ -19661,7 +19973,10 @@ server.tool("query_logs", "Query logs from a Loguro project with filters. Use th
   perPage: exports_external.number().default(20).describe("Results per page (default 20, max 1000)"),
   cursor: exports_external.string().optional().describe("Pagination cursor from previous response"),
   offset: exports_external.number().optional().describe("Alternative to cursor: numeric offset"),
-  order: exports_external.enum(["asc", "desc"]).default("desc").describe("Sort order by timestamp")
+  order: exports_external.enum(["asc", "desc"]).default("desc").describe("Sort order by timestamp"),
+  fields: exports_external.array(exports_external.string()).optional().describe("Project only these top-level fields on each log (e.g. ['id','timestamp','level','message']). Omit for full payload. Applied client-side."),
+  truncateContext: exports_external.boolean().default(true).describe(`Truncate long context values and known long top-level fields (${TRUNCATABLE_TOP_FIELDS.join(", ")}) to prevent LLM context overflow. Set false for raw payload.`),
+  truncateLimit: exports_external.number().default(ENV_TRUNCATE_LIMIT).describe(`Char limit when truncateContext=true. Default ${ENV_TRUNCATE_LIMIT} (override via LOGURO_TRUNCATE_LIMIT env var).`)
 }, async (args) => {
   const params = {
     perPage: args.perPage,
@@ -19701,11 +20016,68 @@ server.tool("query_logs", "Query logs from a Loguro project with filters. Use th
     params["offset"] = args.offset;
   applyContextFilters(params, args.context);
   const data = await logsRequest(args.project, params);
+  let truncated = 0;
+  let projected = 0;
+  const truncateStr = (s) => s.length > args.truncateLimit ? s.slice(0, args.truncateLimit) + `…[truncated ${s.length - args.truncateLimit}ch]` : s;
+  if (Array.isArray(data.items)) {
+    data.items = data.items.map((item) => {
+      let out = item;
+      if (args.truncateContext) {
+        const patched = { ...out };
+        for (const f of TRUNCATABLE_TOP_FIELDS) {
+          const v = patched[f];
+          if (typeof v === "string" && v.length > args.truncateLimit) {
+            patched[f] = truncateStr(v);
+            truncated++;
+          }
+        }
+        if (patched.context && typeof patched.context === "object") {
+          const newCtx = {};
+          for (const [k, v] of Object.entries(patched.context)) {
+            if (typeof v === "string" && v.length > args.truncateLimit) {
+              newCtx[k] = truncateStr(v);
+              truncated++;
+            } else if (v && typeof v === "object") {
+              const serialized = JSON.stringify(v);
+              if (serialized.length > args.truncateLimit) {
+                newCtx[k] = truncateStr(serialized);
+                truncated++;
+              } else {
+                newCtx[k] = v;
+              }
+            } else {
+              newCtx[k] = v;
+            }
+          }
+          patched.context = newCtx;
+        }
+        out = patched;
+      }
+      if (args.fields?.length) {
+        const projectedItem = {};
+        for (const f of args.fields) {
+          if (f in out)
+            projectedItem[f] = out[f];
+        }
+        out = projectedItem;
+        projected++;
+      }
+      return out;
+    });
+  }
+  const meta = {};
+  if (truncated > 0)
+    meta["_truncatedFields"] = truncated;
+  if (projected > 0)
+    meta["_projectedItems"] = projected;
+  if (args.fields?.length)
+    meta["_fields"] = args.fields;
   const summary = [
     `Found ${data.items?.length ?? 0} logs${data.hasMorePages ? " (more available)" : ""}`,
-    data.nextCursor ? `nextCursor: ${data.nextCursor}` : null
+    data.nextCursor ? `nextCursor: ${data.nextCursor}` : null,
+    truncated > 0 ? `truncated ${truncated} long context values` : null
   ].filter(Boolean).join(" | ");
-  return jsonResult(data, summary);
+  return jsonResult({ ...data, ...meta }, summary);
 });
 server.tool("get_log_timeline", "Get logs surrounding a specific log ID within a time window. Useful for understanding context around an error.", {
   project: projectParam(),
@@ -19772,5 +20144,476 @@ server.tool("sample_logs", "Get a random sample of logs, optionally filtered. Go
   const data = await logsRequest(project, params);
   return jsonResult(data);
 });
+var timeRangeSchema = {
+  from: exports_external.string().optional().describe("Start of range (ISO 8601). Relative shortcuts must be resolved client-side."),
+  to: exports_external.string().optional().describe("End of range (ISO 8601)")
+};
+var DEFAULT_DEPLOY_PATTERNS = [
+  "Deployment completed",
+  "deploy finished",
+  "Migration ran",
+  "schema updated",
+  "Service started",
+  "Server listening",
+  "Build completed",
+  "Release tagged"
+];
+var ENV_DEPLOY_PATTERNS = (process.env.LOGURO_DEPLOY_PATTERNS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+server.tool("deploy_markers", "Find deploy/migration/restart signals in logs via message pattern match. Useful as anchor points for compare_windows (before/after deploy). Default patterns cover common signals; override with `patterns` param or LOGURO_DEPLOY_PATTERNS env var.", {
+  project: projectParam(),
+  patterns: exports_external.array(exports_external.string()).optional().describe("Override default patterns. Each = substring match on message (OR). Defaults: Deployment completed, deploy finished, Migration ran, schema updated, Service started, Server listening, Build completed, Release tagged."),
+  from: exports_external.string().optional().describe("Start of range (ISO 8601). Default: last 7 days."),
+  to: exports_external.string().optional().describe("End of range (ISO 8601)"),
+  limit: exports_external.number().default(50).describe("Max markers to return")
+}, async ({ project, patterns, from, to, limit }) => {
+  const effectivePatterns = patterns?.length ? patterns : ENV_DEPLOY_PATTERNS.length ? ENV_DEPLOY_PATTERNS : DEFAULT_DEPLOY_PATTERNS;
+  const params = {
+    message: effectivePatterns,
+    perPage: Math.min(limit, 100),
+    order: "desc"
+  };
+  if (from)
+    params["from"] = from;
+  else
+    params["from"] = new Date(Date.now() - 7 * 86400000).toISOString();
+  if (to)
+    params["to"] = to;
+  const data = await logsRequest(project, params);
+  const markers = (data.items ?? []).map((item) => {
+    const message = String(item.message ?? "");
+    const matchedPattern = effectivePatterns.find((p) => message.toLowerCase().includes(p.toLowerCase())) ?? null;
+    return {
+      id: item.id,
+      timestamp: item.timestamp,
+      level: item.level,
+      message,
+      matchedPattern,
+      context: item.context ?? null
+    };
+  });
+  const summary = markers.length === 0 ? `No deploy markers found (searched ${effectivePatterns.length} pattern(s))` : `Found ${markers.length} deploy marker(s) — latest: ${markers[0]?.timestamp ?? "?"} (${markers[0]?.matchedPattern ?? "?"})`;
+  return jsonResult({
+    markers,
+    patternsUsed: effectivePatterns,
+    patternSource: patterns?.length ? "param" : ENV_DEPLOY_PATTERNS.length ? "env" : "default",
+    hasMore: data.hasMorePages ?? false
+  }, summary);
+});
+server.tool("get_latest", "Fetch the single most recent log matching optional filters. Anchor point for 'when did X last happen?' queries. Returns { items: [log] } with at most 1 entry, plus nextCursor for paging back.", {
+  project: projectParam(),
+  level: exports_external.array(exports_external.string()).optional(),
+  notLevel: exports_external.array(exports_external.string()).optional(),
+  message: exports_external.array(exports_external.string()).optional(),
+  notMessage: exports_external.array(exports_external.string()).optional(),
+  search: exports_external.string().optional(),
+  trace: exports_external.array(exports_external.string()).optional(),
+  slow: exports_external.number().optional().describe("Latest log where context.duration > N ms"),
+  context: contextFilterSchema
+}, async (args) => {
+  const params = {
+    perPage: 1,
+    order: "desc"
+  };
+  if (args.level?.length)
+    params["level"] = args.level;
+  if (args.notLevel?.length)
+    params["notLevel"] = args.notLevel;
+  if (args.message?.length)
+    params["message"] = args.message;
+  if (args.notMessage?.length)
+    params["notMessage"] = args.notMessage;
+  if (args.search)
+    params["search"] = args.search;
+  if (args.trace?.length)
+    params["trace"] = args.trace;
+  if (args.slow !== undefined)
+    params["slow"] = args.slow;
+  applyContextFilters(params, args.context);
+  const data = await logsRequest(args.project, params);
+  const latest = data.items?.[0];
+  const summary = latest ? `Latest: ${latest.level ?? "?"} @ ${latest.timestamp ?? "?"} — ${(latest.message ?? "").slice(0, 80)}` : "No logs matched filters";
+  return jsonResult(data, summary);
+});
+server.tool("count_logs", "Get the count of logs matching filters. Cheap pre-flight before running large queries. Returns { count: number }.", {
+  project: projectParam(),
+  level: exports_external.array(exports_external.string()).optional(),
+  notLevel: exports_external.array(exports_external.string()).optional(),
+  message: exports_external.array(exports_external.string()).optional(),
+  notMessage: exports_external.array(exports_external.string()).optional(),
+  search: exports_external.string().optional(),
+  ...timeRangeSchema,
+  context: contextFilterSchema,
+  unfiltered: exports_external.boolean().default(false).describe("If true, return total project count (ignores filters). Uses /count instead of /count-filtered.")
+}, async (args) => {
+  if (args.unfiltered) {
+    const data2 = await logsSubRequest(args.project, "/count", {}, "POST");
+    return jsonResult(data2, `Total logs in project: ${data2.count}`);
+  }
+  const params = {};
+  if (args.level?.length)
+    params["level"] = args.level;
+  if (args.notLevel?.length)
+    params["notLevel"] = args.notLevel;
+  if (args.message?.length)
+    params["message"] = args.message;
+  if (args.notMessage?.length)
+    params["notMessage"] = args.notMessage;
+  if (args.search)
+    params["search"] = args.search;
+  if (args.from)
+    params["from"] = args.from;
+  if (args.to)
+    params["to"] = args.to;
+  applyContextFilters(params, args.context);
+  const data = await logsSubRequest(args.project, "/count-filtered", params);
+  return jsonResult(data, `Matching logs: ${data.count}`);
+});
+server.tool("get_log", "Fetch a single log by its ULID. Returns the full log entry plus prev/next pointers for navigation.", {
+  project: projectParam(),
+  logId: exports_external.string().describe("ULID of the log")
+}, async ({ project, logId }) => {
+  const data = await logsSubRequest(project, `/one/${encodeURIComponent(logId)}`, {});
+  return jsonResult(data);
+});
+server.tool("expand_log", "Get a log with fully expanded context and related logs. Best tool for root cause analysis on a specific error.", {
+  project: projectParam(),
+  logId: exports_external.string().describe("ULID of the log")
+}, async ({ project, logId }) => {
+  const data = await logsSubRequest(project, `/${encodeURIComponent(logId)}/expanded`, {});
+  return jsonResult(data);
+});
+server.tool("log_occurrences", "How many times has this log message recurred? Returns timestamps of recent occurrences plus total count.", {
+  project: projectParam(),
+  logId: exports_external.string().describe("ULID of the log"),
+  limit: exports_external.number().default(50).describe("Max occurrences to return")
+}, async ({ project, logId, limit }) => {
+  const data = await logsSubRequest(project, `/${encodeURIComponent(logId)}/occurrences`, { limit });
+  return jsonResult(data, `Total occurrences: ${data.total ?? data.occurrences?.length ?? 0}`);
+});
+server.tool("top_field", "Top values for a field ranked by count. Use to find top errors (field=message), top services, top users, etc.", {
+  project: projectParam(),
+  field: exports_external.string().describe("Field to rank: level, message, trace, or a context column name"),
+  limit: exports_external.number().min(1).max(100).default(10),
+  level: exports_external.array(exports_external.string()).optional(),
+  ...timeRangeSchema
+}, async ({ project, field, limit, level, from, to }) => {
+  const params = { field, limit };
+  if (level?.length)
+    params["level"] = level;
+  if (from)
+    params["from"] = from;
+  if (to)
+    params["to"] = to;
+  const data = await logsSubRequest(project, "/top-field", params);
+  return jsonResult(data);
+});
+server.tool("unique_field", "Distinct values for a field with counts. Similar to top_field but returns all unique values up to limit.", {
+  project: projectParam(),
+  field: exports_external.string(),
+  limit: exports_external.number().default(50)
+}, async ({ project, field, limit }) => {
+  const data = await logsSubRequest(project, "/unique-field", { field, limit });
+  return jsonResult(data);
+});
+function parseBucketDateMs(date4) {
+  if (date4.includes(" ") || date4.includes("T")) {
+    return new Date(date4.replace(" ", "T") + (date4.endsWith("Z") ? "" : "Z")).getTime();
+  }
+  return new Date(date4 + "T00:00:00Z").getTime();
+}
+function rollupToHour(timeline) {
+  const buckets = new Map;
+  for (const entry of timeline) {
+    const ms = parseBucketDateMs(entry.date);
+    const hourMs = Math.floor(ms / 3600000) * 3600000;
+    const acc = buckets.get(hourMs);
+    if (acc) {
+      acc.count += Number(entry.count) || 0;
+      acc.error += Number(entry.error) || 0;
+      acc.warning += Number(entry.warning) || 0;
+      acc.info += Number(entry.info) || 0;
+      acc.debug += Number(entry.debug) || 0;
+      acc.critical += Number(entry.critical) || 0;
+    } else {
+      const iso = new Date(hourMs).toISOString();
+      buckets.set(hourMs, {
+        date: `${iso.slice(0, 13)}:00:00`,
+        count: Number(entry.count) || 0,
+        error: Number(entry.error) || 0,
+        warning: Number(entry.warning) || 0,
+        info: Number(entry.info) || 0,
+        debug: Number(entry.debug) || 0,
+        critical: Number(entry.critical) || 0
+      });
+    }
+  }
+  return [...buckets.entries()].sort((a, b) => b[0] - a[0]).map(([, v]) => v);
+}
+function deriveAggregatesFromTimeline(timeline) {
+  const now = new Date;
+  const todayUtc = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}-${String(now.getUTCDate()).padStart(2, "0")}`;
+  const y = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - 1));
+  const yesterdayUtc = `${y.getUTCFullYear()}-${String(y.getUTCMonth() + 1).padStart(2, "0")}-${String(y.getUTCDate()).padStart(2, "0")}`;
+  let totalCount = 0;
+  let todayCount = 0;
+  let yesterdayCount = 0;
+  const levels = { error: 0, warning: 0, info: 0, debug: 0, critical: 0 };
+  for (const e of timeline) {
+    const count = Number(e.count) || 0;
+    totalCount += count;
+    const datePrefix = e.date.slice(0, 10);
+    if (datePrefix === todayUtc)
+      todayCount += count;
+    else if (datePrefix === yesterdayUtc)
+      yesterdayCount += count;
+    levels.error += Number(e.error) || 0;
+    levels.warning += Number(e.warning) || 0;
+    levels.info += Number(e.info) || 0;
+    levels.debug += Number(e.debug) || 0;
+    levels.critical += Number(e.critical) || 0;
+  }
+  const byLevel = Object.entries(levels).filter(([, c]) => c > 0).map(([level, count]) => ({ level, count })).sort((a, b) => b.count - a.count);
+  return { totalCount, todayCount, yesterdayCount, byLevel };
+}
+server.tool("histogram", "Time-bucketed log counts with level breakdown. day = daily timeline + full header aggregates (totalCount/byLevel/topErrors/topServices). hour = minute buckets rolled up to HH:00 client-side; totalCount + byLevel derived from timeline. minute = raw passthrough (~1440 buckets/day; max 24h range). For hour/minute, topErrors/topServices/topEndpoints require raw-log aggregates — use top_field with field='message'/'service'/'context.url' to fetch them separately.", {
+  project: projectParam(),
+  ...timeRangeSchema,
+  granularity: exports_external.enum(["day", "hour", "minute"]).default("hour").describe("day = daily timeline. hour = rolled up to HH:00. minute = raw (~1440/day, narrow ranges only)."),
+  level: exports_external.array(exports_external.string()).optional(),
+  message: exports_external.array(exports_external.string()).optional()
+}, async ({ project, from, to, granularity, level, message }) => {
+  if (granularity === "minute") {
+    const fromMs = from ? new Date(from).getTime() : Date.now() - 24 * 3600000;
+    const toMs = to ? new Date(to).getTime() : Date.now();
+    const rangeHours = (toMs - fromMs) / 3600000;
+    if (rangeHours > 24) {
+      throw new Error(`Range too wide for granularity=minute (${rangeHours.toFixed(1)}h, max 24h). Use granularity=hour or narrow the range.`);
+    }
+  }
+  const params = {};
+  if (from)
+    params["from"] = from;
+  if (to)
+    params["to"] = to;
+  if (granularity !== "day")
+    params["granularity"] = "hour";
+  if (level?.length)
+    params["level"] = level;
+  if (message?.length)
+    params["message"] = message;
+  const data = await logsSubRequest(project, "/analytics", params);
+  if (granularity === "day") {
+    return jsonResult(data);
+  }
+  const rawTimeline = Array.isArray(data?.timeline) ? data.timeline : [];
+  const timeline = granularity === "hour" ? rollupToHour(rawTimeline) : rawTimeline;
+  const { totalCount, todayCount, yesterdayCount, byLevel } = deriveAggregatesFromTimeline(rawTimeline);
+  return jsonResult({
+    ...data,
+    timeline,
+    totalCount,
+    todayCount,
+    yesterdayCount,
+    byLevel,
+    topErrors: null,
+    topServices: null,
+    topEndpoints: null,
+    _granularity: granularity,
+    _aggregateSource: "derived-from-timeline",
+    _aggregateLimitations: "topErrors/topServices/topEndpoints require raw-log aggregates — call top_field separately if needed",
+    _rawBucketCount: rawTimeline.length
+  });
+});
+server.tool("rate", "Logs-per-hour breakdown over a time range. Returns { buckets: [{ hour, count, ... }] }. Bucket size is fixed at 1 hour server-side. Use histogram with granularity=hour for level breakdown per bucket.", {
+  project: projectParam(),
+  ...timeRangeSchema,
+  level: exports_external.array(exports_external.string()).optional(),
+  notLevel: exports_external.array(exports_external.string()).optional(),
+  message: exports_external.array(exports_external.string()).optional(),
+  notMessage: exports_external.array(exports_external.string()).optional()
+}, async ({ project, from, to, level, notLevel, message, notMessage }) => {
+  const params = {};
+  if (from)
+    params["from"] = from;
+  if (to)
+    params["to"] = to;
+  if (level?.length)
+    params["level"] = level;
+  if (notLevel?.length)
+    params["notLevel"] = notLevel;
+  if (message?.length)
+    params["message"] = message;
+  if (notMessage?.length)
+    params["notMessage"] = notMessage;
+  const data = await logsSubRequest(project, "/rate", params);
+  return jsonResult(data);
+});
+server.tool("health_trend", "Error-rate snapshot: last 20 minutes vs previous 20 minutes. Time window is fixed server-side. Returns raw { current, previous, totalCurrent, totalPrevious } where current/previous are error ratios (0..1). MCP-derived: status + trend.", {
+  project: projectParam()
+}, async ({ project }) => {
+  const data = await logsSubRequest(project, "/health-trend", {});
+  const current = Number(data.current ?? 0);
+  const previous = Number(data.previous ?? 0);
+  const totalCurrent = Number(data.totalCurrent ?? 0);
+  const totalPrevious = Number(data.totalPrevious ?? 0);
+  let status;
+  if (totalCurrent === 0 && totalPrevious === 0)
+    status = "idle";
+  else if (current >= 0.2)
+    status = "critical";
+  else if (current >= 0.05)
+    status = "warning";
+  else
+    status = "healthy";
+  let trend;
+  const delta = current - previous;
+  if (Math.abs(delta) < 0.01)
+    trend = "stable";
+  else
+    trend = delta > 0 ? "degrading" : "improving";
+  const enriched = {
+    current,
+    previous,
+    totalCurrent,
+    totalPrevious,
+    errorRatePct: { current: +(current * 100).toFixed(2), previous: +(previous * 100).toFixed(2) },
+    status,
+    trend,
+    window: "last 20 minutes vs previous 20 minutes (server-fixed)"
+  };
+  const summary = `Status: ${status} | Trend: ${trend} | Error rate: ${enriched.errorRatePct.current}% (was ${enriched.errorRatePct.previous}%) | Volume: ${totalCurrent} vs ${totalPrevious}`;
+  return jsonResult(enriched, summary);
+});
+server.tool("compare_windows", "Diff two time windows. Highlights new, spiking, and dropped log patterns. Server parses windows with chrono — supply either a chrono phrase OR explicit ISO from/to pairs (preferred for precise sub-day ranges).", {
+  project: projectParam(),
+  baseline: exports_external.string().optional().describe("Baseline as chrono phrase: 'yesterday', '2 days ago', 'last week'. Omit if using baselineFrom/baselineTo."),
+  baselineFrom: exports_external.string().optional().describe("Baseline start (ISO 8601 with timezone, e.g. 2026-05-12T19:00:00Z)"),
+  baselineTo: exports_external.string().optional().describe("Baseline end (ISO 8601 with timezone)"),
+  comparison: exports_external.string().optional().describe("Comparison as chrono phrase. Omit if using comparisonFrom/comparisonTo or defaulting to 'now'."),
+  comparisonFrom: exports_external.string().optional().describe("Comparison start (ISO 8601 with timezone)"),
+  comparisonTo: exports_external.string().optional().describe("Comparison end (ISO 8601 with timezone)"),
+  spikeThreshold: exports_external.number().default(200).describe("% growth to flag as spike"),
+  dropThreshold: exports_external.number().default(50).describe("% decline to flag as drop")
+}, async (args) => {
+  const buildExpr = (phrase, from, to) => {
+    if (phrase)
+      return phrase;
+    if (from && to)
+      return `${from} to ${to}`;
+    if (from || to) {
+      throw new Error("ISO range requires both *From and *To (got only one).");
+    }
+    return;
+  };
+  const baselineExpr = buildExpr(args.baseline, args.baselineFrom, args.baselineTo);
+  const comparisonExpr = buildExpr(args.comparison, args.comparisonFrom, args.comparisonTo);
+  if (!baselineExpr) {
+    throw new Error("baseline required: provide either `baseline` phrase or `baselineFrom`+`baselineTo` ISO pair.");
+  }
+  const params = {
+    diff_baseline: baselineExpr,
+    diff_spike_threshold: args.spikeThreshold,
+    diff_drop_threshold: args.dropThreshold
+  };
+  if (comparisonExpr)
+    params["diff_comparison"] = comparisonExpr;
+  const data = await logsSubRequest(args.project, "/diff", params);
+  const patterns = Array.isArray(data?.patterns) ? data.patterns : [];
+  const newCount = patterns.filter((p) => p.status === "new").length;
+  const spikeCount = patterns.filter((p) => p.status === "spike").length;
+  const dropCount = patterns.filter((p) => p.status === "dropped").length;
+  const baseTotal = Number(data?.baseline?.totalCount) || 0;
+  const compTotal = Number(data?.comparison?.totalCount) || 0;
+  const volumeDelta = baseTotal > 0 ? `${compTotal > baseTotal ? "+" : ""}${Math.round((compTotal - baseTotal) / baseTotal * 100)}%` : "n/a";
+  const topChange = patterns[0];
+  const topChangeStr = topChange ? ` | top: ${topChange.status} ${topChange.change} "${String(topChange.message).slice(0, 50)}"` : "";
+  const summary = `Volume: ${baseTotal} → ${compTotal} (${volumeDelta}) | Patterns: ${newCount} new, ${spikeCount} spike, ${dropCount} dropped${topChangeStr}`;
+  return jsonResult(data, summary);
+});
+server.tool("context_discovery", "List all context field keys present in this project with sample values. Call this FIRST when you don't know what fields exist.", {
+  project: projectParam()
+}, async ({ project }) => {
+  const data = await logsSubRequest(project, "/context-discovery", {});
+  return jsonResult(data);
+});
+server.tool("context_field_values", "Sample values for a specific context field. Use after context_discovery to see what values a field actually contains.", {
+  project: projectParam(),
+  field: exports_external.string().describe("Context field key (without the context_ prefix)"),
+  limit: exports_external.number().default(50)
+}, async ({ project, field, limit }) => {
+  const data = await logsSubRequest(project, "/context-field-values", { field, limit });
+  return jsonResult(data);
+});
+server.tool("list_projects", "List all projects the user has access to. Use when LOGURO_PROJECT is not set or the user references a project by name.", {}, async () => {
+  const data = await apiRequest("GET", "/api/projects");
+  const projects = (data.projects ?? []).map((p) => ({
+    id: p.id,
+    slug: p.slug,
+    name: p.name,
+    description: p.description
+  }));
+  return jsonResult({ projects }, `Found ${projects.length} project(s)`);
+});
+server.tool("get_investigation", "Fetch a cached AI investigation for a log fingerprint, if one exists. Call before running a new investigation to avoid duplicate work.", {
+  projectId: exports_external.number().describe("Numeric project ID (use list_projects to resolve a slug to id)"),
+  fingerprint: exports_external.string().describe("Log fingerprint (normalized message hash)")
+}, async ({ projectId, fingerprint }) => {
+  const qs = new URLSearchParams({ projectId: String(projectId), fingerprint });
+  const data = await apiRequest("GET", `/api/plugins/investigate?${qs}`);
+  return jsonResult(data, data?.investigation ? "Cached investigation found" : "No cached investigation");
+});
+server.tool("check_investigated", "Batch check which fingerprints have cached AI investigations. Returns { investigated: string[] } — the subset with results.", {
+  project: projectParam(),
+  fingerprints: exports_external.array(exports_external.string()).min(1).describe("List of log fingerprints to check")
+}, async ({ project, fingerprints }) => {
+  const url = `${BASE_URL}/api/logs/${encodeURIComponent(project)}/investigations`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${TOKEN}`,
+      "User-Agent": USER_AGENT2,
+      Accept: "application/json",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ fingerprints }),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  if (!res.ok) {
+    throw new Error(`Loguro API error ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  return jsonResult(data, `Cached investigations: ${data.investigated?.length ?? 0}/${fingerprints.length}`);
+});
+server.tool("list_docs", "Browse the Loguro documentation catalog. Returns titles + paths grouped by section. Call without args to see everything; pass `section` to filter. Use `read_doc` to fetch full content of a page.", {
+  section: exports_external.string().optional().describe("Filter by section: General, CLI, Commands, Features, MCP, TUI, Web Analytics")
+}, async ({ section }) => {
+  const docs = listDocs(section);
+  const sections = listSections();
+  const grouped = {};
+  for (const d of docs) {
+    if (!grouped[d.section])
+      grouped[d.section] = [];
+    grouped[d.section].push({ path: d.path, title: d.title, headings: d.headings });
+  }
+  const summary = section ? `${docs.length} page(s) in section "${section}"` : `${docs.length} pages across ${sections.length} sections: ${sections.map((s) => `${s.section} (${s.count})`).join(", ")}`;
+  return jsonResult({ sections, docs: grouped }, summary);
+});
+server.tool("search_docs", "Search Loguro documentation by keyword. Fetches all docs on first call (cached 15min), then scores matches across title, section, headings, and body. Returns top hits with snippets. Use this when you don't know which page covers a topic.", {
+  query: exports_external.string().min(1).describe("Search terms — natural words, not regex. E.g. 'how do alerts work', 'PAT token', 'context filter'."),
+  limit: exports_external.number().min(1).max(20).default(5).describe("Max results (default 5)")
+}, async ({ query, limit }) => {
+  const hits = await searchDocs(query, limit);
+  const summary = hits.length === 0 ? `No matches for "${query}"` : `Top ${hits.length} hit(s) for "${query}" — best: ${hits[0].title} (${hits[0].section}) score=${hits[0].score}`;
+  return jsonResult({ query, hits }, summary);
+});
+server.tool("read_doc", "Fetch the full markdown body of a documentation page by its path (e.g. '/docs/cli/alerts'). Use after `search_docs` or `list_docs` to read a specific page end-to-end.", {
+  path: exports_external.string().describe("Doc path starting with /docs/ — e.g. /docs/mcp/setup"),
+  refresh: exports_external.boolean().default(false).describe("Bypass the 15min cache and refetch from logu.ro")
+}, async ({ path, refresh }) => {
+  const normalized = path.startsWith("/") ? path : "/" + path;
+  const doc2 = await fetchDoc(normalized, refresh);
+  const summary = `${normalized} (${doc2.body.length} chars, ${doc2.headings.length} heading(s))`;
+  return jsonResult({ path: normalized, headings: doc2.headings, body: doc2.body, fetchedAt: new Date(doc2.fetchedAt).toISOString() }, summary);
+});
 var transport = new StdioServerTransport;
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loguro/mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server for Loguro — query logs from Claude Code, Cursor, and other MCP-compatible AI tools. Reuses the CLI's saved auth (zero config).",
   "keywords": [
     "loguro",