@langwatch/mcp-server 2.1.0 → 2.2.0

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>;
+}

package/src/langwatch-api-run-plans.ts

@@ -1,22 +1,16 @@
 import type { z } from "zod";
-import { makeRequest } from "./langwatch-api.js";
+
+import { makeRequest } from "./langwatch-api.ts";
 import type {
   runParametersSchema,
   runPlanScopeSchema,
   runPlanTargetSchema,
   RunPlanTargetWire,
-} from "./schemas/run-plan.js";
-import type { EvaluatorAttachmentWire } from "./schemas/suite-fields.js";
+} from "./schemas/run-plan.ts";
+import type { EvaluatorAttachmentWire } from "./schemas/suite-fields.ts";
 
-/**
- * Client for `/api/v1/run-plans`.
- *
- * A run plan is what you run, and its NAME identifies it: running against a
- * name that exists replaces that plan's configuration, running against a new
- * name creates one. Configuration is the scope, the targets, the repeat count
- * and the two models. Parameters, the note and the idempotency key belong to
- * one run, not to the plan.
- */
+// Client for /api/v1/run-plans. A run plan is identified by name; re-using the
+// name replaces its config while parameters/notes belong to one run only.
 
 /**
  * The shapes the run plan tools accept, taken from the zod that validates
@@ -77,12 +71,12 @@ export interface RunPlanRunResult {
     scenarios: string[];
     targets: string[];
   };
-  items: Array<{
+  items: {
     scenarioRunId: string;
     scenarioId: string;
     target: RunPlanTargetWire;
     name: string | null;
-  }>;
+  }[];
   runPlanId: string;
   planName: string;
   /** True when this run created the plan, false when it joined an existing one. */
@@ -96,19 +90,14 @@ export interface RunPlanArchiveResponse {
 }
 
 /** Lists the run plans of the project. */
-export async function listRunPlans(params?: {
-  includeArchived?: boolean;
-}): Promise<RunPlan[]> {
+export async function listRunPlans(params?: { includeArchived?: boolean }): Promise<RunPlan[]> {
   const query = params?.includeArchived ? "?includeArchived=true" : "";
   return makeRequest("GET", `/api/v1/run-plans${query}`) as Promise<RunPlan[]>;
 }
 
 /** Retrieves a single run plan by id. */
 export async function getRunPlan(id: string): Promise<RunPlan> {
-  return makeRequest(
-    "GET",
-    `/api/v1/run-plans/${encodeURIComponent(id)}`,
-  ) as Promise<RunPlan>;
+  return makeRequest("GET", `/api/v1/run-plans/${encodeURIComponent(id)}`) as Promise<RunPlan>;
 }
 
 /**
@@ -123,11 +112,7 @@ export async function runRunPlan(data: {
   parameters?: RunParameters;
   note?: string;
 }): Promise<RunPlanRunResult> {
-  return makeRequest(
-    "POST",
-    "/api/v1/run-plans/run",
-    data,
-  ) as Promise<RunPlanRunResult>;
+  return makeRequest("POST", "/api/v1/run-plans/run", data) as Promise<RunPlanRunResult>;
 }
 
 /** Runs a plan again with the configuration it already holds. */
@@ -147,9 +132,7 @@ export async function rerunRunPlan(
 }
 
 /** Archives a run plan. */
-export async function archiveRunPlan(
-  id: string,
-): Promise<RunPlanArchiveResponse> {
+export async function archiveRunPlan(id: string): Promise<RunPlanArchiveResponse> {
   return makeRequest(
     "DELETE",
     `/api/v1/run-plans/${encodeURIComponent(id)}`,

package/src/langwatch-api-scenarios.ts

@@ -1,5 +1,5 @@
-import { makeRequest } from "./langwatch-api.js";
-import type { ScenarioFieldValues } from "./schemas/suite-fields.js";
+import { makeRequest } from "./langwatch-api.ts";
+import type { ScenarioFieldValues } from "./schemas/suite-fields.ts";
 
 // --- Scenario types ---
 
@@ -24,14 +24,14 @@ export interface ScenarioArchiveResponse {
 
 /** Lists all scenarios in the project. */
 export async function listScenarios(): Promise<ScenarioSummary[]> {
-  return makeRequest("GET", "/api/scenarios") as Promise<ScenarioSummary[]>;
+  return makeRequest("GET", "/api/v1/scenarios") as Promise<ScenarioSummary[]>;
 }
 
 /** Retrieves a single scenario by ID. */
 export async function getScenario(id: string): Promise<ScenarioSummary> {
   return makeRequest(
     "GET",
-    `/api/scenarios/${encodeURIComponent(id)}`
+    `/api/v1/scenarios/${encodeURIComponent(id)}`,
   ) as Promise<ScenarioSummary>;
 }
 
@@ -44,7 +44,7 @@ export async function createScenario(data: {
   testSuiteId?: string | null;
   fields?: ScenarioFieldValues;
 }): Promise<ScenarioSummary> {
-  return makeRequest("POST", "/api/scenarios", data) as Promise<ScenarioSummary>;
+  return makeRequest("POST", "/api/v1/scenarios", data) as Promise<ScenarioSummary>;
 }
 
 /** Updates an existing scenario. */
@@ -60,17 +60,15 @@ export async function updateScenario(params: {
   const { id, ...data } = params;
   return makeRequest(
     "PUT",
-    `/api/scenarios/${encodeURIComponent(id)}`,
-    data
+    `/api/v1/scenarios/${encodeURIComponent(id)}`,
+    data,
   ) as Promise<ScenarioSummary>;
 }
 
 /** Archives (soft-deletes) a scenario. */
-export async function archiveScenario(
-  id: string
-): Promise<ScenarioArchiveResponse> {
+export async function archiveScenario(id: string): Promise<ScenarioArchiveResponse> {
   return makeRequest(
     "DELETE",
-    `/api/scenarios/${encodeURIComponent(id)}`
+    `/api/v1/scenarios/${encodeURIComponent(id)}`,
   ) as Promise<ScenarioArchiveResponse>;
 }

package/src/langwatch-api-secrets.ts

@@ -1,4 +1,5 @@
-import { makeRequest } from "./langwatch-api.js";
+import { getConfig } from "./config.ts";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface SecretSummary {
   id: string;
@@ -8,41 +9,47 @@ export interface SecretSummary {
   updatedAt: string;
 }
 
+function projectId(): string {
+  const projectId = getConfig().projectId;
+  if (!projectId) {
+    throw new Error("LANGWATCH_PROJECT_ID is required for secret operations");
+  }
+  return projectId;
+}
+
 export async function listSecrets(): Promise<SecretSummary[]> {
-  return makeRequest("GET", "/api/secrets") as Promise<SecretSummary[]>;
+  const targetProjectId = projectId();
+  return makeRequest(
+    "GET",
+    `/api/v1/secrets?projectId=${encodeURIComponent(targetProjectId)}`,
+  ) as Promise<SecretSummary[]>;
 }
 
 export async function getSecret(id: string): Promise<SecretSummary> {
+  const targetProjectId = projectId();
   return makeRequest(
     "GET",
-    `/api/secrets/${encodeURIComponent(id)}`
+    `/api/v1/secrets/${encodeURIComponent(id)}?projectId=${encodeURIComponent(targetProjectId)}`,
   ) as Promise<SecretSummary>;
 }
 
-export async function createSecret(data: {
-  name: string;
-  value: string;
-}): Promise<SecretSummary> {
-  return makeRequest("POST", "/api/secrets", data) as Promise<SecretSummary>;
+export async function createSecret(data: { name: string; value: string }): Promise<SecretSummary> {
+  return makeRequest("POST", "/api/v1/secrets", {
+    projectId: projectId(),
+    ...data,
+  }) as Promise<SecretSummary>;
 }
 
-export async function updateSecret(params: {
-  id: string;
-  value: string;
-}): Promise<SecretSummary> {
+export async function updateSecret(params: { id: string; value: string }): Promise<SecretSummary> {
   const { id, value } = params;
-  return makeRequest(
-    "PUT",
-    `/api/secrets/${encodeURIComponent(id)}`,
-    { value }
-  ) as Promise<SecretSummary>;
+  return makeRequest("PUT", `/api/v1/secrets/${encodeURIComponent(id)}`, {
+    projectId: projectId(),
+    value,
+  }) as Promise<SecretSummary>;
 }
 
-export async function deleteSecret(
-  id: string
-): Promise<{ id: string; deleted: boolean }> {
-  return makeRequest(
-    "DELETE",
-    `/api/secrets/${encodeURIComponent(id)}`
-  ) as Promise<{ id: string; deleted: boolean }>;
+export async function deleteSecret(id: string): Promise<{ id: string; deleted: boolean }> {
+  return makeRequest("DELETE", `/api/v1/secrets/${encodeURIComponent(id)}`, {
+    projectId: projectId(),
+  }) as Promise<{ id: string; deleted: boolean }>;
 }

package/src/langwatch-api-simulation-runs.ts

@@ -1,5 +1,5 @@
-import { makeRequest } from "./langwatch-api.js";
-import type { SimulationRunEvaluation } from "./tools/format-suite-details.js";
+import { makeRequest } from "./langwatch-api.ts";
+import type { SimulationRunEvaluation } from "./tools/format-suite-details.ts";
 
 export interface SimulationRunSummary {
   scenarioRunId: string;
@@ -18,7 +18,7 @@ export interface SimulationRunSummary {
     /** One result per evaluator that ran after the conversation. */
     evaluations?: SimulationRunEvaluation[];
   } | null;
-  messages?: Array<{ role: string; content: string }>;
+  messages?: { role: string; content: string }[];
   /** Why the run was started, as given when it was queued. Null without one. */
   note?: string | null;
   timestamp: number;
@@ -42,15 +42,13 @@ export async function listSimulationRuns(params?: {
   if (params?.batchRunId) query.set("batchRunId", params.batchRunId);
   if (params?.limit) query.set("limit", String(params.limit));
   const qs = query.toString() ? `?${query}` : "";
-  return makeRequest("GET", `/api/simulation-runs${qs}`) as Promise<SimulationRunListResponse>;
+  return makeRequest("GET", `/api/v1/simulation-runs${qs}`) as Promise<SimulationRunListResponse>;
 }
 
 /** Gets a single simulation run by its ID. */
-export async function getSimulationRun(
-  scenarioRunId: string,
-): Promise<SimulationRunSummary> {
+export async function getSimulationRun(scenarioRunId: string): Promise<SimulationRunSummary> {
   return makeRequest(
     "GET",
-    `/api/simulation-runs/${encodeURIComponent(scenarioRunId)}`,
+    `/api/v1/simulation-runs/${encodeURIComponent(scenarioRunId)}`,
   ) as Promise<SimulationRunSummary>;
 }

package/src/langwatch-api-test-suites.ts

@@ -1,20 +1,12 @@
-import { makeRequest } from "./langwatch-api.js";
-import type {
-  RunParameters,
-  RunPlanRunResult,
-} from "./langwatch-api-run-plans.js";
-import type { RunPlanTargetWire } from "./schemas/run-plan.js";
-import type {
-  EvaluatorAttachmentWire,
-  SuiteField,
-} from "./schemas/suite-fields.js";
+import type { RunParameters, RunPlanRunResult } from "./langwatch-api-run-plans.ts";
+import { makeRequest } from "./langwatch-api.ts";
+import type { RunPlanTargetWire } from "./schemas/run-plan.ts";
+import type { EvaluatorAttachmentWire, SuiteField } from "./schemas/suite-fields.ts";
 
 /**
- * Client for `/api/v1/test-suites`.
- *
- * A test suite groups scenarios: a name and the scenarios filed in it.
- * Running one is sugar over a run plan, so the run returns the same result a
- * run plan does.
+ * Client for `/api/v1/test-suites`. A test suite groups scenarios by
+ * name; running one is sugar over a run plan, returning the same
+ * result shape.
  */
 
 export interface TestSuite {
@@ -34,7 +26,7 @@ export interface TestSuite {
 }
 
 export interface TestSuiteDetail extends TestSuite {
-  scenarios: Array<{ id: string; name: string }>;
+  scenarios: { id: string; name: string }[];
 }
 
 export interface TestSuiteArchiveResponse {
@@ -53,11 +45,7 @@ export async function createTestSuite(data: {
   fields?: SuiteField[];
   evaluators?: EvaluatorAttachmentWire[];
 }): Promise<TestSuite> {
-  return makeRequest(
-    "POST",
-    "/api/v1/test-suites",
-    data,
-  ) as Promise<TestSuite>;
+  return makeRequest("POST", "/api/v1/test-suites", data) as Promise<TestSuite>;
 }
 
 /** Retrieves a test suite with the scenarios filed in it. */
@@ -87,21 +75,14 @@ export async function updateTestSuite(params: {
 }
 
 /** Renames a test suite. */
-export async function renameTestSuite(params: {
-  id: string;
-  name: string;
-}): Promise<TestSuite> {
-  return makeRequest(
-    "PATCH",
-    `/api/v1/test-suites/${encodeURIComponent(params.id)}`,
-    { name: params.name },
-  ) as Promise<TestSuite>;
+export async function renameTestSuite(params: { id: string; name: string }): Promise<TestSuite> {
+  return makeRequest("PATCH", `/api/v1/test-suites/${encodeURIComponent(params.id)}`, {
+    name: params.name,
+  }) as Promise<TestSuite>;
 }
 
 /** Archives a test suite and the scenarios filed in it. */
-export async function archiveTestSuite(
-  id: string,
-): Promise<TestSuiteArchiveResponse> {
+export async function archiveTestSuite(id: string): Promise<TestSuiteArchiveResponse> {
   return makeRequest(
     "DELETE",
     `/api/v1/test-suites/${encodeURIComponent(id)}`,