@alexsarrell/jenkins-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# Jenkins MCP Server
+
+A custom MCP (Model Context Protocol) server for Jenkins integration with Claude Code. Provides 18 tools for comprehensive Jenkins management including pipeline replay, stage-level logs, job configuration editing, and multibranch pipeline support.
+
+## Why?
+
+The official Jenkins MCP plugin has timeout issues (30s timeouts). This standalone server connects directly to Jenkins REST API and works reliably.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "jenkins": {
+      "command": "node",
+      "args": ["/path/to/jenkins-mcp/dist/index.js"],
+      "env": {
+        "JENKINS_URL": "https://your-jenkins.example.com",
+        "JENKINS_USER": "your-username",
+        "JENKINS_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JENKINS_URL` | Yes | Jenkins server URL |
+| `JENKINS_USER` | Yes | Jenkins username |
+| `JENKINS_API_TOKEN` | Yes | Jenkins API token (User > Configure > API Token) |
+
+## Tools (18)
+
+### Job Management
+- **getJobs** — List jobs in a folder with status
+- **getJob** — Job details, parameters, health, branches
+- **getJobConfig** — Get job XML configuration (config.xml)
+- **updateJobConfig** — Update job XML configuration
+
+### Build Operations
+- **triggerBuild** — Trigger builds with optional parameters
+- **getBuild** — Build details (status, duration, changes)
+- **getBuildLog** — Console output with tail/pagination
+- **stopBuild** — Abort a running build
+- **getBuildArtifacts** — List build artifacts
+- **getBuildTestResults** — Test results with failure details
+
+### Pipeline
+- **getPipelineStages** — Stage overview (names, status, duration)
+- **getStageLog** — Log for a specific pipeline stage
+- **getPipelineScript** — Get Jenkinsfile from replay page
+- **replayBuild** — Replay build with optional script changes
+- **restartFromStage** — Restart pipeline from a specific stage
+
+### Discovery
+- **searchBuildLogs** — Search logs across recent builds
+- **getQueue** — View the build queue
+- **enableDisableJob** — Enable or disable a job
+
+## Multibranch Pipelines
+
+Job paths use `/` as separator: `folder/pipeline/branch`
+
+For branches with slashes in the name, use `::` separator:
+```
+my-pipeline::feature/my-branch
+```
+
+## Notes
+
+- **Replay** uses Jenkins' form-based replay endpoint (not a clean REST API)
+- **Restart from Stage** requires the Declarative Pipeline plugin
+- **Config editing** works with raw XML — use getJobConfig to read, modify, then updateJobConfig
+- Build logs are capped at 100KB per response; use pagination for larger logs
+- CSRF crumbs are handled automatically

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { JenkinsClient } from "./jenkins-client.js";
+import { registerJobTools } from "./tools/jobs.js";
+import { registerBuildTools } from "./tools/builds.js";
+import { registerPipelineTools } from "./tools/pipeline.js";
+import { registerDiscoveryTools } from "./tools/discovery.js";
+// Validate environment variables
+const JENKINS_URL = process.env.JENKINS_URL;
+const JENKINS_USER = process.env.JENKINS_USER;
+const JENKINS_API_TOKEN = process.env.JENKINS_API_TOKEN;
+if (!JENKINS_URL || !JENKINS_USER || !JENKINS_API_TOKEN) {
+    console.error("Missing required environment variables. Please set:\n" +
+        "  JENKINS_URL       - Jenkins server URL (e.g., https://jenkins.example.com)\n" +
+        "  JENKINS_USER      - Jenkins username\n" +
+        "  JENKINS_API_TOKEN - Jenkins API token (generate at User > Configure > API Token)");
+    process.exit(1);
+}
+// Create Jenkins client
+const client = new JenkinsClient({
+    url: JENKINS_URL,
+    user: JENKINS_USER,
+    token: JENKINS_API_TOKEN,
+});
+// Create MCP server
+const server = new McpServer({
+    name: "jenkins-mcp-server",
+    version: "1.0.0",
+});
+// Tool registration helper that wraps the McpServer.tool() API
+function register(name, description, schema, handler) {
+    // The MCP SDK expects a ZodRawShape (object with zod fields), not a ZodObject
+    // We need to extract the shape from our z.object() schemas
+    const zodObject = schema;
+    server.tool(name, description, zodObject.shape, async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                content: [{ type: "text", text: `Unexpected error: ${msg}` }],
+                isError: true,
+            };
+        }
+    });
+}
+// Register all tools
+registerJobTools(client, register);
+registerBuildTools(client, register);
+registerPipelineTools(client, register);
+registerDiscoveryTools(client, register);
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Jenkins MCP server started successfully.");
+    console.error(`Connected to: ${JENKINS_URL}`);
+    console.error(`User: ${JENKINS_USER}`);
+}
+main().catch((e) => {
+    console.error("Failed to start Jenkins MCP server:", e);
+    process.exit(1);
+});

package/dist/jenkins-client.d.ts

@@ -0,0 +1,29 @@
+import type { JenkinsConfig } from "./types.js";
+export declare class JenkinsClient {
+    private config;
+    private authHeader;
+    private crumb;
+    constructor(config: JenkinsConfig);
+    private fetchCrumb;
+    private getHeaders;
+    private handleResponse;
+    private throwJenkinsError;
+    get(jobPath: string, suffix: string, params?: Record<string, string>): Promise<unknown>;
+    getRaw(jobPath: string, suffix: string): Promise<string>;
+    getAbsolute(path: string, params?: Record<string, string>): Promise<unknown>;
+    getRawAbsolute(path: string): Promise<string>;
+    post(jobPath: string, suffix: string, body?: string, contentType?: string): Promise<{
+        response: Response;
+        data: unknown;
+    }>;
+    postForm(jobPath: string, suffix: string, formData: URLSearchParams): Promise<{
+        response: Response;
+        data: unknown;
+    }>;
+    postAbsolute(path: string, body?: string, contentType?: string): Promise<{
+        response: Response;
+        data: unknown;
+    }>;
+    private safeParseBody;
+    get baseUrl(): string;
+}

package/dist/jenkins-client.js

@@ -0,0 +1,212 @@
+import { buildJenkinsUrl } from "./utils/path-resolver.js";
+export class JenkinsClient {
+    config;
+    authHeader;
+    crumb = null;
+    constructor(config) {
+        this.config = {
+            ...config,
+            url: config.url.replace(/\/+$/, ""),
+        };
+        this.authHeader =
+            "Basic " +
+                Buffer.from(`${config.user}:${config.token}`).toString("base64");
+    }
+    async fetchCrumb() {
+        try {
+            const resp = await fetch(`${this.config.url}/crumbIssuer/api/json`, {
+                headers: { Authorization: this.authHeader },
+            });
+            if (resp.ok) {
+                const data = (await resp.json());
+                this.crumb = {
+                    field: data.crumbRequestField,
+                    value: data.crumb,
+                };
+            }
+            // If crumb issuer is not available (404), CSRF is disabled — that's fine
+        }
+        catch {
+            // Crumb fetch failed — proceed without it
+        }
+    }
+    getHeaders(extra = {}) {
+        const headers = {
+            Authorization: this.authHeader,
+            ...extra,
+        };
+        if (this.crumb) {
+            headers[this.crumb.field] = this.crumb.value;
+        }
+        return headers;
+    }
+    async handleResponse(resp) {
+        if (resp.ok) {
+            const contentType = resp.headers.get("content-type") || "";
+            if (contentType.includes("json")) {
+                return resp.json();
+            }
+            return resp.text();
+        }
+        await this.throwJenkinsError(resp);
+    }
+    async throwJenkinsError(resp) {
+        let message;
+        try {
+            message = await resp.text();
+        }
+        catch {
+            message = resp.statusText;
+        }
+        let errorCode;
+        switch (resp.status) {
+            case 401:
+                errorCode = "AUTH_FAILED";
+                message =
+                    "Authentication failed. Check JENKINS_USER and JENKINS_API_TOKEN.";
+                break;
+            case 403:
+                errorCode = "FORBIDDEN";
+                message = `Access denied. The user may lack permissions for this operation.`;
+                break;
+            case 404:
+                errorCode = "NOT_FOUND";
+                message = `Resource not found. Check that the job path is correct.`;
+                break;
+            case 500:
+                errorCode = "SERVER_ERROR";
+                break;
+            default:
+                errorCode = "HTTP_ERROR";
+        }
+        const error = {
+            statusCode: resp.status,
+            message,
+            errorCode,
+        };
+        throw error;
+    }
+    async get(jobPath, suffix, params) {
+        const url = new URL(buildJenkinsUrl(this.config.url, jobPath, suffix));
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        const resp = await fetch(url.toString(), {
+            headers: this.getHeaders(),
+        });
+        return this.handleResponse(resp);
+    }
+    async getRaw(jobPath, suffix) {
+        const url = buildJenkinsUrl(this.config.url, jobPath, suffix);
+        const resp = await fetch(url, {
+            headers: this.getHeaders(),
+        });
+        if (!resp.ok) {
+            await this.throwJenkinsError(resp);
+        }
+        return resp.text();
+    }
+    async getAbsolute(path, params) {
+        const url = new URL(`${this.config.url}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        const resp = await fetch(url.toString(), {
+            headers: this.getHeaders(),
+        });
+        return this.handleResponse(resp);
+    }
+    async getRawAbsolute(path) {
+        const url = `${this.config.url}${path}`;
+        const resp = await fetch(url, {
+            headers: this.getHeaders(),
+        });
+        if (!resp.ok) {
+            await this.throwJenkinsError(resp);
+        }
+        return resp.text();
+    }
+    async post(jobPath, suffix, body, contentType) {
+        if (!this.crumb) {
+            await this.fetchCrumb();
+        }
+        const url = buildJenkinsUrl(this.config.url, jobPath, suffix);
+        const headers = this.getHeaders(contentType ? { "Content-Type": contentType } : {});
+        const resp = await fetch(url, {
+            method: "POST",
+            headers,
+            body: body ?? undefined,
+        });
+        // If we get a 403 and have a crumb, try refreshing it
+        if (resp.status === 403 && this.crumb) {
+            this.crumb = null;
+            await this.fetchCrumb();
+            const retryHeaders = this.getHeaders(contentType ? { "Content-Type": contentType } : {});
+            const retryResp = await fetch(url, {
+                method: "POST",
+                headers: retryHeaders,
+                body: body ?? undefined,
+            });
+            if (!retryResp.ok) {
+                await this.throwJenkinsError(retryResp);
+            }
+            return { response: retryResp, data: await this.safeParseBody(retryResp) };
+        }
+        if (!resp.ok) {
+            await this.throwJenkinsError(resp);
+        }
+        return { response: resp, data: await this.safeParseBody(resp) };
+    }
+    async postForm(jobPath, suffix, formData) {
+        return this.post(jobPath, suffix, formData.toString(), "application/x-www-form-urlencoded");
+    }
+    async postAbsolute(path, body, contentType) {
+        if (!this.crumb) {
+            await this.fetchCrumb();
+        }
+        const url = `${this.config.url}${path}`;
+        const headers = this.getHeaders(contentType ? { "Content-Type": contentType } : {});
+        const resp = await fetch(url, {
+            method: "POST",
+            headers,
+            body: body ?? undefined,
+        });
+        if (resp.status === 403 && this.crumb) {
+            this.crumb = null;
+            await this.fetchCrumb();
+            const retryHeaders = this.getHeaders(contentType ? { "Content-Type": contentType } : {});
+            const retryResp = await fetch(url, {
+                method: "POST",
+                headers: retryHeaders,
+                body: body ?? undefined,
+            });
+            if (!retryResp.ok) {
+                await this.throwJenkinsError(retryResp);
+            }
+            return { response: retryResp, data: await this.safeParseBody(retryResp) };
+        }
+        if (!resp.ok) {
+            await this.throwJenkinsError(resp);
+        }
+        return { response: resp, data: await this.safeParseBody(resp) };
+    }
+    async safeParseBody(resp) {
+        const contentType = resp.headers.get("content-type") || "";
+        try {
+            if (contentType.includes("json")) {
+                return await resp.json();
+            }
+            return await resp.text();
+        }
+        catch {
+            return null;
+        }
+    }
+    get baseUrl() {
+        return this.config.url;
+    }
+}

package/dist/tools/builds.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 registerBuildTools(client: JenkinsClient, register: (name: string, description: string, schema: z.ZodType, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => void): void;

package/dist/tools/builds.js

@@ -0,0 +1,207 @@
+import { z } from "zod";
+import { formatBuild, ok, error, truncateText } from "../utils/formatters.js";
+export function registerBuildTools(client, register) {
+    // 5. triggerBuild
+    register("triggerBuild", "Trigger a new build for a Jenkins job. Supports parameterized builds. For multibranch pipelines, trigger on a specific branch. Returns the queue item URL for tracking.", z.object({
+        jobPath: z.string().describe("Full job path (e.g., 'my-folder/my-job' or 'pipeline/main')"),
+        parameters: z.record(z.string(), z.string()).optional().describe("Build parameters as key-value pairs (e.g., {\"BRANCH\": \"main\", \"DEPLOY\": \"true\"})"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const parameters = args.parameters;
+        try {
+            let result;
+            if (parameters && Object.keys(parameters).length > 0) {
+                const formData = new URLSearchParams();
+                const json = JSON.stringify({ parameter: Object.entries(parameters).map(([name, value]) => ({ name, value })) });
+                formData.set("json", json);
+                // Also set individual params for compatibility
+                for (const [key, value] of Object.entries(parameters)) {
+                    formData.set(key, value);
+                }
+                result = await client.postForm(jobPath, "/buildWithParameters", formData);
+            }
+            else {
+                result = await client.post(jobPath, "/build");
+            }
+            const location = result.response.headers.get("location");
+            if (location) {
+                // Extract queue ID from location header
+                const match = location.match(/\/queue\/item\/(\d+)/);
+                if (match) {
+                    return ok(`Build triggered successfully.\nQueue item: #${match[1]}\nTrack at: ${location}`);
+                }
+            }
+            return ok(`Build triggered successfully for ${jobPath}.`);
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 6. getBuild
+    register("getBuild", "Get detailed information about a specific build including status, duration, trigger cause, artifacts, and changes. Defaults to the last build if no number specified.", 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 tree = "number,url,result,building,duration,estimatedDuration,timestamp,displayName,description,fullDisplayName,actions[causes[shortDescription,userName]],artifacts[displayPath,fileName,relativePath],changeSets[items[msg,author[fullName],commitId]]";
+            const data = await client.get(jobPath, `/${num}/api/json`, { tree });
+            return ok(formatBuild(data));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 7. getBuildLog
+    register("getBuildLog", "Get console output of a Jenkins build. By default returns the last 200 lines (tail). Use 'maxLines' to control output size. For large logs, use 'startByte' for byte-offset pagination. Returns hasMore flag and nextStart for follow-up calls.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().optional().describe("Build number (default: last build)"),
+        maxLines: z.number().optional().default(200).describe("Maximum lines to return (default: 200)"),
+        startByte: z.number().optional().describe("Byte offset to start from (for pagination). Use nextStart from previous response."),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        const maxLines = args.maxLines || 200;
+        const startByte = args.startByte;
+        const num = buildNumber ?? "lastBuild";
+        try {
+            if (startByte !== undefined) {
+                // Progressive log with byte offset
+                const url = `/${num}/logText/progressiveText`;
+                const data = await client.get(jobPath, url, { start: String(startByte) });
+                const text = typeof data === "string" ? data : String(data);
+                // Note: progressiveText returns X-Text-Size and X-More-Data headers
+                // but we can't easily access them through our client. Return what we have.
+                return ok(truncateText(text));
+            }
+            // Full console text, then tail
+            const text = await client.getRaw(jobPath, `/${num}/consoleText`);
+            const lines = text.split("\n");
+            const totalLines = lines.length;
+            let output;
+            let hasMore = false;
+            if (lines.length > maxLines) {
+                // Tail from end
+                const start = lines.length - maxLines;
+                output = lines.slice(start).join("\n");
+                hasMore = true;
+            }
+            else {
+                output = text;
+            }
+            const meta = [
+                `--- Build Log (${totalLines} total lines, showing last ${Math.min(maxLines, totalLines)}) ---`,
+            ];
+            if (hasMore) {
+                meta.push(`[Has more content. ${totalLines - maxLines} earlier lines not shown. Increase maxLines or use startByte for full log.]`);
+            }
+            meta.push("");
+            return ok(truncateText(meta.join("\n") + output));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 8. stopBuild
+    register("stopBuild", "Abort/stop a running Jenkins build.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().describe("Build number to stop"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        try {
+            await client.post(jobPath, `/${buildNumber}/stop`);
+            return ok(`Build #${buildNumber} stop signal sent for ${jobPath}.`);
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 9. getBuildArtifacts
+    register("getBuildArtifacts", "List build artifacts with their file names and download paths.", 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}/api/json`, {
+                tree: "number,url,artifacts[displayPath,fileName,relativePath]",
+            });
+            const build = data;
+            if (!build.artifacts || build.artifacts.length === 0) {
+                return ok(`No artifacts found for build #${build.number}.`);
+            }
+            const lines = [`Artifacts for build #${build.number} (${build.artifacts.length}):`];
+            for (const a of build.artifacts) {
+                lines.push(`  - ${a.fileName} (${a.relativePath})`);
+                lines.push(`    Download: ${build.url}artifact/${a.relativePath}`);
+            }
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 10. getBuildTestResults
+    register("getBuildTestResults", "Get test results for a build. By default shows only failures. Set onlyFailures=false to see all tests.", z.object({
+        jobPath: z.string().describe("Full job path"),
+        buildNumber: z.number().optional().describe("Build number (default: last build)"),
+        onlyFailures: z.boolean().optional().default(true).describe("Show only failing tests (default: true)"),
+    }), async (args) => {
+        const jobPath = args.jobPath;
+        const buildNumber = args.buildNumber;
+        const onlyFailures = args.onlyFailures ?? true;
+        const num = buildNumber ?? "lastBuild";
+        try {
+            const data = await client.get(jobPath, `/${num}/testReport/api/json`, {
+                tree: "failCount,passCount,skipCount,totalCount,suites[name,cases[className,name,status,duration,errorDetails,errorStackTrace]]",
+            });
+            const results = data;
+            const lines = [
+                `Test Results for build #${num}:`,
+                `  Total: ${results.totalCount}  Passed: ${results.passCount}  Failed: ${results.failCount}  Skipped: ${results.skipCount}`,
+            ];
+            if (results.suites) {
+                const allCases = results.suites.flatMap((s) => s.cases);
+                const filtered = onlyFailures
+                    ? allCases.filter((c) => c.status === "FAILED" || c.status === "REGRESSION")
+                    : allCases;
+                if (filtered.length > 0) {
+                    lines.push(`\n${onlyFailures ? "Failed" : "All"} Tests (${filtered.length}):`);
+                    for (const tc of filtered.slice(0, 100)) {
+                        lines.push(`  ${tc.status}  ${tc.className}.${tc.name} (${tc.duration.toFixed(2)}s)`);
+                        if (tc.errorDetails) {
+                            lines.push(`    Error: ${tc.errorDetails.substring(0, 500)}`);
+                        }
+                    }
+                    if (filtered.length > 100) {
+                        lines.push(`  ... and ${filtered.length - 100} more`);
+                    }
+                }
+                else if (onlyFailures) {
+                    lines.push("\nNo test failures.");
+                }
+            }
+            return ok(lines.join("\n"));
+        }
+        catch (e) {
+            // 404 often means no test results
+            if (e && typeof e === "object" && "statusCode" in e && e.statusCode === 404) {
+                return ok(`No test results found for build #${num}. The build may not have any test reports.`);
+            }
+            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/discovery.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 registerDiscoveryTools(client: JenkinsClient, register: (name: string, description: string, schema: z.ZodType, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => void): void;