@promptlayer/mcp-server 1.0.0 → 1.2.0

package/gcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "promptlayer-mcp-gcp",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=build/server.mjs --packages=external",
+    "gcp-build": "",
+    "start": "node build/server.mjs",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "express": "^4.21.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.15.0",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/gcp/src/index.ts

@@ -0,0 +1,191 @@
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { TOOL_DEFINITIONS } from "../../src/types.js";
+import { PromptLayerClient } from "../../src/client.js";
+
+// ── Tool handler mapping ────────────────────────────────────────────────────
+
+type Args = Record<string, unknown>;
+type ToolHandler = (client: PromptLayerClient, args: Args) => Promise<unknown>;
+
+function body(args: Args): Args {
+  const { api_key: _, ...rest } = args;
+  return rest;
+}
+
+const TOOL_HANDLERS: Record<string, ToolHandler> = {
+  // Prompt Templates
+  "get-prompt-template": (c, { api_key: _, prompt_name, ...p }) =>
+    c.getPromptTemplate(prompt_name as string, p),
+  "get-prompt-template-raw": (c, { api_key: _, identifier, ...p }) =>
+    c.getPromptTemplateRaw(identifier as string, p),
+  "list-prompt-templates": (c, a) => c.listPromptTemplates(body(a)),
+  "publish-prompt-template": (c, a) => c.publishPromptTemplate(body(a)),
+  "list-prompt-template-labels": (c, { identifier }) =>
+    c.listPromptTemplateLabels(identifier as string),
+  "create-prompt-label": (c, { api_key: _, prompt_id, ...b }) =>
+    c.createPromptLabel(prompt_id as number, b),
+  "move-prompt-label": (c, { api_key: _, prompt_label_id, ...b }) =>
+    c.movePromptLabel(prompt_label_id as number, b),
+  "delete-prompt-label": (c, { prompt_label_id }) =>
+    c.deletePromptLabel(prompt_label_id as number),
+  "get-snippet-usage": (c, { api_key: _, identifier, ...p }) =>
+    c.getSnippetUsage(identifier as string, p),
+
+  // Request Logs
+  "search-request-logs": (c, a) => c.searchRequestLogs(body(a)),
+  "get-request": (c, { request_id }) => c.getRequest(request_id as number),
+
+  // Tracking
+  "log-request": (c, a) => c.logRequest(body(a)),
+  "create-spans-bulk": (c, a) => c.createSpansBulk(body(a)),
+
+  // Datasets
+  "list-datasets": (c, a) => c.listDatasets(body(a)),
+  "create-dataset-group": (c, a) => c.createDatasetGroup(body(a)),
+  "create-dataset-version-from-file": (c, a) => c.createDatasetVersionFromFile(body(a)),
+  "create-dataset-version-from-filter-params": (c, a) => c.createDatasetVersionFromFilterParams(body(a)),
+  "get-dataset-rows": (c, { api_key: _, dataset_id, ...p }) =>
+    c.getDatasetRows(dataset_id as number, p),
+
+  // Evaluations
+  "list-evaluations": (c, a) => c.listEvaluations(body(a)),
+  "get-evaluation-rows": (c, { api_key: _, evaluation_id, ...p }) =>
+    c.getEvaluationRows(evaluation_id as number, p),
+  "create-report": (c, a) => c.createReport(body(a)),
+  "run-report": (c, { api_key: _, report_id, ...b }) =>
+    c.runReport(report_id as number, b),
+  "get-report": (c, { report_id }) => c.getReport(report_id as number),
+  "get-report-score": (c, { report_id }) => c.getReportScore(report_id as number),
+  "update-report-score-card": (c, { api_key: _, report_id, ...b }) =>
+    c.updateReportScoreCard(report_id as number, b),
+  "delete-reports-by-name": (c, { report_name }) =>
+    c.deleteReportsByName(report_name as string),
+
+  // Agents
+  "list-workflows": (c, a) => c.listWorkflows(body(a)),
+  "create-workflow": (c, a) => c.createWorkflow(body(a)),
+  "patch-workflow": (c, { api_key: _, workflow_id_or_name, ...b }) =>
+    c.patchWorkflow(workflow_id_or_name as string, b),
+  "run-workflow": (c, { api_key: _, workflow_name, ...b }) =>
+    c.runWorkflow(workflow_name as string, b),
+  "get-workflow-version-execution-results": (c, a) =>
+    c.getWorkflowVersionExecutionResults(body(a)),
+  "get-workflow": (c, { workflow_id_or_name }) =>
+    c.getWorkflow(workflow_id_or_name as string),
+
+  // Folders
+  "create-folder": (c, a) => c.createFolder(body(a)),
+  "edit-folder": (c, { api_key: _, folder_id, ...b }) =>
+    c.editFolder(folder_id as number, b),
+  "get-folder-entities": (c, a) => c.getFolderEntities(body(a)),
+  "move-folder-entities": (c, a) => c.moveFolderEntities(body(a)),
+  "delete-folder-entities": (c, a) => c.deleteFolderEntities(body(a)),
+  "resolve-folder-id": (c, a) => c.resolveFolderId(body(a)),
+};
+
+// ── Instructions ────────────────────────────────────────────────────────────
+
+const INSTRUCTIONS = `
+PromptLayer is a prompt management and observability platform. This MCP server lets you manage PromptLayer resources.
+
+## Key entities and naming
+
+- **Prompt template**: A versioned prompt in the registry. Each version has a prompt_template (the content) and metadata. Versions are immutable — publishing always creates a new version.
+- **Snippet**: A reusable prompt fragment referenced inside prompt templates with @@@snippet_name@@@ markers. Snippets are themselves prompt templates (with type "completion"). When a prompt is fetched, snippets are expanded inline by default.
+- **Release label**: A pointer (e.g. "prod", "staging") attached to a specific prompt version. Move labels between versions for deployment.
+- **Agent** (backend name: workflow): A multi-step pipeline of nodes. Each node has a type, configuration, and dependencies. Agents are versioned like prompts.
+- **Evaluation pipeline** (backend name: report): Runs evaluation columns against a dataset and produces scores. Columns can be LLM assertions, code execution, comparisons, etc.
+- **Dataset**: A versioned collection of test rows. Belongs to a dataset group. Versions can be created from CSV/JSON files or by filtering request log history.
+- **Folder**: Organizes prompts, agents, datasets, evaluations, and other entities into a hierarchy.
+
+## Working with prompts and snippets
+
+When editing a prompt that may contain snippets, always use get-prompt-template-raw with resolve_snippets=false. This preserves the raw @@@snippet_name@@@ references so they are not lost on re-publish. The response also includes a "snippets" array listing every snippet used.
+
+When publishing back, keep @@@snippet_name@@@ markers intact in the prompt_template content. Do not inline snippet text — this breaks the snippet reference and future snippet updates will no longer propagate.
+
+Use get-prompt-template (the POST variant) only when you need a fully rendered prompt ready to send to an LLM, with input_variables filled in and provider-specific formatting applied.
+
+## Working with evaluations
+
+The recommended way to create an evaluation pipeline is with LLM assertion columns — these use a language model to score each dataset row. For details on all available column types (LLM assertion, code execution, comparison, etc.), search the PromptLayer docs or see https://docs.promptlayer.com/features/evaluations/column-types.
+
+## Additional documentation
+
+For deeper questions about PromptLayer features, configuration, or API details, the PromptLayer docs site has an MCP server you can use for search. See https://docs.promptlayer.com/mcp for setup.
+`.trim();
+
+function resolveApiKey(argKey?: string, headerKey?: string): string {
+  const key = argKey || headerKey;
+  if (!key) {
+    throw new Error(
+      "No API key provided. Set authorization_token in your MCP config " +
+      "or pass api_key to each tool call.",
+    );
+  }
+  if (!key.startsWith("pl_")) {
+    throw new Error("Invalid API key format. PromptLayer API keys must start with 'pl_'.");
+  }
+  return key;
+}
+
+function createMcpServer(defaultApiKey?: string): McpServer {
+  const server = new McpServer(
+    { name: "promptlayer-server", version: "1.0.0" },
+    { instructions: INSTRUCTIONS },
+  );
+
+  for (const [name, def] of Object.entries(TOOL_DEFINITIONS)) {
+    const handler = TOOL_HANDLERS[name];
+    if (!handler) continue;
+
+    server.tool(name, def.description, def.inputSchema.shape, async (args: Args) => {
+      try {
+        const apiKey = resolveApiKey(args.api_key as string | undefined, defaultApiKey);
+        const client = new PromptLayerClient(apiKey);
+        const result = await handler(client, args);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+          }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  return server;
+}
+
+// ── Express app ─────────────────────────────────────────────────────────────
+
+const app = express();
+app.use(express.json());
+
+async function handleMcp(req: express.Request, res: express.Response) {
+  const auth = req.headers.authorization;
+  const apiKey = auth?.startsWith("Bearer ") ? auth.slice(7) : undefined;
+
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+  const server = createMcpServer(apiKey);
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+}
+
+app.post("/mcp", handleMcp);
+app.get("/mcp", handleMcp);
+app.delete("/mcp", handleMcp);
+
+const PORT = parseInt(process.env.PORT || "8080");
+app.listen(PORT, () => {
+  console.log(`PromptLayer MCP server listening on port ${PORT}`);
+});

package/gcp/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["es2022"],
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptlayer/mcp-server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Model Context Protocol server for PromptLayer",
   "type": "module",
   "main": "build/index.js",

package/scripts/diff-endpoints.ts

@@ -105,6 +105,33 @@ const KNOWN_EXCEPTIONS: string[] = [
   // The OpenAPI spec defines scores as object but backend uses a list of {name, operator, value}.
   // Our array type matches what the backend actually accepts.
   'TYPE MISMATCH: POST /api/public/v2/dataset-versions/from-filter-params > "scores": MCP=array, OpenAPI=object [tool: create-dataset-version-from-filter-params]',
+
+  // patch-prompt-template-version exists in the backend and OpenAPI but is not yet implemented
+  // in MCP. Low priority — publish-prompt-template covers most use cases.
+  "MISSING IN MCP: PATCH /rest/prompt-templates/{identifier} (Patch Prompt Template Version)",
+
+  // OTLP trace ingestion endpoint exists in OpenAPI but is not implemented in MCP.
+  // This is a specialized protocol endpoint, not a typical REST API tool.
+  "MISSING IN MCP: POST /v1/traces (Ingest Traces (OTLP))",
+
+  // Semantic search and tags parameters for folder entities are documented in the reference docs
+  // (https://docs.promptlayer.com/reference/list-folder-entities) but not yet in the OpenAPI spec.
+  'EXTRA FIELD: GET /api/public/v2/folders/entities > "semantic_search" not in OpenAPI [tool: get-folder-entities]',
+  'EXTRA FIELD: GET /api/public/v2/folders/entities > "semantic_search_top_k" not in OpenAPI [tool: get-folder-entities]',
+  'EXTRA FIELD: GET /api/public/v2/folders/entities > "semantic_search_threshold" not in OpenAPI [tool: get-folder-entities]',
+  'EXTRA FIELD: GET /api/public/v2/folders/entities > "tags" not in OpenAPI [tool: get-folder-entities]',
+
+  // The OpenAPI spec represents tags as anyOf(string, array) but our Zod union serializes
+  // as "union" vs "union(string,array)". Functionally equivalent.
+  'TYPE MISMATCH: GET /prompt-templates > "tags": MCP=union, OpenAPI=union(string,array) [tool: list-prompt-templates]',
+
+  // filter_type OpenAPI uses oneOf vs our Zod union. Functionally equivalent.
+  'TYPE MISMATCH: GET /api/public/v2/folders/entities > "filter_type": MCP=union, OpenAPI=oneOf [tool: get-folder-entities]',
+
+  // workspace_id is optional in MCP because the API key implicitly provides it.
+  // OpenAPI marks it required but the backend falls back to the API key's workspace.
+  'REQUIRED MISMATCH: GET /api/public/v2/folders/entities > "workspace_id": MCP=false, OpenAPI=true [tool: get-folder-entities]',
+  'REQUIRED MISMATCH: GET /api/public/v2/folders/resolve-id > "workspace_id": MCP=false, OpenAPI=true [tool: resolve-folder-id]',
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 

package/scripts/extract-mcp-tools.ts

@@ -28,13 +28,17 @@ const TOOL_TO_ENDPOINT: Record<string, { method: string; path: string }> = {
   "move-prompt-label":          { method: "PATCH",  path: "/prompt-labels/{prompt_label_id}" },
   "delete-prompt-label":        { method: "DELETE", path: "/prompt-labels/{prompt_label_id}" },
   "get-snippet-usage":          { method: "GET",    path: "/prompt-templates/{identifier}/snippet-usage" },
+  "search-request-logs":        { method: "POST",   path: "/api/public/v2/requests/search" },
+  "get-request":                { method: "GET",    path: "/api/public/v2/requests/{request_id}" },
   "log-request":                { method: "POST",   path: "/log-request" },
   "create-spans-bulk":          { method: "POST",   path: "/spans-bulk" },
   "list-datasets":              { method: "GET",    path: "/api/public/v2/datasets" },
+  "get-dataset-rows":           { method: "GET",    path: "/api/public/v2/datasets/{dataset_id}/rows" },
   "create-dataset-group":       { method: "POST",   path: "/api/public/v2/dataset-groups" },
   "create-dataset-version-from-file": { method: "POST", path: "/api/public/v2/dataset-versions/from-file" },
   "create-dataset-version-from-filter-params": { method: "POST", path: "/api/public/v2/dataset-versions/from-filter-params" },
   "list-evaluations":           { method: "GET",    path: "/api/public/v2/evaluations" },
+  "get-evaluation-rows":        { method: "GET",    path: "/api/public/v2/evaluations/{evaluation_id}/rows" },
   "create-report":              { method: "POST",   path: "/reports" },
   "run-report":                 { method: "POST",   path: "/reports/{report_id}/run" },
   "get-report":                 { method: "GET",    path: "/reports/{report_id}" },

package/src/client.ts

@@ -55,18 +55,24 @@ export class PromptLayerClient {
   deletePromptLabel(labelId: number) { return this.del(`/prompt-labels/${labelId}`); }
   getSnippetUsage(id: string, params?: Body) { return this.get(`/prompt-templates/${this.enc(id)}/snippet-usage`, params); }
 
+  // Request Logs
+  searchRequestLogs(body: Body) { return this.post("/api/public/v2/requests/search", body); }
+  getRequest(requestId: number) { return this.get(`/api/public/v2/requests/${requestId}`); }
+
   // Tracking
   logRequest(body: Body) { return this.post("/log-request", body); }
   createSpansBulk(body: Body) { return this.post("/spans-bulk", body); }
 
   // Datasets
   listDatasets(params?: Body) { return this.get("/api/public/v2/datasets", params); }
+  getDatasetRows(id: number, params?: Body) { return this.get(`/api/public/v2/datasets/${id}/rows`, params); }
   createDatasetGroup(body: Body) { return this.post("/api/public/v2/dataset-groups", body); }
   createDatasetVersionFromFile(body: Body) { return this.post("/api/public/v2/dataset-versions/from-file", body); }
   createDatasetVersionFromFilterParams(body: Body) { return this.post("/api/public/v2/dataset-versions/from-filter-params", body); }
 
   // Evaluations
   listEvaluations(params?: Body) { return this.get("/api/public/v2/evaluations", params); }
+  getEvaluationRows(id: number, params?: Body) { return this.get(`/api/public/v2/evaluations/${id}/rows`, params); }
   createReport(body: Body) { return this.post("/reports", body); }
   runReport(id: number, body: Body) { return this.post(`/reports/${id}/run`, body); }
   getReport(id: number) { return this.get(`/reports/${id}`); }

package/src/handlers.ts

@@ -50,6 +50,13 @@ export function registerAllTools(server: any) {
     (c, a) => { const { api_key: _, identifier, ...p } = a as { identifier: string; api_key?: string } & Args; return c.getSnippetUsage(identifier, p); },
     (r) => `${Array.isArray(r) ? r.length : 0} prompt(s) using snippet`);
 
+  // Request Logs
+  reg(t["search-request-logs"], (c, a) => c.searchRequestLogs(body(a)),
+    (r) => { const { items, total, page, pages } = r as { items?: unknown[]; total?: number; page?: number; pages?: number }; return `${items?.length ?? 0} request(s) (page ${page ?? 1}/${pages ?? 1}, total ${total ?? "?"})`; });
+  reg(t["get-request"],
+    (c, a) => c.getRequest((a as { request_id: number }).request_id),
+    (r) => { const { request_id, model } = r as { request_id?: number; model?: string }; return `Request ${request_id ?? ""}${model ? ` (${model})` : ""} retrieved`; });
+
   // Tracking
   reg(t["log-request"], (c, a) => c.logRequest(body(a)),
     (r) => { const id = (r as { request_id?: unknown }).request_id; return id ? `Logged (ID: ${id})` : "Logged"; });
@@ -62,10 +69,16 @@ export function registerAllTools(server: any) {
   reg(t["create-dataset-group"], (c, a) => c.createDatasetGroup(body(a)), () => "Dataset group created");
   reg(t["create-dataset-version-from-file"], (c, a) => c.createDatasetVersionFromFile(body(a)), () => "Dataset version from file initiated");
   reg(t["create-dataset-version-from-filter-params"], (c, a) => c.createDatasetVersionFromFilterParams(body(a)), () => "Dataset version from history initiated");
+  reg(t["get-dataset-rows"],
+    (c, a) => { const { api_key: _, dataset_id, ...p } = a as { dataset_id: number; api_key?: string } & Args; return c.getDatasetRows(dataset_id, p); },
+    (r) => { const { rows, total, page, pages } = r as { rows?: unknown[]; total?: number; page?: number; pages?: number }; return `${rows?.length ?? 0} row(s) (page ${page ?? 1}/${pages ?? 1}, total ${total ?? "?"})`; });
 
   // Evaluations
   reg(t["list-evaluations"], (c, a) => c.listEvaluations(body(a)),
     (r) => { const { items, total } = r as { items?: unknown[]; total?: number }; return `${items?.length ?? 0} evaluation(s) (total: ${total ?? "?"})`; });
+  reg(t["get-evaluation-rows"],
+    (c, a) => { const { api_key: _, evaluation_id, ...p } = a as { evaluation_id: number; api_key?: string } & Args; return c.getEvaluationRows(evaluation_id, p); },
+    (r) => { const { rows, total, page, pages } = r as { rows?: unknown[]; total?: number; page?: number; pages?: number }; return `${rows?.length ?? 0} row(s) (page ${page ?? 1}/${pages ?? 1}, total ${total ?? "?"})`; });
   reg(t["create-report"], (c, a) => c.createReport(body(a)),
     (r) => { const id = (r as { report_id?: number }).report_id; return id ? `Pipeline created (ID: ${id})` : "Pipeline created"; });
   reg(t["run-report"],

package/src/types.ts

@@ -71,6 +71,7 @@ export const ListPromptTemplatesArgsSchema = z.object({
   per_page: z.number().int().optional().describe("Items per page"),
   label: z.string().optional().describe("Filter by release label"),
   name: z.string().optional().describe("Filter by name (case-insensitive partial match)"),
+  tags: z.union([z.string(), z.array(z.string())]).optional().describe("Filter by tag(s). Only templates whose tags contain all specified values are returned."),
   status: z.enum(["active", "deleted", "all"]).optional().describe("Filter by status (default: 'active')"),
   workspace_id: z.number().int().optional().describe("Workspace ID"),
   api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
@@ -268,6 +269,17 @@ export const CreateDatasetVersionFromFilterParamsArgsSchema = z.object({
 });
 
 
+// ── Get Dataset Rows (GET /api/public/v2/datasets/{dataset_id}/rows) ─────
+
+export const GetDatasetRowsArgsSchema = z.object({
+  dataset_id: z.number().int().describe("The ID of the dataset to retrieve rows from"),
+  workspace_id: z.number().int().optional().describe("Filter by workspace ID"),
+  page: z.number().int().optional().describe("Page number (default: 1)"),
+  per_page: z.number().int().optional().describe("Rows per page (default: 10, max: 100)"),
+  q: z.string().optional().describe("Search query for filtering rows"),
+  api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
+});
+
 // ── List Evaluations (GET /api/public/v2/evaluations) ────────────────────
 
 export const ListEvaluationsArgsSchema = z.object({
@@ -279,6 +291,16 @@ export const ListEvaluationsArgsSchema = z.object({
   api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
 });
 
+// ── Get Evaluation Rows (GET /api/public/v2/evaluations/{evaluation_id}/rows)
+
+export const GetEvaluationRowsArgsSchema = z.object({
+  evaluation_id: z.number().int().describe("The ID of the evaluation to retrieve rows from"),
+  workspace_id: z.number().int().optional().describe("Filter by workspace ID"),
+  page: z.number().int().optional().describe("Page number (default: 1)"),
+  per_page: z.number().int().optional().describe("Rows per page (default: 10, max: 100)"),
+  api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
+});
+
 // ── Create Evaluation Pipeline / Report (POST /reports) ──────────────────
 
 export const CreateReportArgsSchema = z.object({
@@ -434,7 +456,11 @@ const EntityTypeEnum = z.enum([
 export const GetFolderEntitiesArgsSchema = z.object({
   folder_id: z.number().int().optional().describe("Folder ID to list (root if omitted)"),
   filter_type: z.union([EntityTypeEnum, z.array(EntityTypeEnum)]).optional().describe("Entity type(s) to include (default: all)"),
-  search_query: z.string().optional().describe("Search by name (case-insensitive partial match)"),
+  search_query: z.string().optional().describe("Search by name (case-insensitive partial match). For prompts, also searches across prompt version content."),
+  semantic_search: z.boolean().optional().describe("Enable semantic (vector) search instead of text matching. Requires search_query to be set. Currently supports prompts and folders."),
+  semantic_search_top_k: z.number().int().optional().describe("Max results from semantic search (default: 100, range: 1-500)"),
+  semantic_search_threshold: z.number().optional().describe("Max distance threshold for semantic search results (range: (0, 2])"),
+  tags: z.array(z.string()).optional().describe("Filter entities by tags (AND logic — all must match). Applies to prompts, workflows, datasets, evaluations."),
   flatten: z.boolean().optional().describe("Flatten nested folder hierarchy (default: false)"),
   include_metadata: z.boolean().optional().describe("Include entity metadata like latest_version_number (default: false)"),
   workspace_id: z.number().int().optional().describe("Workspace ID"),
@@ -480,6 +506,58 @@ export const ResolveFolderIdArgsSchema = z.object({
 });
 
 
+// ── Search Request Logs (POST /api/public/v2/requests/search) ────────────
+// NOTE: The StructuredFilter and StructuredFilterGroup schemas use loose types
+// (z.unknown()) for value/filters because the backend validates operator-field
+// compatibility at runtime. This is tracked as a known exception in scripts/diff-endpoints.ts.
+
+const StructuredFilterSchema = z.object({
+  field: z.enum([
+    "pl_id", "prompt_id", "engine", "provider_type", "input_text", "output_text",
+    "prompt_version_number", "input_tokens", "output_tokens", "cost", "latency_ms",
+    "request_start_time", "request_end_time", "status",
+    "is_json", "is_tool_call", "is_plain_text",
+    "tags", "metadata_keys", "metadata", "tool_names",
+    "output", "output_keys", "input_variables", "input_variable_keys",
+  ]).describe("Request log field to filter on"),
+  operator: z.enum([
+    "is", "is_not", "in", "not_in",
+    "contains", "not_contains", "starts_with", "ends_with",
+    "eq", "neq", "gt", "gte", "lt", "lte", "between",
+    "before", "after",
+    "is_true", "is_false", "is_empty", "is_not_empty",
+    "is_null", "is_not_null",
+    "key_equals", "key_not_equals", "key_contains",
+  ]).describe("Filter operator (availability depends on field type)"),
+  value: z.unknown().optional().describe("Filter value (type depends on operator)"),
+  nested_key: z.string().optional().describe("Key name for nested field operators (metadata, output, input_variables)"),
+});
+
+const StructuredFilterGroupSchema: z.ZodType = z.object({
+  logic: z.enum(["AND", "OR"]).optional().describe("Logical operator (default: AND)"),
+  filters: z.array(z.union([StructuredFilterSchema, z.lazy(() => StructuredFilterGroupSchema)])).describe("Filters or nested filter groups"),
+});
+
+export const SearchRequestLogsArgsSchema = z.object({
+  filters: z.array(StructuredFilterSchema).optional().describe("Structured filters (combined with AND logic)"),
+  filter_group: StructuredFilterGroupSchema.optional().describe("Filter group with AND/OR logic, supports nesting"),
+  q: z.string().optional().describe("Free-text search across prompt input and LLM output"),
+  page: z.number().int().optional().describe("Page number (default: 1)"),
+  per_page: z.number().int().optional().describe("Items per page (max: 25)"),
+  sort_by: z.enum(["request_start_time", "input_tokens", "output_tokens", "cost", "latency_ms", "status"]).optional().describe("Sort field"),
+  sort_order: z.enum(["asc", "desc"]).optional().describe("Sort direction (must be provided with sort_by)"),
+  include_prompt_name: z.boolean().optional().describe("Include prompt template name in results"),
+  api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
+});
+
+// ── Get Request (GET /api/public/v2/requests/{request_id}) ───────────────
+
+export const GetRequestArgsSchema = z.object({
+  request_id: z.number().int().describe("Request ID to retrieve"),
+  api_key: z.string().optional().describe("PromptLayer API key (optional, defaults to PROMPTLAYER_API_KEY env var)"),
+});
+
+
 export type GetPromptTemplateParams = Omit<
   z.infer<typeof GetPromptTemplateArgsSchema>,
   "prompt_name" | "api_key"
@@ -563,6 +641,40 @@ export const TOOL_DEFINITIONS = {
     annotations: { readOnlyHint: true },
   },
 
+  // ── Request Logs ──────────────────────────────────────────────────
+  "search-request-logs": {
+    name: "search-request-logs",
+    description:
+      "Search and filter request logs using structured filters, free-text search, and sorting. " +
+      "Rate limited to 10 req/min, max 25 results/page.\n\n" +
+      "FILTER SYNTAX: Each filter is {field, operator, value, nested_key?}.\n" +
+      "Operators by field type:\n" +
+      "  - String fields (engine, provider_type): is, is_not, in, not_in\n" +
+      "  - Text fields (input_text, output_text): contains, not_contains, starts_with, ends_with\n" +
+      "  - Numeric fields (cost, latency_ms, input_tokens, output_tokens): eq, neq, gt, gte, lt, lte, between (value=[min,max]), is_null, is_not_null\n" +
+      "  - Datetime fields (request_start_time, request_end_time): is, before, after, between (value=[start,end] as ISO 8601)\n" +
+      "  - Boolean fields (is_json, is_tool_call, is_plain_text): is_true, is_false\n" +
+      "  - Array fields (tags, metadata_keys, tool_names, output_keys, input_variable_keys): contains, not_contains, in, not_in, is_empty, is_not_empty\n" +
+      "  - Nested fields (metadata, output, input_variables): key_equals, key_not_equals, key_contains, in, not_in, is_empty, is_not_empty — requires nested_key\n\n" +
+      "EXAMPLES:\n" +
+      '  Find GPT-4o requests: {filters: [{field:"engine", operator:"is", value:"gpt-4o"}]}\n' +
+      '  Expensive requests: {filters: [{field:"cost", operator:"gte", value:0.10}]}\n' +
+      '  By metadata: {filters: [{field:"metadata", operator:"key_equals", value:"customer_123", nested_key:"user_id"}]}\n' +
+      '  Free-text search: {q: "refund policy"}\n' +
+      '  Complex AND/OR: {filter_group: {logic:"OR", filters: [{field:"tags", operator:"contains", value:"prod"}, {logic:"AND", filters: [...]}]}}',
+    inputSchema: SearchRequestLogsArgsSchema,
+    annotations: { readOnlyHint: true },
+  },
+  "get-request": {
+    name: "get-request",
+    description:
+      "Retrieve a single request's full payload by ID, returned as a prompt blueprint. " +
+      "Includes the prompt template content, model configuration, provider, token counts, " +
+      "cost, and timing data. Useful for debugging, replaying requests, or extracting data for evaluations.",
+    inputSchema: GetRequestArgsSchema,
+    annotations: { readOnlyHint: true },
+  },
+
   // ── Tracking ────────────────────────────────────────────────────────
   "log-request": {
     name: "log-request",
@@ -605,6 +717,12 @@ export const TOOL_DEFINITIONS = {
     inputSchema: CreateDatasetVersionFromFilterParamsArgsSchema,
     annotations: { readOnlyHint: false },
   },
+  "get-dataset-rows": {
+    name: "get-dataset-rows",
+    description: "Get paginated rows from a dataset. Each row is an array of cells with {type: 'dataset', value: ...}. Supports search via the q parameter.",
+    inputSchema: GetDatasetRowsArgsSchema,
+    annotations: { readOnlyHint: true },
+  },
 
   // ── Evaluations ─────────────────────────────────────────────────────
   "list-evaluations": {
@@ -613,6 +731,12 @@ export const TOOL_DEFINITIONS = {
     inputSchema: ListEvaluationsArgsSchema,
     annotations: { readOnlyHint: true },
   },
+  "get-evaluation-rows": {
+    name: "get-evaluation-rows",
+    description: "Get paginated evaluation results with dataset inputs and eval outcomes. Each row has dataset cells ({type: 'dataset', value: ...}) followed by eval cells ({type: 'eval', status: 'PASSED'|'FAILED', value: ...}).",
+    inputSchema: GetEvaluationRowsArgsSchema,
+    annotations: { readOnlyHint: true },
+  },
   "create-report": {
     name: "create-report",
     description: "Create an evaluation pipeline (called 'report' in the API) linked to a dataset group. The recommended approach is to add LLM assertion columns that use a language model to score each row. For all available column types, search the PromptLayer docs or visit https://docs.promptlayer.com/features/evaluations/column-types.",

package/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run build:*)",
-      "Bash(npm install:*)",
-      "Bash(npm run sync:check:*)",
-      "WebSearch",
-      "WebFetch(domain:blog.modelcontextprotocol.io)",
-      "Bash(npx tsx:*)",
-      "WebFetch(domain:docs.promptlayer.com)",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git push:*)"
-    ]
-  }
-}