@alexsarrell/jenkins-mcp-server 1.0.1 → 1.3.0

package/dist/tools/jobs.js

@@ -1,5 +1,40 @@
 import { z } from "zod";
 import { formatJobList, formatJobDetail, ok, error, truncateText } from "../utils/formatters.js";
+import { mapJenkinsParameter } from "../utils/parameter-mapper.js";
+import { parseJobConfig, buildJobXml } from "../utils/job-xml.js";
+import { diffJobSpecs } from "../utils/job-diff.js";
+import { parameterSpec } from "../schemas/parameter.js";
+const pipelineSpecSchema = z.object({
+    type: z.literal("pipeline"),
+    description: z.string().optional(),
+    disabled: z.boolean().optional(),
+    scm: z.object({
+        type: z.literal("git"),
+        url: z.string(),
+        branches: z.array(z.string()).optional(),
+        credentialsId: z.string().optional(),
+        jenkinsfilePath: z.string().optional(),
+    }),
+    triggers: z.object({ cron: z.string().optional() }).optional(),
+    parameters: z.array(parameterSpec).optional(),
+    buildRetention: z.object({ numToKeep: z.number().optional(), daysToKeep: z.number().optional() }).optional(),
+});
+const multibranchSpecSchema = z.object({
+    type: z.literal("multibranch"),
+    description: z.string().optional(),
+    source: z.object({
+        type: z.literal("git"),
+        url: z.string(),
+        credentialsId: z.string().optional(),
+    }),
+    jenkinsfilePath: z.string().optional(),
+    orphanedItemStrategy: z.object({ numToKeep: z.number().optional(), daysToKeep: z.number().optional() }).optional(),
+});
+const folderSpecSchema = z.object({
+    type: z.literal("folder"),
+    description: z.string().optional(),
+});
+const jobSpecSchema = z.discriminatedUnion("type", [pipelineSpecSchema, multibranchSpecSchema, folderSpecSchema]);
 export function registerJobTools(client, register, allowUnsafe) {
     // 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({
@@ -52,6 +87,73 @@ export function registerJobTools(client, register, allowUnsafe) {
             return handleError(e);
         }
     });
+    // 3b. getJobParameters
+    register("getJobParameters", "Get the structured parameter schema for a Jenkins job. Returns each parameter's type (string/choice/boolean/password/file/run/credentials/unknown), default, choices, and description as JSON. Use this instead of getJob when you need to know what to pass to triggerBuild.", z.object({
+        jobPath: z.string().describe("Full job path"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        try {
+            const tree = "property[parameterDefinitions[name,type,description,defaultParameterValue[value],choices,projectName,credentialType,_class]]";
+            const data = await client.get(jobPath, "/api/json", { tree });
+            const job = data;
+            const defs = (job.property ?? []).flatMap((p) => p.parameterDefinitions ?? []);
+            const parameters = defs.map(mapJenkinsParameter);
+            return ok(JSON.stringify({ parameters }, null, 2));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 3c. describeJob
+    register("describeJob", "Get a structured view of a job's config (SCM url/branch, Jenkinsfile path, parameters, retention, cron) without parsing raw XML. Reports unrecognised XML elements via 'unknownXmlElements'. Read-only and safe.", z.object({
+        jobPath: z.string().describe("Full job path"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        try {
+            const xml = await client.getRaw(jobPath, "/config.xml");
+            const desc = parseJobConfig(xml);
+            return ok(JSON.stringify(desc, null, 2));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 3d. previewJobConfig
+    register("previewJobConfig", "Generate Jenkins job XML config from a structured spec. Optionally diff against an existing job's current config (read-only — does not modify Jenkins). Use the resulting XML with updateJobConfig (gated by JENKINS_ALLOW_UNSAFE_OPERATIONS) once it looks right.", z.object({
+        spec: jobSpecSchema,
+        diffAgainstJobPath: z.string().optional().describe("If set, fetch the current config of this job and emit a structured diff."),
+    }), async (args) => {
+        const spec = args.spec;
+        const diffPath = args.diffAgainstJobPath;
+        try {
+            const xml = buildJobXml(spec);
+            const out = [`=== Generated config.xml (${spec.type}) ===`, xml];
+            if (diffPath) {
+                const currentXml = await client.getRaw(diffPath, "/config.xml");
+                const before = parseJobConfig(currentXml);
+                const after = parseJobConfig(xml);
+                const changes = diffJobSpecs(before, after);
+                out.push(`\n=== Diff against ${diffPath} ===`);
+                if (changes.length === 0) {
+                    out.push("(no structural changes)");
+                }
+                else {
+                    for (const c of changes) {
+                        out.push(`@@ ${c.path} @@`);
+                        out.push(`- ${c.before}`);
+                        out.push(`+ ${c.after}`);
+                    }
+                }
+                if (before.unknownXmlElements.length > 0) {
+                    out.push(`\n(skipped: ${before.unknownXmlElements.join(", ")})`);
+                }
+            }
+            return ok(out.join("\n"));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
     // 4. updateJobConfig (unsafe — requires JENKINS_ALLOW_UNSAFE_OPERATIONS=true)
     if (allowUnsafe) {
         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({

package/dist/types.d.ts

@@ -60,6 +60,11 @@ export interface JenkinsBuild {
             shortDescription: string;
             userName?: string;
         }>;
+        parameters?: Array<{
+            _class?: string;
+            name: string;
+            value?: string | boolean | number;
+        }>;
     }>;
     artifacts?: BuildArtifact[];
     changeSets?: Array<{
@@ -128,6 +133,21 @@ export interface QueueItem {
     stuck: boolean;
     blocked: boolean;
 }
+export interface QueueItemDetail {
+    id: number;
+    task: {
+        name: string;
+        url: string;
+    };
+    why: string | null;
+    cancelled?: boolean;
+    executable?: {
+        number: number;
+        url: string;
+    };
+    _class?: string;
+}
+export type QueueItemState = "WAITING" | "BLOCKED" | "BUILDABLE" | "LEFT_QUEUE" | "CANCELLED" | "UNKNOWN";
 export interface JenkinsError {
     statusCode: number;
     message: string;

package/dist/utils/build-payload.d.ts

@@ -0,0 +1,10 @@
+export interface JsonParameter {
+    name: string;
+    value: string | string[];
+}
+export interface TriggerPayload {
+    formData: URLSearchParams;
+    jsonParameters: JsonParameter[];
+}
+export type ParameterValue = string | string[];
+export declare function buildTriggerPayload(parameters: Record<string, ParameterValue>, splitOnComma: boolean): TriggerPayload;

package/dist/utils/build-payload.js

@@ -0,0 +1,19 @@
+export function buildTriggerPayload(parameters, splitOnComma) {
+    const formData = new URLSearchParams();
+    const jsonParameters = [];
+    for (const [name, raw] of Object.entries(parameters)) {
+        const values = Array.isArray(raw)
+            ? raw
+            : splitOnComma && raw.includes(",")
+                ? raw.split(",").map((v) => v.trim())
+                : [raw];
+        for (const v of values) {
+            formData.append(name, v);
+        }
+        jsonParameters.push({
+            name,
+            value: values.length === 1 ? values[0] : values,
+        });
+    }
+    return { formData, jsonParameters };
+}

package/dist/utils/formatters.d.ts

@@ -1,4 +1,4 @@
-import type { JenkinsJob, JenkinsBuild, PipelineStage, QueueItem, ToolResult } from "../types.js";
+import type { JenkinsJob, JenkinsBuild, PipelineStage, QueueItem, QueueItemDetail, 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;
@@ -10,3 +10,4 @@ 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;
+export declare function formatQueueItem(item: QueueItemDetail): string;

package/dist/utils/formatters.js

@@ -116,6 +116,17 @@ export function formatBuild(build) {
     if (causes && causes.length > 0) {
         lines.push(`Triggered by: ${causes.join(", ")}`);
     }
+    // Parameters
+    const parametersAction = build.actions?.find((a) => a.parameters && a.parameters.length > 0);
+    if (parametersAction?.parameters) {
+        lines.push(`\nParameters (${parametersAction.parameters.length}):`);
+        for (const p of parametersAction.parameters) {
+            // Loose substring match — covers PasswordParameterValue and most plugin variants.
+            const isPassword = (p._class || "").toLowerCase().includes("password");
+            const display = isPassword ? "[hidden]" : String(p.value ?? "");
+            lines.push(`  ${p.name} = ${display}`);
+        }
+    }
     // Artifacts
     if (build.artifacts && build.artifacts.length > 0) {
         lines.push(`\nArtifacts (${build.artifacts.length}):`);
@@ -164,3 +175,32 @@ export function error(message, suggestion) {
         text += `\nSuggestion: ${suggestion}`;
     return { content: [{ type: "text", text }], isError: true };
 }
+function classifyQueueItem(item) {
+    if (item.cancelled)
+        return "CANCELLED";
+    const cls = item._class || "";
+    if (cls.endsWith("$WaitingItem"))
+        return "WAITING";
+    if (cls.endsWith("$BlockedItem"))
+        return "BLOCKED";
+    if (cls.endsWith("$BuildableItem"))
+        return "BUILDABLE";
+    if (cls.endsWith("$LeftItem"))
+        return "LEFT_QUEUE";
+    if (cls.endsWith("$CancelledItem"))
+        return "CANCELLED";
+    return "UNKNOWN";
+}
+export function formatQueueItem(item) {
+    const state = classifyQueueItem(item);
+    const lines = [`Queue item #${item.id}: ${state}`];
+    lines.push(`Task: ${item.task.name}`);
+    if (state === "LEFT_QUEUE" && item.executable) {
+        lines.push(`Build started: ${item.task.name} #${item.executable.number}`);
+        lines.push(`URL: ${item.executable.url}`);
+    }
+    else if (item.why) {
+        lines.push(`Why: ${item.why}`);
+    }
+    return lines.join("\n");
+}

package/dist/utils/job-diff.d.ts

@@ -0,0 +1,7 @@
+import type { JobDescription } from "./job-xml.js";
+export interface FieldChange {
+    path: string;
+    before: string;
+    after: string;
+}
+export declare function diffJobSpecs(before: JobDescription, after: JobDescription): FieldChange[];

package/dist/utils/job-diff.js

@@ -0,0 +1,29 @@
+function flatten(obj, prefix) {
+    if (obj === null || obj === undefined)
+        return { [prefix]: "(unset)" };
+    if (typeof obj !== "object")
+        return { [prefix]: String(obj) };
+    if (Array.isArray(obj))
+        return { [prefix]: JSON.stringify(obj) };
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        const next = prefix ? `${prefix}.${k}` : k;
+        Object.assign(out, flatten(v, next));
+    }
+    return out;
+}
+export function diffJobSpecs(before, after) {
+    const a = flatten(before, "");
+    const b = flatten(after, "");
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    const changes = [];
+    for (const k of keys) {
+        if (k === "rawConfigSha" || k.startsWith("unknownXmlElements"))
+            continue;
+        const left = a[k] ?? "(unset)";
+        const right = b[k] ?? "(unset)";
+        if (left !== right)
+            changes.push({ path: k, before: left, after: right });
+    }
+    return changes.sort((x, y) => x.path.localeCompare(y.path));
+}

package/dist/utils/job-xml.d.ts

@@ -0,0 +1,66 @@
+import type { ParameterSpec } from "../schemas/parameter.js";
+export interface PipelineSpec {
+    type: "pipeline";
+    description?: string;
+    disabled?: boolean;
+    scm: {
+        type: "git";
+        url: string;
+        branches?: string[];
+        credentialsId?: string;
+        jenkinsfilePath?: string;
+    };
+    triggers?: {
+        cron?: string;
+    };
+    parameters?: ParameterSpec[];
+    buildRetention?: {
+        numToKeep?: number;
+        daysToKeep?: number;
+    };
+}
+export interface MultibranchSpec {
+    type: "multibranch";
+    description?: string;
+    source: {
+        type: "git";
+        url: string;
+        credentialsId?: string;
+    };
+    jenkinsfilePath?: string;
+    orphanedItemStrategy?: {
+        numToKeep?: number;
+        daysToKeep?: number;
+    };
+}
+export interface FolderSpec {
+    type: "folder";
+    description?: string;
+}
+export type JobSpec = PipelineSpec | MultibranchSpec | FolderSpec;
+export interface JobDescription {
+    type: "pipeline" | "multibranch" | "freestyle" | "folder" | "unknown";
+    description?: string;
+    disabled: boolean;
+    concurrentBuilds: boolean;
+    scm?: {
+        type: "git" | "unknown";
+        url?: string;
+        branches?: string[];
+        credentialsId?: string;
+        jenkinsfilePath?: string;
+    };
+    triggers?: {
+        cron?: string;
+        scmPolling?: string;
+    };
+    parameters?: ParameterSpec[];
+    buildRetention?: {
+        numToKeep?: number;
+        daysToKeep?: number;
+    };
+    unknownXmlElements: string[];
+    rawConfigSha: string;
+}
+export declare function parseJobConfig(xml: string): JobDescription;
+export declare function buildJobXml(spec: JobSpec): string;