scheduleBuild

Instructions

Implementation Reference

• src/tools/build-management.js:99-168 (handler)

  The core handler function for the 'scheduleBuild' tool. It validates inputs, parses the schedule time, handles file and string parameters, constructs a FormData object, and schedules the build on Jenkins using a delay parameter in the API call.

  export async function scheduleBuild(client, args) {
  	const { jobFullName, parameters = {}, scheduleTime } = args;
  	if (!jobFullName)
  		return failure("scheduleBuild", "jobFullName is required");
  	if (!scheduleTime)
  		return failure("scheduleBuild", "scheduleTime is required");
  	const allowAbsolute = process.env.ALLOW_ABSOLUTE_FILE_PARAMS === "1";
  
  	let scheduledDate;
  	try {
  		scheduledDate = parseScheduleTime(scheduleTime);
  	} catch (e) {
  		return failure("scheduleBuild", e.message);
  	}
  	const now = new Date();
  	const delayInSeconds = Math.max(
  		0,
  		Math.floor((scheduledDate - now) / 1000)
  	);
  	const jobPath = encodeURIComponent(jobFullName).replace(/%2F/g, "/");
  
  	const form = new FormData();
  	for (const [key, value] of Object.entries(parameters)) {
  		if (typeof value === "string") {
  			const potentialPath = value;
  			const isAbsolute = path.isAbsolute(potentialPath);
  			const withinCwd =
  				!isAbsolute || potentialPath.startsWith(process.cwd());
  			const exists =
  				withinCwd &&
  				fs.existsSync(potentialPath) &&
  				fs.statSync(potentialPath).isFile();
  			if (exists && (!isAbsolute || allowAbsolute)) {
  				form.append(
  					key,
  					fs.createReadStream(potentialPath),
  					path.basename(potentialPath)
  				);
  				continue;
  			} else if (isAbsolute && !allowAbsolute && exists) {
  				return failure(
  					"scheduleBuild",
  					`Absolute file paths are not allowed: ${potentialPath}`
  				);
  			}
  		}
  		form.append(key, String(value));
  	}
  
  	try {
  		const res = await client.post(
  			`${client.baseUrl}/job/${jobPath}/buildWithParameters?delay=${delayInSeconds}sec`,
  			form,
  			{ headers: form.getHeaders(), maxBodyLength: Infinity }
  		);
  		if (res.status >= 200 && res.status < 300) {
  			return success("scheduleBuild", {
  				status: res.status,
  				queueUrl: res.headers.location,
  			});
  		}
  		return failure(
  			"scheduleBuild",
  			`Schedule returned status ${res.status}`,
  			{ statusCode: res.status }
  		);
  	} catch (error) {
  		return formatError(error, "scheduleBuild");
  	}
  }

• src/tools/index.js:72-101 (registration)

  The registration of the 'scheduleBuild' tool in the central toolRegistry object, including its name, description, input schema for validation, and reference to the handler function. This object is used by getAllTools() for MCP server registration.

  scheduleBuild: {
  	name: "scheduleBuild",
  	description:
  		"Schedule a Jenkins build with file and regular parameters to run at a specific time",
  	inputSchema: {
  		type: "object",
  		properties: {
  			jobFullName: {
  				type: "string",
  				description: 'Jenkins job name (e.g., "PlaywrightBDD")',
  			},
  			scheduleTime: {
  				type: "string",
  				description:
  					"When to run the build (e.g., 'in 5 minutes', 'at 3:30 PM', '2024-12-20 15:30')",
  			},
  			parameters: {
  				type: "object",
  				description: "Build parameters including file paths",
  				additionalProperties: true,
  			},
  			description: {
  				type: "string",
  				description: "Optional description for the scheduled build",
  			},
  		},
  		required: ["jobFullName", "scheduleTime", "parameters"],
  	},
  	handler: scheduleBuild,
  },

• src/tools/index.js:76-99 (schema)

  The inputSchema defining the expected parameters for the 'scheduleBuild' tool, including required fields jobFullName, scheduleTime, parameters, and optional description.

  inputSchema: {
  	type: "object",
  	properties: {
  		jobFullName: {
  			type: "string",
  			description: 'Jenkins job name (e.g., "PlaywrightBDD")',
  		},
  		scheduleTime: {
  			type: "string",
  			description:
  				"When to run the build (e.g., 'in 5 minutes', 'at 3:30 PM', '2024-12-20 15:30')",
  		},
  		parameters: {
  			type: "object",
  			description: "Build parameters including file paths",
  			additionalProperties: true,
  		},
  		description: {
  			type: "string",
  			description: "Optional description for the scheduled build",
  		},
  	},
  	required: ["jobFullName", "scheduleTime", "parameters"],
  },