@langwatch/mcp-server 2.1.0 → 3.0.0

package/src/tools/list-simulation-runs.ts

@@ -1,5 +1,5 @@
-import { listSimulationRuns as apiListSimulationRuns } from "../langwatch-api-simulation-runs.js";
-import { formatRunStatus } from "./format-suite-details.js";
+import { listSimulationRuns as apiListSimulationRuns } from "../langwatch-api-simulation-runs.ts";
+import { formatRunStatus } from "./format-suite-details.ts";
 
 /**
  * Handles the platform_list_simulation_runs MCP tool invocation.
@@ -27,7 +27,9 @@ export async function handleListSimulationRuns(params: {
   }
 
   const lines: string[] = [];
-  lines.push(`# Simulation Runs (${runs.length} results${result.hasMore ? ", more available" : ""})\n`);
+  lines.push(
+    `# Simulation Runs (${runs.length} results${result.hasMore ? ", more available" : ""})\n`,
+  );
 
   for (const run of runs) {
     const statusIcon = formatRunStatus(run.status);
@@ -47,7 +49,9 @@ export async function handleListSimulationRuns(params: {
     lines.push("");
   }
 
-  lines.push("> Use `platform_get_simulation_run` with a run ID to see full details (messages, results).");
+  lines.push(
+    "> Use `platform_get_simulation_run` with a run ID to see full details (messages, results).",
+  );
 
   return lines.join("\n");
 }

package/src/tools/list-test-suites.ts

@@ -1,4 +1,4 @@
-import { listTestSuites as apiListTestSuites } from "../langwatch-api-test-suites.js";
+import { listTestSuites as apiListTestSuites } from "../langwatch-api-test-suites.ts";
 
 /**
  * Handles the platform_list_test_suites MCP tool invocation.

package/src/tools/list-trigger-fires.ts

@@ -0,0 +1,17 @@
+import { listTriggerFires as apiListTriggerFires } from "../langwatch-api-triggers.ts";
+
+/**
+ * Handles the platform_list_trigger_fires MCP tool invocation: one page of
+ * fires, newest first, and the cursor for the next page when there is one.
+ */
+export async function handleListTriggerFires(params: {
+  id: string;
+  limit?: number;
+  cursor?: string;
+}): Promise<string> {
+  const page = await apiListTriggerFires(params);
+  if (page.fires.length === 0) {
+    return params.cursor ? "No more fires." : "This automation has not fired yet.";
+  }
+  return JSON.stringify(page, null, 2);
+}

package/src/tools/list-triggers.ts

@@ -0,0 +1,39 @@
+import { listTriggers as apiListTriggers } from "../langwatch-api-triggers.ts";
+import type { Trigger } from "../schemas/triggers.ts";
+
+/**
+ * Handles the platform_list_triggers MCP tool invocation.
+ */
+export async function handleListTriggers(params: { format?: "digest" | "json" }): Promise<string> {
+  const triggers = await apiListTriggers();
+  if (params.format === "json") return JSON.stringify(triggers, null, 2);
+  if (triggers.length === 0) {
+    return "No triggers found. Use `platform_create_trigger` to create one.";
+  }
+  const lines = [`# Triggers (${triggers.length} total)\n`];
+  for (const trigger of triggers) lines.push(...digestTrigger(trigger), "");
+  return lines.join("\n");
+}
+
+function digestTrigger(trigger: Trigger): string[] {
+  const lines = [
+    `## ${trigger.name}`,
+    `**ID**: ${trigger.id}`,
+    `**Kind**: ${trigger.kind ?? "AUTOMATION"}`,
+    `**Action**: ${trigger.action}`,
+    `**Status**: ${trigger.active ? "active" : "inactive"}`,
+  ];
+  if (trigger.alertType) lines.push(`**Alert**: ${trigger.alertType}`);
+  if (trigger.filterQuery) lines.push(`**Filter query**: ${trigger.filterQuery}`);
+  else if (Object.keys(trigger.filters).length > 0) {
+    lines.push(`**Filters**: ${JSON.stringify(trigger.filters)}`);
+  }
+  if (trigger.graphAlert) {
+    const rule = trigger.graphAlert;
+    lines.push(
+      `**Fires when**: ${rule.seriesName} ${rule.operator} ${rule.threshold} over ${rule.timePeriod}m${trigger.customGraphId ? ` on graph ${trigger.customGraphId}` : ""}`,
+    );
+  }
+  if (trigger.report) lines.push(`**Report**: ${JSON.stringify(trigger.report)}`);
+  return lines;
+}

package/src/tools/list-workflows.ts

@@ -1,4 +1,4 @@
-import { listWorkflows as apiListWorkflows } from "../langwatch-api-workflows.js";
+import { listWorkflows as apiListWorkflows } from "../langwatch-api-workflows.ts";
 
 export async function handleListWorkflows(): Promise<string> {
   const workflows = await apiListWorkflows();
@@ -23,9 +23,7 @@ export async function handleListWorkflows(): Promise<string> {
     lines.push("");
   }
 
-  lines.push(
-    "> Use `platform_get_workflow` with the ID to see full workflow details.",
-  );
+  lines.push("> Use `platform_get_workflow` with the ID to see full workflow details.");
 
   return lines.join("\n");
 }

package/src/tools/rename-prompt-tag.ts

@@ -1,4 +1,4 @@
-import { renamePromptTag as apiRenamePromptTag } from "../langwatch-api.js";
+import { renamePromptTag as apiRenamePromptTag } from "../langwatch-api.ts";
 
 export async function handleRenamePromptTag(params: {
   tag: string;

package/src/tools/rename-test-suite.ts

@@ -1,12 +1,9 @@
-import { renameTestSuite as apiRenameTestSuite } from "../langwatch-api-test-suites.js";
+import { renameTestSuite as apiRenameTestSuite } from "../langwatch-api-test-suites.ts";
 
 /**
  * Handles the platform_rename_test_suite MCP tool invocation.
  */
-export async function handleRenameTestSuite(params: {
-  id: string;
-  name: string;
-}): Promise<string> {
+export async function handleRenameTestSuite(params: { id: string; name: string }): Promise<string> {
   const suite = await apiRenameTestSuite(params);
 
   return [

package/src/tools/report-issue.ts

@@ -5,7 +5,9 @@ import {
   redactSessionJsonl,
   truncateJsonlToByteBudget,
 } from "@langwatch/redaction";
-import { getConfig } from "../config.js";
+
+import { getConfig } from "../config.ts";
+import { LANGWATCH_API_VERSION } from "../langwatch-api.ts";
 
 /** Transcripts are capped after redaction; oldest lines are dropped first. */
 const MAX_SESSION_BYTES = 8 * 1024 * 1024;
@@ -68,17 +70,15 @@ function redactReport(params: ReportIssueParams): RedactedReport {
   };
 }
 
-async function deliverReport(
-  report: RedactedReport,
-  params: ReportIssueParams,
-): Promise<string> {
+async function deliverReport(report: RedactedReport, params: ReportIssueParams): Promise<string> {
   const config = getConfig();
   const endpoint = config.endpoint.replace(/\/+$/, "");
 
-  const response = await fetch(`${endpoint}/api/bug-reports`, {
+  const response = await fetch(`${endpoint}/api/v1/bug-reports`, {
     method: "POST",
     headers: {
       "content-type": "application/json",
+      "x-api-version": LANGWATCH_API_VERSION,
       ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
     },
     body: JSON.stringify({
@@ -117,9 +117,7 @@ async function deliverReport(
  * an API key: the reporter may be struggling precisely because setup failed.
  * When a key is configured it only links the report to the project.
  */
-export async function handleReportIssue(
-  params: ReportIssueParams,
-): Promise<string> {
+export async function handleReportIssue(params: ReportIssueParams): Promise<string> {
   if (!params.user_approved) {
     throw new Error(
       "This sends a report to the LangWatch team, so the user must approve it first. " +

package/src/tools/rerun-run-plan.ts

@@ -1,8 +1,5 @@
-import {
-  rerunRunPlan as apiRerunRunPlan,
-  type RunParameters,
-} from "../langwatch-api-run-plans.js";
-import { formatRunPlanRun } from "./format-run-plan.js";
+import { rerunRunPlan as apiRerunRunPlan, type RunParameters } from "../langwatch-api-run-plans.ts";
+import { formatRunPlanRun } from "./format-run-plan.ts";
 
 /**
  * Handles the platform_rerun_run_plan MCP tool invocation.

package/src/tools/revoke-api-key.ts

@@ -1,8 +1,6 @@
-import { revokeApiKey as apiRevokeApiKey } from "../langwatch-api-api-keys.js";
+import { revokeApiKey as apiRevokeApiKey } from "../langwatch-api-api-keys.ts";
 
-export async function handleRevokeApiKey(params: {
-  id: string;
-}): Promise<string> {
+export async function handleRevokeApiKey(params: { id: string }): Promise<string> {
   await apiRevokeApiKey(params.id);
 
   return `API key ${params.id} revoked successfully.`;

package/src/tools/run-agent.ts

@@ -1,8 +1,6 @@
 import { z } from "zod";
-import {
-  runAgent as apiRunAgent,
-  type AgentCallParams,
-} from "../langwatch-api-agents.js";
+
+import { runAgent as apiRunAgent, type AgentCallParams } from "../langwatch-api-agents.ts";
 
 /**
  * A scalar and an array both parse as JSON, and either one reaches the agent
@@ -11,6 +9,31 @@ import {
 const jsonObjectSchema = z.looseObject({});
 type JsonObject = z.infer<typeof jsonObjectSchema>;
 
+function outputLines(result: object): string[] {
+  const output = (result as Record<string, unknown>).output;
+  if (output !== undefined) {
+    return ["**Output:**", typeof output === "string" ? output : JSON.stringify(output, null, 2)];
+  }
+  return ["**Result:**", JSON.stringify(result, null, 2)];
+}
+
+function connectedLines(result: object): string[] {
+  const lines: string[] = [];
+  const instance = (result as { instance?: { hostname?: string; label?: string | null } }).instance;
+  const durationMs = (result as { durationMs?: number }).durationMs;
+  if (instance?.hostname) {
+    const label = instance.label ? ` (${instance.label})` : "";
+    lines.push(`\n**Instance:** ${instance.hostname}${label}`);
+  }
+  if (typeof durationMs === "number") lines.push(`**Duration:** ${durationMs} ms`);
+  const session = (result as { session?: unknown }).session;
+  if (session !== undefined && session !== null) {
+    lines.push("**Session:**");
+    lines.push(JSON.stringify(session, null, 2));
+  }
+  return lines;
+}
+
 /**
  * Handles the platform_run_agent MCP tool invocation.
  *
@@ -56,28 +79,8 @@ export async function handleRunAgent({
   lines.push(`Agent executed successfully (type: ${agentType}).\n`);
 
   if (typeof result === "object" && result !== null) {
-    const output = (result as Record<string, unknown>).output;
-    if (output !== undefined) {
-      lines.push("**Output:**");
-      lines.push(typeof output === "string" ? output : JSON.stringify(output, null, 2));
-    } else {
-      lines.push("**Result:**");
-      lines.push(JSON.stringify(result, null, 2));
-    }
-    if (agentType === "connected") {
-      const instance = (result as { instance?: { hostname?: string; label?: string | null } }).instance;
-      const durationMs = (result as { durationMs?: number }).durationMs;
-      if (instance?.hostname) {
-        const label = instance.label ? ` (${instance.label})` : "";
-        lines.push(`\n**Instance:** ${instance.hostname}${label}`);
-      }
-      if (typeof durationMs === "number") lines.push(`**Duration:** ${durationMs} ms`);
-      const session = (result as { session?: unknown }).session;
-      if (session !== undefined && session !== null) {
-        lines.push("**Session:**");
-        lines.push(JSON.stringify(session, null, 2));
-      }
-    }
+    lines.push(...outputLines(result));
+    if (agentType === "connected") lines.push(...connectedLines(result));
   }
 
   return lines.join("\n");

package/src/tools/run-experiment.ts

@@ -1,5 +1,5 @@
-import { LangWatchApiError, makeRequest } from "../langwatch-api.js";
-import { deriveRunStatus } from "./experiment-run-status.js";
+import { LangWatchApiError, makeRequest } from "../langwatch-api.ts";
+import { deriveRunStatus } from "./experiment-run-status.ts";
 
 interface EvaluationRunResponse {
   runId: string;
@@ -26,10 +26,12 @@ interface EvaluationStatusResponse {
 
 export async function handleRunExperiment(params: {
   slug: string;
+  concurrency?: number;
 }): Promise<string> {
   const result = (await makeRequest(
     "POST",
-    `/api/experiments/${encodeURIComponent(params.slug)}/run`,
+    `/api/v1/experiments/${encodeURIComponent(params.slug)}/run`,
+    params.concurrency !== undefined ? { concurrency: params.concurrency } : undefined,
   )) as EvaluationRunResponse;
 
   const lines: string[] = [];
@@ -75,7 +77,7 @@ async function statusFromResults(params: {
   try {
     results = (await makeRequest(
       "GET",
-      `/api/experiments/runs/${encodeURIComponent(params.runId)}/results${qs}`,
+      `/api/v1/experiments/runs/${encodeURIComponent(params.runId)}/results${qs}`,
     )) as ResultsForStatus;
   } catch (error) {
     // Only a genuine "no such run" is a fallback miss (-> guidance). Real
@@ -97,19 +99,13 @@ async function statusFromResults(params: {
   lines.push(`**Status**: ${status}`);
   lines.push(`**Progress**: ${progress}/${total} cells`);
   if (results.timestamps.createdAt) {
-    lines.push(
-      `**Started**: ${new Date(results.timestamps.createdAt).toISOString()}`,
-    );
+    lines.push(`**Started**: ${new Date(results.timestamps.createdAt).toISOString()}`);
   }
   if (results.timestamps.finishedAt) {
-    lines.push(
-      `**Finished**: ${new Date(results.timestamps.finishedAt).toISOString()}`,
-    );
+    lines.push(`**Finished**: ${new Date(results.timestamps.finishedAt).toISOString()}`);
   }
   if (results.timestamps.stoppedAt) {
-    lines.push(
-      `**Stopped**: ${new Date(results.timestamps.stoppedAt).toISOString()}`,
-    );
+    lines.push(`**Stopped**: ${new Date(results.timestamps.stoppedAt).toISOString()}`);
   }
   lines.push("");
   lines.push(
@@ -118,6 +114,31 @@ async function statusFromResults(params: {
   return lines.join("\n");
 }
 
+async function statusAfterFailedRead({
+  params,
+  error,
+}: {
+  params: { runId: string; experimentSlug?: string };
+  error: unknown;
+}): Promise<string> {
+  const code = error instanceof LangWatchApiError ? error.status : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+  if (code === 404 || /404|not found/i.test(message)) {
+    const fallback = await statusFromResults(params);
+    if (fallback) return fallback;
+    return [
+      `# Evaluation Run ${params.runId}`,
+      "",
+      "**Status**: not found",
+      "",
+      `Could not find run \`${params.runId}\`. SDK-logged runs and runs older than 24h are not in the live run-state and must be resolved by experiment slug.`,
+      "",
+      "> Pass `experimentSlug`: discover it with `platform_experiment_list`, then use `platform_experiment_list_runs` for the run ids. Or fetch the rows directly with `platform_experiment_results`.",
+    ].join("\n");
+  }
+  throw error;
+}
+
 export async function handleExperimentStatus(params: {
   runId: string;
   experimentSlug?: string;
@@ -126,26 +147,10 @@ export async function handleExperimentStatus(params: {
   try {
     status = (await makeRequest(
       "GET",
-      `/api/experiments/runs/${encodeURIComponent(params.runId)}`,
+      `/api/v1/experiments/runs/${encodeURIComponent(params.runId)}`,
     )) as EvaluationStatusResponse;
   } catch (error) {
-    const code =
-      error instanceof LangWatchApiError ? error.status : undefined;
-    const message = error instanceof Error ? error.message : String(error);
-    if (code === 404 || /404|not found/i.test(message)) {
-      const fallback = await statusFromResults(params);
-      if (fallback) return fallback;
-      return [
-        `# Evaluation Run ${params.runId}`,
-        "",
-        "**Status**: not found",
-        "",
-        `Could not find run \`${params.runId}\`. SDK-logged runs and runs older than 24h are not in the live run-state and must be resolved by experiment slug.`,
-        "",
-        "> Pass `experimentSlug`: discover it with `platform_experiment_list`, then use `platform_experiment_list_runs` for the run ids. Or fetch the rows directly with `platform_experiment_results`.",
-      ].join("\n");
-    }
-    throw error;
+    return statusAfterFailedRead({ params, error });
   }
 
   const lines: string[] = [];
@@ -169,9 +174,7 @@ export async function handleExperimentStatus(params: {
       lines.push(`**Failed**: ${status.summary.failedCells}`);
     }
     if (status.summary.duration) {
-      lines.push(
-        `**Duration**: ${(status.summary.duration / 1000).toFixed(1)}s`,
-      );
+      lines.push(`**Duration**: ${(status.summary.duration / 1000).toFixed(1)}s`);
     }
     if (status.summary.runUrl) {
       lines.push(`**View results**: ${status.summary.runUrl}`);

package/src/tools/run-plan.ts

@@ -3,13 +3,10 @@ import {
   type RunParameters,
   type RunPlanScope,
   type RunPlanTarget,
-} from "../langwatch-api-run-plans.js";
-import { toWireTargets } from "../schemas/run-plan.js";
-import {
-  type EvaluatorAttachmentInput,
-  toWireAttachments,
-} from "../schemas/suite-fields.js";
-import { formatRunPlanRun } from "./format-run-plan.js";
+} from "../langwatch-api-run-plans.ts";
+import { toWireTargets } from "../schemas/run-plan.ts";
+import { type EvaluatorAttachmentInput, toWireAttachments } from "../schemas/suite-fields.ts";
+import { formatRunPlanRun } from "./format-run-plan.ts";
 
 /**
  * Handles the platform_run_plan MCP tool invocation.

package/src/tools/run-query.ts

@@ -0,0 +1,47 @@
+/**
+ * Handles the `run_query` MCP tool: one LangWatchQL statement rendered as a markdown table. Rows
+ * are capped, and the cap is announced, so an unaggregated query cannot flood the conversation.
+ * @see specs/mcp-server/schema-discovery.feature
+ */
+
+import { runQuery } from "../langwatch-api-query.ts";
+import { markdownTable } from "../utils/markdown-table.ts";
+
+/** Rows the table prints. Beyond this, aggregate or export through the CLI. */
+export const RUN_QUERY_ROW_CAP = 50;
+
+export async function handleRunQuery(params: {
+  sql: string;
+  parameters?: Record<string, string | number | boolean | null>;
+}): Promise<string> {
+  const result = await runQuery(params);
+  const headers = result.columns.map((column) => column.name);
+  const shown = result.rows.slice(0, RUN_QUERY_ROW_CAP);
+
+  const lines: string[] = [];
+  lines.push(
+    markdownTable({
+      headers,
+      rows: shown,
+      emptyMessage: "The statement ran and returned no rows.",
+    }),
+  );
+  lines.push("");
+  lines.push(
+    `Returned ${result.rows.length} row${result.rows.length === 1 ? "" : "s"} in ${result.statistics.elapsedMs}ms.`,
+  );
+  if (result.rows.length > shown.length) {
+    lines.push(
+      `Showing the first ${shown.length}. Aggregate further, or export every row with \`langwatch query "<statement>" --format jsonl\`.`,
+    );
+  }
+  if (result.truncated) {
+    lines.push(
+      "The result hit a response ceiling and was cut short, so this is not the whole answer.",
+    );
+  }
+  for (const diagnostic of result.diagnostics) {
+    lines.push(`${diagnostic.code}: ${diagnostic.message}`);
+  }
+  return lines.join("\n");
+}

package/src/tools/run-test-suite.ts

@@ -1,10 +1,7 @@
-import type {
-  RunParameters,
-  RunPlanTarget,
-} from "../langwatch-api-run-plans.js";
-import { toWireTargets } from "../schemas/run-plan.js";
-import { runTestSuite as apiRunTestSuite } from "../langwatch-api-test-suites.js";
-import { formatRunPlanRun } from "./format-run-plan.js";
+import type { RunParameters, RunPlanTarget } from "../langwatch-api-run-plans.ts";
+import { runTestSuite as apiRunTestSuite } from "../langwatch-api-test-suites.ts";
+import { toWireTargets } from "../schemas/run-plan.ts";
+import { formatRunPlanRun } from "./format-run-plan.ts";
 
 /**
  * Handles the platform_run_test_suite MCP tool invocation.

package/src/tools/run-workflow.ts

@@ -1,12 +1,9 @@
-import { runWorkflow as apiRunWorkflow } from "../langwatch-api-workflows.js";
+import { runWorkflow as apiRunWorkflow } from "../langwatch-api-workflows.ts";
 
 /**
  * Handles the platform_run_workflow MCP tool invocation.
  */
-export async function handleRunWorkflow(params: {
-  id: string;
-  input?: string;
-}): Promise<string> {
+export async function handleRunWorkflow(params: { id: string; input?: string }): Promise<string> {
   let parsedInput: Record<string, unknown> = {};
   if (params.input) {
     try {