@langwatch/mcp-server 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langwatch/mcp-server",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "An MCP server for Langwatch.",
   "license": "MIT",
   "author": "",

package/src/create-mcp-server.ts

@@ -28,7 +28,11 @@ import {
   triggerActionSchema,
   validateActionParamsForAction,
 } from "./schemas/triggers.ts";
-import { widgetSourcesInput } from "./schemas/widget-sources.ts";
+import {
+  runQueryProjectsInput,
+  widgetProjectsInput,
+  widgetSourcesInput,
+} from "./schemas/widget-sources.ts";
 import { handleExperimentResults } from "./tools/get-experiment-results.ts";
 import { handleExperimentListRuns } from "./tools/list-experiment-runs.ts";
 import { handleExperimentList } from "./tools/list-experiments.ts";
@@ -248,6 +252,17 @@ function registerObservabilityTools(server: McpServer): void {
         .describe(
           'Values for the parameters the statement declares, e.g. {"days": 7} for {days:UInt32}',
         ),
+      projects: runQueryProjectsInput
+        .optional()
+        .describe(
+          'The project ids to read, or the string "all" for every project the key can read (params.dashboard_context_projects lists them). A key that reaches several projects must name them or send "all"; a key that reads one project defaults to it',
+        ),
+      sources: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "The trace sources {dashboard_context_sources:Array(String)} is bound to (default application). Only a statement that reads that parameter is kept to them; a SOURCES_IGNORED diagnostic says it did not",
+        ),
     },
     withToolLogging("run_query", async (params) => {
       requireApiKey();
@@ -1460,6 +1475,7 @@ function registerDashboardTools(server: McpServer): void {
           "The widget's named LangWatchQL queries: either {name: sql} or an array of {name, sql}. Max 8. Validate each statement with run_query first.",
         ),
       sources: widgetSourcesInput,
+      projects: widgetProjectsInput,
     },
     withToolLogging("add_dashboard_widget", async (params) => {
       requireApiKey();
@@ -1504,6 +1520,7 @@ function registerDashboardTools(server: McpServer): void {
         .optional()
         .describe("What the widget's info tip says: a sentence or two"),
       sources: widgetSourcesInput,
+      projects: widgetProjectsInput,
     },
     withToolLogging("update_dashboard_widget", async (params) => {
       requireApiKey();

package/src/langwatch-api-dashboard-widgets.ts

@@ -14,6 +14,7 @@ export interface DashboardWidgetQueryInput {
   }[];
   /** The trace origins the query counts; `null` makes it unset, counting application. */
   sources?: WidgetSource[] | null;
+  projects?: string[] | null;
 }
 
 /** Where a widget came from, as the platform records it. */

package/src/langwatch-api-query.ts

@@ -25,6 +25,8 @@ export interface QueryRunResponse {
   };
   truncated: boolean;
   diagnostics: { code: string; message: string }[];
+  /** Each placeholder the SQL declares by its name, plus `period`; absent on an older platform. */
+  params?: Record<string, unknown>;
 }
 
 /** One published dataset. */
@@ -101,10 +103,14 @@ export interface QueryReferenceResponse {
 export async function runQuery(params: {
   sql: string;
   parameters?: Record<string, string | number | boolean | null>;
+  projects?: string[] | string;
+  sources?: string[];
 }): Promise<QueryRunResponse> {
   return makeRequest("POST", "/api/v1/query", {
     sql: params.sql,
     ...(params.parameters ? { parameters: params.parameters } : {}),
+    ...(params.projects ? { projects: params.projects } : {}),
+    ...(params.sources ? { sources: params.sources } : {}),
   }) as Promise<QueryRunResponse>;
 }
 

package/src/langwatch-api.ts

@@ -180,6 +180,15 @@ interface ParsedErrorBody {
   docsUrl?: string;
   fault?: HandledErrorFault;
   reasons?: SerializedReason[];
+  /** What the error says beyond its reasons, such as the names it refused. */
+  meta?: Record<string, unknown>;
+}
+
+/** The error's own facts: `meta` without the reasons (shown apart) and the request echo. */
+function detailsOf(meta: Record<string, unknown>): Record<string, unknown> | undefined {
+  const { reasons: _reasons, target: _target, fields: _fields, ...details } = meta;
+
+  return Object.keys(details).length > 0 ? details : undefined;
 }
 
 const VALID_FAULTS: readonly HandledErrorFault[] = [
@@ -216,11 +225,14 @@ function parseErrorBody(responseBody: string): ParsedErrorBody {
     const fault = VALID_FAULTS.includes(body.fault as HandledErrorFault)
       ? (body.fault as HandledErrorFault)
       : undefined;
+    // The v1 envelope carries the per-field failures in `meta.reasons`; older ones at the top.
+    const meta = isRecord(body.meta) ? body.meta : {};
+    const rawReasons = Array.isArray(body.reasons) ? body.reasons : meta.reasons;
     const reasons =
-      Array.isArray(body.reasons) && body.reasons.every((r) => !!r && typeof r === "object")
-        ? (body.reasons as SerializedReason[])
+      Array.isArray(rawReasons) && rawReasons.every((r) => !!r && typeof r === "object")
+        ? (rawReasons as SerializedReason[])
         : undefined;
-    return { code, message, tips, docsUrl, fault, reasons };
+    return { code, message, tips, docsUrl, fault, reasons, meta: detailsOf(meta) };
   } catch {
     return {};
   }
@@ -267,6 +279,39 @@ function describeReason(reason: SerializedReason): string | null {
   return parts.join(" — ");
 }
 
+/** The error an unsuccessful response becomes: its message, code, details, fields and tips. */
+function apiErrorOf({
+  status,
+  responseBody,
+}: {
+  status: number;
+  responseBody: string;
+}): LangWatchApiError {
+  const parsed = parseErrorBody(responseBody);
+  const lines = [`LangWatch API error ${status}: ${parsed.message ?? responseBody}`];
+  if (parsed.code) lines.push(`Code: ${parsed.code}`);
+  if (parsed.meta) lines.push(`Details: ${JSON.stringify(parsed.meta)}`);
+  const reasonLines = (parsed.reasons ?? [])
+    .map(describeReason)
+    .filter((line): line is string => line !== null);
+  if (reasonLines.length > 0) {
+    lines.push("Rejected fields:", ...reasonLines);
+  }
+  if (parsed.tips && parsed.tips.length > 0) {
+    lines.push("Tips:", ...parsed.tips.map((tip) => `- ${tip}`));
+  }
+  if (parsed.docsUrl) {
+    lines.push(`Docs: ${parsed.docsUrl}`);
+  }
+  return new LangWatchApiError(lines.join("\n"), status, responseBody, {
+    code: parsed.code,
+    tips: parsed.tips,
+    docsUrl: parsed.docsUrl,
+    fault: parsed.fault,
+    reasons: parsed.reasons,
+  });
+}
+
 /**
  * Sends an HTTP request to the LangWatch API. Builds the full URL from the configured endpoint,
  * adds authentication, and handles JSON serialization/deserialization. @throws
@@ -301,30 +346,8 @@ export async function makeRequest(
     ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
   });
 
-  if (!response.ok) {
-    const responseBody = await response.text();
-    const parsed = parseErrorBody(responseBody);
-    const lines = [`LangWatch API error ${response.status}: ${parsed.message ?? responseBody}`];
-    const reasonLines = (parsed.reasons ?? [])
-      .map(describeReason)
-      .filter((line): line is string => line !== null);
-    if (reasonLines.length > 0) {
-      lines.push("Rejected fields:", ...reasonLines);
-    }
-    if (parsed.tips && parsed.tips.length > 0) {
-      lines.push("Tips:", ...parsed.tips.map((tip) => `- ${tip}`));
-    }
-    if (parsed.docsUrl) {
-      lines.push(`Docs: ${parsed.docsUrl}`);
-    }
-    throw new LangWatchApiError(lines.join("\n"), response.status, responseBody, {
-      code: parsed.code,
-      tips: parsed.tips,
-      docsUrl: parsed.docsUrl,
-      fault: parsed.fault,
-      reasons: parsed.reasons,
-    });
-  }
+  if (!response.ok)
+    throw apiErrorOf({ status: response.status, responseBody: await response.text() });
 
   if (response.status === 204 || response.headers?.get("content-length") === "0") {
     return null;

package/src/schemas/widget-sources.ts

@@ -4,6 +4,8 @@
  */
 import { z } from "zod";
 
+const isAllWord = (id: string) => id.trim().toLowerCase() === "all";
+
 /** The sources the platform takes, "other" being every origin not listed before it. */
 export const WIDGET_SOURCES = [
   "application",
@@ -31,3 +33,37 @@ export const widgetSourcesInput = z
   .describe(
     `The trace origins every query of the widget counts: any of ${WIDGET_SOURCES.join(", ")} (other = any origin not listed). A new widget counts ["application"]; add "langy" to count your own conversations, as a widget about Langy's requests needs. null makes it unset again, counting the default.`,
   );
+
+/**
+ * The tools' `projects` input: the project ids every query of the widget reads. Absent, a query
+ * keeps what it stores (a new widget reads its board's project); null makes it unset again.
+ */
+const ALL_NOT_STORED = 'projects holds project ids; "all" is not stored in a widget';
+// run_query takes "all"; a widget stores ids. The refine carries the message for "all" as a
+// string or inside the array, and adds nothing to the tool's JSON Schema.
+export const widgetProjectsInput = z
+  .array(z.string().min(1), {
+    error: (issue) =>
+      typeof issue.input === "string" && isAllWord(issue.input) ? ALL_NOT_STORED : undefined,
+  })
+  .min(1)
+  .refine((ids) => !ids.some(isAllWord), { message: ALL_NOT_STORED })
+  .nullable()
+  .optional()
+  .describe(
+    "The project ids every query of the widget reads, each one you can read. A new widget reads its board's project. null makes it unset again, reading the board's project.",
+  );
+
+/**
+ * run_query's `projects`: ids, or the lone word "all" in any case. Mirrors holdsAllWord and
+ * LWQL_ALL_STANDS_ALONE in analytics-lwql.schemas.ts, which MCP cannot import.
+ */
+export const runQueryProjectsInput = z.union([
+  z.string().refine(isAllWord),
+  z
+    .array(z.string().min(1))
+    .min(1)
+    .refine((ids) => !ids.some(isAllWord), {
+      message: '"all" stands alone; send it by itself, or list project ids',
+    }),
+]);

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

@@ -8,7 +8,7 @@ import type { WidgetSource } from "../schemas/widget-sources.js";
 import {
   type DashboardWidgetQueriesInput,
   normalizeDashboardWidgetQueries,
-  withSources,
+  withLists,
 } from "./dashboard-widget-queries.js";
 
 export interface AddDashboardWidgetParams {
@@ -18,12 +18,15 @@ export interface AddDashboardWidgetParams {
   queries: DashboardWidgetQueriesInput;
   /** Set on every query; absent, the platform stores application on each. */
   sources?: WidgetSource[] | null;
+  /** Set on every query; absent, the widget reads its board's project. */
+  projects?: string[] | null;
 }
 
 export async function handleAddDashboardWidget(params: AddDashboardWidgetParams): Promise<string> {
-  const queries = withSources({
+  const queries = withLists({
     queries: normalizeDashboardWidgetQueries({ queries: params.queries }),
     sources: params.sources,
+    projects: params.projects,
   });
 
   let widget;

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

@@ -1,16 +1,25 @@
 import type { DashboardWidgetQueryInput } from "../langwatch-api-dashboard-widgets.js";
 import type { WidgetSource } from "../schemas/widget-sources.js";
 
-/** Every query with `sources` set to the list given; as given when no list was named. */
-export function withSources({
+/**
+ * Every query with `sources` and `projects` set to the lists given; a list not named is left as
+ * the query has it.
+ */
+export function withLists({
   queries,
   sources,
+  projects,
 }: {
   queries: readonly DashboardWidgetQueryInput[];
   sources: WidgetSource[] | null | undefined;
+  projects?: string[] | null | undefined;
 }): DashboardWidgetQueryInput[] {
-  if (sources === undefined) return [...queries];
-  return queries.map((query) => ({ ...query, sources }));
+  if (sources === undefined && projects === undefined) return [...queries];
+  return queries.map((query) => ({
+    ...query,
+    ...(sources === undefined ? {} : { sources }),
+    ...(projects === undefined ? {} : { projects }),
+  }));
 }
 
 /** A widget file rarely needs more than a couple of named queries (server bound). */

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

@@ -11,7 +11,7 @@ import type { WidgetSource } from "../schemas/widget-sources.js";
 import {
   type DashboardWidgetQueriesInput,
   normalizeDashboardWidgetQueries,
-  withSources,
+  withLists,
 } from "./dashboard-widget-queries.js";
 
 export interface UpdateDashboardWidgetParams {
@@ -23,16 +23,18 @@ export interface UpdateDashboardWidgetParams {
   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, sources } = params;
-  const fields = [name, code, params.queries, description, sources];
+  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 or sources to change.",
+      "Provide at least one of name, code, queries, description, sources or projects to change.",
     );
   }
 
@@ -42,8 +44,9 @@ export async function handleUpdateDashboardWidget(
       ? undefined
       : normalizeDashboardWidgetQueries({ queries: params.queries });
   // Sources alone: the stored queries go back with the new list on each.
-  const base = given ?? (sources === undefined ? undefined : current.definition.queries);
-  const queries = base === undefined ? undefined : withSources({ queries: base, sources });
+  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 changes = {
     ...(name === undefined ? {} : { name }),