@langwatch/mcp-server 2.1.0 → 3.0.0

package/src/langwatch-api.ts

@@ -1,9 +1,23 @@
-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,
+};
+
+/** The dated API version every request names (specs/api-reference/client-api-version.feature). */
+export const LANGWATCH_API_VERSION = "2026-10-26";
+
+/** Names the hosted MCP server's calls apart from a local server's. */
+export const HOSTED_MCP_HEADER = "X-LangWatch-MCP-Host";
 
 // --- Response types ---
 
@@ -46,7 +60,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 +75,7 @@ export interface TraceDetailResponse {
       tokens_estimated?: boolean;
       cost?: number;
     };
-  }>;
+  }[];
 }
 
 export interface AnalyticsBucket {
@@ -87,14 +101,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 +113,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 +144,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 +182,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 +226,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,27 +268,28 @@ 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-API-Version": LANGWATCH_API_VERSION,
     "X-Auth-Token": requireApiKey(),
   };
   if (config.projectId) {
     headers["X-Project-Id"] = config.projectId;
   }
+  if (config.hosted) {
+    headers[HOSTED_MCP_HEADER] = "hosted";
+  }
 
   if (body !== undefined) {
     headers["Content-Type"] = "application/json";
@@ -293,9 +304,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 +317,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 +333,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 +353,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 +362,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 +387,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 +408,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 +459,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 +482,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)}`);
 }

package/src/public-http-request.ts

@@ -3,7 +3,7 @@ import { request as httpRequest, type RequestOptions } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 
-import { classify } from "@langwatch/ssrf";
+import { classify } from "@langwatch/egress/ssrf";
 
 const MAX_REDIRECTS = 5;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
@@ -20,7 +20,10 @@ const SENSITIVE_REDIRECT_HEADERS = new Set([
   "x-access-token",
 ]);
 
-type DnsResolver = (hostname: string, options: { all: true; verbatim: true }) => Promise<ResolvedAddress[]>;
+type DnsResolver = (
+  hostname: string,
+  options: { all: true; verbatim: true },
+) => Promise<ResolvedAddress[]>;
 
 interface ResolvedAddress {
   address: string;
@@ -34,7 +37,9 @@ export interface PublicDestination {
 }
 
 function unsafeDestinationError(): Error {
-  return new Error("HTTP agent destinations must resolve only to globally routable public addresses");
+  return new Error(
+    "HTTP agent destinations must resolve only to globally routable public addresses",
+  );
 }
 
 function hostnameWithoutBrackets(hostname: string): string {
@@ -66,21 +71,21 @@ async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T
 
 export function headersForRedirect(
   headers: Record<string, string> | undefined,
-  crossOrigin: boolean
+  crossOrigin: boolean,
 ): Record<string, string> | undefined {
   if (!headers || !crossOrigin) {
     return headers;
   }
 
   const safeHeaders = Object.fromEntries(
-    Object.entries(headers).filter(([name]) => !SENSITIVE_REDIRECT_HEADERS.has(name.toLowerCase()))
+    Object.entries(headers).filter(([name]) => !SENSITIVE_REDIRECT_HEADERS.has(name.toLowerCase())),
   );
   return Object.keys(safeHeaders).length > 0 ? safeHeaders : undefined;
 }
 
 export async function resolvePublicDestination(
   input: string,
-  resolver: DnsResolver = dnsLookup
+  resolver: DnsResolver = dnsLookup,
 ): Promise<PublicDestination> {
   let url: URL;
   try {
@@ -89,7 +94,11 @@ export async function resolvePublicDestination(
     throw new Error("HTTP agent URL is invalid");
   }
 
-  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username !== "" || url.password !== "") {
+  if (
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.username !== "" ||
+    url.password !== ""
+  ) {
     throw unsafeDestinationError();
   }
 
@@ -104,7 +113,7 @@ export async function resolvePublicDestination(
   try {
     addresses = await withTimeout(
       resolver(hostname, { all: true, verbatim: true }),
-      REQUEST_TIMEOUT_MS
+      REQUEST_TIMEOUT_MS,
     );
   } catch {
     throw new Error("HTTP agent destination could not be resolved");
@@ -135,7 +144,7 @@ interface PublicJsonRequestOptions {
 
 function requestBody(
   destination: PublicDestination,
-  options: PublicJsonRequestOptions
+  options: PublicJsonRequestOptions,
 ): Promise<{ body: string; location?: string; statusCode: number }> {
   return new Promise((resolve, reject) => {
     const hostname = hostnameWithoutBrackets(destination.url.hostname);
@@ -198,7 +207,7 @@ function requestBody(
 export async function requestPublicJson(
   input: string,
   options: PublicJsonRequestOptions = {},
-  redirectCount = 0
+  redirectCount = 0,
 ): Promise<Record<string, unknown>> {
   const destination = await resolvePublicDestination(input);
   const response = await requestBody(destination, options);
@@ -210,7 +219,7 @@ export async function requestPublicJson(
     const redirectUrl = new URL(response.location, destination.url);
     const redirectHeaders = headersForRedirect(
       options.headers,
-      redirectUrl.origin !== destination.url.origin
+      redirectUrl.origin !== destination.url.origin,
     );
     const preserveBody = response.statusCode === 307 || response.statusCode === 308;
     return requestPublicJson(
@@ -223,7 +232,7 @@ export async function requestPublicJson(
             headers: redirectHeaders,
             method: "GET",
           },
-      redirectCount + 1
+      redirectCount + 1,
     );
   }
 

package/src/schemas/analytics-metrics.ts

@@ -124,17 +124,7 @@ export const analyticsMetrics: MetricInfo[] = [
     category: "events",
     name: "event_score",
     label: "Event Score",
-    allowedAggregations: [
-      "terms",
-      "avg",
-      "sum",
-      "min",
-      "max",
-      "median",
-      "p99",
-      "p95",
-      "p90",
-    ],
+    allowedAggregations: ["terms", "avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
     description: "Numeric score from events (requires event_type key and metrics key)",
   },
   {
@@ -142,8 +132,7 @@ export const analyticsMetrics: MetricInfo[] = [
     name: "event_details",
     label: "Event Details",
     allowedAggregations: ["cardinality"],
-    description:
-      "Event detail key/value distribution (requires event_type key and details key)",
+    description: "Event detail key/value distribution (requires event_type key and details key)",
   },
   // evaluations
   {
@@ -158,8 +147,7 @@ export const analyticsMetrics: MetricInfo[] = [
     name: "evaluation_pass_rate",
     label: "Evaluation Pass Rate",
     allowedAggregations: ["avg", "sum", "min", "max", "median", "p99", "p95", "p90"],
-    description:
-      "Percentage of traces passing evaluation (requires evaluator_id key)",
+    description: "Percentage of traces passing evaluation (requires evaluator_id key)",
   },
   {
     category: "evaluations",

package/src/schemas/create-dataset.ts

@@ -16,6 +16,7 @@ export const DATASET_COLUMN_TYPES = [
   "annotations",
   "evaluations",
   "image",
+  "file",
 ] as const;
 
 /**
@@ -34,10 +35,8 @@ export const datasetColumnDefinitionSchema = z.object({
 });
 
 /**
- * Zod schema for the platform_create_dataset MCP tool parameters.
- *
- * Extracted so it can be shared between the MCP tool registration
- * (create-mcp-server.ts) and unit tests.
+ * Zod schema for the platform_create_dataset MCP tool parameters,
+ * extracted so it's shared between create-mcp-server.ts and unit tests.
  */
 export const createDatasetSchema = z.object({
   name: z.string().min(1).describe("Dataset name"),