@langwatch/mcp-server 2.1.0 → 3.0.0

package/dist/{discover-schema-L6QDPON3.js → discover-schema-J2ANOBKO.js}

@@ -1,117 +1,83 @@
+import {
+  getQueryReference,
+  markdownTable
+} from "./chunk-GA5JUSPT.js";
+import "./chunk-FOKVY3BK.js";
+import "./chunk-7CZQDZ2K.js";
+import "./chunk-DULFP3MK.js";
 import "./chunk-SAS5OB7F.js";
 
-// src/schemas/filter-fields.ts
-var filterFields = [
-  {
-    field: "topics.topics",
-    description: "Main topic classification of the trace",
-    example: "billing"
-  },
-  {
-    field: "topics.subtopics",
-    description: "Subtopic classification",
-    example: "refund-request"
-  },
-  {
-    field: "metadata.user_id",
-    description: "User ID from trace metadata",
-    example: "user-123"
-  },
-  {
-    field: "metadata.thread_id",
-    description: "Conversation thread ID",
-    example: "thread-456"
-  },
-  {
-    field: "metadata.customer_id",
-    description: "Customer/organization ID",
-    example: "customer-789"
-  },
-  {
-    field: "metadata.labels",
-    description: "Custom labels attached to traces",
-    example: "production"
-  },
-  {
-    field: "metadata.key",
-    description: "Custom metadata key",
-    example: "environment"
-  },
-  {
-    field: "metadata.value",
-    description: "Custom metadata value (used with metadata.key)",
-    example: "staging"
-  },
-  {
-    field: "metadata.prompt_ids",
-    description: "Prompt IDs used in the trace"
-  },
-  {
-    field: "traces.error",
-    description: "Whether the trace has errors",
-    example: "true"
-  },
+// src/schemas/analytics-groups.ts
+var analyticsGroups = [
   {
-    field: "spans.type",
-    description: "Span type (llm, tool, agent, chain, rag)",
-    example: "llm"
+    name: "topics.topics",
+    label: "Topic",
+    description: "Group by topic classification"
   },
   {
-    field: "spans.model",
-    description: "LLM model name used in spans",
-    example: "gpt-4o"
+    name: "metadata.user_id",
+    label: "User",
+    description: "Group by user ID"
   },
   {
-    field: "evaluations.evaluator_id",
-    description: "Evaluator that ran on the trace"
+    name: "metadata.thread_id",
+    label: "Thread",
+    description: "Group by conversation thread"
   },
   {
-    field: "evaluations.evaluator_id.guardrails_only",
-    description: "Evaluator ID filtered to guardrails only"
+    name: "metadata.customer_id",
+    label: "Customer ID",
+    description: "Group by customer/organization"
   },
   {
-    field: "evaluations.passed",
-    description: "Whether evaluations passed",
-    example: "true"
+    name: "metadata.labels",
+    label: "Label",
+    description: "Group by custom labels"
   },
   {
-    field: "evaluations.score",
-    description: "Evaluation score (numeric)"
+    name: "metadata.model",
+    label: "Model",
+    description: "Group by LLM model name"
   },
   {
-    field: "evaluations.state",
-    description: "Evaluation state (processed, error, skipped)"
+    name: "metadata.span_type",
+    label: "Span Type",
+    description: "Group by span type (llm, tool, agent, etc.)"
   },
   {
-    field: "evaluations.label",
-    description: "Evaluation label result"
+    name: "sentiment.input_sentiment",
+    label: "Input Sentiment",
+    description: "Group by detected input sentiment (positive, negative, neutral)"
   },
   {
-    field: "events.event_type",
-    description: "Type of event (thumbs_up_down, custom)",
-    example: "thumbs_up_down"
+    name: "sentiment.thumbs_up_down",
+    label: "Thumbs Up/Down",
+    description: "Group by user feedback (positive, negative, neutral)"
   },
   {
-    field: "events.metrics.key",
-    description: "Event metric key"
+    name: "events.event_type",
+    label: "Event Type",
+    description: "Group by event type"
   },
   {
-    field: "events.metrics.value",
-    description: "Event metric value (numeric)"
+    name: "evaluations.evaluation_passed",
+    label: "Evaluation Passed",
+    description: "Group by evaluation pass/fail status"
   },
   {
-    field: "events.event_details.key",
-    description: "Event detail key"
+    name: "evaluations.evaluation_label",
+    label: "Evaluation Label",
+    description: "Group by evaluation label result"
   },
   {
-    field: "annotations.hasAnnotation",
-    description: "Whether trace has human annotations",
-    example: "true"
+    name: "evaluations.evaluation_processing_state",
+    label: "Evaluation Processing State",
+    description: "Group by evaluation processing state"
   },
   {
-    field: "sentiment.input_sentiment",
-    description: "Detected sentiment of input",
-    example: "positive"
+    name: "error.has_error",
+    label: "Contains Error",
+    description: "Group by whether the trace contains an error"
   }
 ];
 
@@ -234,17 +200,7 @@ var analyticsMetrics = [
     category: "events",
     name: "event_score",
     label: "Event Score",
-    allowedAggregations: [
-      "terms",
-      "avg",
-      "sum",
-      "min",
-      "max",
-      "median",
-      "p99",
-      "p95",
-      "p90"
-    ],
+    allowedAggregations: ["terms", "avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
     description: "Numeric score from events (requires event_type key and metrics key)"
   },
   {
@@ -286,85 +242,19 @@ var analyticsMetrics = [
   }
 ];
 
-// src/schemas/analytics-groups.ts
-var analyticsGroups = [
-  {
-    name: "topics.topics",
-    label: "Topic",
-    description: "Group by topic classification"
-  },
-  {
-    name: "metadata.user_id",
-    label: "User",
-    description: "Group by user ID"
-  },
-  {
-    name: "metadata.thread_id",
-    label: "Thread",
-    description: "Group by conversation thread"
-  },
-  {
-    name: "metadata.customer_id",
-    label: "Customer ID",
-    description: "Group by customer/organization"
-  },
-  {
-    name: "metadata.labels",
-    label: "Label",
-    description: "Group by custom labels"
-  },
-  {
-    name: "metadata.model",
-    label: "Model",
-    description: "Group by LLM model name"
-  },
-  {
-    name: "metadata.span_type",
-    label: "Span Type",
-    description: "Group by span type (llm, tool, agent, etc.)"
-  },
-  {
-    name: "sentiment.input_sentiment",
-    label: "Input Sentiment",
-    description: "Group by detected input sentiment (positive, negative, neutral)"
-  },
-  {
-    name: "sentiment.thumbs_up_down",
-    label: "Thumbs Up/Down",
-    description: "Group by user feedback (positive, negative, neutral)"
-  },
-  {
-    name: "events.event_type",
-    label: "Event Type",
-    description: "Group by event type"
-  },
-  {
-    name: "evaluations.evaluation_passed",
-    label: "Evaluation Passed",
-    description: "Group by evaluation pass/fail status"
-  },
-  {
-    name: "evaluations.evaluation_label",
-    label: "Evaluation Label",
-    description: "Group by evaluation label result"
-  },
-  {
-    name: "evaluations.evaluation_processing_state",
-    label: "Evaluation Processing State",
-    description: "Group by evaluation processing state"
-  },
-  {
-    name: "error.has_error",
-    label: "Contains Error",
-    description: "Group by whether the trace contains an error"
-  }
-];
-
 // src/tools/discover-schema.ts
-function formatSchema(category) {
+var PLATFORM_BACKED = /* @__PURE__ */ new Set(["filters", "lwql", "all"]);
+function needsQueryReference(category) {
+  return PLATFORM_BACKED.has(category);
+}
+async function formatSchema(category, reference) {
   const sections = [];
+  const resolved = needsQueryReference(category) && !reference ? await getQueryReference() : reference;
   if (category === "filters" || category === "all") {
-    sections.push(formatFilters());
+    sections.push(formatFilters(resolved));
+  }
+  if (category === "lwql" || category === "all") {
+    sections.push(formatLangWatchQL(resolved));
   }
   if (category === "metrics" || category === "all") {
     sections.push(formatMetrics());
@@ -375,27 +265,133 @@ function formatSchema(category) {
   if (category === "groups" || category === "all") {
     sections.push(formatGroups());
   }
+  if (category === "all" && resolved) {
+    sections.push(formatDecisionTable(resolved));
+  }
   return sections.join("\n\n");
 }
-function formatFilters() {
-  const lines = ["## Available Filter Fields", ""];
+var knownValuesCell = (field) => {
+  if (field.knownValues.length > 0) return field.knownValues.join(", ");
+  return field.facetable ? "open set, read them from GET /api/v1/traces/facets" : "";
+};
+function formatFilters(reference) {
+  if (!reference) {
+    return "## Trace Filter Fields\n\nUnavailable: the platform could not be reached.";
+  }
+  const lines = ["## Trace Filter Fields", ""];
+  lines.push(
+    "Send one of these as the `filter` parameter of `search_traces`, in the language the Trace Explorer's search bar speaks: `status:error AND model:gpt-*`."
+  );
+  lines.push(
+    "The `filters` parameter is the older per-field map and still works; both are combined when you send both."
+  );
+  lines.push("");
+  lines.push(
+    markdownTable({
+      headers: ["Field", "Type", "Group", "Known values"],
+      rows: reference.traceFilter.fields.map((field) => ({
+        Field: field.name,
+        Type: field.valueType,
+        Group: field.group ?? "",
+        "Known values": knownValuesCell(field)
+      }))
+    })
+  );
+  lines.push("");
+  lines.push("### Attribute namespaces", "");
   lines.push(
-    "Use these in the `filters` parameter of `search_traces` and `get_analytics`."
+    markdownTable({
+      headers: ["Prefix", "Matches", "Older spellings"],
+      rows: reference.traceFilter.dynamicPrefixes.map((prefix) => ({
+        Prefix: `${prefix.prefix}<key>`,
+        Matches: prefix.description,
+        "Older spellings": prefix.aliases.join(", ")
+      }))
+    })
   );
-  lines.push('Format: `{ "field_name": ["value1", "value2"] }`');
   lines.push("");
-  for (const f of filterFields) {
+  lines.push("### Syntax", "");
+  lines.push(reference.traceFilter.syntax);
+  lines.push("");
+  lines.push("### Worked filters", "");
+  for (const example of reference.examples.filter(
+    (candidate) => candidate.language === "trace-filter"
+  )) {
+    lines.push(`- \`${example.text}\` \u2014 ${example.title}`);
+  }
+  return lines.join("\n");
+}
+function formatLangWatchQL(reference) {
+  if (!reference) {
+    return "## Analytics SQL\n\nUnavailable: the platform could not be reached.";
+  }
+  if (!reference.lwql.enabled) {
+    return [
+      "## Analytics SQL",
+      "",
+      "Not enabled for this project, so `run_query` will refuse. Use `search_traces` and `get_analytics` instead."
+    ].join("\n");
+  }
+  const lines = ["## Analytics SQL", ""];
+  lines.push(
+    "Run one read-only SELECT with `run_query`. The statement is executed as written: nothing rewrites it."
+  );
+  lines.push(
+    `Ceilings: ${reference.lwql.limits.maxRowsReturned} rows, ${reference.lwql.limits.maxExecutionTimeSeconds} seconds. ${reference.lwql.limits.pagination}`
+  );
+  lines.push("");
+  for (const view of reference.lwql.schema.views) {
+    lines.push(`### ${view.name}`);
+    lines.push(`${view.description} One row is: ${view.grain}`);
     lines.push(
-      `- **${f.field}**: ${f.description}${f.example ? ` (e.g., \`${f.example}\`)` : ""}`
+      `Filter on \`${view.timeColumn}\` to prune partitions. Join keys: ${view.joinKeys.join(", ") || "none"}.`
     );
+    lines.push("");
+    lines.push(
+      markdownTable({
+        headers: ["Column", "Type", "Available", "Description"],
+        rows: view.columns.map((column) => ({
+          Column: column.name,
+          Type: column.type,
+          Available: column.available ? "yes" : `needs ${column.gates.join(", ")}`,
+          Description: column.description
+        }))
+      })
+    );
+    lines.push("");
+  }
+  lines.push("### Worked statements", "");
+  for (const example of reference.examples.filter((candidate) => candidate.language === "lwql")) {
+    lines.push(
+      `**${example.title}**${example.available ? "" : ` (needs ${example.requires.gates.join(", ")})`}`
+    );
+    lines.push("```sql");
+    lines.push(example.text);
+    lines.push("```");
+    for (const parameter of example.parameters) {
+      lines.push(`- \`{${parameter.name}:${parameter.type}}\` \u2014 ${parameter.description}`);
+    }
+    lines.push("");
   }
   return lines.join("\n");
 }
-function formatMetrics() {
-  const lines = ["## Available Metrics", ""];
+function formatDecisionTable(reference) {
+  const lines = ["## Which one to reach for", ""];
   lines.push(
-    "Use these in `get_analytics` as `metric` parameter in `category.name` format."
+    markdownTable({
+      headers: ["When you want", "Use", "Why"],
+      rows: reference.decisionTable.map((row) => ({
+        "When you want": row.when,
+        Use: row.use,
+        Why: row.why
+      }))
+    })
   );
+  return lines.join("\n");
+}
+function formatMetrics() {
+  const lines = ["## Available Metrics", ""];
+  lines.push("Use these in `get_analytics` as `metric` parameter in `category.name` format.");
   lines.push("");
   const byCategory = /* @__PURE__ */ new Map();
   for (const m of analyticsMetrics) {
@@ -433,9 +429,7 @@ function formatAggregations() {
 }
 function formatGroups() {
   const lines = ["## Available Group-By Options", ""];
-  lines.push(
-    "Use these in the `groupBy` parameter of `get_analytics`."
-  );
+  lines.push("Use these in the `groupBy` parameter of `get_analytics`.");
   lines.push("");
   for (const g of analyticsGroups) {
     lines.push(`- **${g.name}** (${g.label}): ${g.description}`);
@@ -443,6 +437,7 @@ function formatGroups() {
   return lines.join("\n");
 }
 export {
-  formatSchema
+  formatSchema,
+  needsQueryReference
 };
-//# sourceMappingURL=discover-schema-L6QDPON3.js.map
+//# sourceMappingURL=discover-schema-J2ANOBKO.js.map

package/dist/get-agent-5T3CXQOR.js

@@ -0,0 +1,69 @@
+import {
+  getAgent
+} from "./chunk-EYPJBL7P.js";
+import "./chunk-7CZQDZ2K.js";
+import "./chunk-DULFP3MK.js";
+
+// src/tools/get-agent.ts
+var describeParameter = ({
+  name,
+  type,
+  options,
+  default: defaultValue,
+  description,
+  required
+}) => {
+  const parts = [type];
+  if (options?.length) parts.push(`one of ${options.join(", ")}`);
+  if (defaultValue !== void 0) parts.push(`default ${JSON.stringify(defaultValue)}`);
+  if (required) parts.push("required");
+  const suffix = description ? `: ${description}` : "";
+  return `- **${name}** (${parts.join(", ")})${suffix}`;
+};
+function instancesSection(instances) {
+  const lines = [`
+## Instances (${instances.length})
+`];
+  for (const instance of instances) {
+    const label = instance.label ? ` (${instance.label})` : "";
+    lines.push(`- ${instance.hostname || instance.id}${label}, connected ${instance.connectedAt}`);
+  }
+  return lines;
+}
+async function handleGetAgent({ id }) {
+  const agent = await getAgent(id);
+  const lines = [];
+  lines.push(`# ${agent.name}
+`);
+  lines.push(`**ID**: ${agent.id}`);
+  lines.push(`**Type**: ${agent.type}`);
+  if (agent.environment) lines.push(`**Environment**: ${agent.environment}`);
+  if (agent.status) lines.push(`**Status**: ${agent.status}`);
+  if (agent.owner?.name) lines.push(`**Owner**: ${agent.owner.name}`);
+  else if (agent.hostLabel) lines.push(`**Host**: ${agent.hostLabel}`);
+  if (agent.selectable === false) {
+    lines.push("**Run**: only its owner can run this agent");
+  }
+  if (agent.lastSeenAt) lines.push(`**Last seen**: ${agent.lastSeenAt}`);
+  lines.push(`**Created**: ${agent.createdAt}`);
+  lines.push(`**Updated**: ${agent.updatedAt}`);
+  if (agent.parameters && agent.parameters.length > 0) {
+    lines.push("\n## Parameters\n");
+    for (const parameter of agent.parameters) lines.push(describeParameter(parameter));
+  }
+  if (agent.instances && agent.instances.length > 0) {
+    lines.push(...instancesSection(agent.instances));
+  }
+  if (agent.config && Object.keys(agent.config).length > 0) {
+    lines.push("\n## Config\n");
+    lines.push("```json");
+    lines.push(JSON.stringify(agent.config, null, 2));
+    lines.push("```");
+  }
+  return lines.join("\n");
+}
+export {
+  describeParameter,
+  handleGetAgent
+};
+//# sourceMappingURL=get-agent-5T3CXQOR.js.map

package/dist/{get-agent-7THF7HCU.js → get-agent-ZKYQJUQ7.js}

@@ -1,8 +1,8 @@
 import {
   getAgent
-} from "./chunk-EYXMLE5X.js";
-import "./chunk-GELJ2MQR.js";
-import "./chunk-WT4PO4A3.js";
+} from "./chunk-4RX3G62A.js";
+import "./chunk-7CZQDZ2K.js";
+import "./chunk-DULFP3MK.js";
 import "./chunk-SAS5OB7F.js";
 
 // src/tools/get-agent.ts
@@ -21,6 +21,16 @@ var describeParameter = ({
   const suffix = description ? `: ${description}` : "";
   return `- **${name}** (${parts.join(", ")})${suffix}`;
 };
+function instancesSection(instances) {
+  const lines = [`
+## Instances (${instances.length})
+`];
+  for (const instance of instances) {
+    const label = instance.label ? ` (${instance.label})` : "";
+    lines.push(`- ${instance.hostname || instance.id}${label}, connected ${instance.connectedAt}`);
+  }
+  return lines;
+}
 async function handleGetAgent({ id }) {
   const agent = await getAgent(id);
   const lines = [];
@@ -43,13 +53,7 @@ async function handleGetAgent({ id }) {
     for (const parameter of agent.parameters) lines.push(describeParameter(parameter));
   }
   if (agent.instances && agent.instances.length > 0) {
-    lines.push(`
-## Instances (${agent.instances.length})
-`);
-    for (const instance of agent.instances) {
-      const label = instance.label ? ` (${instance.label})` : "";
-      lines.push(`- ${instance.hostname || instance.id}${label}, connected ${instance.connectedAt}`);
-    }
+    lines.push(...instancesSection(agent.instances));
   }
   if (agent.config && Object.keys(agent.config).length > 0) {
     lines.push("\n## Config\n");
@@ -63,4 +67,4 @@ export {
   describeParameter,
   handleGetAgent
 };
-//# sourceMappingURL=get-agent-7THF7HCU.js.map
+//# sourceMappingURL=get-agent-ZKYQJUQ7.js.map

package/dist/get-analytics-4MPEK4KV.js

@@ -0,0 +1,79 @@
+import {
+  parseRelativeDate
+} from "./chunk-BIIKE3EI.js";
+import {
+  getAnalyticsTimeseries
+} from "./chunk-7CZQDZ2K.js";
+import "./chunk-DULFP3MK.js";
+
+// src/tools/get-analytics.ts
+function getGroupedData(bucket, groupBy) {
+  const data = bucket[groupBy];
+  if (typeof data === "object" && data !== null && !Array.isArray(data)) {
+    return data;
+  }
+  return void 0;
+}
+function groupedPeriodTable({
+  currentPeriod,
+  groupBy
+}) {
+  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
+}) {
+  if (currentPeriod.length === 0) return ["No data available for this period."];
+  if (groupBy && currentPeriod.some((b) => getGroupedData(b, groupBy) !== void 0)) {
+    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 : void 0).find((v) => v !== void 0) ?? "N/A";
+    lines.push(`| ${bucket.date} | ${value} |`);
+  }
+  return lines;
+}
+async function handleGetAnalytics(params) {
+  const now = Date.now();
+  const startDate = params.startDate ? parseRelativeDate(params.startDate) : now - 7 * 864e5;
+  const endDate = params.endDate ? parseRelativeDate(params.endDate) : now;
+  const [category, name] = params.metric.includes(".") ? params.metric.split(".", 2) : ["metadata", params.metric];
+  const metricKey = `${category}.${name}`;
+  const aggregation = params.aggregation ?? "avg";
+  const result = await getAnalyticsTimeseries({
+    series: [{ metric: metricKey, aggregation }],
+    startDate,
+    endDate,
+    timeZone: params.timeZone ?? "UTC",
+    groupBy: params.groupBy,
+    filters: params.filters
+  });
+  const lines = [];
+  lines.push(`# Analytics: ${metricKey} (${aggregation})
+`);
+  lines.push(
+    `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("");
+  lines.push(
+    ...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");
+}
+export {
+  handleGetAnalytics
+};
+//# sourceMappingURL=get-analytics-4MPEK4KV.js.map