{"_id":"@nch1802/jenkins-mcp","name":"@nch1802/jenkins-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@nch1802/jenkins-mcp","version":"0.1.0","type":"module","description":"MCP server (stdio) for Jenkins: discover jobs and their real parameters, trigger builds without blocking, and read build status and logs. Multi-environment aware.","keywords":["mcp","modelcontextprotocol","model-context-protocol","jenkins","ci","claude","llm"],"license":"MIT","author":{"name":"Hau Nguyen","email":"nch180297@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/nch180297/jenkins-mcp.git"},"bin":{"jenkins-mcp":"dist/index.js"},"main":"./dist/index.js","exports":{".":"./dist/index.js"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.json","start":"node dist/index.js","dev":"tsc -p tsconfig.json --watch","typecheck":"tsc -p tsconfig.json --noEmit","prepare":"pnpm run build","prepublishOnly":"pnpm run typecheck"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","dotenv":"^17.2.3","zod":"^4.4.3"},"devDependencies":{"@types/node":"^22.10.2","typescript":"^5.7.2"},"gitHead":"d3870f24788b503544bfb92a867448fdadbc966a","_id":"@nch1802/jenkins-mcp@0.1.0","bugs":{"url":"https://github.com/nch180297/jenkins-mcp/issues"},"homepage":"https://github.com/nch180297/jenkins-mcp#readme","_nodeVersion":"22.22.3","_npmVersion":"11.14.1","dist":{"integrity":"sha512-CLxaEgL2LFaVTyLK6z1x0GwhWS54/Ld8hi4ld5Sn2wnk2GMinR5EMcVGQuugGcDl96KYQiUqGtWfueXjwIzJuQ==","shasum":"f6c920039c6521da81308e64fc0afc9049dfc81a","tarball":"https://registry.npmjs.org/@nch1802/jenkins-mcp/-/jenkins-mcp-0.1.0.tgz","fileCount":17,"unpackedSize":182886,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCxTVW/0AS1OYyZE5EaBhYPBwUPkzYRCIgiTZcf785ONAIgR5pOuBj7ppmjyczwxndngYpu4VzsJcs74zYzbcHWISM="}]},"_npmUser":{"name":"nch1802","email":"nch180297@gmail.com"},"directories":{},"maintainers":[{"name":"nch1802","email":"nch180297@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/jenkins-mcp_0.1.0_1785991921950_0.9770207403715083"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-06T04:52:01.776Z","0.1.0":"2026-08-06T04:52:02.082Z","modified":"2026-08-06T04:52:02.287Z"},"maintainers":[{"name":"nch1802","email":"nch180297@gmail.com"}],"description":"MCP server (stdio) for Jenkins: discover jobs and their real parameters, trigger builds without blocking, and read build status and logs. Multi-environment aware.","homepage":"https://github.com/nch180297/jenkins-mcp#readme","keywords":["mcp","modelcontextprotocol","model-context-protocol","jenkins","ci","claude","llm"],"repository":{"type":"git","url":"git+https://github.com/nch180297/jenkins-mcp.git"},"author":{"name":"Hau Nguyen","email":"nch180297@gmail.com"},"bugs":{"url":"https://github.com/nch180297/jenkins-mcp/issues"},"license":"MIT","readme":"# @nch1802/jenkins-mcp\n\nAn MCP server (stdio) for Jenkins. It lets an agent discover jobs and their **real**\nparameter definitions, trigger builds **without blocking**, and read build status and logs\n— across several Jenkins servers at once.\n\nScope is **read + one write**: everything can be read, and the only write is triggering a\nbuild. The server does not decide *where* you may build — every configured environment is\nbuildable, and restricting that is Jenkins' own permission model, not this server's.\n\n## Install\n\n```jsonc\n// .mcp.json / claude_desktop_config.json\n{\n  \"mcpServers\": {\n    \"jenkins\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nch1802/jenkins-mcp\"],\n      \"env\": {\n        \"JENKINS_URL\": \"https://jenkins.example.com\",\n        \"JENKINS_USERNAME\": \"your-user\",\n        \"JENKINS_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\nRequires Node >= 18. Get the API token from Jenkins → *Your name* → *Security* →\n*API Token*.\n\n## Tools\n\nSix tools are always available:\n\n| Tool | What it does |\n|---|---|\n| `list_jobs` | Walk the job/folder tree (up to 3 levels) of one environment. |\n| `get_job_info` | A job's **real** parameter definitions: name, type, choices, defaults — read live from Jenkins. |\n| `trigger_build` | Trigger any job with free-form params. Non-blocking. |\n| `get_build_status` | Poll once: still queued (with the reason), running, or finished. |\n| `get_build_log` | Tail of the console log — for explaining *why* a build failed. |\n| `get_recent_builds` | Recent build history, for \"was X deployed?\" questions. |\n\nTwo more appear only when the config file declares shortcuts (see below):\n`list_build_targets` — every configured environment, its documented jobs and its shortcut\nkeywords — and `trigger_catalog_build`.\n\n## Design notes\n\nThree things this server does deliberately, which matter if you are wiring an agent to it:\n\n1. **No tool ever waits for a build.** A build can take half an hour; a tool that waited\n   would time out at the client and stall the reply. The agent polls `get_build_status` on\n   a later turn instead. The single bounded exception is a ~2 s wait after a trigger, just\n   long enough for Jenkins to assign a build number so the result can carry a real console\n   link.\n2. **Parameters are validated against the job's real definitions before triggering.**\n   Jenkins **silently ignores** a misnamed parameter and still returns `201` — the build\n   then runs with default values and nobody is warned. This server reads the job's\n   definitions first and refuses on a mismatch (including a wrong-case name, since Jenkins\n   is case-sensitive). Use `skip_preflight` only when the definitions cannot be read.\n3. **One environment = one Jenkins server, and there is no default one.** Each environment\n   gets its own URL and credentials. Which one to use is resolved in this order: an explicit\n   `env` argument → the single environment whose config file declares that job → the only\n   environment, if you configured just one. If none of the three applies, the call **fails\n   and asks for `env`** — reads included. This happens **before** any HTTP call and can never\n   fall back to \"ask Jenkins\": you would need a server chosen in order to ask one. Two\n   environments can be entirely different Jenkins servers, so a guess is not a harmless\n   convenience — it reads someone else's job tree, or triggers on the wrong box.\n\n**There is no environment allowlist.** Configuring credentials for a Jenkins *is* allowing\nbuilds on it — which environment to build is the requester's call, and the server should not\nsecond-guess it. If a Jenkins must stay read-only, give it an API token belonging to a user\nwithout *Job/Build* permission; that is the only restriction that actually holds, since it\nholds against everything, not just this server.\n\n**Which environments exist is configuration, not code.** The server hard-codes no\nenvironment names, no job names, and no variable names — not even a naming convention for\nthem: it reads them all from your config file (see below). With no config file it runs as a\nsingle environment called `default`, reading `JENKINS_URL` / `JENKINS_USERNAME` /\n`JENKINS_API_TOKEN`.\n\n`console_url` is the only link meant for a human — it opens the running log. `queue_url` is\nmachinery: it feeds `get_build_status` and any build watcher you write.\n\n## Minimum setup\n\nThree variables. Nothing else is required:\n\n```bash\nJENKINS_URL=https://jenkins.example.com\nJENKINS_USERNAME=your-user\nJENKINS_API_TOKEN=your-token\n```\n\nAll six always-registered tools work on that alone — the agent finds its way by discovery: `list_jobs` to\nlocate a job, `get_job_info` to read its real parameters, `trigger_build` to run it. Only the\ntwo shortcut tools are absent, because a shortcut keyword is your team's vocabulary and the\nserver has no way to invent one.\n\n## Config file (optional)\n\n`JENKINS_CATALOG_FILE` points at one JSON file. It holds **only what Jenkins cannot state\nitself**: which servers exist, which variable holds each credential, your own keywords, and\nwhich environment owns a job name.\n\nFull field-by-field guide: [docs/catalog.md](docs/catalog.md). Runnable example:\n[catalog.example.json](catalog.example.json).\n\n```json\n{\n  \"configs\": [\n    {\n      \"name\": \"development\",\n      \"description\": \"The dev Jenkins for the platform team\",\n      \"credentials\": {\n        \"url\": \"MY_DEV_ENDPOINT\",\n        \"username\": \"MY_DEV_USER\",\n        \"apiToken\": \"MY_DEV_TOKEN\"\n      },\n      \"defaultFolder\": \"platform\",\n      \"jobs\": [\"nightly-e2e (DEV)\"],\n      \"shortcuts\": {\n        \"api\": { \"job\": \"backend-deploy (DEV)\", \"params\": { \"SERVICE\": \"api\" } }\n      }\n    }\n  ]\n}\n```\n\n**What must NOT go in here: job descriptions and parameter definitions.** `get_job_info`\nalready returns a parameter's name, type, allowed choices, default and description straight\nfrom Jenkins, so a copy in this file is a second source of truth that only drifts. The file\nis a routing and vocabulary layer, not a mirror of your job tree.\n\n**`credentials` carries variable NAMES, never values.** The role is declared explicitly, so\nyour variables can be named anything — `MY_DEV_TOKEN`, `CI_PASS`, whatever your deployment\nalready uses. The server imposes no prefix or suffix convention. The file is meant to be\ncommitted; the tokens are not.\n\n| Role | Holds | Required |\n|---|---|---|\n| `url` | Base URL of that Jenkins | yes |\n| `username` | Jenkins user | yes |\n| `apiToken` | Jenkins API token | yes |\n\n### Per-config fields\n\n| Field | Notes |\n|---|---|\n| `name` | How the requester and the `env` tool argument refer to this Jenkins. Free-form, matched case-insensitively, must be unique. |\n| `description` | Shown to the agent by `list_build_targets` — write it for a reader who does not know your infrastructure. |\n| `credentials` | Role → variable name, as above. |\n| `defaultFolder` | Folder a single-segment `job_path` resolves under. Optional; empty means the Jenkins root. |\n| `jobs` | Plain job **names**, for routing only — see below. Usually unnecessary. |\n| `shortcuts` | Keyword → job (+ fixed params) for `trigger_catalog_build`. The only kind of build target. |\n\n**`jobs` exists for routing, not documentation.** It is how the server knows which Jenkins a\njob lives on — the main way an `env` argument becomes unnecessary. Every job named by\n`shortcuts` is added automatically, so list a job here only when it has no shortcut and you\nstill want it to resolve without `env`. A job absent from the file always builds fine through\n`trigger_build`.\n\nJob names are written **exactly as they appear on Jenkins**, including any environment\nmarker your team uses (`backend-deploy (DEV)`). Nothing is appended at call time, and the\nmarker does **not** decide which server is used — only which config declares the job does.\n\n`defaultFolder` lives here, not in a variable, because it describes your job tree rather than\na secret. With no config file there is no default folder — and none is needed, since\n`list_jobs` hands the agent ready-made `job_path`s instead of having it assemble one.\n\nA relative path is resolved against the process working directory — normally the directory\nholding your `.mcp.json`.\n\n## Environment variables\n\nEverything except the credentials themselves:\n\n| Variable | Default | Notes |\n|---|---|---|\n| `JENKINS_CATALOG_FILE` | — | Path to the config JSON above. |\n\nThat is the only one — plus whatever variable names your config file's `credentials` blocks\ndeclare. There is deliberately no variable selecting a default environment, none restricting\nwhere builds may go, and none holding a default folder: the first would make an unresolved\ncall silently pick a server, the second is a fence anyone holding the credentials can step\nover, and the third is structure that belongs in the config file.\n\nWith **no** `JENKINS_CATALOG_FILE`, the server runs one implicit config named `default` that\nreads `JENKINS_URL` / `JENKINS_USERNAME` / `JENKINS_API_TOKEN`. A single environment is\nunambiguous, so every job belongs to it and nothing has to be declared up front. The two\ncatalog tools are not registered.\n\nSetting only **some** of a config's three variables fails at **startup** rather than\nmid-build, since the config would otherwise be skipped and every build aimed at it would land\non another server. Setting **none** of them is fine — that is a config awaiting credentials —\nbut the skipped environments are printed to stderr at startup, because a config you *believe*\nyou configured appearing in that list is the signal that a variable name does not match.\n\n## Development\n\n```bash\npnpm install     # also builds\npnpm build       # tsc -> dist/\npnpm typecheck\npnpm dev         # tsc --watch\n```\n\n`dist/` is gitignored and hosts run `dist/index.js` directly, so **rebuild after editing\n`src/`**.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-c5cb8b46f8f43fc40dfc3867b15e2825"}