@alexsarrell/jenkins-mcp-server 1.0.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
-# @alexsarrell/jenkins-mcp-server
+# @alexsarrell/jenkins-mcp-server v1.3.0
 
-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.
+A custom MCP (Model Context Protocol) server for Jenkins integration with Claude Code. Provides 22 tools (20 default + 2 unsafe) for comprehensive Jenkins management including pipeline replay, stage-level logs, structured config reads, parameter introspection, and rich log search.
 
 ## Why?
 
@@ -63,18 +63,21 @@ To enable them, add the env variable to your MCP config:
 }
 ```
 
-## Tools (16 default + 2 unsafe)
+## Tools (20 default + 2 unsafe)
 
 ### Job Management
 - **getJobs** - List jobs in a folder with status summary
 - **getJob** - Job details, parameters, health, branches (for multibranch pipelines)
 - **getJobConfig** - Get job XML configuration (config.xml)
+- **getJobParameters** - Structured `ParameterSpec[]` for the job (types, choices, defaults). Use this before `triggerBuild` to know what to pass.
+- **describeJob** - Structured read of `config.xml` (SCM url/branch, Jenkinsfile path, parameters, cron, retention) without parsing raw XML.
+- **previewJobConfig** - Generate a `config.xml` from a structured spec (pipeline / multibranch / folder), optionally diffed against an existing job. Read-only.
 - **updateJobConfig** - Update job XML configuration
 
 ### Build Operations
-- **triggerBuild** - Trigger builds with optional parameters (supports parameterized builds)
-- **getBuild** - Build details (status, duration, changes)
-- **getBuildLog** - Console output with tail/pagination support
+- **triggerBuild** - Trigger builds with optional parameters (string or string[] values for multi-value parameters)
+- **getBuild** - Build details (status, duration, parameters, artifacts, changes); use `include` to control returned sections
+- **getBuildLog** - Console output with tail / byte-pagination / grep modes (regex + before/after context)
 - **stopBuild** - Abort a running build
 - **getBuildArtifacts** - List build artifacts
 - **getBuildTestResults** - Test results with failure details
@@ -87,8 +90,9 @@ To enable them, add the env variable to your MCP config:
 - **restartFromStage** - Restart pipeline from a specific stage
 
 ### Discovery & Utilities
-- **searchBuildLogs** - Grep across build logs for a pattern
+- **searchBuildLogs** - Grep across build logs (regex, before/after context, `onlyResults` filter, progressive read)
 - **getQueue** - View the build queue
+- **getQueueItem** - Map a queue item ID (returned by `triggerBuild`) to the build that started, or its current waiting/cancelled state
 - **enableDisableJob** - Enable or disable a job
 
 ## Multibranch Pipelines
@@ -100,12 +104,26 @@ For branches with slashes in the name, use `::` separator:
 my-pipeline::feature/my-branch
 ```
 
+## Multi-value parameters
+
+`triggerBuild` accepts each parameter value as either a string or a string array. The string form is **never** split on commas — passing `"hello, world"` sends one value verbatim. For multi-select / `ExtendedChoiceParameter (PT_CHECKBOX)` parameters, pass an array:
+
+```js
+triggerBuild({ jobPath: "x", parameters: { TAGS: ["alpha", "beta", "gamma"] } });
+```
+
+A legacy `splitOnComma: true` flag preserves the pre-1.3 behaviour (split string values on commas) — deprecated, will be removed in v2.0.
+
+## Log search and grep
+
+Both `getBuildLog` and `searchBuildLogs` accept a `pattern` (with optional `regex`) and `before`/`after` context lines. `getBuildLog` switches to grep mode when `pattern` is set; otherwise it returns a tail. `searchBuildLogs` streams logs via Jenkins' progressive-text API and stops early once `maxMatchesPerBuild` is reached, and an `onlyResults: ["FAILURE"]` filter prunes builds before fetching their logs.
+
 ## 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
+- **Config editing** works with raw XML — use `getJobConfig` (or `describeJob` for a structured subset) to read, modify, then `updateJobConfig`. For new configs from a spec, use `previewJobConfig` then paste into `updateJobConfig`.
+- Build logs are capped at 100KB per response; use grep mode or pagination for larger logs
 - CSRF crumbs are handled automatically
 - Authentication uses HTTP Basic Auth with user API token
 

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { JenkinsClient } from "./jenkins-client.js";
@@ -6,6 +9,7 @@ import { registerJobTools } from "./tools/jobs.js";
 import { registerBuildTools } from "./tools/builds.js";
 import { registerPipelineTools } from "./tools/pipeline.js";
 import { registerDiscoveryTools } from "./tools/discovery.js";
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
 // Validate environment variables
 const JENKINS_URL = process.env.JENKINS_URL;
 const JENKINS_USER = process.env.JENKINS_USER;
@@ -27,7 +31,7 @@ const client = new JenkinsClient({
 // Create MCP server
 const server = new McpServer({
     name: "jenkins-mcp-server",
-    version: "1.0.0",
+    version: pkg.version,
 });
 // Tool registration helper that wraps the McpServer.tool() API
 function register(name, description, schema, handler) {

package/dist/jenkins-client.d.ts

@@ -10,6 +10,12 @@ export declare class JenkinsClient {
     private throwJenkinsError;
     get(jobPath: string, suffix: string, params?: Record<string, string>): Promise<unknown>;
     getRaw(jobPath: string, suffix: string): Promise<string>;
+    /**
+     * Stream a Jenkins console log chunk-by-chunk via /logText/progressiveText.
+     * Yields chunks until the log ends. Caller can stop iteration early.
+     * Falls back gracefully — if the endpoint returns 404, the caller should retry with /consoleText.
+     */
+    getProgressiveText(jobPath: string, buildNumber: number | "lastBuild"): AsyncGenerator<string, void, void>;
     getAbsolute(path: string, params?: Record<string, string>): Promise<unknown>;
     getRawAbsolute(path: string): Promise<string>;
     post(jobPath: string, suffix: string, body?: string, contentType?: string): Promise<{

package/dist/jenkins-client.js

@@ -108,6 +108,34 @@ export class JenkinsClient {
         }
         return resp.text();
     }
+    /**
+     * Stream a Jenkins console log chunk-by-chunk via /logText/progressiveText.
+     * Yields chunks until the log ends. Caller can stop iteration early.
+     * Falls back gracefully — if the endpoint returns 404, the caller should retry with /consoleText.
+     */
+    async *getProgressiveText(jobPath, buildNumber) {
+        let start = 0;
+        const url = buildJenkinsUrl(this.config.url, jobPath, `/${buildNumber}/logText/progressiveText`);
+        while (true) {
+            const u = new URL(url);
+            u.searchParams.set("start", String(start));
+            const resp = await fetch(u.toString(), { headers: this.getHeaders() });
+            if (!resp.ok) {
+                await this.throwJenkinsError(resp);
+            }
+            const text = await resp.text();
+            if (text.length > 0)
+                yield text;
+            const moreData = resp.headers.get("X-More-Data");
+            const sizeHeader = resp.headers.get("X-Text-Size");
+            if (moreData !== "true")
+                return;
+            const newStart = sizeHeader ? Number(sizeHeader) : start + text.length;
+            if (newStart <= start)
+                return; // protect against infinite loop
+            start = newStart;
+        }
+    }
     async getAbsolute(path, params) {
         const url = new URL(`${this.config.url}${path}`);
         if (params) {

package/dist/schemas/parameter.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+export declare const parameterSpec: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"string">;
+    name: z.ZodString;
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    trim: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    name: z.ZodString;
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+    name: z.ZodString;
+    default: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    name: z.ZodString;
+    choices: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"password">;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"run">;
+    name: z.ZodString;
+    projectName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"credentials">;
+    name: z.ZodString;
+    credentialType: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"unknown">;
+    name: z.ZodString;
+    rawType: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type ParameterSpec = z.infer<typeof parameterSpec>;

package/dist/schemas/parameter.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+export const parameterSpec = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("string"),
+        name: z.string(),
+        default: z.string().optional(),
+        description: z.string().optional(),
+        trim: z.boolean().optional(),
+    }),
+    z.object({
+        type: z.literal("text"),
+        name: z.string(),
+        default: z.string().optional(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("boolean"),
+        name: z.string(),
+        default: z.boolean().optional(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("choice"),
+        name: z.string(),
+        choices: z.array(z.string()).min(1),
+        default: z.string().optional(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("password"),
+        name: z.string(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("file"),
+        name: z.string(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("run"),
+        name: z.string(),
+        projectName: z.string().optional(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("credentials"),
+        name: z.string(),
+        credentialType: z.string().optional(),
+        description: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal("unknown"),
+        name: z.string(),
+        rawType: z.string(),
+        description: z.string().optional(),
+    }),
+]);

package/dist/tools/builds.js

@@ -1,23 +1,26 @@
 import { z } from "zod";
 import { formatBuild, ok, error, truncateText } from "../utils/formatters.js";
+import { buildTriggerPayload } from "../utils/build-payload.js";
+import { grepLog } from "../utils/log-grep.js";
 export function registerBuildTools(client, register) {
+    const DEFAULT_GET_BUILD_INCLUDE = ["causes", "parameters", "artifacts", "changes"];
     // 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\"})"),
+        parameters: z.record(z.string(), z.union([z.string(), z.array(z.string()).nonempty()])).optional()
+            .describe("Build parameters. String values are submitted as-is (no comma splitting). Use string[] for multi-value parameters (ExtendedChoiceParameter, multi-select)."),
+        splitOnComma: z.boolean().optional().default(false)
+            .describe("[DEPRECATED] Legacy behaviour: split comma-bearing string values into multi-value submissions. Will be removed in v2.0. Prefer string[] values instead."),
     }), async (args) => {
         const jobPath = args.jobPath;
         const parameters = args.parameters;
         try {
             let result;
+            const splitOnComma = args.splitOnComma ?? false;
             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);
-                }
+                const { formData, jsonParameters } = buildTriggerPayload(parameters, splitOnComma);
+                // jsonParameters is reserved for the v1.3 FILE/CREDENTIALS payload; not sent today.
+                void jsonParameters;
                 result = await client.postForm(jobPath, "/buildWithParameters", formData);
             }
             else {
@@ -38,16 +41,32 @@ export function registerBuildTools(client, register) {
         }
     });
     // 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({
+    register("getBuild", "Get detailed information about a specific build including status, duration, trigger cause, parameters, artifacts, and changes. Defaults to the last build if no number specified. Use 'include' to control which optional sections are returned.", z.object({
         jobPath: z.string().describe("Full job path"),
         buildNumber: z.number().optional().describe("Build number (default: last build)"),
+        include: z.array(z.enum(["artifacts", "changes", "causes", "parameters"])).optional()
+            .describe(`Sections to include. Default: ${JSON.stringify(DEFAULT_GET_BUILD_INCLUDE)}`),
     }), async (args) => {
         const jobPath = args.jobPath;
         const buildNumber = args.buildNumber;
+        const include = args.include ?? [...DEFAULT_GET_BUILD_INCLUDE];
         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 });
+            const treeFields = [
+                "number,url,result,building,duration,estimatedDuration,timestamp,displayName,description,fullDisplayName",
+            ];
+            const actionFields = [];
+            if (include.includes("causes"))
+                actionFields.push("causes[shortDescription,userName]");
+            if (include.includes("parameters"))
+                actionFields.push("parameters[name,value,_class]");
+            if (actionFields.length > 0)
+                treeFields.push(`actions[${actionFields.join(",")}]`);
+            if (include.includes("artifacts"))
+                treeFields.push("artifacts[displayPath,fileName,relativePath]");
+            if (include.includes("changes"))
+                treeFields.push("changeSets[items[msg,author[fullName],commitId]]");
+            const data = await client.get(jobPath, `/${num}/api/json`, { tree: treeFields.join(",") });
             return ok(formatBuild(data));
         }
         catch (e) {
@@ -55,37 +74,65 @@ export function registerBuildTools(client, register) {
         }
     });
     // 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({
+    register("getBuildLog", "Get console output of a Jenkins build. Three modes: (a) tail (default — returns last `maxLines`), (b) byte-offset pagination via `startByte`, (c) grep mode if `pattern` is set (returns matches with `before`/`after` context lines). Modes are mutually exclusive — if `pattern` is set, tail/startByte are ignored.", 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."),
+        maxLines: z.number().optional().default(200).describe("[Tail mode] Maximum lines to return"),
+        startByte: z.number().optional().describe("[Pagination mode] Byte offset to start from"),
+        pattern: z.string().optional().describe("[Grep mode] Search pattern. Switches the tool to grep mode when set."),
+        regex: z.boolean().optional().default(false).describe("[Grep mode] Treat pattern as regex (default: case-insensitive substring)"),
+        before: z.number().optional().default(0).describe("[Grep mode] Lines of context before each match"),
+        after: z.number().optional().default(0).describe("[Grep mode] Lines of context after each match"),
+        maxMatches: z.number().optional().default(50).describe("[Grep mode] Stop after this many matches"),
     }), async (args) => {
         const jobPath = args.jobPath;
         const buildNumber = args.buildNumber;
         const maxLines = args.maxLines || 200;
         const startByte = args.startByte;
+        const pattern = args.pattern;
+        const regex = args.regex ?? false;
+        const before = args.before ?? 0;
+        const after = args.after ?? 0;
+        const maxMatches = args.maxMatches ?? 50;
         const num = buildNumber ?? "lastBuild";
         try {
+            // Grep mode
+            if (pattern !== undefined) {
+                const text = await client.getRaw(jobPath, `/${num}/consoleText`);
+                let result;
+                try {
+                    result = grepLog(text, { pattern, regex, before, after, maxMatches });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return error(msg);
+                }
+                const header = [
+                    `--- Build Log Search: pattern="${pattern}" (regex=${regex}, before=${before}, after=${after}) ---`,
+                    `Total matches: ${result.matches.length}${result.truncated ? ` (truncated at maxMatches=${maxMatches})` : ""}`,
+                    "",
+                ];
+                const blocks = result.matches.map((m, idx) => {
+                    const ctxLines = m.context.map((c) => `${String(c.lineNumber).padStart(6)}: ${c.text}`);
+                    return `=== match #${idx + 1} (line ${m.lineNumber}) ===\n${ctxLines.join("\n")}`;
+                });
+                return ok(truncateText(header.join("\n") + blocks.join("\n\n")));
+            }
+            // Pagination mode
             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
+            // Tail mode (default)
             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");
+                output = lines.slice(lines.length - maxLines).join("\n");
                 hasMore = true;
             }
             else {
@@ -95,7 +142,7 @@ export function registerBuildTools(client, register) {
                 `--- 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(`[Has more content. ${totalLines - maxLines} earlier lines not shown. Increase maxLines, use startByte, or use pattern for grep mode.]`);
             }
             meta.push("");
             return ok(truncateText(meta.join("\n") + output));

package/dist/tools/discovery.js

@@ -1,51 +1,71 @@
 import { z } from "zod";
-import { formatQueue, ok, error } from "../utils/formatters.js";
+import { formatQueue, formatQueueItem, ok, error, truncateText } 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({
+    // 16. searchBuildLogs (v2)
+    register("searchBuildLogs", "Search build logs for a pattern across recent builds. Supports regex, context lines, result filter, and progressive read for large logs. Streams the log and stops early once maxMatchesPerBuild is hit per build.", 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)"),
+        pattern: z.string().describe("Pattern to search for"),
+        buildNumber: z.number().optional().describe("Search a specific build only. Overrides lastN/onlyResults."),
+        lastN: z.number().optional().default(5).describe("Number of recent builds to search (max 20)"),
+        regex: z.boolean().optional().default(false).describe("Treat pattern as regex (default: case-insensitive substring)"),
+        before: z.number().optional().default(0).describe("Lines of context before each match"),
+        after: z.number().optional().default(0).describe("Lines of context after each match"),
+        maxMatchesPerBuild: z.number().optional().default(10).describe("Stop scanning a build after this many matches"),
+        onlyResults: z.array(z.enum(["SUCCESS", "FAILURE", "UNSTABLE", "ABORTED", "NOT_BUILT"])).optional()
+            .describe("Filter builds by result before searching. Default: search all."),
     }), async (args) => {
         const jobPath = args.jobPath;
         const pattern = args.pattern;
         const buildNumber = args.buildNumber;
         const lastN = Math.min(args.lastN || 5, 20);
+        const regex = args.regex ?? false;
+        const before = args.before ?? 0;
+        const after = args.after ?? 0;
+        const maxMatchesPerBuild = args.maxMatchesPerBuild ?? 10;
+        const onlyResults = args.onlyResults;
         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}`));
+            const matcher = (() => {
+                try {
+                    return regex ? new RegExp(pattern) : null;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Invalid regex: ${msg}`);
                 }
+            })();
+            const isMatch = (line) => matcher ? matcher.test(line) : line.toLowerCase().includes(pattern.toLowerCase());
+            // Determine which builds to search.
+            let buildsToSearch;
+            if (buildNumber !== undefined) {
+                buildsToSearch = [buildNumber];
             }
             else {
-                // Get recent builds
                 const data = await client.get(jobPath, "/api/json", {
-                    tree: "builds[number]{0," + lastN + "}",
+                    tree: `builds[number,result]{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("");
+                const builds = jobData.builds ?? [];
+                buildsToSearch = builds
+                    .filter((b) => !onlyResults || (b.result !== null && onlyResults.includes(b.result)))
+                    .map((b) => b.number);
+            }
+            const results = [];
+            for (const num of buildsToSearch) {
+                const matches = await searchOneBuild(client, jobPath, num, isMatch, before, after, maxMatchesPerBuild);
+                if (matches.length === 0)
+                    continue;
+                results.push(`Build #${num} (${matches.length}${matches.length >= maxMatchesPerBuild ? "+" : ""} matches):`);
+                for (const m of matches.slice(0, maxMatchesPerBuild)) {
+                    for (const c of m.context) {
+                        results.push(`  ${String(c.lineNumber).padStart(6)}: ${c.text}`);
                     }
+                    results.push("");
                 }
             }
             if (results.length === 0) {
-                return ok(`No matches found for "${pattern}" in ${buildNumber ? `build #${buildNumber}` : `last ${lastN} builds`}.`);
+                return ok(`No matches for "${pattern}" in ${buildNumber ? `build #${buildNumber}` : `last ${buildsToSearch.length} build(s)`}.`);
             }
-            return ok(`Search results for "${pattern}":\n\n${results.join("\n")}`);
+            return ok(truncateText(results.join("\n")));
         }
         catch (e) {
             return handleError(e);
@@ -64,7 +84,20 @@ export function registerDiscoveryTools(client, register) {
             return handleError(e);
         }
     });
-    // 18. enableDisableJob
+    // 18. getQueueItem
+    register("getQueueItem", "Get the state of a specific queue item by ID. Use the queue ID returned from triggerBuild ('Queue item: #N') to find which build was started — this bridges queue → build.", z.object({
+        queueId: z.number().int().describe("Queue item ID"),
+    }), async (args) => {
+        const queueId = args.queueId;
+        try {
+            const data = await client.getAbsolute(`/queue/item/${queueId}/api/json`);
+            return ok(formatQueueItem(data));
+        }
+        catch (e) {
+            return handleError(e);
+        }
+    });
+    // 19. 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"),
@@ -81,24 +114,101 @@ export function registerDiscoveryTools(client, register) {
         }
     });
 }
-async function searchBuildLog(client, jobPath, buildNumber, patternLower) {
+async function searchOneBuild(client, jobPath, buildNumber, isMatch, before, after, maxMatches) {
+    const matches = [];
+    let lineNumber = 0;
+    // Sliding context buffer of recent lines.
+    const tail = [];
+    // Pending matches awaiting `after` lines.
+    const pending = [];
+    let leftover = "";
     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
-                });
+        for await (const chunk of client.getProgressiveText(jobPath, buildNumber)) {
+            const data = leftover + chunk;
+            const lines = data.split("\n");
+            // The last fragment may be a partial line — keep it for the next chunk.
+            leftover = lines.pop() ?? "";
+            for (const line of lines) {
+                lineNumber++;
+                // Drain pending after-context.
+                for (let i = pending.length - 1; i >= 0; i--) {
+                    const p = pending[i];
+                    p.context.push({ lineNumber, text: line });
+                    p.collected++;
+                    if (p.collected >= after) {
+                        matches.push({ lineNumber: p.lineNumber, context: p.context });
+                        pending.splice(i, 1);
+                        if (matches.length >= maxMatches)
+                            return matches;
+                    }
+                }
+                if (isMatch(line)) {
+                    const ctx = [];
+                    // Take last `before` lines from tail.
+                    const startIdx = Math.max(0, tail.length - before);
+                    for (let j = startIdx; j < tail.length; j++) {
+                        ctx.push({ lineNumber: lineNumber - (tail.length - j), text: tail[j] });
+                    }
+                    ctx.push({ lineNumber, text: line });
+                    if (after === 0) {
+                        matches.push({ lineNumber, context: ctx });
+                    }
+                    else {
+                        pending.push({ lineNumber, collected: 0, context: ctx });
+                    }
+                    if (matches.length >= maxMatches)
+                        return matches;
+                }
+                tail.push(line);
+                if (tail.length > before)
+                    tail.shift();
             }
         }
-        return matches;
     }
     catch {
-        return [];
+        // Fallback to /consoleText (e.g., progressiveText not available).
+        const text = await client.getRaw(jobPath, `/${buildNumber}/consoleText`);
+        return fallbackSearch(text, isMatch, before, after, maxMatches);
+    }
+    // Process trailing fragment if log doesn't end with \n.
+    if (leftover.length > 0) {
+        lineNumber++;
+        for (const p of pending) {
+            p.context.push({ lineNumber, text: leftover });
+        }
+        if (isMatch(leftover)) {
+            const ctx = [];
+            const startIdx = Math.max(0, tail.length - before);
+            for (let j = startIdx; j < tail.length; j++) {
+                ctx.push({ lineNumber: lineNumber - (tail.length - j), text: tail[j] });
+            }
+            ctx.push({ lineNumber, text: leftover });
+            matches.push({ lineNumber, context: ctx });
+        }
+    }
+    // Final flush: emit pending matches with whatever after-context we got.
+    for (const p of pending) {
+        matches.push({ lineNumber: p.lineNumber, context: p.context });
+    }
+    return matches.slice(0, maxMatches);
+}
+function fallbackSearch(text, isMatch, before, after, maxMatches) {
+    const lines = text.split("\n");
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!isMatch(lines[i]))
+            continue;
+        const ctx = [];
+        const start = Math.max(0, i - before);
+        const end = Math.min(lines.length - 1, i + after);
+        for (let j = start; j <= end; j++) {
+            ctx.push({ lineNumber: j + 1, text: lines[j] });
+        }
+        matches.push({ lineNumber: i + 1, context: ctx });
+        if (matches.length >= maxMatches)
+            return matches;
     }
+    return matches;
 }
 function handleError(e) {
     if (e && typeof e === "object" && "errorCode" in e) {