@langwatch/mcp-server 2.0.0 → 2.2.0

package/src/schemas/run-plan.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+/**
+ * Typed inputs for the run plan tools, mirroring the platform's REST
+ * validation (`suiteScopeSchema` and `suiteTargetSchema`) so an agent
+ * learns what's accepted before the request goes out.
+ */
+
+/** What a run plan covers. */
+export const runPlanScopeSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("all") }).describe("Every non-archived scenario of the project"),
+  z
+    .object({
+      mode: z.literal("test_suites"),
+      testSuiteIds: z.array(z.string()).describe("The test suite IDs whose scenarios to run"),
+    })
+    .describe("The non-archived scenarios filed in the given test suites"),
+  z
+    .object({
+      mode: z.literal("labels"),
+      labels: z.array(z.string()).describe("The labels to select scenarios by"),
+    })
+    .describe("The non-archived scenarios carrying at least one of the given labels"),
+  z
+    .object({ mode: z.literal("scenarios") })
+    .describe("The scenarios named in scenarioIds, picked by hand"),
+]);
+
+/** The values a run supplies for the parameters its scenarios declare. */
+export const runParametersSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean()]),
+);
+
+/**
+ * One thing a plan runs its scenarios against, and the values it alone
+ * runs with. Parameters make a comparison run: two targets may name the
+ * same agent with different values, each run and reported on its own.
+ */
+export const runPlanTargetSchema = z.object({
+  type: z
+    .enum(["connected", "prompt", "http", "code", "workflow"])
+    .describe(
+      "What kind of thing the target is. A connected agent is one that registered itself from code with connectAgent (TypeScript) or connect_agent (Python).",
+    ),
+  referenceId: z
+    .string()
+    .describe(
+      "The ID of the prompt, agent or workflow to run against. A connected agent may also be named as <name>@<environment>, for example support-agent@production; the platform resolves it.",
+    ),
+  parameters: runParametersSchema
+    .optional()
+    .describe(
+      "Parameter values this target alone runs with, by name. They override the run-level parameters for this target. Name the same agent twice with different values here to compare it on two models.",
+    ),
+});
+
+/**
+ * One target as `/api/v1` carries it. Tool input spells per-target
+ * values `parameters`, beside run-level `parameters`; the REST body
+ * spells them `runParameters` since a target holds the values it runs with.
+ */
+export interface RunPlanTargetWire {
+  type: z.infer<typeof runPlanTargetSchema>["type"];
+  referenceId: string;
+  runParameters?: z.infer<typeof runParametersSchema>;
+}
+
+/** The targets of a tool call, as the REST body carries them. */
+export function toWireTargets(targets: z.infer<typeof runPlanTargetSchema>[]): RunPlanTargetWire[] {
+  return targets.map((target) => ({
+    type: target.type,
+    referenceId: target.referenceId,
+    ...(target.parameters ? { runParameters: target.parameters } : {}),
+  }));
+}

package/src/schemas/suite-fields.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+
+// Typed inputs for suite fields, evaluators, and scenario values that mirror the
+// server-side validation schemas so agents know what's accepted before sending.
+
+/** The value types a field can hold. */
+export const SUITE_FIELD_TYPES = ["text", "number", "boolean"] as const;
+
+/** One field a test suite declares. */
+export const suiteFieldSchema = z.object({
+  identifier: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z][a-z0-9_]*$/, "Lowercase letters, digits and underscores, starting with a letter")
+    .describe(
+      "The field name, as scenarios and evaluator mappings address it, for example golden_sql. Lowercase letters, digits and underscores, starting with a letter. situation, criteria, name, input and output are reserved.",
+    ),
+  type: z.enum(SUITE_FIELD_TYPES).describe("The value type every scenario carries for this field."),
+});
+
+/** The fields a test suite declares, in the order the platform shows them. */
+export const suiteFieldsSchema = z
+  .array(suiteFieldSchema)
+  .max(30)
+  .describe(
+    "The fields the test suite declares, in order. Up to 30. Every scenario filed in the suite carries one value per field, and an evaluator attached to the suite reads them through its mappings.",
+  );
+
+/** The sources an evaluator input can read from. */
+export const SCENARIO_MAPPING_SOURCE_IDS = ["conversation", "scenario", "trace"] as const;
+
+/** Where one evaluator input reads its value: a source path or a literal. */
+export const scenarioMappingSchema = z
+  .discriminatedUnion("type", [
+    z.object({
+      type: z.literal("source"),
+      sourceId: z
+        .enum(SCENARIO_MAPPING_SOURCE_IDS)
+        .describe(
+          "conversation, scenario or trace. See discover_schema({ category: 'scenarios' }) for the paths each one offers.",
+        ),
+      path: z
+        .array(z.string().min(1).max(256))
+        .min(1)
+        .max(3)
+        .describe(
+          "The path inside the source. conversation: [first_user_message] | [last_agent_message] | [transcript] | [messages]. scenario: [situation] | [criteria] | [fields, <identifier>]. trace: [contexts] | [tool_calls, <toolName>, input|output].",
+        ),
+    }),
+    z.object({
+      type: z.literal("value"),
+      value: z.string().max(65_536).describe("A literal the input reads."),
+    }),
+  ])
+  .describe(
+    "Where one evaluator input reads its value: a path into the conversation, the scenario or the trace, or a literal value.",
+  );
+
+/** One evaluator attached to a test suite or a run plan. */
+export const evaluatorAttachmentSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe(
+      "The attachment id, stable across edits. Leave it out on a new attachment and one is generated.",
+    ),
+  evaluatorId: z
+    .string()
+    .min(1)
+    .describe(
+      "The id of the saved evaluator to run. Read it from platform_list_evaluators or platform_get_evaluator.",
+    ),
+  required: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether a failing result fails the scenario. Defaults to true. A score-only evaluator reports and never gates, whatever this says.",
+    ),
+  mappings: z
+    .record(z.string().min(1).max(128), scenarioMappingSchema)
+    .describe(
+      "Where each evaluator input reads its value, keyed by input name. Read the inputs from platform_get_evaluator. A required input with no mapping makes the platform refuse the run until it is set.",
+    ),
+});
+
+/** The evaluators attached to a test suite or a run plan. */
+export const evaluatorAttachmentsSchema = z
+  .array(evaluatorAttachmentSchema)
+  .max(20)
+  .describe(
+    "The evaluators that run after every scenario run, with their mappings. Up to 20. A required evaluator that fails fails the scenario; a score-only one reports beside the verdict.",
+  );
+
+/** The values a scenario carries for the fields its suite declares. */
+export const scenarioFieldValuesSchema = z
+  .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+  .describe(
+    "The scenario's value for each field its test suite declares, by identifier, for example { golden_sql: 'SELECT ...' }. A text field takes a string, a number field a number and a boolean field true or false. A field the suite does not declare is refused. On update, an empty object clears the values.",
+  );
+
+export type SuiteField = z.infer<typeof suiteFieldSchema>;
+export type ScenarioMapping = z.infer<typeof scenarioMappingSchema>;
+export type EvaluatorAttachmentInput = z.infer<typeof evaluatorAttachmentSchema>;
+export type ScenarioFieldValues = z.infer<typeof scenarioFieldValuesSchema>;
+
+/** One attachment as the REST surface carries it: id and gate settled. */
+export interface EvaluatorAttachmentWire {
+  id: string;
+  evaluatorId: string;
+  required: boolean;
+  mappings: Record<string, ScenarioMapping>;
+}
+
+const newAttachmentId = (): string => `att_${crypto.randomUUID().replace(/-/g, "").slice(0, 21)}`;
+
+/**
+ * The attachments of a tool call, as the REST body carries them: a missing
+ * id is generated and a missing gate defaults to required.
+ */
+export function toWireAttachments(
+  attachments: EvaluatorAttachmentInput[],
+): EvaluatorAttachmentWire[] {
+  return attachments.map((attachment) => ({
+    id: attachment.id ?? newAttachmentId(),
+    evaluatorId: attachment.evaluatorId,
+    required: attachment.required ?? true,
+    mappings: attachment.mappings,
+  }));
+}

package/src/schemas/triggers.ts

@@ -0,0 +1,365 @@
+import { z } from "zod";
+
+/** The shape of an automation on the `/api/v1/triggers` surface, stated once for
+ *  the tool registrations and the API client. Every type is inferred from its
+ *  schema, so what the API sends and what a caller reads cannot drift. */
+
+export const triggerActionSchema = z.enum([
+  "SEND_EMAIL",
+  "SEND_SLACK_MESSAGE",
+  "SEND_WEBHOOK",
+  "ADD_TO_DATASET",
+  "ADD_TO_ANNOTATION_QUEUE",
+]);
+export const alertTypeSchema = z.enum(["CRITICAL", "WARNING", "INFO"]);
+
+/** The delivery configuration each channel reads, stated per channel so an agent
+ *  can configure one without a round trip. Each passes unknown fields through:
+ *  every Slack field is optional, so a webhook destination would otherwise read
+ *  as an empty Slack one and be sent as nothing. */
+const emailActionParamsSchema = z
+  .object({
+    members: z
+      .array(z.string())
+      .min(1)
+      .describe("Who receives the email. Any address, not only teammates."),
+  })
+  .passthrough();
+
+const slackActionParamsSchema = z
+  .object({
+    slackIntegrationId: z
+      .string()
+      .optional()
+      .describe(
+        "The Slack connection to post through (an organization connection or one of this project's; they are listed in LangWatch under Settings, Integrations, Slack). A bot connection also needs `slackChannelId`; a webhook connection needs nothing else. Preferred over `slackWebhook` and `slackBotToken`.",
+      ),
+    slackDelivery: z
+      .enum(["webhook", "bot"])
+      .optional()
+      .describe(
+        "How the message reaches Slack. `webhook` posts to an incoming webhook URL, `bot` posts as the LangWatch Slack app. With `slackIntegrationId` it follows the connection's kind. Absent without a connection means `webhook`.",
+      ),
+    slackWebhook: z
+      .string()
+      .optional()
+      .describe(
+        "Legacy, accepted for one release: an incoming webhook URL (https://hooks.slack.com/...). It is stored as a Slack connection and the automation keeps only the connection id. Send `slackIntegrationId` instead.",
+      ),
+    slackChannelId: z
+      .string()
+      .optional()
+      .describe("The channel the bot posts in, for a bot connection or `bot` delivery."),
+    slackBotToken: z
+      .string()
+      .optional()
+      .describe(
+        "Legacy, accepted for one release: a bot token, stored as a Slack connection. It never reads back. Send `slackIntegrationId` instead.",
+      ),
+    slackBotTokenSet: z
+      .boolean()
+      .optional()
+      .describe(
+        "Legacy. Read: whether an automation not yet moved to a connection stores its own bot token. Write: true keeps it.",
+      ),
+  })
+  .passthrough();
+
+const webhookActionParamsSchema = z
+  .object({
+    url: z.string().describe("Where the request goes. https only, and not a private host."),
+    method: z.enum(["POST", "PUT", "PATCH"]).optional(),
+    headers: z
+      .record(z.string(), z.string())
+      .optional()
+      .describe(
+        "Static headers sent with every delivery. The values are credentials: they read back as [redacted], and sending [redacted] back keeps the stored ones. Changing `url` means sending the values again in the same call.",
+      ),
+    bodyTemplate: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "A Liquid template for the JSON body. Absent sends the standard LangWatch envelope.",
+      ),
+    signingSecret: z
+      .string()
+      .nullable()
+      .optional()
+      .describe("Signs every delivery so the receiver can verify it."),
+  })
+  .passthrough();
+
+const datasetActionParamsSchema = z
+  .object({
+    datasetId: z.string().describe("The dataset matched traces are appended to."),
+    datasetMapping: z
+      .object({
+        mapping: z.record(z.string(), z.unknown()),
+        expansions: z.array(z.string()).optional(),
+      })
+      .describe("How a trace becomes a row in that dataset."),
+  })
+  .passthrough();
+
+const annotationQueueActionParamsSchema = z
+  .object({
+    annotators: z
+      .array(z.object({ id: z.string(), name: z.string() }))
+      .min(1)
+      .describe("Who the queued items go to."),
+  })
+  .passthrough();
+
+export const actionParamsSchema = z.union([
+  emailActionParamsSchema,
+  slackActionParamsSchema,
+  webhookActionParamsSchema,
+  datasetActionParamsSchema,
+  annotationQueueActionParamsSchema,
+]);
+
+/** The write-side Slack shape: a redacted read round-trips, but a WRITE with no
+ *  destination cannot deliver, so it is refused with the field named. A
+ *  connection decides its own kind; without one, the legacy fields need a
+ *  webhook URL, or a channel and a token. */
+const slackActionParamsWriteSchema = slackActionParamsSchema.superRefine((params, ctx) => {
+  const delivery = params.slackDelivery ?? "webhook";
+  if (delivery === "bot" && !params.slackChannelId) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackChannelId"],
+      message: params.slackIntegrationId
+        ? "a bot connection needs the channel to post in"
+        : "bot delivery needs the channel to post in",
+    });
+  }
+  if (params.slackIntegrationId) return;
+  if (delivery === "webhook" && !params.slackWebhook) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackIntegrationId"],
+      message: "name the Slack connection to post through",
+    });
+  }
+  if (delivery === "bot" && !params.slackBotToken && params.slackBotTokenSet !== true) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["slackIntegrationId"],
+      message: "bot delivery needs the Slack connection to post through",
+    });
+  }
+});
+
+const ACTION_PARAMS_SCHEMA_BY_ACTION: Partial<Record<string, z.ZodTypeAny>> = {
+  SEND_EMAIL: emailActionParamsSchema,
+  SEND_SLACK_MESSAGE: slackActionParamsWriteSchema,
+  SEND_WEBHOOK: webhookActionParamsSchema,
+  ADD_TO_DATASET: datasetActionParamsSchema,
+  ADD_TO_ANNOTATION_QUEUE: annotationQueueActionParamsSchema,
+};
+
+/** A WRITE's `actionParams` is bound to the channel named in `action`, or a
+ *  `SEND_WEBHOOK` with `{}` slips through the all-optional Slack shape and is
+ *  refused server-side with worse words. An action this build does not know
+ *  validates against the loose union, the tolerance reads keep. */
+export function validateActionParamsForAction({
+  action,
+  actionParams,
+}: {
+  action: string;
+  actionParams: unknown;
+}): { ok: true } | { ok: false; message: string } {
+  const schema = ACTION_PARAMS_SCHEMA_BY_ACTION[action] ?? actionParamsSchema;
+  const parsed = schema.safeParse(actionParams);
+  if (parsed.success) return { ok: true };
+  const issues = parsed.error.issues
+    .map((issue) => `${issue.path.join(".") || "(actionParams)"}: ${issue.message}`)
+    .join("; ");
+  return {
+    ok: false,
+    message: `actionParams does not fit ${action} — ${issues}`,
+  };
+}
+
+/** How `filters` is written. A keyed field sent flat never matches, so each
+ *  keyed shape is spelled out; see the `/api/v1/triggers` 422 for the refusal. */
+export const TRIGGER_FILTERS_DESCRIPTION = [
+  "Trace conditions as a JSON object string.",
+  'Unkeyed fields take a list of values: {"traces.error":["true"]}.',
+  'Keyed fields nest a key above the list. evaluations.* is keyed by the MONITOR id (the `id` from `platform_list_monitors` / GET /api/v1/monitors, not its evaluatorId): {"evaluations.passed":{"<monitorId>":["false"]}}.',
+  'metadata.value is keyed by the metadata key: {"metadata.value":{"<key>":["true"]}}.',
+  "A keyed field sent as a bare list, or keyed by anything but a monitor id, is refused.",
+].join(" ");
+
+export const TRIGGER_FILTER_QUERY_DESCRIPTION = [
+  "Trace query in the syntax the traces view uses; the alternative to `filters`, and it supersedes them.",
+  'Examples: status:error · evaluator:"<evaluator name>" AND evaluatorVerdict:fail · trace.attribute.<key>:<value>.',
+].join(" ");
+
+/** Stated on the create tool: Slack needs a connection or it never posts. */
+export const SLACK_DELIVERY_NOTE =
+  'For SEND_SLACK_MESSAGE, send {"slackIntegrationId":"<connection id>"} for a webhook connection, or {"slackIntegrationId":"<connection id>","slackChannelId":"C..."} for a bot connection. Slack connections are listed and added in LangWatch under Settings, Integrations, Slack (organization-wide or for one project); they are also listed by GET /api/v1/slack-connections and `langwatch slack-connection list`, or ask the user for the id. slackIntegrationId is preferred: a legacy {"slackWebhook":"https://hooks.slack.com/..."} or {"slackDelivery":"bot","slackBotToken":"xoxb-...","slackChannelId":"C..."} is still accepted for one release and is stored as a connection. A Slack automation with no connection will never post.';
+
+export const graphAlertSchema = z
+  .object({
+    seriesName: z.string().describe("The series on the graph to watch."),
+    operator: z.enum(["gt", "lt", "gte", "lte", "eq"]),
+    threshold: z.number(),
+    timePeriod: z
+      .union([
+        z.literal(1),
+        z.literal(5),
+        z.literal(15),
+        z.literal(30),
+        z.literal(60),
+        z.literal(1440),
+      ])
+      .describe("The window, in minutes, the series is read over."),
+  })
+  .describe("The rule an alert fires by. Send it with `customGraphId` and `alertType`.");
+
+/** What a scheduled report renders and when. Structured, not a loose record: an
+ *  agent that cannot see the field names guesses them, and a guess is a 422.
+ *  The server holds a write to this same shape, so looseness only delays it. */
+export const reportSchema = z
+  .object({
+    source: z
+      .discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("dashboard"),
+          dashboardId: z.string(),
+        }),
+        z.object({
+          kind: z.literal("customGraph"),
+          customGraphId: z.string(),
+        }),
+        z.object({
+          kind: z.literal("traceQuery"),
+          filters: z.record(z.string(), z.unknown()).optional(),
+          metric: z.string().optional(),
+          topN: z.number().int().min(1).max(100).optional(),
+        }),
+      ])
+      .describe("What the report renders: a dashboard, one graph, or a table of traces."),
+    schedule: z
+      .object({
+        cron: z
+          .string()
+          .describe(
+            'A 5-field cron expression (minute hour day-of-month month day-of-week), for example "0 9 * * 1". It can send at most every 15 minutes.',
+          ),
+        timezone: z.string().describe('An IANA timezone, for example "Europe/Amsterdam" or "UTC".'),
+      })
+      .describe("When it sends."),
+    compareToPrevious: z
+      .boolean()
+      .optional()
+      .describe("Include a this-period-versus-last comparison."),
+  })
+  .describe(
+    "What a scheduled report renders and when. Send it with a channel that can carry a message: email or Slack.",
+  );
+
+export const templatesSchema = z
+  .object({
+    slackTemplateType: z.enum(["string", "block_kit"]).nullable().optional(),
+    slackTemplate: z.string().nullable().optional(),
+    emailSubjectTemplate: z.string().nullable().optional(),
+    emailBodyTemplate: z.string().nullable().optional(),
+  })
+  .describe(
+    "The Liquid templates the message is rendered from. Absent fields render the LangWatch default.",
+  );
+
+export const notificationCadenceSchema = z
+  .enum(["immediate", "5min_digest", "15min_digest", "hourly_digest"])
+  .describe(
+    "How often a notification automation may send. A new one starts on a five-minute digest.",
+  );
+
+/**
+ * What a read answers with. Permissive on purpose: an MCP client talks to whichever LangWatch it
+ * is pointed at, so an unknown field is carried through and a field a deployment does not send
+ * yet is absent rather than fatal.
+ */
+export const triggerSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    action: z.string(),
+    /** Where it delivers. The rule it fires by is stated separately, below,
+     *  the same way a write states it. */
+    actionParams: z.record(z.string(), z.unknown()).default({}),
+    graphAlert: graphAlertSchema.nullable().optional(),
+    // A read stays tolerant of a deployment that words this differently; a
+    // write is held to `reportSchema`.
+    report: z.record(z.string(), z.unknown()).nullable().optional(),
+    filters: z.record(z.string(), z.unknown()).default({}),
+    filterQuery: z.string().nullable().optional(),
+    kind: z.string().optional(),
+    customGraphId: z.string().nullable().optional(),
+    notificationCadence: z.string().nullable().optional(),
+    traceDebounceMs: z.number().nullable().optional(),
+    templates: z.record(z.string(), z.unknown()).optional(),
+    active: z.boolean(),
+    message: z.string().nullable(),
+    alertType: z.string().nullable(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    platformUrl: z.string().optional(),
+  })
+  .passthrough();
+
+const triggerFireSchema = z
+  .object({
+    id: z.string(),
+    triggerId: z.string(),
+    customGraphId: z.string().nullable(),
+    firedAt: z.string(),
+    resolvedAt: z.string().nullable(),
+  })
+  .passthrough();
+
+/** A page of fires: `{ fires, nextCursor }`, or the bare array an older
+ *  deployment answers with, which has no next page. */
+export const triggerFirePageSchema = z.union([
+  z.array(triggerFireSchema).transform((fires) => ({ fires, nextCursor: null })),
+  z
+    .object({
+      fires: z.array(triggerFireSchema).optional(),
+      data: z.array(triggerFireSchema).optional(),
+      nextCursor: z.string().nullable().optional(),
+    })
+    .transform(({ fires, data, nextCursor }) => ({
+      fires: fires ?? data ?? [],
+      nextCursor: nextCursor ?? null,
+    })),
+]);
+
+export const testFireResultSchema = z
+  .object({
+    channel: z.string(),
+    recipientCount: z.number(),
+    usedDefault: z.boolean(),
+    missingVariables: z.array(z.string()).default([]),
+    errors: z.array(z.string()).default([]),
+    httpStatus: z.number().optional(),
+  })
+  .passthrough();
+
+export const deletedTriggerSchema = z.object({
+  id: z.string(),
+  deleted: z.boolean(),
+});
+
+export type Trigger = z.infer<typeof triggerSchema>;
+export type TriggerFirePage = z.infer<typeof triggerFirePageSchema>;
+export type TestFireResult = z.infer<typeof testFireResultSchema>;
+export type TriggerAction = z.infer<typeof triggerActionSchema>;
+export type TriggerAlertType = z.infer<typeof alertTypeSchema>;
+export type TriggerActionParams = z.infer<typeof actionParamsSchema>;
+export type GraphAlertRule = z.infer<typeof graphAlertSchema>;
+export type ReportRule = z.infer<typeof reportSchema>;
+export type TriggerTemplates = z.infer<typeof templatesSchema>;
+export type NotificationCadence = z.infer<typeof notificationCadenceSchema>;

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

@@ -0,0 +1,63 @@
+/**
+ * The `add_dashboard_widget` MCP tool: create, then place, as the platform's own write path
+ * does. The dashboard is checked first so a typo leaves no unplaced widget behind, and a
+ * failed placement deletes the widget it just created.
+ */
+
+import {
+  assignDashboardWidgetToDashboard,
+  createDashboardWidget,
+  deleteDashboardWidget,
+} from "../langwatch-api-dashboard-widgets.js";
+import { getCurrentProject } from "../langwatch-api-projects.js";
+import { assertDashboardExists } from "./dashboard-exists.js";
+import {
+  type DashboardWidgetQueriesInput,
+  normalizeDashboardWidgetQueries,
+} from "./dashboard-widget-queries.js";
+
+export interface AddDashboardWidgetParams {
+  dashboardId: string;
+  name: string;
+  code: string;
+  queries: DashboardWidgetQueriesInput;
+}
+
+export async function handleAddDashboardWidget(params: AddDashboardWidgetParams): Promise<string> {
+  const queries = normalizeDashboardWidgetQueries({ queries: params.queries });
+
+  const project = await getCurrentProject();
+  await assertDashboardExists({ projectId: project.id, dashboardId: params.dashboardId });
+
+  const widget = await createDashboardWidget({
+    projectId: project.id,
+    name: params.name,
+    code: params.code,
+    queries,
+  });
+
+  try {
+    await assignDashboardWidgetToDashboard({
+      projectId: project.id,
+      widgetId: widget.id,
+      dashboardId: params.dashboardId,
+    });
+  } catch (error) {
+    // The widget now exists but is not on the dashboard we promised — never
+    // leave it dangling because the dashboard vanished between the check
+    // above and this call.
+    await deleteDashboardWidget({
+      projectId: project.id,
+      widgetId: widget.id,
+    }).catch(() => {
+      // Best-effort cleanup; the assign error below is what the caller needs.
+    });
+    throw error;
+  }
+
+  return [
+    `Widget "${params.name}" created and added to dashboard "${params.dashboardId}".`,
+    `**Widget ID**: ${widget.id}`,
+    `**Queries**: ${queries.map((q) => q.name).join(", ")}`,
+  ].join("\n");
+}

package/src/tools/archive-project.ts

@@ -1,8 +1,6 @@
-import { archiveProject as apiArchiveProject } from "../langwatch-api-projects.js";
+import { archiveProject as apiArchiveProject } from "../langwatch-api-projects.ts";
 
-export async function handleArchiveProject(params: {
-  id: string;
-}): Promise<string> {
+export async function handleArchiveProject(params: { id: string }): Promise<string> {
   const result = await apiArchiveProject(params.id);
 
   return (

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

@@ -0,0 +1,10 @@
+import { archiveRunPlan as apiArchiveRunPlan } from "../langwatch-api-run-plans.ts";
+
+/**
+ * Handles the platform_archive_run_plan MCP tool invocation.
+ */
+export async function handleArchiveRunPlan(params: { id: string }): Promise<string> {
+  const result = await apiArchiveRunPlan(params.id);
+
+  return `Run plan ${result.id} is archived. Its past runs stay readable, and the name is free for a new plan.`;
+}

package/src/tools/archive-scenario.ts

@@ -1,13 +1,11 @@
-import { archiveScenario as apiArchiveScenario } from "../langwatch-api-scenarios.js";
+import { archiveScenario as apiArchiveScenario } from "../langwatch-api-scenarios.ts";
 
 /**
  * Handles the platform_archive_scenario MCP tool invocation.
  *
  * Archives (soft-deletes) a scenario and returns confirmation.
  */
-export async function handleArchiveScenario(params: {
-  scenarioId: string;
-}): Promise<string> {
+export async function handleArchiveScenario(params: { scenarioId: string }): Promise<string> {
   const result = await apiArchiveScenario(params.scenarioId);
 
   const lines: string[] = [];

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

@@ -0,0 +1,10 @@
+import { archiveTestSuite as apiArchiveTestSuite } from "../langwatch-api-test-suites.ts";
+
+/**
+ * Handles the platform_archive_test_suite MCP tool invocation.
+ */
+export async function handleArchiveTestSuite(params: { id: string }): Promise<string> {
+  const result = await apiArchiveTestSuite(params.id);
+
+  return `Test suite ${result.id} is archived, and the scenarios filed in it are archived with it.`;
+}