@langwatch/mcp-server 2.2.0 → 3.1.0

package/src/tools/list-analytics-reports.ts

@@ -0,0 +1,27 @@
+import { listAnalyticsReports } from "../langwatch-api-analytics-reports.ts";
+
+export async function handleListAnalyticsReports(): Promise<string> {
+  const result = await listAnalyticsReports();
+  const reports = result.data;
+
+  if (!Array.isArray(reports) || reports.length === 0) {
+    return "No Analytics Reports found in this project.\n\n> Tip: Use `platform_create_analytics_report` to create a new Analytics Report.";
+  }
+
+  const lines: string[] = [];
+  lines.push(`# Analytics Reports (${reports.length} total)\n`);
+
+  for (const report of reports) {
+    lines.push(`## ${report.name}`);
+    lines.push(`**ID**: ${report.id}`);
+    lines.push(`**Graphs**: ${report.graphCount}`);
+    lines.push(`**Updated**: ${report.updatedAt}`);
+    lines.push("");
+  }
+
+  lines.push(
+    "> Use `platform_get_analytics_report` with the ID to see the Analytics Report's details including graphs.",
+  );
+
+  return lines.join("\n");
+}

package/src/tools/list-dashboards.ts

@@ -1,27 +1,26 @@
-import { listDashboards as apiListDashboards } from "../langwatch-api-dashboards.ts";
+/**
+ * The `list_dashboards` MCP tool: the dashboards a widget can be added to, with
+ * the id `add_dashboard_widget` and `update_dashboard_widget` take.
+ */
 
-export async function handleListDashboards(): Promise<string> {
-  const result = await apiListDashboards();
-  const dashboards = result.data;
-
-  if (!Array.isArray(dashboards) || dashboards.length === 0) {
-    return "No dashboards found in this project.\n\n> Tip: Use `platform_create_dashboard` to create a new dashboard.";
-  }
+import { listDashboards } from "../langwatch-api-dashboards.js";
 
-  const lines: string[] = [];
-  lines.push(`# Dashboards (${dashboards.length} total)\n`);
+export async function handleListDashboards(): Promise<string> {
+  const { data: dashboards } = await listDashboards();
 
-  for (const d of dashboards) {
-    lines.push(`## ${d.name}`);
-    lines.push(`**ID**: ${d.id}`);
-    lines.push(`**Graphs**: ${d.graphCount}`);
-    lines.push(`**Updated**: ${d.updatedAt}`);
-    lines.push("");
+  if (dashboards.length === 0) {
+    return "No dashboards found in this project. Create one in the Dashboards area first.";
   }
 
-  lines.push(
-    "> Use `platform_get_dashboard` with the ID to see dashboard details including graphs.",
-  );
-
-  return lines.join("\n");
+  return [
+    `# Dashboards (${dashboards.length} total)\n`,
+    ...dashboards.flatMap((dashboard) => [
+      `## ${dashboard.name}`,
+      `**ID**: ${dashboard.id}`,
+      `**Widgets**: ${dashboard.widgetCount}`,
+      `**URL**: ${dashboard.platformUrl}`,
+      "",
+    ]),
+    "> Pass the ID to `add_dashboard_widget` to add a widget to that dashboard.",
+  ].join("\n");
 }

package/src/tools/report-issue.ts

@@ -7,6 +7,7 @@ import {
 } from "@langwatch/redaction";
 
 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;
@@ -77,6 +78,7 @@ async function deliverReport(report: RedactedReport, params: ReportIssueParams):
     method: "POST",
     headers: {
       "content-type": "application/json",
+      "x-api-version": LANGWATCH_API_VERSION,
       ...(config.apiKey ? { authorization: `Bearer ${config.apiKey}` } : {}),
     },
     body: JSON.stringify({

package/src/tools/run-experiment.ts

@@ -24,10 +24,14 @@ interface EvaluationStatusResponse {
   };
 }
 
-export async function handleRunExperiment(params: { slug: string }): Promise<string> {
+export async function handleRunExperiment(params: {
+  slug: string;
+  concurrency?: number;
+}): Promise<string> {
   const result = (await makeRequest(
     "POST",
     `/api/v1/experiments/${encodeURIComponent(params.slug)}/run`,
+    params.concurrency !== undefined ? { concurrency: params.concurrency } : undefined,
   )) as EvaluationRunResponse;
 
   const lines: string[] = [];

package/src/tools/run-query.ts

@@ -5,16 +5,28 @@
  */
 
 import { runQuery } from "../langwatch-api-query.ts";
+import { LangWatchApiError } from "../langwatch-api.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;
 
+/** What the tool tells an agent whose key names no project (the platform's `projects_required`). */
+const PROJECTS_REQUIRED_MESSAGE =
+  'Name the projects to query: pass `projects`, a list of project ids, or "all"';
+
 export async function handleRunQuery(params: {
   sql: string;
   parameters?: Record<string, string | number | boolean | null>;
+  projects?: string[] | string;
+  sources?: string[];
 }): Promise<string> {
-  const result = await runQuery(params);
+  const result = await runQuery(params).catch((error: unknown) => {
+    if (error instanceof LangWatchApiError && error.code === "projects_required") {
+      throw new Error(PROJECTS_REQUIRED_MESSAGE);
+    }
+    throw error;
+  });
   const headers = result.columns.map((column) => column.name);
   const shown = result.rows.slice(0, RUN_QUERY_ROW_CAP);
 
@@ -43,5 +55,15 @@ export async function handleRunQuery(params: {
   for (const diagnostic of result.diagnostics) {
     lines.push(`${diagnostic.code}: ${diagnostic.message}`);
   }
+  if (result.params) lines.push("", describeParams(result.params));
   return lines.join("\n");
 }
+
+/** What the run was bound to: every placeholder the SQL declares, by its SQL name. */
+function describeParams(
+  params: NonNullable<Awaited<ReturnType<typeof runQuery>>["params"]>,
+): string {
+  return ["Ran with these placeholders:", "```json", JSON.stringify(params, null, 2), "```"].join(
+    "\n",
+  );
+}

package/src/tools/update-dashboard-widget.ts

@@ -1,20 +1,17 @@
 /**
- * The `update_dashboard_widget` MCP tool over the widget PATCH: a field left out keeps its
- * stored value. The widget must sit on the named dashboard, so an agent never edits one it
- * found somewhere else by mistake. Spec: modules/dashboard/specs/dashboard-widget-mcp.feature
+ * `update_dashboard_widget`: the widget must sit on the named dashboard, so an agent never edits
+ * one it found elsewhere by mistake.
+ * Spec: modules/dashboard/specs/dashboard-widget-mcp.feature
  */
 
-import {
-  type DashboardWidget,
-  getDashboardWidget,
-  updateDashboardWidget,
-} from "../langwatch-api-dashboard-widgets.js";
-import { getCurrentProject } from "../langwatch-api-projects.js";
+import type { DashboardWidget } from "../langwatch-api-dashboard-widgets.js";
+import { getWidgetOnDashboard, updateWidgetOnDashboard } from "../langwatch-api-dashboards.js";
 import { LangWatchApiError } from "../langwatch-api.js";
-import { assertDashboardExists } from "./dashboard-exists.js";
+import type { WidgetSource } from "../schemas/widget-sources.js";
 import {
   type DashboardWidgetQueriesInput,
   normalizeDashboardWidgetQueries,
+  withLists,
 } from "./dashboard-widget-queries.js";
 
 export interface UpdateDashboardWidgetParams {
@@ -24,37 +21,41 @@ export interface UpdateDashboardWidgetParams {
   code?: string;
   queries?: DashboardWidgetQueriesInput;
   description?: string;
+  /** Set on every query; alone, it is sent with the widget's stored queries. */
+  sources?: WidgetSource[] | null;
+  /** Set on every query; alone, it is sent with the widget's stored queries. */
+  projects?: string[] | null;
 }
 
 export async function handleUpdateDashboardWidget(
   params: UpdateDashboardWidgetParams,
 ): Promise<string> {
-  const { dashboardId, widgetId, name, code, description } = params;
-  if (
-    name === undefined &&
-    code === undefined &&
-    params.queries === undefined &&
-    description === undefined
-  ) {
-    throw new Error("Provide at least one of name, code, queries or description to change.");
+  const { dashboardId, widgetId, name, code, description, sources, projects } = params;
+  const fields = [name, code, params.queries, description, sources, projects];
+  if (fields.every((field) => field === undefined)) {
+    throw new Error(
+      "Provide at least one of name, code, queries, description, sources or projects to change.",
+    );
   }
-  const queries =
+
+  const current = await widgetOnDashboardOrRefused({ widgetId, dashboardId });
+  const given =
     params.queries === undefined
       ? undefined
       : normalizeDashboardWidgetQueries({ queries: params.queries });
+  // Sources alone: the stored queries go back with the new list on each.
+  const listed = sources !== undefined || projects !== undefined;
+  const base = given ?? (listed ? current.definition.queries : undefined);
+  const queries = base === undefined ? undefined : withLists({ queries: base, sources, projects });
 
-  const project = await getCurrentProject();
-  await assertDashboardExists({ projectId: project.id, dashboardId });
-  const current = await getWidgetOnDashboard({ projectId: project.id, widgetId, dashboardId });
-
-  const widget = await updateDashboardWidget({
-    projectId: project.id,
-    widgetId: current.id,
+  const changes = {
     ...(name === undefined ? {} : { name }),
     ...(code === undefined ? {} : { code }),
     ...(queries === undefined ? {} : { queries }),
     ...(description === undefined ? {} : { description }),
-  });
+  };
+
+  const widget = await updateWidgetOnDashboard({ dashboardId, widgetId: current.id, ...changes });
 
   return [
     `Widget "${widget.name}" updated on dashboard "${dashboardId}".`,
@@ -67,31 +68,22 @@ export async function handleUpdateDashboardWidget(
   ].join("\n");
 }
 
-/** The widget, refused by id when it is not in this project or not on this dashboard. */
-async function getWidgetOnDashboard({
-  projectId,
+/** The widget, refused by id when it is not on this dashboard (the dashboard route answers 404). */
+async function widgetOnDashboardOrRefused({
   widgetId,
   dashboardId,
 }: {
-  projectId: string;
   widgetId: string;
   dashboardId: string;
 }): Promise<DashboardWidget> {
-  let widget: DashboardWidget;
   try {
-    widget = await getDashboardWidget({ projectId, widgetId });
+    return await getWidgetOnDashboard({ dashboardId, widgetId });
   } catch (error) {
     if (error instanceof LangWatchApiError && error.status === 404) {
       throw new Error(
-        `No widget with ID "${widgetId}" was found in this project. Use the widget ID add_dashboard_widget returned.`,
+        `No widget with ID "${widgetId}" was found on dashboard "${dashboardId}". Use the widget ID add_dashboard_widget returned, and the dashboard it was added to.`,
       );
     }
     throw error;
   }
-  if (widget.dashboardId !== dashboardId) {
-    throw new Error(
-      `Widget "${widgetId}" is not on dashboard "${dashboardId}". Pass the dashboard the widget was added to.`,
-    );
-  }
-  return widget;
 }