mcp-wsl-exec

Instructions

Implementation Reference

• src/index.ts:324-395 (registration)

  Complete MCP tool registration for 'execute_command', defining name, description, input schema, annotations, and the handler function that manages execution with safety checks.

  // execute_command tool - potentially destructive
  this.server.tool(
  	{
  		name: 'execute_command',
  		description: 'Execute a command in WSL (use read-only tools when possible)',
  		schema: v.object({
  			command: v.pipe(
  				v.string(),
  				v.description('Command to execute'),
  			),
  			working_dir: v.optional(
  				v.pipe(
  					v.string(),
  					v.description('Working directory'),
  				),
  			),
  			timeout: v.optional(
  				v.pipe(
  					v.number(),
  					v.description('Timeout (ms)'),
  				),
  			),
  		}),
  		annotations: {
  			readOnlyHint: false,
  			destructiveHint: true,
  		},
  	},
  	async ({ command, working_dir, timeout }) => {
  		try {
  			const result = await this.execute_wsl_command(
  				command,
  				working_dir,
  				timeout,
  			);
  
  			if (result.requires_confirmation) {
  				return {
  					content: [
  						{
  							type: 'text' as const,
  							text: result.stderr,
  						},
  					],
  				};
  			}
  
  			return {
  				content: [
  					{
  						type: 'text' as const,
  						text: this.format_output(result),
  					},
  				],
  			};
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: 'text' as const,
  						text: `Error executing command: ${
  							error instanceof Error
  								? error.message
  								: String(error)
  						}`,
  					},
  				],
  				isError: true,
  			};
  		}
  	},
  );

• src/command-executor.ts:60-119 (handler)

  Low-level handler in CommandExecutor class that performs the actual command execution: sanitizes inputs, spawns WSL process, captures output, handles timeout and errors.

  public async execute_command(
  	command: string,
  	working_dir?: string,
  	timeout?: number,
  ): Promise<CommandResponse> {
  	return new Promise((resolve, reject) => {
  		const sanitized_command = this.sanitize_command(command);
  		const validated_dir = this.validate_working_dir(working_dir);
  		const validated_timeout = this.validate_timeout(timeout);
  
  		const cd_command = validated_dir ? `cd "${validated_dir}" && ` : '';
  		const full_command = `${cd_command}${sanitized_command}`;
  
  		const wsl_process = spawn(wsl_config.executable, [
  			'--exec',
  			wsl_config.shell,
  			'-c',
  			full_command,
  		]);
  
  		let stdout = '';
  		let stderr = '';
  
  		wsl_process.stdout.on('data', (data) => {
  			stdout += data.toString();
  		});
  
  		wsl_process.stderr.on('data', (data) => {
  			stderr += data.toString();
  		});
  
  		let timeout_id: NodeJS.Timeout | undefined;
  		if (validated_timeout) {
  			timeout_id = setTimeout(() => {
  				wsl_process.kill();
  				reject(new CommandTimeoutError(validated_timeout));
  			}, validated_timeout);
  		}
  
  		wsl_process.on('close', (code) => {
  			if (timeout_id) {
  				clearTimeout(timeout_id);
  			}
  			resolve({
  				stdout,
  				stderr,
  				exit_code: code,
  				command: sanitized_command,
  				working_dir: validated_dir,
  			});
  		});
  
  		wsl_process.on('error', (error) => {
  			if (timeout_id) {
  				clearTimeout(timeout_id);
  			}
  			reject(error);
  		});
  	});
  }

• src/types.ts:1-8 (schema)

  Type definition for CommandResponse, used as the return type for command execution results.

  export interface CommandResponse {
  	stdout: string;
  	stderr: string;
  	exit_code: number | null;
  	command: string;
  	requires_confirmation?: boolean;
  	error?: string;
  	working_dir?: string;

• src/command-executor.ts:52-58 (helper)

  Helper method to detect potentially dangerous commands requiring confirmation.

  public is_dangerous_command(command: string): boolean {
  	return dangerous_commands.some(
  		(dangerous) =>
  			command.toLowerCase().includes(dangerous.toLowerCase()) ||
  			command.match(new RegExp(`\\b${dangerous}\\b`, 'i')),
  	);
  }

• src/index.ts:329-346 (schema)

  Valibot input schema defining parameters for the execute_command tool.

  schema: v.object({
  	command: v.pipe(
  		v.string(),
  		v.description('Command to execute'),
  	),
  	working_dir: v.optional(
  		v.pipe(
  			v.string(),
  			v.description('Working directory'),
  		),
  	),
  	timeout: v.optional(
  		v.pipe(
  			v.number(),
  			v.description('Timeout (ms)'),
  		),
  	),
  }),