@langwatch/mcp-server 2.0.0 → 2.2.0

package/dist/discover-schema-A33SLMXW.js

@@ -0,0 +1,442 @@
+import {
+  getQueryReference,
+  markdownTable
+} from "./chunk-SUPUUC4W.js";
+import "./chunk-FOKVY3BK.js";
+import "./chunk-UWLE5T2F.js";
+import "./chunk-H6WGMG2T.js";
+
+// 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/schemas/analytics-metrics.ts
+var analyticsMetrics = [
+  // metadata
+  {
+    category: "metadata",
+    name: "trace_id",
+    label: "Traces",
+    allowedAggregations: ["cardinality"],
+    description: "Count of unique traces"
+  },
+  {
+    category: "metadata",
+    name: "user_id",
+    label: "Users",
+    allowedAggregations: ["cardinality"],
+    description: "Count of unique users"
+  },
+  {
+    category: "metadata",
+    name: "thread_id",
+    label: "Threads",
+    allowedAggregations: ["cardinality"],
+    description: "Count of unique conversation threads"
+  },
+  {
+    category: "metadata",
+    name: "span_type",
+    label: "Span Type",
+    allowedAggregations: ["cardinality"],
+    description: "Count of spans, optionally filtered by span type"
+  },
+  // sentiment
+  {
+    category: "sentiment",
+    name: "input_sentiment",
+    label: "Input Sentiment Score",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Sentiment analysis score of inputs"
+  },
+  {
+    category: "sentiment",
+    name: "thumbs_up_down",
+    label: "Thumbs Up/Down Score",
+    allowedAggregations: [
+      "terms",
+      "cardinality",
+      "avg",
+      "sum",
+      "min",
+      "max",
+      "median",
+      "p99",
+      "p95",
+      "p90"
+    ],
+    description: "User feedback score (-1 to 1)"
+  },
+  // performance
+  {
+    category: "performance",
+    name: "completion_time",
+    label: "Completion Time",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Time to complete the trace (ms)"
+  },
+  {
+    category: "performance",
+    name: "first_token",
+    label: "Time to First Token",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Time to first token (ms)"
+  },
+  {
+    category: "performance",
+    name: "total_cost",
+    label: "Total Cost",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Cost per trace in USD"
+  },
+  {
+    category: "performance",
+    name: "prompt_tokens",
+    label: "Prompt Tokens",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Input token count"
+  },
+  {
+    category: "performance",
+    name: "completion_tokens",
+    label: "Completion Tokens",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Output token count"
+  },
+  {
+    category: "performance",
+    name: "total_tokens",
+    label: "Total Tokens",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Total token count (input + output)"
+  },
+  {
+    category: "performance",
+    name: "tokens_per_second",
+    label: "Tokens per Second",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Token generation speed"
+  },
+  // events
+  {
+    category: "events",
+    name: "event_type",
+    label: "Event Type",
+    allowedAggregations: ["cardinality"],
+    description: "Count of events, optionally filtered by event type"
+  },
+  {
+    category: "events",
+    name: "event_score",
+    label: "Event Score",
+    allowedAggregations: ["terms", "avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Numeric score from events (requires event_type key and metrics key)"
+  },
+  {
+    category: "events",
+    name: "event_details",
+    label: "Event Details",
+    allowedAggregations: ["cardinality"],
+    description: "Event detail key/value distribution (requires event_type key and details key)"
+  },
+  // evaluations
+  {
+    category: "evaluations",
+    name: "evaluation_score",
+    label: "Evaluation Score",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Numeric evaluation score (requires evaluator_id key)"
+  },
+  {
+    category: "evaluations",
+    name: "evaluation_pass_rate",
+    label: "Evaluation Pass Rate",
+    allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
+    description: "Percentage of traces passing evaluation (requires evaluator_id key)"
+  },
+  {
+    category: "evaluations",
+    name: "evaluation_runs",
+    label: "Evaluation Runs",
+    allowedAggregations: ["cardinality"],
+    description: "Count of evaluation executions"
+  },
+  // threads
+  {
+    category: "threads",
+    name: "average_duration_per_thread",
+    label: "Thread Duration",
+    allowedAggregations: ["avg"],
+    description: "Average duration of conversation threads (ms)"
+  }
+];
+
+// src/tools/discover-schema.ts
+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(resolved));
+  }
+  if (category === "lwql" || category === "all") {
+    sections.push(formatLangWatchQL(resolved));
+  }
+  if (category === "metrics" || category === "all") {
+    sections.push(formatMetrics());
+  }
+  if (category === "aggregations" || category === "all") {
+    sections.push(formatAggregations());
+  }
+  if (category === "groups" || category === "all") {
+    sections.push(formatGroups());
+  }
+  if (category === "all" && resolved) {
+    sections.push(formatDecisionTable(resolved));
+  }
+  return sections.join("\n\n");
+}
+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(
+    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("");
+  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(
+      `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 formatDecisionTable(reference) {
+  const lines = ["## Which one to reach for", ""];
+  lines.push(
+    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) {
+    const list = byCategory.get(m.category) || [];
+    list.push(m);
+    byCategory.set(m.category, list);
+  }
+  for (const [cat, metrics] of byCategory) {
+    lines.push(`### ${cat}`);
+    for (const m of metrics) {
+      lines.push(`- **${cat}.${m.name}** (${m.label}): ${m.description}`);
+      lines.push(`  Aggregations: ${m.allowedAggregations.join(", ")}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function formatAggregations() {
+  return [
+    "## Available Aggregation Types",
+    "",
+    "- **cardinality**: Count unique values",
+    "- **terms**: Distribution/breakdown of values",
+    "- **avg**: Average",
+    "- **sum**: Sum total",
+    "- **min**: Minimum",
+    "- **max**: Maximum",
+    "- **median**: 50th percentile",
+    "- **p90**: 90th percentile",
+    "- **p95**: 95th percentile",
+    "- **p99**: 99th percentile",
+    "",
+    "Note: Not all aggregations are available for all metrics. Check the metric's allowed aggregations."
+  ].join("\n");
+}
+function formatGroups() {
+  const lines = ["## Available Group-By Options", ""];
+  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}`);
+  }
+  return lines.join("\n");
+}
+export {
+  formatSchema,
+  needsQueryReference
+};
+//# sourceMappingURL=discover-schema-A33SLMXW.js.map

package/dist/get-agent-LJQX7OF4.js

@@ -0,0 +1,69 @@
+import {
+  getAgent
+} from "./chunk-YCARO42Z.js";
+import "./chunk-UWLE5T2F.js";
+import "./chunk-H6WGMG2T.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-LJQX7OF4.js.map

package/dist/get-agent-OTIYUFZA.js

@@ -0,0 +1,70 @@
+import {
+  getAgent
+} from "./chunk-HGELNIVY.js";
+import "./chunk-UWLE5T2F.js";
+import "./chunk-H6WGMG2T.js";
+import "./chunk-SAS5OB7F.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-OTIYUFZA.js.map

package/dist/get-analytics-DCS72353.js

@@ -0,0 +1,80 @@
+import {
+  parseRelativeDate
+} from "./chunk-BIIKE3EI.js";
+import {
+  getAnalyticsTimeseries
+} from "./chunk-UWLE5T2F.js";
+import "./chunk-H6WGMG2T.js";
+import "./chunk-SAS5OB7F.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-DCS72353.js.map