feat(cli): Expand and improve the MCP server and dev CLI command

Author: ericallam

.changeset/fix-list-deploys-nullable.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Fix `list_deploys` MCP tool failing when deployments have null `runtime` or `runtimeVersion` fields.

.changeset/mcp-query-tools.md

@@ -0,0 +1,42 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+MCP server improvements: new tools, bug fixes, and new flags.
+
+**New tools:**
+- `get_query_schema` — discover available TRQL tables and columns
+- `query` — execute TRQL queries against your data
+- `list_dashboards` — list built-in dashboards and their widgets
+- `run_dashboard_query` — execute a single dashboard widget query
+- `whoami` — show current profile, user, and API URL
+- `list_profiles` — list all configured CLI profiles
+- `switch_profile` — switch active profile for the MCP session
+- `start_dev_server` — start `trigger dev` in the background and stream output
+- `stop_dev_server` — stop the running dev server
+- `dev_server_status` — check dev server status and view recent logs
+
+**New API endpoints:**
+- `GET /api/v1/query/schema` — query table schema discovery
+- `GET /api/v1/query/dashboards` — list built-in dashboards
+
+**New features:**
+- `--readonly` flag hides write tools (`deploy`, `trigger_task`, `cancel_run`) so the AI cannot make changes
+- `read:query` JWT scope for query endpoint authorization
+- `get_run_details` trace output is now paginated with cursor support
+- MCP tool annotations (`readOnlyHint`, `destructiveHint`) for all tools
+
+**Bug fixes:**
+- Fixed `search_docs` tool failing due to renamed upstream Mintlify tool (`SearchTriggerDev` → `search_trigger_dev`)
+- Fixed `list_deploys` failing when deployments have null `runtime`/`runtimeVersion` fields (#3139)
+- Fixed `list_preview_branches` crashing due to incorrect response shape access
+- Fixed `metrics` table column documented as `value` instead of `metric_value` in query docs
+- Fixed dev CLI leaking build directories on rebuild — deprecated workers now clean up their build dirs when their last run completes
+
+**Context optimizations:**
+- `get_query_schema` now requires a table name and returns only one table's schema (was returning all tables)
+- `get_current_worker` no longer inlines payload schemas; use new `get_task_schema` tool instead
+- Query results formatted as text tables instead of JSON (~50% fewer tokens)
+- `cancel_run`, `list_deploys`, `list_preview_branches` formatted as text instead of raw JSON
+- Schema and dashboard API responses cached to avoid redundant fetches

apps/webapp/app/routes/api.v1.query.dashboards._index.ts

@@ -0,0 +1,46 @@
+import { json } from "@remix-run/server-runtime";
+import type { DashboardSummary, DashboardWidgetSummary } from "@trigger.dev/core/v3/schemas";
+import type { BuiltInDashboard } from "~/presenters/v3/MetricDashboardPresenter.server";
+import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+import { builtInDashboardList } from "~/presenters/v3/BuiltInDashboards.server";
+
+function serializeDashboard(dashboard: BuiltInDashboard): DashboardSummary {
+  const widgets: DashboardWidgetSummary[] = [];
+
+  if (dashboard.layout.version === "1") {
+    for (const [id, widget] of Object.entries(dashboard.layout.widgets)) {
+      // Skip title widgets — they're just section headers
+      if (widget.display.type === "title") continue;
+
+      widgets.push({
+        id,
+        title: widget.title,
+        query: widget.query,
+        type: widget.display.type,
+      });
+    }
+  }
+
+  return {
+    key: dashboard.key,
+    title: dashboard.title,
+    widgets,
+  };
+}
+
+export const loader = createLoaderApiRoute(
+  {
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: () => ({ query: "dashboards" }),
+      superScopes: ["read:query", "read:all", "admin"],
+    },
+  },
+  async () => {
+    const dashboards = builtInDashboardList().map(serializeDashboard);
+    return json({ dashboards });
+  }
+);

apps/webapp/app/routes/api.v1.query.schema.ts

@@ -0,0 +1,58 @@
+import { json } from "@remix-run/server-runtime";
+import type { ColumnSchema, TableSchema } from "@internal/tsql";
+import { createLoaderApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+import { querySchemas } from "~/v3/querySchemas";
+
+function serializeColumn(col: ColumnSchema) {
+  const result: Record<string, unknown> = {
+    name: col.name,
+    type: col.type,
+  };
+
+  if (col.description) {
+    result.description = col.description;
+  }
+  if (col.example) {
+    result.example = col.example;
+  }
+  if (col.allowedValues && col.allowedValues.length > 0) {
+    if (col.valueMap) {
+      result.allowedValues = Object.values(col.valueMap);
+    } else {
+      result.allowedValues = col.allowedValues;
+    }
+  }
+  if (col.coreColumn) {
+    result.coreColumn = true;
+  }
+
+  return result;
+}
+
+function serializeTable(table: TableSchema) {
+  const columns = Object.values(table.columns).map(serializeColumn);
+
+  return {
+    name: table.name,
+    description: table.description,
+    timeColumn: table.timeConstraint,
+    columns,
+  };
+}
+
+export const loader = createLoaderApiRoute(
+  {
+    allowJWT: true,
+    corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: () => ({ query: "schema" }),
+      superScopes: ["read:query", "read:all", "admin"],
+    },
+  },
+  async () => {
+    const tables = querySchemas.map(serializeTable);
+    return json({ tables });
+  }
+);

apps/webapp/app/routes/api.v1.query.ts

@@ -5,6 +5,7 @@ import { createActionApiRoute } from "~/services/routeBuilders/apiBuilder.server
 import { executeQuery, type QueryScope } from "~/services/queryService.server";
 import { logger } from "~/services/logger.server";
 import { rowsToCSV } from "~/utils/dataExport";
+import { querySchemas } from "~/v3/querySchemas";
 
 const BodySchema = z.object({
   query: z.string(),
@@ -15,10 +16,27 @@ const BodySchema = z.object({
   format: z.enum(["json", "csv"]).default("json"),
 });
 
+/** Extract table names from a TRQL query for authorization */
+function detectTables(query: string): string[] {
+  return querySchemas
+    .filter((s) => new RegExp(`\\bFROM\\s+${s.name}\\b`, "i").test(query))
+    .map((s) => s.name);
+}
+
 const { action, loader } = createActionApiRoute(
   {
     body: BodySchema,
+    allowJWT: true,
     corsStrategy: "all",
+    findResource: async () => 1,
+    authorization: {
+      action: "read",
+      resource: (_, __, ___, body) => {
+        const tables = detectTables(body.query);
+        return { query: tables.length > 0 ? tables : "all" };
+      },
+      superScopes: ["read:query", "read:all", "admin"],
+    },
   },
   async ({ body, authentication }) => {
     const { query, scope, period, from, to, format } = body;

apps/webapp/app/services/authorization.server.ts

@@ -1,6 +1,6 @@
 export type AuthorizationAction = "read" | "write" | string; // Add more actions as needed
 
-const ResourceTypes = ["tasks", "tags", "runs", "batch", "waitpoints", "deployments", "inputStreams"] as const;
+const ResourceTypes = ["tasks", "tags", "runs", "batch", "waitpoints", "deployments", "inputStreams", "query"] as const;
 
 export type AuthorizationResources = {
   [key in (typeof ResourceTypes)[number]]?: string | string[];

apps/webapp/test/authorization.test.ts

@@ -310,6 +310,84 @@ describe("checkAuthorization", () => {
     });
   });
 
+  describe("Query resource type", () => {
+    it("should grant access with read:query super scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: "runs" },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should grant access with table-specific query scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query:runs"],
+      };
+      const result = checkAuthorization(entity, "read", { query: "runs" });
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should deny access to different table with table-specific scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query:runs"],
+      };
+      const result = checkAuthorization(entity, "read", { query: "llm_metrics" });
+      expect(result.authorized).toBe(false);
+    });
+
+    it("should grant access with general read:query scope to any table", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+
+      const runsResult = checkAuthorization(entity, "read", { query: "runs" });
+      expect(runsResult.authorized).toBe(true);
+
+      const metricsResult = checkAuthorization(entity, "read", { query: "metrics" });
+      expect(metricsResult.authorized).toBe(true);
+
+      const llmResult = checkAuthorization(entity, "read", { query: "llm_metrics" });
+      expect(llmResult.authorized).toBe(true);
+    });
+
+    it("should grant access to multiple tables when querying with super scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: ["runs", "llm_metrics"] },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+
+    it("should grant access to schema with read:query scope", () => {
+      const entity: AuthorizationEntity = {
+        type: "PUBLIC_JWT",
+        scopes: ["read:query"],
+      };
+      const result = checkAuthorization(
+        entity,
+        "read",
+        { query: "schema" },
+        ["read:query", "read:all", "admin"]
+      );
+      expect(result.authorized).toBe(true);
+    });
+  });
+
   describe("Without super scope", () => {
     const entityWithoutSuperPermissions: AuthorizationEntity = {
       type: "PUBLIC_JWT",

packages/cli-v3/package.json

@@ -78,7 +78,9 @@
     "test:e2e": "vitest --run -c ./e2e/vitest.config.ts",
     "update-version": "tsx ../../scripts/updateVersion.ts",
     "install-mcp": "./install-mcp.sh",
-    "inspector": "npx @modelcontextprotocol/inspector dist/esm/index.js mcp --log-file .mcp.log --api-url http://localhost:3030"
+    "inspector": "npx @modelcontextprotocol/inspector dist/esm/index.js mcp --log-file .mcp.log --api-url http://localhost:3030",
+    "mcp:test": "tsx src/mcp/tools.test.ts",
+    "mcp:smoke": "tsx src/mcp/smoke.test.ts"
   },
   "dependencies": {
     "@clack/prompts": "0.11.0",

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

@@ -20,6 +20,7 @@ const McpCommandOptions = CommonCommandOptions.extend({
   projectRef: z.string().optional(),
   logFile: z.string().optional(),
   devOnly: z.boolean().default(false),
+  readonly: z.boolean().default(false),
   rulesInstallManifestPath: z.string().optional(),
   rulesInstallBranch: z.string().optional(),
 });
@@ -36,6 +37,10 @@ export function configureMcpCommand(program: Command) {
         "--dev-only",
         "Only run the MCP server for the dev environment. Attempts to access other environments will fail."
       )
+      .option(
+        "--readonly",
+        "Run in read-only mode. Write tools (deploy, trigger_task, cancel_run) are hidden from the AI."
+      )
       .option("--log-file <log file>", "The file to log to")
       .addOption(
         new CommandOption(
@@ -97,6 +102,7 @@ export async function mcpCommand(options: McpCommandOptions) {
 
   server.server.oninitialized = async () => {
     fileLogger?.log("initialized mcp command", { options, argv: process.argv });
+    await context.loadProjectProfile();
   };
 
   // Start receiving messages on stdin and sending messages on stdout
@@ -111,6 +117,7 @@ export async function mcpCommand(options: McpCommandOptions) {
     fileLogger,
     apiUrl: options.apiUrl ?? CLOUD_API_URL,
     profile: options.profile,
+    readonly: options.readonly,
   });
 
   registerTools(context);

packages/cli-v3/src/dev/backgroundWorker.ts

@@ -6,6 +6,8 @@ import { prettyError } from "../utilities/cliOutput.js";
 import { writeJSONFile } from "../utilities/fileSystem.js";
 import { logger } from "../utilities/logger.js";
 import type { Metafile } from "esbuild";
+import { trail } from "agentcrumbs"; // @crumbs
+const crumb = trail("cli"); // @crumbs
 
 export type BackgroundWorkerOptions = {
   env: Record<string, string>;
@@ -37,6 +39,7 @@ export class BackgroundWorker {
   }
 
   stop() {
+    crumb("BackgroundWorker.stop", { version: this.serverWorker?.version, outputPath: this.build.outputPath }); // @crumbs
     logger.debug("[BackgroundWorker] Stopping worker", {
       version: this.serverWorker?.version,
       outputPath: this.build.outputPath,