@langwatch/mcp-server 2.0.0 → 2.2.0

package/src/langwatch-api-datasets.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { LangWatchApiError, makeRequest } from "./langwatch-api.ts";
 
 // --- Dataset types ---
 
@@ -40,6 +40,10 @@ export interface DatasetDetailResponse {
   createdAt: string;
   updatedAt: string;
   data: DatasetRecord[];
+  /** Records in the dataset, when `data` is a preview of them. */
+  totalRecords?: number;
+  /** Records of the dataset left out of `data`. */
+  omittedRecords?: number;
 }
 
 export interface DatasetMutationResponse {
@@ -72,8 +76,16 @@ export interface DatasetRecordListResponse {
     limit: number;
     totalPages: number;
   };
+  /** The dataset the page belongs to. Absent on servers that do not send it. */
+  dataset?: DatasetMutationResponse;
 }
 
+/** The most records a dataset preview holds. */
+export const DATASET_PREVIEW_MAX_RECORDS = 100;
+
+/** The most bytes of records a dataset preview holds. */
+export const DATASET_PREVIEW_MAX_BYTES = 1024 * 1024;
+
 // --- Dataset API functions ---
 
 /** Lists all datasets in the project (paginated). */
@@ -85,18 +97,82 @@ export async function listDatasets(params?: {
   if (params?.page != null) query.set("page", String(params.page));
   if (params?.limit != null) query.set("limit", String(params.limit));
   const qs = query.toString();
-  const path = qs ? `/api/dataset?${qs}` : "/api/dataset";
+  const path = qs ? `/api/v1/dataset?${qs}` : "/api/v1/dataset";
   return makeRequest("GET", path) as Promise<DatasetListResponse>;
 }
 
-/** Retrieves a single dataset by slug or ID, including records. */
-export async function getDataset(
-  slugOrId: string,
-): Promise<DatasetDetailResponse> {
-  return makeRequest(
-    "GET",
-    `/api/dataset/${encodeURIComponent(slugOrId)}`,
-  ) as Promise<DatasetDetailResponse>;
+/**
+ * Retrieves a dataset by slug or ID with a preview of its records: the first page, cut at
+ * `DATASET_PREVIEW_MAX_RECORDS` records and `DATASET_PREVIEW_MAX_BYTES` bytes. A dataset of
+ * any size can be read this way. `omittedRecords` counts what the preview leaves out.
+ */
+export async function getDataset(slugOrId: string): Promise<DatasetDetailResponse> {
+  const page = await readPreviewPage(slugOrId);
+  // A server without the records endpoint, or one that sends no dataset with a page, is
+  // asked for the whole dataset in one response.
+  if (!page?.dataset) {
+    return makeRequest(
+      "GET",
+      `/api/v1/dataset/${encodeURIComponent(slugOrId)}`,
+    ) as Promise<DatasetDetailResponse>;
+  }
+
+  const data: DatasetRecord[] = [];
+  let bytes = 0;
+  for (const record of page.data) {
+    bytes += JSON.stringify(record).length;
+    if (bytes > DATASET_PREVIEW_MAX_BYTES) break;
+    data.push(record);
+  }
+
+  const { id, name, slug, columnTypes, createdAt, updatedAt } = page.dataset;
+  const totalRecords = page.pagination.total;
+  return {
+    id,
+    name,
+    slug,
+    columnTypes,
+    createdAt,
+    updatedAt,
+    data,
+    totalRecords,
+    omittedRecords: Math.max(0, totalRecords - data.length),
+  };
+}
+
+/**
+ * The first page of a dataset's records, or `null` when the records endpoint answers 404. A
+ * page refused as too large is asked for again with the size the refusal suggests, or half.
+ */
+async function readPreviewPage(slugOrId: string): Promise<DatasetRecordListResponse | null> {
+  let limit = DATASET_PREVIEW_MAX_RECORDS;
+  for (;;) {
+    try {
+      return await listDatasetRecords({ slugOrId, page: 1, limit });
+    } catch (error) {
+      if (!(error instanceof LangWatchApiError)) throw error;
+      if (error.status === 404) return null;
+      if (error.status !== 413 || limit <= 1) throw error;
+      limit = smallerLimit(limit, error.responseBody);
+    }
+  }
+}
+
+/** The page size a `dataset_page_too_large` refusal suggests, or half the refused one. */
+function smallerLimit(limit: number, responseBody: string): number {
+  const half = Math.max(1, Math.floor(limit / 2));
+  try {
+    const suggested: unknown = (JSON.parse(responseBody) as { meta?: { suggestedLimit?: unknown } })
+      .meta?.suggestedLimit;
+    const usable =
+      typeof suggested === "number" &&
+      Number.isInteger(suggested) &&
+      suggested >= 1 &&
+      suggested < limit;
+    return usable ? suggested : half;
+  } catch {
+    return half;
+  }
 }
 
 /** Creates a new dataset. */
@@ -104,11 +180,7 @@ export async function createDataset(data: {
   name: string;
   columnTypes?: DatasetColumnType[];
 }): Promise<DatasetMutationResponse> {
-  return makeRequest(
-    "POST",
-    "/api/dataset",
-    data,
-  ) as Promise<DatasetMutationResponse>;
+  return makeRequest("POST", "/api/v1/dataset", data) as Promise<DatasetMutationResponse>;
 }
 
 /** Updates an existing dataset by slug or ID. */
@@ -120,18 +192,16 @@ export async function updateDataset(params: {
   const { slugOrId, ...data } = params;
   return makeRequest(
     "PATCH",
-    `/api/dataset/${encodeURIComponent(slugOrId)}`,
+    `/api/v1/dataset/${encodeURIComponent(slugOrId)}`,
     data,
   ) as Promise<DatasetMutationResponse>;
 }
 
 /** Archives (soft-deletes) a dataset by slug or ID. */
-export async function deleteDataset(
-  slugOrId: string,
-): Promise<DatasetArchiveResponse> {
+export async function deleteDataset(slugOrId: string): Promise<DatasetArchiveResponse> {
   return makeRequest(
     "DELETE",
-    `/api/dataset/${encodeURIComponent(slugOrId)}`,
+    `/api/v1/dataset/${encodeURIComponent(slugOrId)}`,
   ) as Promise<DatasetArchiveResponse>;
 }
 
@@ -141,11 +211,9 @@ export async function createDatasetRecords(params: {
   entries: Record<string, unknown>[];
 }): Promise<BatchCreateRecordsResponse> {
   const { slugOrId, entries } = params;
-  return makeRequest(
-    "POST",
-    `/api/dataset/${encodeURIComponent(slugOrId)}/records`,
-    { entries },
-  ) as Promise<BatchCreateRecordsResponse>;
+  return makeRequest("POST", `/api/v1/dataset/${encodeURIComponent(slugOrId)}/records`, {
+    entries,
+  }) as Promise<BatchCreateRecordsResponse>;
 }
 
 /** Updates or creates a single record in a dataset. */
@@ -157,7 +225,7 @@ export async function updateDatasetRecord(params: {
   const { slugOrId, recordId, entry } = params;
   return makeRequest(
     "PATCH",
-    `/api/dataset/${encodeURIComponent(slugOrId)}/records/${encodeURIComponent(recordId)}`,
+    `/api/v1/dataset/${encodeURIComponent(slugOrId)}/records/${encodeURIComponent(recordId)}`,
     { entry },
   ) as Promise<DatasetRecord>;
 }
@@ -168,11 +236,9 @@ export async function deleteDatasetRecords(params: {
   recordIds: string[];
 }): Promise<DeleteRecordsResponse> {
   const { slugOrId, recordIds } = params;
-  return makeRequest(
-    "DELETE",
-    `/api/dataset/${encodeURIComponent(slugOrId)}/records`,
-    { recordIds },
-  ) as Promise<DeleteRecordsResponse>;
+  return makeRequest("DELETE", `/api/v1/dataset/${encodeURIComponent(slugOrId)}/records`, {
+    recordIds,
+  }) as Promise<DeleteRecordsResponse>;
 }
 
 /** Lists records in a dataset (paginated). */
@@ -186,6 +252,6 @@ export async function listDatasetRecords(params: {
   if (params.page != null) query.set("page", String(params.page));
   if (params.limit != null) query.set("limit", String(params.limit));
   const qs = query.toString();
-  const path = `/api/dataset/${encodeURIComponent(slugOrId)}/records${qs ? `?${qs}` : ""}`;
+  const path = `/api/v1/dataset/${encodeURIComponent(slugOrId)}/records${qs ? `?${qs}` : ""}`;
   return makeRequest("GET", path) as Promise<DatasetRecordListResponse>;
 }

package/src/langwatch-api-evaluators.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 // --- Evaluator types ---
 
@@ -13,8 +13,8 @@ export interface EvaluatorSummary {
   copiedFromEvaluatorId: string | null;
   createdAt: string;
   updatedAt: string;
-  fields: Array<{ identifier: string; type: string; optional?: boolean }>;
-  outputFields: Array<{ identifier: string; type: string; optional?: boolean }>;
+  fields: { identifier: string; type: string; optional?: boolean }[];
+  outputFields: { identifier: string; type: string; optional?: boolean }[];
   workflowName?: string;
   workflowIcon?: string;
 }
@@ -25,25 +25,22 @@ export interface EvaluatorSummary {
  * Extracts the evaluatorType from an evaluator's config.
  * Centralises the cast so callers don't repeat it.
  */
-export function getEvaluatorType(
-  evaluator: Pick<EvaluatorSummary, "config">,
-): string | undefined {
-  return (evaluator.config as Record<string, unknown> | null)
-    ?.evaluatorType as string | undefined;
+export function getEvaluatorType(evaluator: Pick<EvaluatorSummary, "config">): string | undefined {
+  return (evaluator.config as Record<string, unknown> | null)?.evaluatorType as string | undefined;
 }
 
 // --- Evaluator API functions ---
 
 /** Lists all evaluators in the project. */
 export async function listEvaluators(): Promise<EvaluatorSummary[]> {
-  return makeRequest("GET", "/api/evaluators") as Promise<EvaluatorSummary[]>;
+  return makeRequest("GET", "/api/v1/evaluators") as Promise<EvaluatorSummary[]>;
 }
 
 /** Retrieves a single evaluator by ID or slug. */
 export async function getEvaluator(idOrSlug: string): Promise<EvaluatorSummary> {
   return makeRequest(
     "GET",
-    `/api/evaluators/${encodeURIComponent(idOrSlug)}`,
+    `/api/v1/evaluators/${encodeURIComponent(idOrSlug)}`,
   ) as Promise<EvaluatorSummary>;
 }
 
@@ -52,7 +49,7 @@ export async function createEvaluator(data: {
   name: string;
   config: Record<string, unknown>;
 }): Promise<EvaluatorSummary> {
-  return makeRequest("POST", "/api/evaluators", data) as Promise<EvaluatorSummary>;
+  return makeRequest("POST", "/api/v1/evaluators", data) as Promise<EvaluatorSummary>;
 }
 
 /** Updates an existing evaluator. */
@@ -64,17 +61,14 @@ export async function updateEvaluator(params: {
   const { id, ...data } = params;
   return makeRequest(
     "PUT",
-    `/api/evaluators/${encodeURIComponent(id)}`,
+    `/api/v1/evaluators/${encodeURIComponent(id)}`,
     data,
   ) as Promise<EvaluatorSummary>;
 }
 
 /** Archives (soft-deletes) an evaluator. */
-export async function deleteEvaluator(
-  idOrSlug: string,
-): Promise<{ id: string; archived: boolean }> {
-  return makeRequest(
-    "DELETE",
-    `/api/evaluators/${encodeURIComponent(idOrSlug)}`,
-  ) as Promise<{ id: string; archived: boolean }>;
+export async function deleteEvaluator(idOrSlug: string): Promise<{ success: boolean }> {
+  return makeRequest("DELETE", `/api/v1/evaluators/${encodeURIComponent(idOrSlug)}`) as Promise<{
+    success: boolean;
+  }>;
 }

package/src/langwatch-api-model-providers.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 // --- Model Provider types ---
 
@@ -13,14 +13,14 @@ export interface ModelProviderEntry {
   customEmbeddingsModels?: unknown[] | null;
   disabledByDefault?: boolean;
   deploymentMapping?: unknown;
-  extraHeaders?: Array<{ key: string; value: string }> | null;
+  extraHeaders?: { key: string; value: string }[] | null;
 }
 
 // --- Model Provider API functions ---
 
 /** Lists all model providers for the project, with masked API keys. */
 export async function listModelProviders(): Promise<Record<string, ModelProviderEntry>> {
-  return makeRequest("GET", "/api/model-providers") as Promise<
+  return makeRequest("GET", "/api/v1/model-providers") as Promise<
     Record<string, ModelProviderEntry>
   >;
 }
@@ -35,7 +35,7 @@ export async function setModelProvider(params: {
   const { provider, ...data } = params;
   return makeRequest(
     "PUT",
-    `/api/model-providers/${encodeURIComponent(provider)}`,
+    `/api/v1/model-providers/${encodeURIComponent(provider)}`,
     data,
   ) as Promise<Record<string, ModelProviderEntry>>;
 }

package/src/langwatch-api-monitors.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface MonitorSummary {
   id: string;
@@ -19,13 +19,13 @@ export interface MonitorSummary {
 }
 
 export async function listMonitors(): Promise<MonitorSummary[]> {
-  return makeRequest("GET", "/api/monitors") as Promise<MonitorSummary[]>;
+  return makeRequest("GET", "/api/v1/monitors") as Promise<MonitorSummary[]>;
 }
 
 export async function getMonitor(id: string): Promise<MonitorSummary> {
   return makeRequest(
     "GET",
-    `/api/monitors/${encodeURIComponent(id)}`
+    `/api/v1/monitors/${encodeURIComponent(id)}`,
   ) as Promise<MonitorSummary>;
 }
 
@@ -38,7 +38,7 @@ export async function createMonitor(data: {
   level?: string;
   parameters?: Record<string, unknown>;
 }): Promise<MonitorSummary> {
-  return makeRequest("POST", "/api/monitors", {
+  return makeRequest("POST", "/api/v1/monitors", {
     ...data,
     preconditions: [],
     parameters: data.parameters ?? {},
@@ -56,8 +56,8 @@ export async function updateMonitor(params: {
   const { id, ...data } = params;
   return makeRequest(
     "PATCH",
-    `/api/monitors/${encodeURIComponent(id)}`,
-    data
+    `/api/v1/monitors/${encodeURIComponent(id)}`,
+    data,
   ) as Promise<MonitorSummary>;
 }
 
@@ -65,18 +65,14 @@ export async function toggleMonitor(params: {
   id: string;
   enabled: boolean;
 }): Promise<{ id: string; enabled: boolean }> {
-  return makeRequest(
-    "POST",
-    `/api/monitors/${encodeURIComponent(params.id)}/toggle`,
-    { enabled: params.enabled }
-  ) as Promise<{ id: string; enabled: boolean }>;
+  return makeRequest("POST", `/api/v1/monitors/${encodeURIComponent(params.id)}/toggle`, {
+    enabled: params.enabled,
+  }) as Promise<{ id: string; enabled: boolean }>;
 }
 
-export async function deleteMonitor(
-  id: string
-): Promise<{ id: string; deleted: boolean }> {
-  return makeRequest(
-    "DELETE",
-    `/api/monitors/${encodeURIComponent(id)}`
-  ) as Promise<{ id: string; deleted: boolean }>;
+export async function deleteMonitor(id: string): Promise<{ id: string; deleted: boolean }> {
+  return makeRequest("DELETE", `/api/v1/monitors/${encodeURIComponent(id)}`) as Promise<{
+    id: string;
+    deleted: boolean;
+  }>;
 }

package/src/langwatch-api-projects.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface ProjectSummary {
   id: string;
@@ -35,16 +35,33 @@ export async function listProjects(params?: {
   if (params?.page) query.set("page", String(params.page));
   if (params?.limit) query.set("limit", String(params.limit));
   const qs = query.toString() ? `?${query}` : "";
-  return makeRequest("GET", `/api/projects${qs}`) as Promise<ProjectListResponse>;
+  return makeRequest("GET", `/api/v1/projects${qs}`) as Promise<ProjectListResponse>;
 }
 
 export async function getProject(id: string): Promise<ProjectSummary> {
   return makeRequest(
     "GET",
-    `/api/projects/${encodeURIComponent(id)}`,
+    `/api/v1/projects/${encodeURIComponent(id)}`,
   ) as Promise<ProjectSummary>;
 }
 
+/** Identity of the project the calling API key belongs to. */
+export interface CurrentProjectIdentity {
+  id: string;
+  name: string;
+  slug: string;
+  isPersonal: boolean;
+}
+
+/**
+ * Resolves the project behind the configured API key. Needed for the
+ * `/api/v1/projects/:projectId/...` route family, whose path must name the
+ * caller's own project — there is no "current project" shorthand there.
+ */
+export async function getCurrentProject(): Promise<CurrentProjectIdentity> {
+  return makeRequest("GET", "/api/v1/me/project") as Promise<CurrentProjectIdentity>;
+}
+
 export async function createProject(data: {
   name: string;
   language: string;
@@ -52,7 +69,7 @@ export async function createProject(data: {
   teamId?: string;
   newTeamName?: string;
 }): Promise<ProjectCreateResponse> {
-  return makeRequest("POST", "/api/projects", data) as Promise<ProjectCreateResponse>;
+  return makeRequest("POST", "/api/v1/projects", data) as Promise<ProjectCreateResponse>;
 }
 
 export async function updateProject(params: {
@@ -65,7 +82,7 @@ export async function updateProject(params: {
   const { id, ...data } = params;
   return makeRequest(
     "PATCH",
-    `/api/projects/${encodeURIComponent(id)}`,
+    `/api/v1/projects/${encodeURIComponent(id)}`,
     data,
   ) as Promise<ProjectSummary>;
 }
@@ -75,8 +92,9 @@ export async function archiveProject(id: string): Promise<{
   name: string;
   archivedAt: string;
 }> {
-  return makeRequest(
-    "DELETE",
-    `/api/projects/${encodeURIComponent(id)}`,
-  ) as Promise<{ id: string; name: string; archivedAt: string }>;
+  return makeRequest("DELETE", `/api/v1/projects/${encodeURIComponent(id)}`) as Promise<{
+    id: string;
+    name: string;
+    archivedAt: string;
+  }>;
 }

package/src/langwatch-api-query.ts

@@ -0,0 +1,114 @@
+/**
+ * The query family: the analytics SQL door and the reference describing both query languages.
+ * Fetched, replacing a hand-copied field list that drifted, so this server cannot describe a
+ * missing field.
+ * @see specs/mcp-server/schema-discovery.feature
+ */
+
+import { makeRequest } from "./langwatch-api.ts";
+
+/** One column of a query result. */
+export interface QueryResultColumn {
+  name: string;
+  type: string;
+}
+
+/** What `POST /api/v1/query` answers with. */
+export interface QueryRunResponse {
+  columns: QueryResultColumn[];
+  rows: Record<string, unknown>[];
+  statistics: {
+    elapsedMs: number;
+    rowsRead: number;
+    bytesRead: number;
+    rowsReturned: number;
+  };
+  truncated: boolean;
+  diagnostics: { code: string; message: string }[];
+}
+
+/** One published dataset. */
+export interface QueryReferenceView {
+  name: string;
+  description: string;
+  grain: string;
+  joinKeys: string[];
+  timeColumn: string;
+  freshness: string;
+  columns: {
+    name: string;
+    type: string;
+    description: string;
+    unit: string | null;
+    gates: string[];
+    available: boolean;
+  }[];
+  exampleSql: string;
+}
+
+/** One worked query, in either language. */
+export interface QueryReferenceExample {
+  id: string;
+  title: string;
+  intent: string;
+  language: "lwql" | "trace-filter";
+  tags: string[];
+  text: string;
+  parameters: { name: string; type: string; description: string }[];
+  requires: { gates: string[]; functions: string[] };
+  available: boolean;
+  notes?: string;
+}
+
+/** What `GET /api/v1/query/reference` answers with. */
+export interface QueryReferenceResponse {
+  version: string;
+  lwql: {
+    enabled: boolean;
+    schema: { database: string; views: QueryReferenceView[] };
+    limits: {
+      maxStatementLength: number;
+      maxRowsReturned: number;
+      maxResultBytes: number;
+      maxExecutionTimeSeconds: number;
+      pagination: string;
+    };
+    endpoints: { method: string; path: string; description: string }[];
+  };
+  traceFilter: {
+    syntax: string;
+    fields: {
+      name: string;
+      label: string;
+      valueType: string;
+      group: string | null;
+      facetable: boolean;
+      knownValues: string[];
+    }[];
+    dynamicPrefixes: {
+      prefix: string;
+      label: string;
+      description: string;
+      aliases: string[];
+    }[];
+    endpoints: { method: string; path: string; description: string }[];
+  };
+  examples: QueryReferenceExample[];
+  decisionTable: { when: string; use: string; why: string }[];
+}
+
+/** Runs one read-only LangWatchQL statement, as written. */
+export async function runQuery(params: {
+  sql: string;
+  parameters?: Record<string, string | number | boolean | null>;
+}): Promise<QueryRunResponse> {
+  return makeRequest("POST", "/api/v1/query", {
+    sql: params.sql,
+    ...(params.parameters ? { parameters: params.parameters } : {}),
+  }) as Promise<QueryRunResponse>;
+}
+
+/** Reads the query reference: both languages, their fields and worked examples. */
+export async function getQueryReference(): Promise<QueryReferenceResponse> {
+  return makeRequest("GET", "/api/v1/query/reference") as Promise<QueryReferenceResponse>;
+}