@langwatch/mcp-server 2.1.0 → 2.2.0

package/src/langwatch-api-triggers.ts

@@ -1,48 +1,110 @@
-import { makeRequest } from "./langwatch-api.js";
+import { z } from "zod";
 
-export interface TriggerSummary {
-  id: string;
-  name: string;
-  action: string;
-  actionParams: Record<string, unknown>;
-  filters: Record<string, unknown>;
-  active: boolean;
-  message: string | null;
-  alertType: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
+import { makeRequest } from "./langwatch-api.ts";
+import {
+  deletedTriggerSchema,
+  type GraphAlertRule,
+  type NotificationCadence,
+  type ReportRule,
+  type TestFireResult,
+  type Trigger,
+  type TriggerAction,
+  type TriggerActionParams,
+  type TriggerAlertType,
+  type TriggerFirePage,
+  type TriggerTemplates,
+  testFireResultSchema,
+  triggerFirePageSchema,
+  triggerSchema,
+} from "./schemas/triggers.ts";
 
-export async function listTriggers(): Promise<TriggerSummary[]> {
-  return makeRequest("GET", "/api/triggers") as Promise<TriggerSummary[]>;
-}
+/**
+ * The `/api/v1/triggers` calls, each answering with the shape `schemas/triggers` declares.
+ * Responses are read through that schema, not cast, so a deployment that stops sending something
+ * a tool renders fails loudly instead of leaving an `undefined` in an agent's message.
+ */
 
-export async function getTrigger(id: string): Promise<TriggerSummary> {
-  return makeRequest("GET", `/api/triggers/${encodeURIComponent(id)}`) as Promise<TriggerSummary>;
-}
-
-export async function createTrigger(data: {
+export interface CreateTriggerInput {
   name: string;
-  action: string;
-  actionParams?: Record<string, unknown>;
+  action: TriggerAction;
+  /** Omitted sends `{}`, as before `actionParams` was stated per channel. */
+  actionParams?: TriggerActionParams;
   filters?: Record<string, unknown>;
+  filterQuery?: string | null;
   message?: string;
-  alertType?: string;
-}): Promise<TriggerSummary> {
-  return makeRequest("POST", "/api/triggers", data) as Promise<TriggerSummary>;
+  alertType?: TriggerAlertType;
+  customGraphId?: string;
+  graphAlert?: GraphAlertRule;
+  report?: ReportRule;
+  templates?: TriggerTemplates;
+  notificationCadence?: NotificationCadence;
 }
 
-export async function updateTrigger(params: {
+/** `actionParams` replaces the delivery configuration as a whole; a credential
+ *  sent back as `[redacted]` keeps the stored one. The channel cannot change. */
+type UpdateTriggerInput = Partial<
+  Omit<CreateTriggerInput, "action" | "customGraphId" | "message" | "alertType">
+> & {
   id: string;
-  name?: string;
   active?: boolean;
   message?: string | null;
-  alertType?: string | null;
-}): Promise<TriggerSummary> {
-  const { id, ...data } = params;
-  return makeRequest("PATCH", `/api/triggers/${encodeURIComponent(id)}`, data) as Promise<TriggerSummary>;
+  alertType?: TriggerAlertType | null;
+};
+
+export async function listTriggers(): Promise<Trigger[]> {
+  return z.array(triggerSchema).parse(await makeRequest("GET", "/api/v1/triggers"));
+}
+
+export async function getTrigger(id: string): Promise<Trigger> {
+  return triggerSchema.parse(
+    await makeRequest("GET", `/api/v1/triggers/${encodeURIComponent(id)}`),
+  );
+}
+
+export async function createTrigger(input: CreateTriggerInput): Promise<Trigger> {
+  return triggerSchema.parse(
+    await makeRequest("POST", "/api/v1/triggers", {
+      ...input,
+      actionParams: input.actionParams ?? {},
+    }),
+  );
+}
+
+export async function updateTrigger({ id, ...data }: UpdateTriggerInput): Promise<Trigger> {
+  return triggerSchema.parse(
+    await makeRequest("PATCH", `/api/v1/triggers/${encodeURIComponent(id)}`, data),
+  );
+}
+
+/** Send the automation's message to the destination it is saved with. */
+export async function testFireTrigger(id: string): Promise<TestFireResult> {
+  return testFireResultSchema.parse(
+    await makeRequest("POST", `/api/v1/triggers/${encodeURIComponent(id)}/test-fire`),
+  );
+}
+
+/** What the automation has done, newest first. Metadata only. `cursor` reads
+ *  the page after the one that answered with it as `nextCursor`. */
+export async function listTriggerFires({
+  id,
+  limit,
+  cursor,
+}: {
+  id: string;
+  limit?: number;
+  cursor?: string;
+}): Promise<TriggerFirePage> {
+  const query = new URLSearchParams();
+  if (limit !== undefined) query.set("limit", String(limit));
+  if (cursor) query.set("cursor", cursor);
+  const search = query.toString() ? `?${query.toString()}` : "";
+  return triggerFirePageSchema.parse(
+    await makeRequest("GET", `/api/v1/triggers/${encodeURIComponent(id)}/fires${search}`),
+  );
 }
 
-export async function deleteTrigger(id: string): Promise<{ id: string; deleted: boolean }> {
-  return makeRequest("DELETE", `/api/triggers/${encodeURIComponent(id)}`) as Promise<{ id: string; deleted: boolean }>;
+export async function deleteTrigger(id: string): Promise<z.infer<typeof deletedTriggerSchema>> {
+  return deletedTriggerSchema.parse(
+    await makeRequest("DELETE", `/api/v1/triggers/${encodeURIComponent(id)}`),
+  );
 }

package/src/langwatch-api-workflows.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface WorkflowSummary {
   id: string;
@@ -12,30 +12,30 @@ export interface WorkflowSummary {
 }
 
 export async function listWorkflows(): Promise<WorkflowSummary[]> {
-  return makeRequest("GET", "/api/workflows") as Promise<WorkflowSummary[]>;
+  return makeRequest("GET", "/api/v1/workflows") as Promise<WorkflowSummary[]>;
 }
 
 export async function getWorkflow(id: string): Promise<WorkflowSummary> {
   return makeRequest(
     "GET",
-    `/api/workflows/${encodeURIComponent(id)}`,
+    `/api/v1/workflows/${encodeURIComponent(id)}`,
   ) as Promise<WorkflowSummary>;
 }
 
 export async function runWorkflow(
   id: string,
-  input?: Record<string, unknown>
+  input?: Record<string, unknown>,
 ): Promise<Record<string, unknown>> {
   return makeRequest(
     "POST",
-    `/api/workflows/${encodeURIComponent(id)}/run`,
+    `/api/v1/workflows/${encodeURIComponent(id)}/run`,
     input ?? {},
   ) as Promise<Record<string, unknown>>;
 }
 
 export async function deleteWorkflow(id: string): Promise<{ id: string; archived: boolean }> {
-  return makeRequest(
-    "DELETE",
-    `/api/workflows/${encodeURIComponent(id)}`,
-  ) as Promise<{ id: string; archived: boolean }>;
+  return makeRequest("DELETE", `/api/v1/workflows/${encodeURIComponent(id)}`) as Promise<{
+    id: string;
+    archived: boolean;
+  }>;
 }

package/src/langwatch-api.ts

@@ -1,9 +1,17 @@
-import type {
-  HandledErrorFault,
-  SerializedReason,
-} from "@langwatch/handled-error";
-import { getConfig, requireApiKey } from "./config.js";
-import type { EvaluationSummary } from "./utils/format-evaluations.js";
+import type { HandledErrorFault, SerializedReason } from "@langwatch/handled-error";
+
+import packageJson from "../package.json" with { type: "json" };
+import { getConfig, requireApiKey } from "./config.ts";
+import type { EvaluationSummary } from "./utils/format-evaluations.ts";
+
+/** Every request names itself so the platform attributes it. */
+// See specs/observability/traffic-attribution.feature.
+export const MCP_IDENTITY_HEADERS: Record<string, string> = {
+  "User-Agent": `langwatch-mcp/${packageJson.version}`,
+  "X-LangWatch-SDK-Name": "langwatch-mcp",
+  "X-LangWatch-SDK-Language": "typescript",
+  "X-LangWatch-SDK-Version": packageJson.version,
+};
 
 // --- Response types ---
 
@@ -46,7 +54,7 @@ export interface TraceDetailResponse {
   error?: Record<string, unknown>;
   ascii_tree?: string;
   evaluations?: EvaluationSummary[];
-  spans?: Array<{
+  spans?: {
     span_id: string;
     name?: string;
     type?: string;
@@ -61,7 +69,7 @@ export interface TraceDetailResponse {
       tokens_estimated?: boolean;
       cost?: number;
     };
-  }>;
+  }[];
 }
 
 export interface AnalyticsBucket {
@@ -87,14 +95,10 @@ export interface PromptTag {
   versionId: string;
 }
 
-export type PromptFieldList = Array<{ identifier: string; type: string }>;
+export type PromptFieldList = { identifier: string; type: string }[];
 
 /**
- * A single versioned prompt payload. `GET /api/prompts/:id` returns the
- * requested version's data flattened to the top level (merged with the base
- * prompt data), and `GET /api/prompts/:id/versions` returns an array of
- * entries in this same shape — there is no nested `versions` array on the
- * detail response.
+ * A single versioned prompt payload.
  */
 export interface PromptVersion {
   versionId?: string;
@@ -103,7 +107,7 @@ export interface PromptVersion {
   model?: string;
   /** Legacy single-text prompt body. */
   prompt?: string;
-  messages?: Array<{ role: string; content: string }>;
+  messages?: { role: string; content: string }[];
   temperature?: number;
   maxTokens?: number;
   responseFormat?: Record<string, unknown> | null;
@@ -134,10 +138,9 @@ export class LangWatchApiError extends Error {
   readonly docsUrl?: string;
   readonly fault?: HandledErrorFault;
   /**
-   * The per-field failures behind this error, verbatim from the envelope.
-   * A validation failure carries the offending field and the values it would
-   * have accepted here — the difference between an agent correcting its own
-   * request and an agent guessing again.
+   * The per-field failures behind this error, verbatim from the envelope. A validation failure
+   * carries the offending field and the values it would have accepted here — the difference
+   * between an agent correcting its own request and an agent guessing again.
    */
   readonly reasons?: SerializedReason[];
 
@@ -173,56 +176,42 @@ interface ParsedErrorBody {
   reasons?: SerializedReason[];
 }
 
-const VALID_FAULTS: readonly HandledErrorFault[] = ["customer", "platform", "provider"];
+const VALID_FAULTS: readonly HandledErrorFault[] = [
+  "customer",
+  "platform",
+  "provider",
+  "presumed_platform",
+];
 
 /**
- * Parses an error response body as a handled-error envelope. Accepts three
- * shapes: the canonical v1 envelope
- * (`{ error: { type, code, message, meta?, trace_id } }`), the legacy REST
- * shape (`{ error: "<code>", message, tips?, docsUrl?, fault? }`) and the
- * serialized tRPC shape (`{ code, message?, tips?, docsUrl?, fault?, ... }`).
- * Returns an empty object when the body is not a recognizable error envelope.
+ * Parses an error response body as a handled-error envelope.
  */
 function parseErrorBody(responseBody: string): ParsedErrorBody {
   try {
     const parsed: unknown = JSON.parse(responseBody);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      return {};
-    }
-    const envelope = parsed as Record<string, unknown>;
+    if (!isRecord(parsed)) return {};
+    const envelope = parsed;
     // The canonical v1 envelope nests everything under `error`. Read the
     // nested object as the body so one parser serves both generations.
-    const nested =
-      typeof envelope.error === "object" &&
-      envelope.error !== null &&
-      !Array.isArray(envelope.error)
-        ? (envelope.error as Record<string, unknown>)
-        : null;
+    const nestedValue = envelope.error;
+    const nested = isRecord(nestedValue) ? nestedValue : null;
     const body = nested ?? envelope;
-    // Prefer `code` (the domain discriminant) over `error` — the
-    // packages/api unversioned envelope uses `error` for the HTTP status
-    // text ("Not Found") while `code` holds the real code.
-    const code =
-      typeof body.code === "string"
-        ? body.code
-        : typeof body.error === "string"
-          ? body.error
-          : undefined;
+    // `code` is the domain discriminant. The `error` fallback reads the
+    // legacy envelope some non-framework families still send; the framework's
+    // own unversioned union envelope, which used `error` for the HTTP status
+    // text, is gone (packages/api/adrs/002).
+    const code = readErrorCode(body);
     const message = typeof body.message === "string" ? body.message : undefined;
     if (code === undefined && message === undefined) {
       return {};
     }
-    const tips =
-      Array.isArray(body.tips) && body.tips.every((t) => typeof t === "string")
-        ? (body.tips as string[])
-        : undefined;
+    const tips = readStringArray(body.tips);
     const docsUrl = typeof body.docsUrl === "string" ? body.docsUrl : undefined;
     const fault = VALID_FAULTS.includes(body.fault as HandledErrorFault)
       ? (body.fault as HandledErrorFault)
       : undefined;
     const reasons =
-      Array.isArray(body.reasons) &&
-      body.reasons.every((r) => !!r && typeof r === "object")
+      Array.isArray(body.reasons) && body.reasons.every((r) => !!r && typeof r === "object")
         ? (body.reasons as SerializedReason[])
         : undefined;
     return { code, message, tips, docsUrl, fault, reasons };
@@ -231,14 +220,29 @@ function parseErrorBody(responseBody: string): ParsedErrorBody {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readErrorCode(body: Record<string, unknown>): string | undefined {
+  if (typeof body.code === "string") return body.code;
+  if (typeof body.error === "string") return body.error;
+  return undefined;
+}
+
+function readStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || !value.every(isString)) return undefined;
+  return value;
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
 /**
- * The human line for one per-field failure: the field, what it would have
- * accepted, and what it got. Returns null when a reason names no field, so a
- * generic nested error adds no noise to the message.
- *
- * This exists because the MCP transport's only channel to the caller is the
- * error MESSAGE — an agent never sees the `reasons` array itself, so a
- * rejection whose remedy lives only there is unfollowable.
+ * The human line for one per-field failure: the field, what it would have accepted, and what it
+ * got. Returns null when a reason names no field, so a generic nested error adds no noise to
+ * the message.
  */
 function describeReason(reason: SerializedReason): string | null {
   const meta = reason.meta;
@@ -258,22 +262,19 @@ function describeReason(reason: SerializedReason): string | null {
 }
 
 /**
- * Sends an HTTP request to the LangWatch API.
- *
- * Builds the full URL from the configured endpoint, adds authentication,
- * and handles JSON serialization/deserialization.
- *
- * @throws LangWatchApiError with status code and response body when the
- * response is not OK.
+ * Sends an HTTP request to the LangWatch API. Builds the full URL from the configured endpoint,
+ * adds authentication, and handles JSON serialization/deserialization. @throws
+ * LangWatchApiError with status code and response body when the response is not OK.
  */
 export async function makeRequest(
   method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
   path: string,
-  body?: unknown
+  body?: unknown,
 ): Promise<unknown> {
   const config = getConfig();
   const url = config.endpoint + path;
   const headers: Record<string, string> = {
+    ...MCP_IDENTITY_HEADERS,
     "X-Auth-Token": requireApiKey(),
   };
   if (config.projectId) {
@@ -293,9 +294,7 @@ export async function makeRequest(
   if (!response.ok) {
     const responseBody = await response.text();
     const parsed = parseErrorBody(responseBody);
-    const lines = [
-      `LangWatch API error ${response.status}: ${parsed.message ?? responseBody}`,
-    ];
+    const lines = [`LangWatch API error ${response.status}: ${parsed.message ?? responseBody}`];
     const reasonLines = (parsed.reasons ?? [])
       .map(describeReason)
       .filter((line): line is string => line !== null);
@@ -308,18 +307,13 @@ export async function makeRequest(
     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,
-      },
-    );
+    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.status === 204 || response.headers?.get("content-length") === "0") {
@@ -329,16 +323,19 @@ export async function makeRequest(
 }
 
 /**
- * Searches traces with optional filters and pagination.
- *
- * Paging is by `scrollId` only: pass the one the previous response returned,
- * and stop when a response carries none. `pageOffset` used to be accepted here
- * but was never read by the server, so an offset walk silently re-served the
- * first page; it is rejected at the boundary now (#6808).
+ * Searches traces with optional filters and pagination. Paging is by `scrollId` only: pass the
+ * one the previous response returned, and stop when a response carries none.
  */
 export async function searchTraces(params: {
   query?: string;
+  /** Exact trace ids: a primary-key seek on trace_summaries, not a scan (ADR-164). */
+  traceIds?: string[];
   filters?: Record<string, string[]>;
+  /**
+   * The Trace Explorer's query language, as one string. Combined server-side
+   * with `filters`, `query` and `traceIds` rather than replacing any of them.
+   */
+  filter?: string;
   startDate: number;
   endDate: number;
   pageSize?: number;
@@ -346,7 +343,7 @@ export async function searchTraces(params: {
   format?: "digest" | "json";
 }): Promise<SearchTracesResponse> {
   const { format = "digest", ...rest } = params;
-  return makeRequest("POST", "/api/traces/search", {
+  return makeRequest("POST", "/api/v1/traces/search", {
     ...rest,
     format,
   }) as Promise<SearchTracesResponse>;
@@ -355,22 +352,22 @@ export async function searchTraces(params: {
 /** Retrieves a single trace by its ID. */
 export async function getTraceById(
   traceId: string,
-  format: "digest" | "json" = "digest"
+  format: "digest" | "json" = "digest",
 ): Promise<TraceDetailResponse> {
   return makeRequest(
     "GET",
-    `/api/traces/${encodeURIComponent(traceId)}?format=${format}`
+    `/api/v1/traces/${encodeURIComponent(traceId)}?format=${format}`,
   ) as Promise<TraceDetailResponse>;
 }
 
 /** Fetches analytics timeseries data for the given metrics and date range. */
 export async function getAnalyticsTimeseries(params: {
-  series: Array<{
+  series: {
     metric: string;
     aggregation: string;
     key?: string;
     subkey?: string;
-  }>;
+  }[];
   startDate: number;
   endDate: number;
   timeZone?: string;
@@ -380,20 +377,20 @@ export async function getAnalyticsTimeseries(params: {
 }): Promise<AnalyticsTimeseriesResponse> {
   return makeRequest(
     "POST",
-    "/api/analytics/timeseries",
-    params
+    "/api/v1/analytics/timeseries",
+    params,
   ) as Promise<AnalyticsTimeseriesResponse>;
 }
 
 /** Lists all prompts in the project. */
 export async function listPrompts(): Promise<PromptSummary[]> {
-  return makeRequest("GET", "/api/prompts") as Promise<PromptSummary[]>;
+  return makeRequest("GET", "/api/v1/prompts") as Promise<PromptSummary[]>;
 }
 
 /** Retrieves a single prompt by ID or handle. */
 export async function getPrompt(
   idOrHandle: string,
-  options?: { version?: number; tag?: string }
+  options?: { version?: number; tag?: string },
 ): Promise<PromptDetailResponse> {
   const params = new URLSearchParams();
   if (options?.version != null) params.set("version", String(options.version));
@@ -401,48 +398,42 @@ export async function getPrompt(
   const query = params.toString() ? `?${params}` : "";
   return makeRequest(
     "GET",
-    `/api/prompts/${encodeURIComponent(idOrHandle)}${query}`
+    `/api/v1/prompts/${encodeURIComponent(idOrHandle)}${query}`,
   ) as Promise<PromptDetailResponse>;
 }
 
 /** Lists all versions of a prompt (versioned data only). */
-export async function getPromptVersions(
-  idOrHandle: string
-): Promise<PromptVersion[]> {
+export async function getPromptVersions(idOrHandle: string): Promise<PromptVersion[]> {
   return makeRequest(
     "GET",
-    `/api/prompts/${encodeURIComponent(idOrHandle)}/versions`
+    `/api/v1/prompts/${encodeURIComponent(idOrHandle)}/versions`,
   ) as Promise<PromptVersion[]>;
 }
 
 /** Creates a new prompt. */
 export async function createPrompt(data: {
   handle: string;
-  messages: Array<{ role: string; content: string }>;
+  messages: { role: string; content: string }[];
   model: string;
   tags?: string[];
 }): Promise<PromptMutationResponse> {
-  return makeRequest(
-    "POST",
-    "/api/prompts",
-    data
-  ) as Promise<PromptMutationResponse>;
+  return makeRequest("POST", "/api/v1/prompts", data) as Promise<PromptMutationResponse>;
 }
 
 /** Updates an existing prompt by ID or handle. */
 export async function updatePrompt(
   idOrHandle: string,
   data: {
-    messages?: Array<{ role: string; content: string }>;
+    messages?: { role: string; content: string }[];
     model?: string;
     commitMessage: string;
     tags?: string[];
-  }
+  },
 ): Promise<PromptMutationResponse> {
   return makeRequest(
     "PUT",
-    `/api/prompts/${encodeURIComponent(idOrHandle)}`,
-    data
+    `/api/v1/prompts/${encodeURIComponent(idOrHandle)}`,
+    data,
   ) as Promise<PromptMutationResponse>;
 }
 
@@ -458,19 +449,19 @@ export async function assignPromptTag({
 }): Promise<unknown> {
   return makeRequest(
     "PUT",
-    `/api/prompts/${encodeURIComponent(idOrHandle)}/tags/${encodeURIComponent(tag)}`,
-    { versionId }
+    `/api/v1/prompts/${encodeURIComponent(idOrHandle)}/tags/${encodeURIComponent(tag)}`,
+    { versionId },
   );
 }
 
 /** Lists all prompt tag definitions for the organization. */
 export async function listPromptTags(): Promise<unknown> {
-  return makeRequest("GET", "/api/prompts/tags");
+  return makeRequest("GET", "/api/v1/prompts/tags");
 }
 
 /** Creates a custom prompt tag definition. */
 export async function createPromptTag(name: string): Promise<unknown> {
-  return makeRequest("POST", "/api/prompts/tags", { name });
+  return makeRequest("POST", "/api/v1/prompts/tags", { name });
 }
 
 /** Renames an existing prompt tag. */
@@ -481,17 +472,10 @@ export async function renamePromptTag({
   tag: string;
   name: string;
 }): Promise<unknown> {
-  return makeRequest(
-    "PUT",
-    `/api/prompts/tags/${encodeURIComponent(tag)}`,
-    { name }
-  );
+  return makeRequest("PUT", `/api/v1/prompts/tags/${encodeURIComponent(tag)}`, { name });
 }
 
 /** Deletes a prompt tag and all its assignments. */
 export async function deletePromptTag(tag: string): Promise<unknown> {
-  return makeRequest(
-    "DELETE",
-    `/api/prompts/tags/${encodeURIComponent(tag)}`
-  );
+  return makeRequest("DELETE", `/api/v1/prompts/tags/${encodeURIComponent(tag)}`);
 }