Improved the get tasks tool, fixed mintlify MCP search

Author: ericallam

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.ts

@@ -74,10 +74,12 @@ export async function getEnvironmentFromEnv({
   projectId,
   userId,
   env,
+  branch,
 }: {
   projectId: string;
   userId: string;
   env: ParamsSchema["env"];
+  branch?: string;
 }): Promise<
   | {
       success: true;
@@ -126,6 +128,48 @@ export async function getEnvironmentFromEnv({
       break;
   }
 
+  if (slug === "preview") {
+    if (!branch) {
+      return {
+        success: false,
+        error: "Preview environment requires a branch. Please set the x-trigger-branch header.",
+      };
+    }
+
+    const previewEnvironment = await prisma.runtimeEnvironment.findFirst({
+      where: {
+        projectId,
+        slug: "preview",
+      },
+    });
+
+    if (!previewEnvironment) {
+      return {
+        success: false,
+        error: "Preview environment not found",
+      };
+    }
+
+    const branchEnvironment = await prisma.runtimeEnvironment.findFirst({
+      where: {
+        parentEnvironmentId: previewEnvironment.id,
+        branchName: branch,
+      },
+    });
+
+    if (!branchEnvironment) {
+      return {
+        success: false,
+        error: `Preview branch ${branch} not found`,
+      };
+    }
+
+    return {
+      success: true,
+      environment: branchEnvironment,
+    };
+  }
+
   const environment = await prisma.runtimeEnvironment.findFirst({
     where: {
       projectId,

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.workers.$tagName.ts

@@ -5,13 +5,19 @@ import { authenticateApiRequestWithPersonalAccessToken } from "~/services/person
 import { findCurrentWorkerFromEnvironment } from "~/v3/models/workerDeployment.server";
 import { getEnvironmentFromEnv } from "./api.v1.projects.$projectRef.$env";
 import { GetWorkerByTagResponse } from "@trigger.dev/core/v3/schemas";
+import { env as $env } from "~/env.server";
+import { v3RunsPath } from "~/utils/pathBuilder";
 
 const ParamsSchema = z.object({
   projectRef: z.string(),
   tagName: z.string(),
   env: z.enum(["dev", "staging", "prod", "preview"]),
 });
 
+const HeadersSchema = z.object({
+  "x-trigger-branch": z.string().optional(),
+});
+
 type ParamsSchema = z.infer<typeof ParamsSchema>;
 
 export async function loader({ request, params }: LoaderFunctionArgs) {
@@ -27,6 +33,10 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     return json({ error: "Invalid Params" }, { status: 400 });
   }
 
+  const parsedHeaders = HeadersSchema.safeParse(Object.fromEntries(request.headers));
+
+  const branch = parsedHeaders.success ? parsedHeaders.data["x-trigger-branch"] : undefined;
+
   const { projectRef, env } = parsedParams.data;
 
   const project = await prisma.project.findFirst({
@@ -40,6 +50,15 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
         },
       },
     },
+    select: {
+      id: true,
+      slug: true,
+      organization: {
+        select: {
+          slug: true,
+        },
+      },
+    },
   });
 
   if (!project) {
@@ -50,6 +69,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     projectId: project.id,
     userId: authenticationResult.userId,
     env,
+    branch,
   });
 
   if (!envResult.success) {
@@ -88,6 +108,15 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
     },
   });
 
+  const urls = {
+    runs: `${$env.APP_ORIGIN}${v3RunsPath(
+      { slug: project.organization.slug },
+      { slug: project.slug },
+      { slug: env },
+      { versions: [currentWorker.version] }
+    )}`,
+  };
+
   // Prepare the response object
   const response: GetWorkerByTagResponse = {
     worker: {
@@ -105,10 +134,8 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
         payloadSchema: task.payloadSchema,
       })),
     },
+    urls,
   };
 
-  // Optionally validate the response before returning (for type safety)
-  // WorkerResponseSchema.parse(response);
-
   return json(response);
 }

packages/cli-v3/src/mcp/config.ts

@@ -46,6 +46,12 @@ export const toolsMetadata = {
     description:
       "Get all tasks in the project. Useful when searching for a task and for looking up a task identifier/slug",
   },
+  get_current_worker: {
+    name: "get_current_worker",
+    title: "Get Current Worker",
+    description:
+      "Get the current worker for the project. Useful when searching for a task and for looking up a task identifier/slug and payload schema, or looking for the latest version in a specific environment.",
+  },
   trigger_task: {
     name: "trigger_task",
     title: "Trigger Task",

packages/cli-v3/src/mcp/mintlifyClient.ts

@@ -1,5 +1,5 @@
-export async function performSearch(query: string) {
-  const body = callToolBody("search", { query });
+export async function performSearch(query: string, signal: AbortSignal) {
+  const body = callToolBody("Search", { query });
 
   const response = await fetch("https://trigger.dev/docs/mcp", {
     method: "POST",
@@ -8,6 +8,7 @@ export async function performSearch(query: string) {
       Accept: "application/json, text/event-stream",
       "MCP-Protocol-Version": "2025-06-18",
     },
+    signal,
     body: JSON.stringify(body),
   });
 

packages/cli-v3/src/mcp/schemas.ts

@@ -67,19 +67,10 @@ export const TriggerTaskInput = CommonProjectsInput.extend({
       "The ID/slug of the task to trigger. Use the get_tasks tool to get a list of tasks and ask the user to select one if it's not clear which one to use."
     ),
   payload: z
-    .string()
-    .transform((val, ctx) => {
-      try {
-        return JSON.parse(val);
-      } catch {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: "The payload must be a valid JSON string",
-        });
-        return z.NEVER;
-      }
-    })
-    .describe("The payload to trigger the task with, must be a valid JSON string"),
+    .any()
+    .describe(
+      "The payload to trigger the task with. Should match the task's payload schema. Not a JSON string, but the actual payload object"
+    ),
   options: z
     .object({
       queue: z

packages/cli-v3/src/mcp/tools.ts

@@ -9,7 +9,7 @@ import {
 } from "./tools/orgs.js";
 import { listPreviewBranchesTool } from "./tools/previewBranches.js";
 import { cancelRunTool, getRunDetailsTool, listRunsTool } from "./tools/runs.js";
-import { getTasksTool, triggerTaskTool } from "./tools/tasks.js";
+import { getCurrentWorker, triggerTaskTool } from "./tools/tasks.js";
 import { respondWithError } from "./utils.js";
 
 export function registerTools(context: McpContext) {
@@ -19,7 +19,7 @@ export function registerTools(context: McpContext) {
     listProjectsTool,
     createProjectInOrgTool,
     initializeProjectTool,
-    getTasksTool,
+    getCurrentWorker,
     triggerTaskTool,
     listRunsTool,
     getRunDetailsTool,

packages/cli-v3/src/mcp/tools/docs.ts

@@ -10,13 +10,11 @@ export const searchDocsTool = {
   inputSchema: {
     query: z.string(),
   },
-  handler: toolHandler({ query: z.string() }, async (input, { ctx }) => {
+  handler: toolHandler({ query: z.string() }, async (input, { ctx, signal }) => {
     ctx.logger?.log("calling search_docs", { input });
 
-    const results = await performSearch(input.query);
+    const results = await performSearch(input.query, signal);
 
-    return {
-      content: [{ type: "text", text: results.result }],
-    };
+    return results.result;
   }),
 };

packages/cli-v3/src/mcp/tools/tasks.ts

@@ -3,13 +3,13 @@ import { CommonProjectsInput, TriggerTaskInput } from "../schemas.js";
 import { ToolMeta } from "../types.js";
 import { respondWithError, toolHandler } from "../utils.js";
 
-export const getTasksTool = {
-  name: toolsMetadata.get_tasks.name,
-  title: toolsMetadata.get_tasks.title,
-  description: toolsMetadata.get_tasks.description,
+export const getCurrentWorker = {
+  name: toolsMetadata.get_current_worker.name,
+  title: toolsMetadata.get_current_worker.title,
+  description: toolsMetadata.get_current_worker.description,
   inputSchema: CommonProjectsInput.shape,
   handler: toolHandler(CommonProjectsInput.shape, async (input, { ctx }) => {
-    ctx.logger?.log("calling get_tasks", { input });
+    ctx.logger?.log("calling get_current_worker", { input });
 
     if (ctx.options.devOnly && input.environment !== "dev") {
       return respondWithError(
@@ -24,14 +24,60 @@ export const getTasksTool = {
 
     const cliApiClient = await ctx.getCliApiClient(input.branch);
 
-    const worker = await cliApiClient.getWorkerByTag(projectRef, input.environment, "current");
+    const workerResult = await cliApiClient.getWorkerByTag(
+      projectRef,
+      input.environment,
+      "current"
+    );
+
+    if (!workerResult.success) {
+      return respondWithError(workerResult.error);
+    }
+
+    const { worker, urls } = workerResult.data;
+
+    const contents = [
+      `Current worker for ${input.environment} is ${worker.version} using ${worker.sdkVersion} of the SDK.`,
+    ];
+
+    if (worker.tasks.length > 0) {
+      contents.push(`The worker has ${worker.tasks.length} tasks registered:`);
+
+      for (const task of worker.tasks) {
+        if (task.payloadSchema) {
+          contents.push(
+            `- ${task.slug} in ${task.filePath} (payload schema: ${JSON.stringify(
+              task.payloadSchema
+            )})`
+          );
+        } else {
+          contents.push(`- ${task.slug} in ${task.filePath}`);
+        }
+      }
+    } else {
+      contents.push(`The worker has no tasks registered.`);
+    }
 
-    if (!worker.success) {
-      return respondWithError(worker.error);
+    contents.push(`\n`);
+    contents.push(`URLs:`);
+    contents.push(`- Runs: ${urls.runs}`);
+    contents.push(`\n`);
+    contents.push(
+      `You can use the list_runs tool with the version ${worker.version} to get the list of runs for this worker.`
+    );
+
+    if (
+      typeof worker.sdkVersion === "string" &&
+      typeof worker.cliVersion === "string" &&
+      worker.sdkVersion !== worker.cliVersion
+    ) {
+      contents.push(
+        `WARNING: The SDK version (${worker.sdkVersion}) is different from the CLI version (${worker.cliVersion}). This might cause issues with the task execution. Make sure to pin the CLI and the SDK versions to ${worker.sdkVersion}.`
+      );
     }
 
     return {
-      content: [{ type: "text", text: JSON.stringify(worker.data, null, 2) }],
+      content: [{ type: "text", text: contents.join("\n") }],
     };
   }),
 };
@@ -62,8 +108,20 @@ export const triggerTaskTool = {
       branch: input.branch,
     });
 
+    ctx.logger?.log("triggering task", { input });
+
+    let payload = input.payload;
+
+    if (typeof payload === "string") {
+      try {
+        payload = JSON.parse(payload);
+      } catch {
+        ctx.logger?.log("payload is not a valid JSON string, using as is", { payload });
+      }
+    }
+
     const result = await apiClient.triggerTask(input.taskId, {
-      payload: input.payload,
+      payload,
       options: input.options,
     });
 

packages/core/src/v3/schemas/api.ts

@@ -100,6 +100,9 @@ export const GetWorkerByTagResponse = z.object({
     cliVersion: z.string().nullish(),
     tasks: z.array(GetWorkerTaskResponse),
   }),
+  urls: z.object({
+    runs: z.string(),
+  }),
 });
 
 export type GetWorkerByTagResponse = z.infer<typeof GetWorkerByTagResponse>;