@alexsarrell/jenkins-mcp-server 1.0.0

package/dist/tools/discovery.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { formatQueue, ok, error } from "../utils/formatters.js";
+export function registerDiscoveryTools(client, register) {
+    // 16. searchBuildLogs
+    register("searchBuildLogs", "Search build logs for a text pattern across recent builds. Like grep for Jenkins logs. Searches the last N builds (default: 5) and returns matching lines with context.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        pattern: z.string().describe("Text pattern to search for (case-insensitive substring match)"),
+        buildNumber: z.number().optional().describe("Search a specific build number only"),
+        lastN: z.number().optional().default(5).describe("Number of recent builds to search (default: 5, max: 20)"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const pattern = args.pattern;
+        const buildNumber = args.buildNumber;
+        const lastN = Math.min(args.lastN || 5, 20);
+        try {
+            const patternLower = pattern.toLowerCase();
+            const results = [];
+            if (buildNumber) {
+                // Search specific build
+                const matches = await searchBuildLog(client, jobPath, buildNumber, patternLower);
+                if (matches.length > 0) {
+                    results.push(`Build #${buildNumber} (${matches.length} matches):`);
+                    results.push(...matches.map((m) => `  L${m.line}: ${m.text}`));
+                }
+            }
+            else {
+                // Get recent builds
+                const data = await client.get(jobPath, "/api/json", {
+                    tree: "builds[number]{0," + lastN + "}",
+                });
+                const jobData = data;
+                const builds = jobData.builds || [];
+                for (const build of builds) {
+                    const matches = await searchBuildLog(client, jobPath, build.number, patternLower);
+                    if (matches.length > 0) {
+                        results.push(`Build #${build.number} (${matches.length} matches):`);
+                        results.push(...matches.slice(0, 20).map((m) => `  L${m.line}: ${m.text}`));
+                        if (matches.length > 20) {
+                            results.push(`  ... and ${matches.length - 20} more matches`);
+                        }
+                        results.push("");
+                    }
+                }
+            }
+            if (results.length === 0) {
+                return ok(`No matches found for "${pattern}" in ${buildNumber ? `build #${buildNumber}` : `last ${lastN} builds`}.`);
+            }
+            return ok(`Search results for "${pattern}":\n\n${results.join("\n")}`);
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 17. getQueue
+    register("getQueue", "View the Jenkins build queue - shows jobs waiting to be built, why they're waiting, and if they're stuck.", z.object({}), async () => {
+        try {
+            const data = await client.getAbsolute("/queue/api/json", {
+                tree: "items[id,task[name,url],why,buildableStartMilliseconds,stuck,blocked]",
+            });
+            const queue = data;
+            return ok(formatQueue(queue.items || []));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 18. enableDisableJob
+    register("enableDisableJob", "Enable or disable a Jenkins job. Disabled jobs cannot be triggered.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        enabled: z.boolean().describe("true to enable, false to disable"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const enabled = args.enabled;
+        try {
+            const action = enabled ? "/enable" : "/disable";
+            await client.post(jobPath, action);
+            return ok(`Job ${jobPath} ${enabled ? "enabled" : "disabled"} successfully.`);
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+}
+async function searchBuildLog(client, jobPath, buildNumber, patternLower) {
+    try {
+        const logText = await client.getRaw(jobPath, `/${buildNumber}/consoleText`);
+        const lines = logText.split("\n");
+        const matches = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].toLowerCase().includes(patternLower)) {
+                matches.push({
+                    line: i + 1,
+                    text: lines[i].substring(0, 200), // Truncate long lines
+                });
+            }
+        }
+        return matches;
+    }
+    catch {
+        return [];
+    }
+}
+function handleError(e) {
+    if (e && typeof e === "object" && "errorCode" in e) {
+        const je = e;
+        return error(`[${je.errorCode}] ${je.message}`);
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return error(msg);
+}

package/dist/tools/jobs.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+import type { JenkinsClient } from "../jenkins-client.js";
+import type { ToolResult } from "../types.js";
+export declare function registerJobTools(client: JenkinsClient, register: (name: string, description: string, schema: z.ZodType, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => void): void;

package/dist/tools/jobs.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { formatJobList, formatJobDetail, ok, error, truncateText } from "../utils/formatters.js";
+export function registerJobTools(client, register) {
+    // 1. getJobs
+    register("getJobs", "List Jenkins jobs at root level or in a specific folder. Returns job names, status, and last build info. For multibranch pipelines, lists branches as sub-jobs.", z.object({
+        folder: z.string().optional().describe("Folder path (e.g., 'my-folder' or 'folder/subfolder'). Omit for root level."),
+        limit: z.number().optional().default(50).describe("Maximum number of jobs to return (default: 50)"),
+    }), async (args) => {
+        const folder = args.folder;
+        const limit = args.limit || 50;
+        try {
+            const tree = "jobs[name,url,color,description,fullName,lastBuild[number,result,timestamp]]";
+            let data;
+            if (folder) {
+                data = await client.get(folder, "/api/json", { tree });
+            }
+            else {
+                data = await client.getAbsolute("/api/json", { tree });
+            }
+            const result = data;
+            const jobs = (result.jobs || []).slice(0, limit);
+            return ok(formatJobList(jobs));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 2. getJob
+    register("getJob", "Get detailed information about a specific Jenkins job including status, health, parameter definitions, and last build info. For multibranch pipelines, also lists branches.", z.object({
+        jobPath: z.string().describe("Full job path (e.g., 'my-folder/my-job' or 'pipeline/main'). For branches with slashes, use :: separator: 'pipeline::feature/branch'"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        try {
+            const tree = "name,fullName,url,color,description,buildable,healthReport[description,score],lastBuild[number,result,timestamp,url],lastSuccessfulBuild[number,url],lastFailedBuild[number,url],property[parameterDefinitions[name,type,description,defaultParameterValue[value]]],jobs[name,color,url,fullName]";
+            const data = await client.get(jobPath, "/api/json", { tree });
+            return ok(formatJobDetail(data));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 3. getJobConfig
+    register("getJobConfig", "Get the XML configuration of a Jenkins job (config.xml). Useful for understanding job setup, viewing pipeline definitions, or preparing edits.", z.object({
+        jobPath: z.string().describe("Full job path (e.g., 'my-folder/my-job')"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        try {
+            const xml = await client.getRaw(jobPath, "/config.xml");
+            return ok(truncateText(xml));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 4. updateJobConfig
+    register("updateJobConfig", "Update a Jenkins job's XML configuration. Send the complete config.xml content. Use getJobConfig first to read the current config, modify it, then submit.", z.object({
+        jobPath: z.string().describe("Full job path (e.g., 'my-folder/my-job')"),
+        configXml: z.string().describe("Complete XML configuration for the job"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const configXml = args.configXml;
+        try {
+            await client.post(jobPath, "/config.xml", configXml, "application/xml");
+            return ok(`Job config updated successfully: ${jobPath}`);
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+}
+function handleError(e) {
+    if (e && typeof e === "object" && "errorCode" in e) {
+        const je = e;
+        return error(`[${je.errorCode}] ${je.message}`);
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return error(msg);
+}

package/dist/tools/pipeline.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+import type { JenkinsClient } from "../jenkins-client.js";
+import type { ToolResult } from "../types.js";
+export declare function registerPipelineTools(client: JenkinsClient, register: (name: string, description: string, schema: z.ZodType, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => void): void;

package/dist/tools/pipeline.js

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import { formatStages, formatDuration, ok, error, truncateText } from "../utils/formatters.js";
+export function registerPipelineTools(client, register) {
+    // 11. getPipelineStages
+    register("getPipelineStages", "Get pipeline stages overview for a build - shows stage names, status, and duration. Works with Pipeline (Workflow) jobs. Useful for understanding which stage failed.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().optional().describe("Build number (default: last build)"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        const num = buildNumber ?? "lastBuild";
+        try {
+            const data = await client.get(jobPath, `/${num}/wfapi/describe`);
+            const run = data;
+            if (!run.stages || run.stages.length === 0) {
+                return ok("No pipeline stages found. This may not be a Pipeline job, or the build hasn't started stages yet.");
+            }
+            return ok(formatStages(run.stages));
+        }
+        catch (e) {
+            return handleError(e, "This endpoint requires a Pipeline (Workflow) job. Classic Freestyle jobs don't have stages.");
+        }
+    });
+    // 12. getStageLog
+    register("getStageLog", "Get the console log for a specific pipeline stage. Provide the stage name as it appears in getPipelineStages output.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().describe("Build number"),
+        stageName: z.string().describe("Stage name (as shown in getPipelineStages)"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        const stageName = args.stageName;
+        try {
+            // First, get the pipeline description to find the stage ID
+            const data = await client.get(jobPath, `/${buildNumber}/wfapi/describe`);
+            const run = data;
+            const stage = run.stages?.find((s) => s.name.toLowerCase() === stageName.toLowerCase());
+            if (!stage) {
+                const available = run.stages?.map((s) => s.name).join(", ") || "none";
+                return error(`Stage "${stageName}" not found.`, `Available stages: ${available}`);
+            }
+            // Get the stage log using the node ID
+            const logData = await client.getRaw(jobPath, `/${buildNumber}/execution/node/${stage.id}/wfapi/log`);
+            // The wfapi/log endpoint returns JSON with a text field
+            let logText;
+            try {
+                const parsed = JSON.parse(logData);
+                logText = parsed.text;
+            }
+            catch {
+                // If it's not JSON, use raw text
+                logText = logData;
+            }
+            // Strip HTML tags that Jenkins sometimes includes
+            logText = logText.replace(/<[^>]*>/g, "");
+            return ok(truncateText(`--- Stage Log: ${stage.name} (${stage.status}, ${formatDuration(stage.durationMillis)}) ---\n\n${logText}`));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 13. getPipelineScript
+    register("getPipelineScript", "Get the Jenkinsfile/pipeline script used in a build. Fetches from the replay page. Useful for reviewing or modifying the script before replaying.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().describe("Build number"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        try {
+            const html = await client.getRaw(jobPath, `/${buildNumber}/replay`);
+            // Parse the main script from the replay page
+            // The replay page has a <textarea> with class "ace-editor" or name "_.mainScript"
+            const mainScriptMatch = html.match(/name="_.mainScript"[^>]*>([\s\S]*?)<\/textarea>/);
+            const scripts = [];
+            if (mainScriptMatch) {
+                // Decode HTML entities
+                const script = decodeHtmlEntities(mainScriptMatch[1]);
+                scripts.push({ name: "Jenkinsfile (main)", content: script });
+            }
+            // Also look for loaded library scripts
+            const scriptBlocks = html.matchAll(/name="_.([^"]+)"[^>]*class="[^"]*jenkins-readonly-crumb[^"]*"[^>]*>([\s\S]*?)<\/textarea>/g);
+            for (const match of scriptBlocks) {
+                if (match[1] !== "mainScript") {
+                    scripts.push({
+                        name: match[1],
+                        content: decodeHtmlEntities(match[2]),
+                    });
+                }
+            }
+            // Try alternative pattern if nothing found
+            if (scripts.length === 0) {
+                // Try finding any textarea with script content
+                const textareaMatches = html.matchAll(/<textarea[^>]*name="([^"]*)"[^>]*>([\s\S]*?)<\/textarea>/g);
+                for (const match of textareaMatches) {
+                    const name = match[1].replace("_.", "");
+                    if (name && match[2].trim()) {
+                        scripts.push({
+                            name,
+                            content: decodeHtmlEntities(match[2]),
+                        });
+                    }
+                }
+            }
+            if (scripts.length === 0) {
+                return error("Could not extract pipeline script from replay page.", "The build may not be a Pipeline job, or replay may not be available.");
+            }
+            const lines = [];
+            for (const s of scripts) {
+                lines.push(`=== ${s.name} ===`);
+                lines.push(s.content);
+                lines.push("");
+            }
+            return ok(truncateText(lines.join("\n")));
+        }
+        catch (e) {
+            return handleError(e, "Replay page may not be available. Ensure the build is a Pipeline job.");
+        }
+    });
+    // 14. replayBuild
+    register("replayBuild", "Replay a pipeline build with optional script modifications. If no script is provided, replays with the same script. Use getPipelineScript first to get the current script, modify it, then replay.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().describe("Build number to replay"),
+        mainScript: z.string().optional().describe("Modified Jenkinsfile content. If omitted, replays with the original script."),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        let mainScript = args.mainScript;
+        try {
+            // If no script provided, fetch current one
+            if (!mainScript) {
+                const html = await client.getRaw(jobPath, `/${buildNumber}/replay`);
+                const match = html.match(/name="_.mainScript"[^>]*>([\s\S]*?)<\/textarea>/);
+                if (match) {
+                    mainScript = decodeHtmlEntities(match[1]);
+                }
+                else {
+                    return error("Could not extract current pipeline script for replay.", "Try providing the script explicitly via the mainScript parameter.");
+                }
+            }
+            // Submit replay
+            const formData = new URLSearchParams();
+            formData.set("mainScript", mainScript);
+            formData.set("json", JSON.stringify({ mainScript }));
+            const result = await client.postForm(jobPath, `/${buildNumber}/replay/run`, formData);
+            // The response redirects to the new build page
+            const location = result.response.headers.get("location");
+            if (location) {
+                return ok(`Replay triggered successfully.\nNew build: ${location}`);
+            }
+            return ok(`Replay triggered for ${jobPath} build #${buildNumber}.`);
+        }
+        catch (e) {
+            return handleError(e, "Replay requires Pipeline job type and appropriate permissions.");
+        }
+    });
+    // 15. restartFromStage
+    register("restartFromStage", "Restart a pipeline from a specific stage. Requires the Declarative Pipeline plugin with 'Restart from Stage' support. Only works with top-level stages in Declarative pipelines and completed builds.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().describe("Build number"),
+        stageName: z.string().describe("Stage name to restart from"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        const stageName = args.stageName;
+        try {
+            // First verify the stage exists
+            const data = await client.get(jobPath, `/${buildNumber}/wfapi/describe`);
+            const run = data;
+            const stage = run.stages?.find((s) => s.name.toLowerCase() === stageName.toLowerCase());
+            if (!stage) {
+                const available = run.stages?.map((s) => s.name).join(", ") || "none";
+                return error(`Stage "${stageName}" not found.`, `Available stages: ${available}`);
+            }
+            // Try the restart endpoint
+            // This uses the Pipeline: Stage Step plugin's restart functionality
+            const formData = new URLSearchParams();
+            formData.set("stageName", stage.name);
+            formData.set("json", JSON.stringify({ stageName: stage.name }));
+            const result = await client.postForm(jobPath, `/${buildNumber}/restart/restart`, formData);
+            const location = result.response.headers.get("location");
+            if (location) {
+                return ok(`Restart from stage "${stage.name}" triggered.\nNew build: ${location}`);
+            }
+            return ok(`Restart from stage "${stage.name}" triggered for ${jobPath} build #${buildNumber}.`);
+        }
+        catch (e) {
+            return handleError(e, "Restart from stage requires: (1) Declarative Pipeline plugin, (2) a completed build, (3) a top-level stage. Not all Jenkins installations support this.");
+        }
+    });
+}
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#x27;/g, "'")
+        .replace(/&#x2F;/g, "/");
+}
+function handleError(e, suggestion) {
+    if (e && typeof e === "object" && "errorCode" in e) {
+        const je = e;
+        return error(`[${je.errorCode}] ${je.message}`, suggestion);
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return error(msg, suggestion);
+}

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+export interface JenkinsConfig {
+    url: string;
+    user: string;
+    token: string;
+}
+export interface JenkinsJob {
+    _class: string;
+    name: string;
+    url: string;
+    color: string;
+    description: string | null;
+    fullName: string;
+    buildable?: boolean;
+    healthReport?: Array<{
+        description: string;
+        score: number;
+    }>;
+    lastBuild?: {
+        number: number;
+        result: string | null;
+        timestamp: number;
+        url: string;
+    };
+    lastSuccessfulBuild?: {
+        number: number;
+        url: string;
+    };
+    lastFailedBuild?: {
+        number: number;
+        url: string;
+    };
+    jobs?: JenkinsJob[];
+    property?: Array<{
+        _class: string;
+        parameterDefinitions?: Array<{
+            name: string;
+            type: string;
+            description: string;
+            defaultParameterValue?: {
+                value: string;
+            };
+        }>;
+    }>;
+}
+export interface JenkinsBuild {
+    _class: string;
+    number: number;
+    url: string;
+    result: string | null;
+    building: boolean;
+    duration: number;
+    estimatedDuration: number;
+    timestamp: number;
+    displayName: string;
+    description: string | null;
+    fullDisplayName: string;
+    actions?: Array<{
+        _class: string;
+        causes?: Array<{
+            shortDescription: string;
+            userName?: string;
+        }>;
+    }>;
+    artifacts?: BuildArtifact[];
+    changeSets?: Array<{
+        items: Array<{
+            msg: string;
+            author: {
+                fullName: string;
+            };
+            commitId: string;
+        }>;
+    }>;
+}
+export interface BuildArtifact {
+    displayPath: string;
+    fileName: string;
+    relativePath: string;
+}
+export interface PipelineStage {
+    id: string;
+    name: string;
+    status: string;
+    startTimeMillis: number;
+    durationMillis: number;
+    pauseDurationMillis: number;
+    stageFlowNodes?: Array<{
+        id: string;
+        name: string;
+        status: {
+            result: string;
+        };
+    }>;
+}
+export interface PipelineRun {
+    id: string;
+    name: string;
+    status: string;
+    startTimeMillis: number;
+    durationMillis: number;
+    stages: PipelineStage[];
+}
+export interface TestResult {
+    failCount: number;
+    passCount: number;
+    skipCount: number;
+    totalCount: number;
+    suites?: Array<{
+        name: string;
+        cases: Array<{
+            className: string;
+            name: string;
+            status: string;
+            duration: number;
+            errorDetails?: string;
+            errorStackTrace?: string;
+        }>;
+    }>;
+}
+export interface QueueItem {
+    id: number;
+    task: {
+        name: string;
+        url: string;
+    };
+    why: string | null;
+    buildableStartMilliseconds: number;
+    stuck: boolean;
+    blocked: boolean;
+}
+export interface JenkinsError {
+    statusCode: number;
+    message: string;
+    errorCode: string;
+}
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/formatters.d.ts

@@ -0,0 +1,12 @@
+import type { JenkinsJob, JenkinsBuild, PipelineStage, QueueItem, ToolResult } from "../types.js";
+export declare function truncateText(text: string, maxBytes?: number): string;
+export declare function formatJobStatus(color: string): string;
+export declare function formatTimestamp(ts: number): string;
+export declare function formatDuration(ms: number): string;
+export declare function formatJobList(jobs: JenkinsJob[]): string;
+export declare function formatJobDetail(job: JenkinsJob): string;
+export declare function formatBuild(build: JenkinsBuild): string;
+export declare function formatStages(stages: PipelineStage[]): string;
+export declare function formatQueue(items: QueueItem[]): string;
+export declare function ok(text: string): ToolResult;
+export declare function error(message: string, suggestion?: string): ToolResult;