Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@dramabox-jenkins-mcp Deploy dramabox_other HOT to master branch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DramaBox Jenkins HOT/QAT/QAT2 部署助手（MCP Server），支持 Claude Code、Claude Desktop、Cursor 等任意 MCP 客户端。
让 Agent 在对话里完成完整部署闭环：定位 Job → 查询 Jenkins 真实构建状态 → 防覆盖检查 → 修改分支并触发构建。全程不把 Token 贴进对话。
关联需求：【PRD】Jenkins HOT/QAT 部署助手 MCP
cd /Users/luoluo/Desktop/my-github/dramabox-jenkins-mcp
npm install
npm run build自检（不连外网、不需要 Token）：
npm run self-check各客户端配置文件位置：
客户端 | 配置位置 |
Claude Code | 项目 |
Claude Desktop | 设置 → 开发者 → |
Cursor |
|
配置内容通用（标准 mcpServers 格式）：
{
"mcpServers": {
"dramabox-jenkins": {
"command": "node",
"args": [
"/Users/luoluo/Desktop/my-github/dramabox-jenkins-mcp/dist/index.js"
],
"env": {
"GITLAB_URL": "https://你的-gitlab-域名",
"GITLAB_TOKEN": "你的 GitLab Personal Access Token",
"JENKINS_URL": "http://你的-jenkins:8080",
"JENKINS_USER": "你的 Jenkins 用户名",
"JENKINS_TOKEN": "你的 Jenkins API Token"
}
}
}
}变量 | 说明 |
| GitLab 根地址；Token 需要至少 |
| GitLab Personal Access Token（ |
| Jenkins 根地址，如 |
| Jenkins 用户名 |
| Jenkins API Token（用户设置里生成，不是登录密码） |
凭证只通过 MCP 配置的
env注入进程，进程内不读取.env文件；缺失任一变量时 server 启动即报错（fail-fast），不会等到调用时才发现。请勿把 Token 提交到仓库或贴进对话。
团队推广时：每人复制同一段 mcpServers 配置，各自换成自己的 Token；后续若发 npm 包，把 command/args 换成 npx 即可，env 字段不用改。
保存配置后重启客户端（或刷新 MCP server），确认 dramabox-jenkins 已连接：Claude Code 里执行 /mcp 查看，Cursor 在 Settings → MCP 看绿点。
若刚改过代码，先 npm run build，再重启该 server。
新开对话，让 Agent 调用工具（见下方示例）。
Related MCP server: MCP-Jenkins
对话里直接说：
帮我把 dramabox_other 的 HOT 环境部署到 sunjt-0716-fix 分支
Agent 会自动串联：find_job 定位 → deploy 防覆盖检查后改分支并触发构建。切换代码线且最近成功部署版本未进入主干时会先告警，需要你明确同意后才允许 force。其他常用说法：
dramabox_other 的 QAT 当前配置、最近构建和最近成功部署分别是什么？（→ find_job + get_status）
dramabox_other 的 QAT2 最近成功部署的是哪个分支和 commit？（→ find_job(env=qat2) + get_status）
工具 | 作用 | 写操作 |
| 按 GitLab 仓库定位候选 Job，返回 Job 名、Jenkins 当前配置分支、仓库地址和链接 | 否 |
| 当前配置、最近构建尝试、最近严格成功部署、触发来源、主干合并状态及 Job 描述中的部署页线索 | 否 |
| 并发与防覆盖检查 → 改 BranchSpec → 触发 Jenkins 构建 | 是 |
Jenkins 当前配置分支 来自 config.xml BranchSpec，只表示下一次准备构建什么，不代表服务器正在运行什么。
最近构建尝试 来自 lastBuild，可能是 BUILDING、FAILURE、ABORTED 或 SUCCESS。
最近一次成功部署 来自 lastStableBuild，客户端还会再次要求 result === "SUCCESS" && building === false。
实际 commit SHA 和 branch label 来自 Git Plugin BuildData.lastBuiltRevision；多 SCM 时必须由 remoteUrls 与 Job 仓库精确匹配。
Jenkins 构建开始时间为 timestamp，展示的完成时间使用 timestamp + duration，不声称是部署步骤的精确完成时刻。
Job 已在 queue 或 lastBuild.building === true：硬拦截，force 不能绕过。写配置前会再次检查，以缩小竞态窗口。
最近成功部署的实际分支与目标分支标准化后同名：直接允许重部署，包括个人分支 force-push 后再次部署。
分支名不同或 BuildData branch label 无法唯一确定：通过 GitLab merge_base(deployedSha, defaultBranch) 判断实际部署 SHA 是否已进入主干。
SHA 已进入主干：允许切换分支；明确未进入或查询结果 unknown：要求用户确认后用 force=true。
无 lastStableBuild、构建历史轮转、BuildData 无法匹配、跨 GitLab 实例或 token 无权限：均按 unknown 处理，非 force 不修改 Jenkins。
目标分支明确不存在：始终拒绝。存在性请求失败时，非 force 拦截；用户明确确认 force=true 后警告并继续，由 Jenkins 最终校验分支。
同分支判断有一项明确接受的边界：分支删除后以同名重建，也会被当作同分支重部署。个人开发分支允许频繁 force-push 后，单靠 Git 历史无法同时区分“正常改写”和“同名重建”。如果 BuildData 返回多个不同的标准化 branch label，工具不会猜测唯一来源，而会进入跨分支检查。
Squash merge 不保留原 deployed SHA，因此 merge_base 会判定该 SHA 未进入主干。工具可以根据 branch label 查询已合并 MR 并给出提示，但 MR 只用于辅助人工判断，不能自动放行。
Job 与仓库的对应关系取自 Jenkins Remote API 导出的 SCM 配置，归一化 IP/域名、.git 后缀、斜杠和大小写后，与 GitLab 项目路径全等比较，不按 Job 名模糊猜测。环境过滤支持 hot、qat、qat2，按 Job 名分隔词精确匹配，QAT 不会混入 QAT2。
find_job 不缓存 Jenkins Job 配置，每次调用都通过一次带 tree 过滤的 bulk API 请求读取当前 Job 列表、Git remote 和 BranchSpec，不逐个请求 config.xml。
内网 IP 与域名映射位于 src/match.ts 的 HOST_ALIAS。GITLAB_URL 和 Job remote 必须归一到同一实例，否则跨实例守卫会 fail-closed；换 IP、域名或实例时需要同步维护映射。
list_history、rollback 和本地部署日志已从工具与 CLI 中删除。本地 JSONL 只能记录当前机器经本 MCP 发起的操作，无法覆盖其他用户直接通过 Jenkins 的部署，不能作为多人环境的权威历史。
升级不会自动删除已有的 ~/.dramabox-jenkins-mcp/deploy-log.jsonl，但程序不再读取它；确认不需要后可由用户自行清理。
已确认不存在绕过 Jenkins 的常规手工服务器部署路径。
待真实 QAT/HOT 验证：Jenkins SUCCESS 必须等价于目标服务器实际部署成功。
待真实 QAT/HOT 验证：FAILURE/ABORTED 不得留下服务器部分更新状态。
如果上述前提不成立，应由服务器暴露 /version、release manifest、commit SHA 或制品 digest，并以运行时信息作为最终权威源。
npm run build
npm run self-checkself-check 不访问外网，通过注入式 HTTP mock 覆盖 Jenkins BuildData、严格 SUCCESS、GitLab merge_base、同分支重部署、跨分支拦截和并发硬拦截。
修改 BranchSpec 并触发构建。并发构建会硬拦截；同一实际部署分支可直接重部署，切换分支时基于最近成功部署 SHA 防覆盖。
| Name | Required | Description | Default |
|---|---|---|---|
| job | Yes | Jenkins Job 精确名称（可先用 find_job 定位） | |
| force | No | 仅在用户明确同意覆盖未合并或无法确认的成功部署版本后传 true | |
| branch | Yes | 要部署的目标分支名 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses substantive behavior: concurrent builds are hard-blocked, the same deployment branch can be redeployed directly, and switching branches has an anti-overwrite safeguard based on the most recent successful deployment SHA. This goes well beyond a generic 'deploys a branch' statement, though it does not cover permissions or failure results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action and then the key behavioral constraints. There is no redundant or filler content; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter deployment tool with no output schema and no annotations, the description plus schema covers the core action, essential constraints (concurrency, redeploy, anti-overwrite), and the conditional use of the force parameter. It does not describe return values, but the sibling get_status tool can supplement that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a clear description: job requires the exact Jenkins job name, branch is the target branch, and force requires explicit user consent to overwrite. The description adds no additional per-parameter meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: '修改 BranchSpec 并触发构建' (modify BranchSpec and trigger a build), and the title '部署分支到 Job' identifies the resource. This distinguishes it from sibling tools find_job and get_status, which are lookup and status operations respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the title and action, and provides behavioral conditions like concurrent-build hard-blocking and redeployment rules. However, it does not explicitly state when to use deploy versus find_job/get_status, nor does it mention exclusions or prerequisites beyond the schema hint to locate the job with find_job.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按 GitLab 仓库定位 Jenkins HOT/QAT/QAT2 候选 Job，返回 Job 名、Jenkins 当前配置分支、仓库地址和链接。
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 环境过滤：hot / qat / qat2；不传则返回全部候选 | |
| repo | Yes | GitLab 仓库名或关键词，如 dramabox_other |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context by stating what is returned: 'Job 名、Jenkins 当前配置分支、仓库地址和链接' (job name, current branch, repo URL, link). This goes beyond the annotation and clarifies the output nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. No redundant words or filler. It efficiently communicates the tool's purpose and result in one line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple read-only lookup tool with two parameters and no output schema, the description adequately covers what the tool does and what it returns. It does not mention potential edge cases like multiple results or empty results, but for this scope it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'repo' and 'env' have descriptions. The tool description does not add additional parameter semantics beyond the schema; it simply restates the overall purpose. Baseline of 3 is appropriate since the schema carries full weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb '定位' (locate/find) with a clear resource: 'Jenkins HOT/QAT/QAT2 候选 Job' by GitLab repository. It clearly distinguishes from siblings like 'deploy' and 'get_status' by focusing on locating candidate jobs rather than deploying or checking status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need to locate Jenkins jobs for a GitLab repo, use this tool. It mentions optional environment filtering, but does not explicitly state when to use this tool versus alternatives like 'get_status' or 'deploy'. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看 Jenkins 当前配置、最近构建尝试、最近一次严格成功部署及其相对主干的合并状态。
| Name | Required | Description | Default |
|---|---|---|---|
| job | Yes | Jenkins Job 精确名称（可先用 find_job 定位） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, the description adds specific behavioral context by enumerating exactly what status information is included (current config, build attempts, successful deployment, merge status). This goes beyond the basic read-only hint without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action (查看) and lists the exact scope. Every word contributes to the user's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description fully covers the purpose and scope. It clearly enumerates what the user can expect to see, making it contextually complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description doesn't need to elaborate on the job parameter. The schema already documents it as an exact Jenkins job name with a find_job hint, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool views Jenkins configuration, recent build attempts, latest successful deployment, and merge status. The verb '查看' (view) is specific and the resource scope distinguishes it from sibling tools find_job and deploy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The schema hint '可先用 find_job 定位' provides clear context that this tool should be used after locating the job with find_job. It implicitly distinguishes from deploy, but doesn't explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0deployfind_jobget_statusScored across 3 tools
Each tool has a distinct, non-overlapping purpose: locating candidate jobs, checking deployment status, and triggering deployments. The clear separation makes it easy for an agent to select the right tool for each step.
Names follow a verb-based pattern with 'find_job' and 'get_status' using verb_noun, while 'deploy' is a bare verb. Minor inconsistency but still predictable and readable.
Three tools is an ideal, focused set for the server's purpose of Jenkins deployment management. Each tool is essential and there is no bloat.
The set covers the core workflow: find a job, inspect its status, and deploy. It lacks an explicit cancel or rollback operation, but for the stated purpose of locating, checking, and deploying, coverage is solid.
Devopness MCP server for DevOps happiness! Empower AI Agents to deploy apps and infra, to any cloud.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Public MCP server for discovering open jobs. Search, filter, and get application links.
