@alexsarrell/jenkins-mcp-server 1.0.0 → 1.3.0

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;

package/dist/utils/job-xml.js

@@ -0,0 +1,415 @@
+import { XMLParser, XMLBuilder } from "fast-xml-parser";
+import { createHash } from "node:crypto";
+import { mapJenkinsParameter } from "./parameter-mapper.js";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: true,
+});
+const KNOWN_ROOTS = {
+    "flow-definition": "pipeline",
+    "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject": "multibranch",
+    "com.cloudbees.hudson.plugins.folder.Folder": "folder",
+    project: "freestyle",
+};
+const PIPELINE_KNOWN = new Set(["description", "keepDependencies", "properties", "triggers", "definition", "disabled"]);
+const MULTIBRANCH_KNOWN = new Set(["description", "disabled", "sources", "factory", "orphanedItemStrategy", "properties", "triggers"]);
+const FREESTYLE_KNOWN = new Set(["description", "disabled", "concurrentBuild", "properties", "triggers"]);
+function asArray(v) {
+    if (v === undefined || v === null)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+function asString(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "object" && v !== null && "#text" in v)
+        return String(v["#text"]);
+    return String(v);
+}
+function asBoolean(v, fallback) {
+    const s = asString(v);
+    if (s === "true")
+        return true;
+    if (s === "false")
+        return false;
+    return fallback;
+}
+function asNumber(v) {
+    const s = asString(v);
+    if (s === undefined)
+        return undefined;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : undefined;
+}
+function extractParameters(properties) {
+    if (!properties || typeof properties !== "object")
+        return undefined;
+    const props = properties;
+    const paramProp = props["hudson.model.ParametersDefinitionProperty"];
+    if (!paramProp || typeof paramProp !== "object")
+        return undefined;
+    const defsContainer = paramProp.parameterDefinitions;
+    if (!defsContainer || typeof defsContainer !== "object")
+        return undefined;
+    const defs = [];
+    for (const [tag, raw] of Object.entries(defsContainer)) {
+        for (const item of asArray(raw)) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const obj = item;
+            const name = asString(obj.name);
+            if (!name)
+                continue;
+            const description = asString(obj.description);
+            const def = {
+                _class: tag,
+                name,
+                description,
+                defaultParameterValue: { value: parseDefaultValue(tag, obj.defaultValue) },
+            };
+            if (tag === "hudson.model.ChoiceParameterDefinition") {
+                const choicesNode = obj.choices;
+                const stringList = choicesNode && typeof choicesNode === "object"
+                    ? choicesNode.a
+                    : undefined;
+                const stringEntries = stringList && typeof stringList === "object"
+                    ? asArray(stringList.string).map(asString).filter((s) => typeof s === "string")
+                    : [];
+                def.choices = stringEntries;
+            }
+            defs.push(def);
+        }
+    }
+    return defs.map(mapJenkinsParameter);
+}
+function parseDefaultValue(tag, raw) {
+    if (raw === undefined)
+        return undefined;
+    if (tag === "hudson.model.BooleanParameterDefinition") {
+        const s = asString(raw);
+        return s === "true";
+    }
+    return asString(raw);
+}
+function extractRetention(properties) {
+    if (!properties || typeof properties !== "object")
+        return undefined;
+    const props = properties;
+    const disc = props["jenkins.model.BuildDiscarderProperty"];
+    if (!disc || typeof disc !== "object")
+        return undefined;
+    const strategy = disc.strategy;
+    if (!strategy || typeof strategy !== "object")
+        return undefined;
+    const s = strategy;
+    const out = {};
+    const numToKeep = asNumber(s.numToKeep);
+    const daysToKeep = asNumber(s.daysToKeep);
+    if (numToKeep !== undefined && numToKeep > 0)
+        out.numToKeep = numToKeep;
+    if (daysToKeep !== undefined && daysToKeep > 0)
+        out.daysToKeep = daysToKeep;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function extractCronTrigger(triggers) {
+    if (!triggers || typeof triggers !== "object")
+        return undefined;
+    const t = triggers["hudson.triggers.TimerTrigger"];
+    if (!t || typeof t !== "object")
+        return undefined;
+    return asString(t.spec);
+}
+function parsePipelineScm(definition) {
+    if (!definition || typeof definition !== "object")
+        return undefined;
+    const def = definition;
+    const scm = def.scm;
+    const scriptPath = asString(def.scriptPath);
+    if (!scm || typeof scm !== "object") {
+        return scriptPath ? { type: "unknown", jenkinsfilePath: scriptPath } : undefined;
+    }
+    const scmCls = scm["@_class"];
+    if (scmCls === "hudson.plugins.git.GitSCM") {
+        const remote = scm.userRemoteConfigs;
+        const config = remote ? remote["hudson.plugins.git.UserRemoteConfig"] : undefined;
+        const url = config ? asString(config.url) : undefined;
+        const credentialsId = config ? asString(config.credentialsId) : undefined;
+        const branchesNode = scm.branches;
+        const branches = branchesNode
+            ? asArray(branchesNode["hudson.plugins.git.BranchSpec"]).map((b) => asString(b.name)).filter((b) => !!b)
+            : undefined;
+        const out = { type: "git" };
+        if (url)
+            out.url = url;
+        if (credentialsId)
+            out.credentialsId = credentialsId;
+        if (branches && branches.length > 0)
+            out.branches = branches;
+        if (scriptPath)
+            out.jenkinsfilePath = scriptPath;
+        return out;
+    }
+    return scriptPath ? { type: "unknown", jenkinsfilePath: scriptPath } : { type: "unknown" };
+}
+function parseMultibranchScm(sources, factory) {
+    const factoryScript = factory && typeof factory === "object"
+        ? asString(factory.scriptPath)
+        : undefined;
+    const data = sources && typeof sources === "object"
+        ? sources.data
+        : undefined;
+    const branchSource = data && typeof data === "object"
+        ? data["jenkins.branch.BranchSource"]
+        : undefined;
+    const source = branchSource ? branchSource.source : undefined;
+    if (!source) {
+        return factoryScript ? { type: "unknown", jenkinsfilePath: factoryScript } : undefined;
+    }
+    const sourceCls = source["@_class"];
+    const out = { type: sourceCls === "jenkins.plugins.git.GitSCMSource" ? "git" : "unknown" };
+    const url = asString(source.remote);
+    const credentialsId = asString(source.credentialsId);
+    if (url)
+        out.url = url;
+    if (credentialsId)
+        out.credentialsId = credentialsId;
+    if (factoryScript)
+        out.jenkinsfilePath = factoryScript;
+    return out;
+}
+function listUnknownChildren(node, known) {
+    return Object.keys(node).filter((k) => !k.startsWith("@_") && k !== "?xml" && !known.has(k));
+}
+export function parseJobConfig(xml) {
+    const sha = createHash("sha256").update(xml).digest("hex").slice(0, 12);
+    const tree = parser.parse(xml);
+    const rootEntry = Object.entries(tree).find(([k]) => k !== "?xml");
+    const rootName = rootEntry?.[0] ?? "";
+    const rootNode = rootEntry?.[1] ?? {};
+    const type = KNOWN_ROOTS[rootName] ?? "unknown";
+    if (type === "unknown") {
+        return { type, disabled: false, concurrentBuilds: false, unknownXmlElements: [rootName], rawConfigSha: sha };
+    }
+    const description = asString(rootNode.description);
+    const disabled = asBoolean(rootNode.disabled, false);
+    const concurrentBuilds = type === "freestyle" ? asBoolean(rootNode.concurrentBuild, false) : false;
+    const properties = rootNode.properties;
+    const parameters = extractParameters(properties);
+    const buildRetention = extractRetention(properties);
+    const cron = extractCronTrigger(rootNode.triggers);
+    let scm;
+    let unknownChildren;
+    if (type === "pipeline") {
+        scm = parsePipelineScm(rootNode.definition);
+        unknownChildren = listUnknownChildren(rootNode, PIPELINE_KNOWN);
+    }
+    else if (type === "multibranch") {
+        scm = parseMultibranchScm(rootNode.sources, rootNode.factory);
+        unknownChildren = listUnknownChildren(rootNode, MULTIBRANCH_KNOWN);
+    }
+    else if (type === "freestyle") {
+        unknownChildren = listUnknownChildren(rootNode, FREESTYLE_KNOWN);
+    }
+    else {
+        unknownChildren = [];
+    }
+    const out = {
+        type,
+        disabled,
+        concurrentBuilds,
+        unknownXmlElements: unknownChildren,
+        rawConfigSha: sha,
+    };
+    if (description)
+        out.description = description;
+    if (scm)
+        out.scm = scm;
+    if (cron)
+        out.triggers = { cron };
+    if (parameters && parameters.length > 0)
+        out.parameters = parameters;
+    if (buildRetention)
+        out.buildRetention = buildRetention;
+    return out;
+}
+// ─── buildJobXml ─────────────────────────────────────────────────────────────
+const builder = new XMLBuilder({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    format: true,
+    indentBy: "  ",
+    suppressEmptyNode: false,
+});
+function paramDefXml(p) {
+    if (p.type === "string") {
+        return {
+            tag: "hudson.model.StringParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", defaultValue: p.default ?? "", trim: p.trim ?? false },
+        };
+    }
+    if (p.type === "text") {
+        return {
+            tag: "hudson.model.TextParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", defaultValue: p.default ?? "" },
+        };
+    }
+    if (p.type === "boolean") {
+        return {
+            tag: "hudson.model.BooleanParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", defaultValue: String(p.default ?? false) },
+        };
+    }
+    if (p.type === "choice") {
+        return {
+            tag: "hudson.model.ChoiceParameterDefinition",
+            body: {
+                name: p.name,
+                description: p.description ?? "",
+                choices: { "@_class": "java.util.Arrays$ArrayList", a: { "@_class": "string-array", string: p.choices } },
+            },
+        };
+    }
+    if (p.type === "password") {
+        return {
+            tag: "hudson.model.PasswordParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", defaultValue: "" },
+        };
+    }
+    if (p.type === "file") {
+        return { tag: "hudson.model.FileParameterDefinition", body: { name: p.name, description: p.description ?? "" } };
+    }
+    if (p.type === "run") {
+        return {
+            tag: "hudson.model.RunParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", projectName: p.projectName ?? "" },
+        };
+    }
+    if (p.type === "credentials") {
+        return {
+            tag: "com.cloudbees.plugins.credentials.CredentialsParameterDefinition",
+            body: { name: p.name, description: p.description ?? "", credentialType: p.credentialType ?? "" },
+        };
+    }
+    // unknown — emit as a string parameter with a marker description
+    return {
+        tag: "hudson.model.StringParameterDefinition",
+        body: { name: p.name, description: `[UNKNOWN ORIGINAL TYPE: ${p.rawType}] ${p.description ?? ""}`, defaultValue: "" },
+    };
+}
+function buildPipelineRoot(spec) {
+    const properties = {};
+    if (spec.parameters && spec.parameters.length > 0) {
+        const grouped = {};
+        for (const p of spec.parameters) {
+            const { tag, body } = paramDefXml(p);
+            (grouped[tag] ??= []).push(body);
+        }
+        properties["hudson.model.ParametersDefinitionProperty"] = { parameterDefinitions: grouped };
+    }
+    if (spec.buildRetention) {
+        properties["jenkins.model.BuildDiscarderProperty"] = {
+            strategy: {
+                "@_class": "hudson.tasks.LogRotator",
+                daysToKeep: String(spec.buildRetention.daysToKeep ?? -1),
+                numToKeep: String(spec.buildRetention.numToKeep ?? -1),
+                artifactDaysToKeep: "-1",
+                artifactNumToKeep: "-1",
+            },
+        };
+    }
+    const triggers = {};
+    if (spec.triggers?.cron) {
+        triggers["hudson.triggers.TimerTrigger"] = { spec: spec.triggers.cron };
+    }
+    const definition = {
+        "@_class": "org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition",
+        "@_plugin": "workflow-cps",
+        scm: {
+            "@_class": "hudson.plugins.git.GitSCM",
+            "@_plugin": "git",
+            userRemoteConfigs: {
+                "hudson.plugins.git.UserRemoteConfig": {
+                    url: spec.scm.url,
+                    ...(spec.scm.credentialsId ? { credentialsId: spec.scm.credentialsId } : {}),
+                },
+            },
+            branches: {
+                "hudson.plugins.git.BranchSpec": (spec.scm.branches ?? ["*/main"]).map((name) => ({ name })),
+            },
+        },
+        scriptPath: spec.scm.jenkinsfilePath ?? "Jenkinsfile",
+        lightweight: "true",
+    };
+    return {
+        "flow-definition": {
+            "@_plugin": "workflow-job",
+            description: spec.description ?? "",
+            keepDependencies: "false",
+            ...(Object.keys(properties).length > 0 ? { properties } : { properties: "" }),
+            ...(Object.keys(triggers).length > 0 ? { triggers } : {}),
+            definition,
+            disabled: String(spec.disabled ?? false),
+        },
+    };
+}
+function buildMultibranchRoot(spec) {
+    return {
+        "org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject": {
+            "@_plugin": "workflow-multibranch",
+            description: spec.description ?? "",
+            disabled: "false",
+            sources: {
+                "@_class": "jenkins.branch.MultiBranchProject$BranchSourceList",
+                data: {
+                    "jenkins.branch.BranchSource": {
+                        source: {
+                            "@_class": "jenkins.plugins.git.GitSCMSource",
+                            "@_plugin": "git",
+                            id: "1",
+                            remote: spec.source.url,
+                            ...(spec.source.credentialsId ? { credentialsId: spec.source.credentialsId } : {}),
+                        },
+                    },
+                },
+            },
+            factory: {
+                "@_class": "org.jenkinsci.plugins.workflow.multibranch.WorkflowBranchProjectFactory",
+                scriptPath: spec.jenkinsfilePath ?? "Jenkinsfile",
+            },
+            ...(spec.orphanedItemStrategy
+                ? {
+                    orphanedItemStrategy: {
+                        "@_class": "com.cloudbees.hudson.plugins.folder.computed.DefaultOrphanedItemStrategy",
+                        pruneDeadBranches: "true",
+                        daysToKeep: String(spec.orphanedItemStrategy.daysToKeep ?? -1),
+                        numToKeep: String(spec.orphanedItemStrategy.numToKeep ?? -1),
+                    },
+                }
+                : {}),
+        },
+    };
+}
+function buildFolderRoot(spec) {
+    return {
+        "com.cloudbees.hudson.plugins.folder.Folder": {
+            "@_plugin": "cloudbees-folder",
+            description: spec.description ?? "",
+        },
+    };
+}
+export function buildJobXml(spec) {
+    let body;
+    if (spec.type === "pipeline")
+        body = buildPipelineRoot(spec);
+    else if (spec.type === "multibranch")
+        body = buildMultibranchRoot(spec);
+    else
+        body = buildFolderRoot(spec);
+    const xml = builder.build(body);
+    return `<?xml version='1.1' encoding='UTF-8'?>\n${xml}`;
+}

package/dist/utils/log-grep.d.ts

@@ -0,0 +1,20 @@
+export interface GrepOptions {
+    pattern: string;
+    regex?: boolean;
+    before?: number;
+    after?: number;
+    maxMatches?: number;
+}
+export interface GrepMatch {
+    lineNumber: number;
+    text: string;
+    context: Array<{
+        lineNumber: number;
+        text: string;
+    }>;
+}
+export interface GrepResult {
+    matches: GrepMatch[];
+    truncated: boolean;
+}
+export declare function grepLog(text: string, opts: GrepOptions): GrepResult;

package/dist/utils/log-grep.js

@@ -0,0 +1,43 @@
+function buildMatcher(pattern, regex) {
+    if (regex) {
+        let re;
+        try {
+            re = new RegExp(pattern);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Invalid regex: ${msg}`);
+        }
+        return (s) => re.test(s);
+    }
+    const lower = pattern.toLowerCase();
+    return (s) => s.toLowerCase().includes(lower);
+}
+export function grepLog(text, opts) {
+    const before = opts.before ?? 0;
+    const after = opts.after ?? 0;
+    const maxMatches = opts.maxMatches ?? 50;
+    const matches = [];
+    const lines = text.split("\n");
+    const matcher = buildMatcher(opts.pattern, opts.regex ?? false);
+    for (let i = 0; i < lines.length; i++) {
+        if (!matcher(lines[i]))
+            continue;
+        const ctxStart = Math.max(0, i - before);
+        const ctxEnd = Math.min(lines.length - 1, i + after);
+        const context = [];
+        for (let j = ctxStart; j <= ctxEnd; j++) {
+            context.push({ lineNumber: j + 1, text: lines[j] });
+        }
+        matches.push({ lineNumber: i + 1, text: lines[i], context });
+        if (matches.length >= maxMatches) {
+            // Check if there are any further matches; if so, signal truncation.
+            for (let k = i + 1; k < lines.length; k++) {
+                if (matcher(lines[k]))
+                    return { matches, truncated: true };
+            }
+            return { matches, truncated: false };
+        }
+    }
+    return { matches, truncated: false };
+}

package/dist/utils/parameter-mapper.d.ts

@@ -0,0 +1,13 @@
+import type { ParameterSpec } from "../schemas/parameter.js";
+export interface JenkinsParameterDefinition {
+    _class?: string;
+    name: string;
+    description?: string;
+    defaultParameterValue?: {
+        value?: string | boolean | number;
+    };
+    choices?: string[];
+    projectName?: string;
+    credentialType?: string;
+}
+export declare function mapJenkinsParameter(p: JenkinsParameterDefinition): ParameterSpec;

package/dist/utils/parameter-mapper.js

@@ -0,0 +1,70 @@
+export function mapJenkinsParameter(p) {
+    const cls = p._class || "";
+    const last = cls.split(".").pop() || "";
+    const desc = p.description || undefined;
+    const rawDefault = p.defaultParameterValue?.value;
+    if (last === "StringParameterDefinition") {
+        const out = { type: "string", name: p.name };
+        if (typeof rawDefault === "string" && rawDefault !== "")
+            out.default = rawDefault;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "TextParameterDefinition") {
+        const out = { type: "text", name: p.name };
+        if (typeof rawDefault === "string" && rawDefault !== "")
+            out.default = rawDefault;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "BooleanParameterDefinition") {
+        const out = { type: "boolean", name: p.name };
+        if (typeof rawDefault === "boolean")
+            out.default = rawDefault;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "ChoiceParameterDefinition" && p.choices && p.choices.length > 0) {
+        const out = { type: "choice", name: p.name, choices: p.choices };
+        if (typeof rawDefault === "string")
+            out.default = rawDefault;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "PasswordParameterDefinition") {
+        const out = { type: "password", name: p.name };
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "FileParameterDefinition") {
+        const out = { type: "file", name: p.name };
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "RunParameterDefinition") {
+        const out = { type: "run", name: p.name };
+        if (p.projectName)
+            out.projectName = p.projectName;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    if (last === "CredentialsParameterDefinition") {
+        const out = { type: "credentials", name: p.name };
+        if (p.credentialType)
+            out.credentialType = p.credentialType;
+        if (desc)
+            out.description = desc;
+        return out;
+    }
+    const fallback = { type: "unknown", name: p.name, rawType: cls };
+    if (desc)
+        fallback.description = desc;
+    return fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexsarrell/jenkins-mcp-server",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Jenkins MCP server for Claude Code integration",
   "main": "dist/index.js",
   "bin": {
@@ -8,8 +8,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
     "dev": "tsc --watch",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "type": "module",
   "files": [
@@ -23,10 +27,16 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "fast-xml-parser": "^4.5.6",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@eslint/js": "9.28.0",
     "@types/node": "^25.5.0",
-    "typescript": "^5.9.3"
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "9.28.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "8.57.2",
+    "vitest": "^3.2.4"
   }
 }