@langwatch/mcp-server 2.0.0 → 2.2.0

package/src/tools/get-analytics.ts

@@ -1,13 +1,10 @@
-import type { AnalyticsBucket } from "../langwatch-api.js";
-import { getAnalyticsTimeseries as apiGetAnalytics } from "../langwatch-api.js";
-import { parseRelativeDate } from "../utils/date-parsing.js";
+import type { AnalyticsBucket } from "../langwatch-api.ts";
+import { getAnalyticsTimeseries as apiGetAnalytics } from "../langwatch-api.ts";
+import { parseRelativeDate } from "../utils/date-parsing.ts";
 
 type GroupedData = Record<string, Record<string, number>>;
 
-function getGroupedData(
-  bucket: AnalyticsBucket,
-  groupBy: string,
-): GroupedData | undefined {
+function getGroupedData(bucket: AnalyticsBucket, groupBy: string): GroupedData | undefined {
   const data = bucket[groupBy];
   if (typeof data === "object" && data !== null && !Array.isArray(data)) {
     return data as GroupedData;
@@ -15,11 +12,50 @@ function getGroupedData(
   return undefined;
 }
 
+function groupedPeriodTable({
+  currentPeriod,
+  groupBy,
+}: {
+  currentPeriod: AnalyticsBucket[];
+  groupBy: string;
+}): string[] {
+  const lines = ["| Date | Group | Value |", "|------|-------|-------|"];
+  for (const bucket of currentPeriod) {
+    const groups = getGroupedData(bucket, groupBy);
+    if (!groups) continue;
+    for (const [groupKey, metrics] of Object.entries(groups)) {
+      const value = Object.values(metrics).find((v) => typeof v === "number") ?? "N/A";
+      lines.push(`| ${bucket.date} | ${groupKey} | ${value} |`);
+    }
+  }
+  return lines;
+}
+
+function periodTable({
+  currentPeriod,
+  groupBy,
+}: {
+  currentPeriod: AnalyticsBucket[];
+  groupBy: string | undefined;
+}): string[] {
+  if (currentPeriod.length === 0) return ["No data available for this period."];
+  if (groupBy && currentPeriod.some((b) => getGroupedData(b, groupBy) !== undefined)) {
+    return groupedPeriodTable({ currentPeriod, groupBy });
+  }
+  const lines = ["| Date | Value |", "|------|-------|"];
+  for (const bucket of currentPeriod) {
+    const value =
+      Object.entries(bucket)
+        .map(([k, v]) => (k !== "date" && typeof v === "number" ? v : undefined))
+        .find((v) => v !== undefined) ?? "N/A";
+    lines.push(`| ${bucket.date} | ${value} |`);
+  }
+  return lines;
+}
+
 /**
- * Handles the get_analytics MCP tool invocation.
- *
- * Queries analytics timeseries from LangWatch and formats the results
- * as an AI-readable markdown table.
+ * Handles the get_analytics MCP tool: queries analytics timeseries and
+ * formats them as an AI-readable markdown table.
  */
 export async function handleGetAnalytics(params: {
   metric: string;
@@ -31,9 +67,7 @@ export async function handleGetAnalytics(params: {
   filters?: Record<string, string[]>;
 }): Promise<string> {
   const now = Date.now();
-  const startDate = params.startDate
-    ? parseRelativeDate(params.startDate)
-    : now - 7 * 86400000;
+  const startDate = params.startDate ? parseRelativeDate(params.startDate) : now - 7 * 86400000;
   const endDate = params.endDate ? parseRelativeDate(params.endDate) : now;
 
   // Parse metric format "category.name"
@@ -55,44 +89,16 @@ export async function handleGetAnalytics(params: {
   const lines: string[] = [];
   lines.push(`# Analytics: ${metricKey} (${aggregation})\n`);
   lines.push(
-    `Period: ${new Date(startDate).toISOString().split("T")[0]} to ${new Date(endDate).toISOString().split("T")[0]}`
+    `Period: ${new Date(startDate).toISOString().split("T")[0]} to ${new Date(endDate).toISOString().split("T")[0]}`,
   );
   if (params.groupBy) lines.push(`Grouped by: ${params.groupBy}`);
   lines.push("");
 
-  const currentPeriod = result.currentPeriod ?? [];
-  if (currentPeriod.length === 0) {
-    lines.push("No data available for this period.");
-  } else if (
-    params.groupBy &&
-    currentPeriod.some((b) => getGroupedData(b, params.groupBy!) !== undefined)
-  ) {
-    lines.push("| Date | Group | Value |");
-    lines.push("|------|-------|-------|");
-    for (const bucket of currentPeriod) {
-      const groups = getGroupedData(bucket, params.groupBy);
-      if (!groups) continue;
-      for (const [groupKey, metrics] of Object.entries(groups)) {
-        const value =
-          Object.values(metrics).find((v) => typeof v === "number") ?? "N/A";
-        lines.push(`| ${bucket.date} | ${groupKey} | ${value} |`);
-      }
-    }
-  } else {
-    lines.push("| Date | Value |");
-    lines.push("|------|-------|");
-    for (const bucket of currentPeriod) {
-      const value =
-        Object.entries(bucket).find(
-          ([k]) => k !== "date" && typeof bucket[k] === "number"
-        )?.[1] ?? "N/A";
-      lines.push(`| ${bucket.date} | ${value} |`);
-    }
-  }
-
   lines.push(
-    "\n> Tip: Use `discover_schema` to see all available metrics and aggregation types."
+    ...periodTable({ currentPeriod: result.currentPeriod ?? [], groupBy: params.groupBy }),
   );
 
+  lines.push("\n> Tip: Use `discover_schema` to see all available metrics and aggregation types.");
+
   return lines.join("\n");
 }

package/src/tools/get-dashboard.ts

@@ -1,4 +1,4 @@
-import { getDashboard as apiGetDashboard } from "../langwatch-api-dashboards.js";
+import { getDashboard as apiGetDashboard } from "../langwatch-api-dashboards.ts";
 
 export async function handleGetDashboard(params: { id: string }): Promise<string> {
   const dashboard = await apiGetDashboard(params.id);

package/src/tools/get-dataset.ts

@@ -1,27 +1,24 @@
 import {
+  DATASET_PREVIEW_MAX_BYTES,
+  DATASET_PREVIEW_MAX_RECORDS,
   getDataset as apiGetDataset,
   type DatasetDetailResponse,
-} from "../langwatch-api-datasets.js";
-import { escapeMarkdown } from "../utils/escape-markdown.js";
+} from "../langwatch-api-datasets.ts";
+import { escapeMarkdown } from "../utils/escape-markdown.ts";
 
 /**
  * Formats a dataset detail response into AI-readable markdown.
  *
  * Exported for unit testing.
  */
-export function formatDatasetResponse(
-  dataset: DatasetDetailResponse,
-): string {
+export function formatDatasetResponse(dataset: DatasetDetailResponse): string {
   const lines: string[] = [];
   lines.push(`# Dataset: ${escapeMarkdown(dataset.name)}\n`);
   lines.push(`**Slug**: ${escapeMarkdown(dataset.slug)}`);
   lines.push(`**ID**: ${escapeMarkdown(dataset.id)}`);
 
   // Column table
-  if (
-    Array.isArray(dataset.columnTypes) &&
-    dataset.columnTypes.length > 0
-  ) {
+  if (Array.isArray(dataset.columnTypes) && dataset.columnTypes.length > 0) {
     lines.push("\n## Columns\n");
     lines.push("| Name | Type |");
     lines.push("|------|------|");
@@ -34,20 +31,40 @@ export function formatDatasetResponse(
   if (Array.isArray(dataset.data) && dataset.data.length > 0) {
     lines.push(`\n## Records (${dataset.data.length} shown)\n`);
     for (const record of dataset.data) {
-      lines.push(`**${escapeMarkdown(record.id)}**: ${escapeMarkdown(JSON.stringify(record.entry))}`);
+      lines.push(
+        `**${escapeMarkdown(record.id)}**: ${escapeMarkdown(JSON.stringify(record.entry))}`,
+      );
     }
-  } else {
+  } else if (!dataset.omittedRecords) {
     lines.push("\nNo records in this dataset.");
   }
 
+  const note = omittedRecordsNote(dataset);
+  if (note) lines.push(`\n${note}`);
+
   return lines.join("\n");
 }
 
 /**
- * Handles the platform_get_dataset MCP tool invocation.
- *
- * Retrieves a specific dataset by slug or ID and formats it as
- * AI-readable markdown or raw JSON.
+ * Says how many records a preview leaves out and how to read them, or `undefined` when the
+ * preview holds every record.
+ */
+export function omittedRecordsNote(dataset: DatasetDetailResponse): string | undefined {
+  if (!dataset.omittedRecords) return undefined;
+
+  const shown = Array.isArray(dataset.data) ? dataset.data.length : 0;
+  const megabytes = DATASET_PREVIEW_MAX_BYTES / (1024 * 1024);
+  return (
+    `Showing ${shown} of ${dataset.totalRecords ?? shown + dataset.omittedRecords} records: ` +
+    `${dataset.omittedRecords} are left out. A preview holds at most ` +
+    `${DATASET_PREVIEW_MAX_RECORDS} records and ${megabytes} MB. ` +
+    "Read the rest with platform_list_dataset_records, using its page and limit parameters."
+  );
+}
+
+/**
+ * Handles the platform_get_dataset MCP tool: retrieves a dataset by
+ * slug or ID and formats it as AI-readable markdown or raw JSON.
  */
 export async function handleGetDataset(params: {
   slugOrId: string;
@@ -56,7 +73,8 @@ export async function handleGetDataset(params: {
   const dataset = await apiGetDataset(params.slugOrId);
 
   if (params.format === "json") {
-    return JSON.stringify(dataset, null, 2);
+    const note = omittedRecordsNote(dataset);
+    return JSON.stringify(note ? { ...dataset, note } : dataset, null, 2);
   }
 
   return formatDatasetResponse(dataset);

package/src/tools/get-evaluator.ts

@@ -1,17 +1,10 @@
-import {
-  getEvaluator as apiGetEvaluator,
-  getEvaluatorType,
-} from "../langwatch-api-evaluators.js";
+import { getEvaluator as apiGetEvaluator, getEvaluatorType } from "../langwatch-api-evaluators.ts";
 
 /**
- * Handles the platform_get_evaluator MCP tool invocation.
- *
- * Retrieves a specific evaluator by ID or slug and formats it as
- * AI-readable markdown.
+ * Handles the platform_get_evaluator MCP tool: retrieves an evaluator by
+ * ID or slug and formats it as AI-readable markdown.
  */
-export async function handleGetEvaluator(params: {
-  idOrSlug: string;
-}): Promise<string> {
+export async function handleGetEvaluator(params: { idOrSlug: string }): Promise<string> {
   const evaluator = await apiGetEvaluator(params.idOrSlug);
 
   const evaluatorType = getEvaluatorType(evaluator);