refactor: improve MCP server option validation and error messages

- Add environment name validation for --env-only flag
- Simplify environment validation logic (remove redundant devOnly check)
- Standardize error messages across all tools
- Add getAllowedEnvironments() helper method for consistent messaging

Author: hongkongkiwi

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

@@ -131,6 +131,15 @@ export async function mcpCommand(options: McpCommandOptions) {
   let envOnly: string[] | undefined;
   if (options.envOnly) {
     envOnly = options.envOnly.split(',').map(env => env.trim());
+
+    // Validate environment names
+    const validEnvironments = ['dev', 'staging', 'prod', 'preview'];
+    const invalidEnvs = envOnly.filter(env => !validEnvironments.includes(env));
+    if (invalidEnvs.length > 0) {
+      logger.error(`Error: Invalid environment(s): ${invalidEnvs.join(', ')}`);
+      logger.error(`Valid environments are: ${validEnvironments.join(', ')}`);
+      process.exit(1);
+    }
   } else if (options.devOnly) {
     // For backward compatibility, convert devOnly to envOnly
     envOnly = ['dev'];

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

@@ -189,17 +189,19 @@ export class McpContext {
   }
 
   public isEnvironmentAllowed(environment: string): boolean {
-    // If envOnly is specified, use that
+    // If envOnly is specified, use that (devOnly is already converted to envOnly)
     if (this.options.envOnly && this.options.envOnly.length > 0) {
       return this.options.envOnly.includes(environment);
     }
 
-    // For backward compatibility, check devOnly
-    if (this.options.devOnly) {
-      return environment === "dev";
-    }
-
-    // If neither is specified, all environments are allowed
+    // If no restrictions, all environments are allowed
     return true;
   }
+
+  public getAllowedEnvironments(): string {
+    if (this.options.envOnly && this.options.envOnly.length > 0) {
+      return this.options.envOnly.join(", ");
+    }
+    return "all environments";
+  }
 }

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

@@ -20,9 +20,8 @@ export const deployTool = {
 
     // Check if the deployment target environment is allowed
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You cannot deploy to ${input.environment}.`
+        `Cannot deploy to ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 
@@ -121,9 +120,8 @@ export const listDeploysTool = {
     ctx.logger?.log("calling list_deploys", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 

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

@@ -13,9 +13,8 @@ export const getRunDetailsTool = {
     ctx.logger?.log("calling get_run_details", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 
@@ -71,9 +70,8 @@ export const waitForRunToCompleteTool = {
     ctx.logger?.log("calling wait_for_run_to_complete", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 
@@ -125,9 +123,8 @@ export const cancelRunTool = {
     ctx.logger?.log("calling cancel_run", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 
@@ -166,9 +163,8 @@ export const listRunsTool = {
     ctx.logger?.log("calling list_runs", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 

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

@@ -12,9 +12,8 @@ export const getCurrentWorker = {
     ctx.logger?.log("calling get_current_worker", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }
 
@@ -92,9 +91,8 @@ export const triggerTaskTool = {
     ctx.logger?.log("calling trigger_task", { input });
 
     if (!ctx.isEnvironmentAllowed(input.environment)) {
-      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
+        `Cannot access ${input.environment} environment. This MCP server is restricted to: ${ctx.getAllowedEnvironments()}`
       );
     }