This Jenkins MCP server has moderate tool definitions with mixed quality. All 5 tools are properly registered with @mcp.tool() decorators and have basic descriptions. However, there are significant gaps in parameter descriptions, output schema documentation, error handling guidance, and input validation. The tool names follow verb-noun convention (getAllJobs, getJob, getBuild, triggerBuild, getBuildLog) which is good, but parameter documentation is sparse. No tool has complete parameter descriptions for all inputs. The server uses STDIO transport only, which is a hard cap at 50 points for protocol readiness. Descriptions are present but minimal (10-80 chars), falling below the production baseline of 194 chars average. No output schemas are documented. Error handling is absent, failed API calls will raise unhandled exceptions without recovery guidance.
Tools (5)
getAllJobsread onlyauthsource verified50/100
Get a list of all Jenkins jobs.
getBuildread onlyauthsource verified62/100
Retrieve a specific build or the last build of a Jenkins job.
getBuildLogread onlyauthsource verified63/100
Retrieve log lines for a specific build or the last build of a Jenkins job. Supports pagination via 'start'.
No output schema documentation for any tool. LLMs cannot predict response structure, limiting composability and downstream tool chain planning. Each tool's return type is unspecified.
getAllJobs() has zero input parameters but its description ('Get a list of all Jenkins jobs') does not specify pagination behavior, result limits, or response structure. No limit or pagination parameters offered, risking context window exhaustion with large Jenkins instances.
Tool descriptions are too short (10-80 chars vs. production baseline of 194 chars). Descriptions lack WHEN to use each tool, dependencies (e.g., 'Call getJob first to verify the job exists'), or recovery hints. LLMs cannot distinguish between similar tools or plan multi-step sequences.
getAllJobsgetJobgetBuildtriggerBuildgetBuildLog
Recommendations
Add complete output schema documentation to each tool. Document the structure of getAllJobs response (e.g., {"jobs": [{"name": string, "url": string, "color": string}], "_class": string}), getJob response structure (name, url, builds array, lastBuild), getBuild structure (number, timestamp, status, result), triggerBuild response (confirmation message or queue URL), and getBuildLog structure (text, more: boolean). Use TypedDict or formal JSON Schema examples in docstrings.
Expand tool descriptions to 100-200 characters each. Include WHEN to use (e.g., 'Use getAllJobs to discover available job names before calling getJob; consider pagination for large Jenkins instances'), dependencies (e.g., 'Requires a valid Jenkins URL and API token'), and what the response contains. Example: 'Get a list of all Jenkins jobs. Returns job names, URLs, and status indicators. Use this to discover available jobs before calling getJob(). Note: Returns all jobs; consider filtering by name pattern if Jenkins has >100 jobs.'
Add pagination and limit enforcement to getAllJobs. Accept optional 'limit' (max 100) and 'offset' parameters. Return {"jobs": [...], "total": int, "limit": int, "offset": int} so agents can iterate large Jenkins instances without blowing context. Document the limit in the description.
Add a dry-run or confirmation pattern to triggerBuild. Either require an explicit 'confirm=true' parameter, or return a confirmation-required error that the agent must acknowledge. Example: return {"status": "confirmation_required", "message": "Ready to trigger build for job: <full_path>. Call triggerBuild again with confirm=true to proceed."}. This prevents accidental CI/CD invocations.
Irreversible write operation (triggerBuild) lacks confirmation or dry-run capability. Agents can trigger builds without safeguards, risking unintended CI/CD activation. No confirmation_request or idempotency hint provided.
No error handling guidance. API failures (invalid job path, missing build, auth failures) will raise unhandled httpx exceptions or MCP errors without actionable recovery hints. LLMs receive raw exceptions instead of 'Try search_jobs() to find valid paths' or 'Check Jenkins URL and token credentials'.
getBuild and getBuildLog accept optional 'build_number' parameter with no guidance on valid range, how to discover available build numbers, or what 'lastBuild' returns when no builds exist. LLMs cannot validate inputs before calling.
getBuildLog 'start' parameter (pagination offset) lacks min/max constraints or description of line semantics. No documentation of response format (text, structured lines, tail behavior). LLMs cannot construct valid pagination sequences.
Jenkins URL and Token are injected via environment variables or request headers depending on transport. No documentation of this conditional behavior in tool descriptions. Agents have no visibility into credential requirements or configuration.
getAllJobsgetJobgetBuildtriggerBuildgetBuildLog
Implement structured error handling with recovery guidance. Wrap jenkins_api_call in a try-catch that translates httpx exceptions to actionable messages. Examples: 'Job not found at path: <full_path>. Call getAllJobs() to list available jobs.' 'Invalid Jenkins URL or token. Check environment variables JENKINS_URL and JENKINS_TOKEN.' 'Build number <N> does not exist for job <full_path>. Valid range: 1 to <lastBuildNumber>.' Return errors as {"error": string, "recovery_hint": string, "retryable": boolean} in tool responses.
Document build_number parameter constraints and semantics. Add to getBuild and getBuildLog descriptions: 'build_number: Optional integer. If omitted, returns the last build. Use getAllBuilds() (if available) to discover valid build numbers. Pass null/omit to default to lastBuild; returns error if no builds exist for the job.'
Add range constraints and validation to getBuildLog start parameter. Document: 'start: integer, default 0. Starting line number for log pagination. Jenkins returns log text from this line onwards. Max safe line count per response is typically 100000; use pagination for large logs. Example: call with start=0 to get lines 0-N, then start=N+1 for the next batch.'
Add tool annotations (toolAnnotations) to indicate read-only vs. destructive operations. Mark getAllJobs, getJob, getBuild, getBuildLog with readOnlyHint=true. Mark triggerBuild with destructiveHint=true so agents know it has side effects and plan accordingly.
Create a discovery tool or document tool interdependencies. Consider adding a searchJobs(name_pattern: string) tool that returns matching job names, enabling agents to validate job paths before calling getJob or triggerBuild. At minimum, add to each tool description: 'Call getAllJobs() first to verify job paths if unsure.'
Add per-tool permission/scope declarations in descriptions or metadata. Example: getAllJobs, getJob, getBuild, getBuildLog require 'read:jobs' scope. triggerBuild requires 'write:jobs' scope. This helps document least-privilege configuration.
Handle missing builds and empty log gracefully. If a build does not exist, return {"error": "Build not found", "lastBuildNumber": int, "available_range": "1 to <N>"} instead of raising an exception. If log is empty, return {"text": "", "more": false} instead of 404. This prevents agent failures on edge cases.
Document API timeout and retry behavior. Add to server documentation (README or docstring): 'API calls timeout after 30s. Transient failures (connection reset, 5xx) should be retried by the agent. 4xx errors (not found, invalid path) are not retryable.' Let agents know which failures warrant retry.