MCPX注册表Jenkins插件
一个Jenkins插件,它添加了一个构建参数,从MCPX注册表中列出MCP服务器,并为您的作业选择一个。
目录
- 登录行为 - 作业级别覆盖 - 为什么选择CLI而不是HTTP? - 诊断:探头
- 使用Bash脚本(推荐用于Shell作业) - 在管道中运行MCP服务器
特性
- 注册表基URL的全局配置
- 参数化作业输入,用于从注册表中选择MCP服务器
- 作业配置中支持默认值的文本输入参数
- 将所选值显示为环境变量:
$MCP_SERVER(或自定义参数名称) - 作业配置中的默认值:在参数配置中设置“默认MCP服务器”以预填充该值
- 从包中自动提取参数:当
MCP_SERVER已设置,参数来自服务器packages配置(运行时参数和环境变量)会自动提取并设置为具有默认值的环境变量 - 在管道中运行MCP服务器:使用基于注册表类型(docker、binary、npm、pypi、wheel)的自动命令构造在标记的代理上执行MCP服务器
- mcpx cli集成:配置cli路径
- 作业级别覆盖:每个作业的CLI设置(路径、注册表URL)-适用于自由式项目和管道作业
- 诊断:点击“探测”按钮,测试mcpx cli的运行位置并预览原始JSON
- 全力支持自由式项目和管道作业
快速开始
- 构建插件
mvn -U -e -ntp -DskipTests package结果 .hpi 将低于 target/.
- 在Jenkins中安装
- 管理Jenkins→ 插件→ 高级→ 上传插件→ 选择已构建
.hpi.
- 配置注册表
- 管理Jenkins→ 系统→ MCPX注册表:设置注册表基URL
- 配置mcpx cli
- 管理Jenkins→ 系统→ MCPX CLI:
- CLI路径:指向mcpx CLI的路径(例如。, /home/jenkins/.local/bin/mcpx-cli, /usr/local/bin/mcpx-cli,或 ~/.local/bin/mcpx-cli) - 笔记: - 您可以使用绝对路径或路径 ~ (波浪号)-bash脚本将自动展开 ~ 到用户的主目录 - 如果作业的CLI路径为空,则测试CLI将使用全局CLI路径 - 确保控制器和/或将运行刷新操作的任何代理上存在配置的路径
全局(系统)配置示例:
- 向作业添加参数(推荐)
- 配置作业→ 此构建已参数化→ 添加参数→ “MCPX注册表中的MCP服务器”
- 设置“默认MCP服务器”(可选):输入默认服务器值,该值将预先填写在“使用参数构建”中
- 参数配置页面显示:
- “默认MCP服务器”:构建时使用的默认值 - “可用MCP服务器”:注册表中服务器的只读预览 - “刷新”按钮:从注册表中获取最新服务器 - “Probe”按钮:测试mcpx cli运行的位置并显示原始JSON输出
- 在“使用参数构建”中,文本字段将预先填充配置中的默认值
- 如果留空,将使用配置中的默认值
- 将完整的服务器名称粘贴或键入文本框(例如。,
io.modelcontextprotocol.anonymous/gerrit-mcp-server)
- 在构建步骤中使用它
包装参数
当 MCP_SERVER 如果配置了(在作业配置中或通过“使用参数构建”),插件会自动:
- 集合
MCPX_REGISTRY_BASE_URL作为配置的注册表基URL中的环境变量(作业级别>全局>默认) - 使用mcpx cli查询服务器详细信息以获取
packages配置 - 从第一个包中提取参数
registryType,runtimeArguments,以及environmentVariables - 将它们设置为具有包定义中默认值的环境变量
参数命名
参数会根据其类型自动命名:
- 包元数据:
MCPX_REGISTRY_TYPE(从registryType在包装中。,docker,binary,npm,pypi,wheel) - 命名运行时参数:
- 如果 valueHint 存在: MCPX_ (例如。, -p 随着 valueHint: "port_mapping" → MCPX_PORT_MAPPING) - 否则: MCPX_ (例如。, --port → MCPX_PORT, --host → MCPX_HOST)
- 位置运行时参数:
MCPX_(例如。,port_mapping→MCPX_PORT_MAPPING对于HTTP模式,volume_mapping→MCPX_VOLUME_MAPPING用于STDIO模式) - 环境变量:
MCPX_(例如。,GERRIT_BASE_URL→MCPX_GERRIT_BASE_URL)
默认值
默认值会自动从包定义中提取:
- 如果参数具有
default在包中的值,它将被设置为环境变量的默认值 - 用户提供的参数值(来自“使用参数构建”)优先于默认值
- 如果参数不是由用户提供的,并且在包中有默认值,则使用默认值
建筑中的使用
包参数在构建步骤中自动作为环境变量可用:
pipeline {
agent any
stages {
stage('Use package parameters') {
steps {
echo "MCP Server: ${env.MCP_SERVER}"
echo "Registry Type: ${env.MCPX_REGISTRY_TYPE}"
echo "Port: ${env.MCPX_PORT}"
echo "Host: ${env.MCPX_HOST}"
echo "Gerrit URL: ${env.MCPX_GERRIT_BASE_URL}"
}
}
}
}示例:包配置
示例1:带valueHint的命名参数
{
"packages": [
{
"registryType": "docker",
"runtimeArguments": [
{
"type": "named",
"name": "-p",
"valueHint": "port_mapping",
"default": "8004:8000",
"description": "Port mapping for the container"
},
{
"type": "named",
"name": "--port",
"default": "8005",
"description": "Server port number"
}
]
}
]
}当 MCP_SERVER 设置为此服务器:
MCPX_REGISTRY_TYPE:docker(从registryType包装内)MCPX_PORT_MAPPING:8004:8000(使用valueHint从-p论点)MCPX_PORT:8005(使用name从--port论点)
示例2:带有环境变量的STDIO模式
{
"packages": [
{
"registryType": "docker",
"transport": {
"type": "stdio"
},
"runtimeArguments": [
{
"type": "named",
"name": "--rm",
"description": "Remove container after exit",
"isRequired": true
},
{
"type": "positional",
"valueHint": "volume_mapping",
"description": "Volume mount for configuration access",
"format": "string",
"default": "${PWD}:/workspace",
"isRequired": false
}
],
"environmentVariables": [
{
"name": "GERRIT_BASE_URL",
"default": "https://gerrit-review.googlesource.com/",
"description": "Default Gerrit server URL"
},
{
"name": "MCP_LOG_LEVEL",
"default": "INFO",
"description": "Logging level"
}
]
}
]
}当 MCP_SERVER 如果设置为此服务器,则以下环境变量将可用:
MCP_SERVER:所选服务器名称MCPX_REGISTRY_TYPE:docker(从registryType包装内)MCPX_VOLUME_MAPPING:${PWD}:/workspace(默认值来自位置参数)MCPX_GERRIT_BASE_URL:https://gerrit-review.googlesource.com/(默认来自环境变量)MCPX_MCP_LOG_LEVEL:INFO(默认来自环境变量)
向作业配置添加参数
要在“使用参数构建”中使用包参数,您可以将它们添加为作业配置中的字符串参数:
- 配置作业→ 此构建已参数化→ 添加参数→ 字符串参数
- 使用命名约定命名参数:
- MCPX_REGISTRY_TYPE -包中的注册表类型(例如。, docker, binary, npm, pypi, wheel) - MCPX_PORT, MCPX_HOST, MCPX_PORT_MAPPING, MCPX_NETWORK_MODE -HTTP模式的运行时参数 - MCPX_VOLUME_MAPPING -STDIO模式(卷装载)的运行时参数 - MCPX_GERRIT_BASE_URL, MCPX_MCP_LOG_LEVEL等等。-包中的环境变量
- 将默认值留空-当发生以下情况时,它将从包中自动设置
MCP_SERVER已配置
或者,您可以查询服务器的可用参数:
- 在参数配置页面中,使用“获取包参数”操作(如果可用)查看服务器包中定义了哪些参数
- 将这些参数添加为作业配置中的字符串参数
备注:包参数会自动作为环境变量注入,即使它们没有明确定义为作业参数。但是,将它们添加为作业参数允许用户覆盖“使用参数构建”中的默认值。
MCPX CLI集成
该插件使用mcpx cli获取服务器列表。
登录行为
在列出服务器之前,插件使用匿名登录初始化CLI会话,然后列出服务器:
mcpx-cli --base-url= login --method anonymous
mcpx-cli --base-url= servers --json作业级别覆盖
自由式项目和管道作业都可以覆盖全局CLI设置。 作业级别配置优先于全局配置。
- 配置作业→ 检查“MCPX注册表插件配置”
- 设置以下任一项:
- CLI路径(例如,特定代理上的不同版本或路径)- 覆盖全局CLI路径
- 注册表基URL(为此作业使用其他注册表)- 覆盖全局注册表基URL
- 使用“测试CLI”按钮验证CLI是否在配置的路径上工作
配置优先级:
- 作业级别设置覆盖全局设置
- 如果作业级别设置为空或未配置,则使用全局设置
- 如果两者都为空,则使用默认值(例如。,
mcpx-cli对于CLI路径)
作业配置示例:
为什么选择CLI而不是HTTP?
- 避免CORS:无浏览器限制
- 更好的身份验证处理:CLI管理令牌/config
- 一致的工具:与开发人员工作流程相同
- 可靠的代理/防火墙后
有意不使用HTTP来避免CORS和环境特定的约束。在Jenkins控制器/代理上安装CLI。
诊断:探头
参数配置页面提供“刷新”和“探测”按钮:
- 刷新:从注册表中获取最新服务器并更新“可用MCP服务器”预览
- 探测:对插件使用的节点选择(自由式项目的作业标记代理)执行mcpx cli→ 任何在线代理→ 控制器)并返回一条短消息:
- 运行位置:“控制器”或代理的节点名称 - 使用了哪个基本URL和CLI路径 - 原始JSON的简短片段 mcpx-cli servers --json
注: 对于自由式项目,插件尊重作业分配的标签(“限制此项目的运行位置”)。对于流水线作业,Jenkins对标签限制的处理方式不同,因此插件在退回控制器之前会尝试任何在线代理。
典型用途:
- 点击参数配置中的“Probe”,确认mcpx cli已安装在您在至少一个候选节点上配置的路径上
- 如果探测器在代理上成功,请单击“刷新”以更新可用选项预览
- 如果Probe在所有候选对象上都失败,请在控制器上安装mcpx cli,或将作业配置为在具有mcpx-cli的代理上运行,并相应地设置作业级别的cli路径
在Jenkins中运行MCP服务器
使用Bash脚本(推荐用于Shell作业)
对于 自由式项目 (shell作业),使用bash脚本 test/jenkins/jenkins.job 以避免Pipeline脚本安全沙盒问题。此脚本:
- 作为标准shell脚本运行(无管道安全限制)
- 使用Jenkins提供的环境变量
- 使用以下命令获取服务器详细信息
mcpx-cli - 从JSON解析包配置
- 根据注册表类型动态构建和执行命令
设置:
- 创建一个 自由式项目 (不是管道作业)
- 添加MCP服务器参数(通过Jenkins插件配置)
- 在“构建”部分,添加“执行shell”构建步骤
- 粘贴以下内容
test/jenkins/jenkins.job或将其作为脚本文件引用 - 确保
jq已安装在Jenkins代理上(apt-get install jq或yum install jq)
先决条件:
jq必须安装在Jenkins代理上才能进行JSON解析mcpx-cli必须可用(通过插件设置配置)- 环境变量由插件自动设置:
- MCP_SERVER:所选服务器名称 - MCPX_CLI_PATH:配置中的CLI路径(作业级别>全局>默认),其中 ~ 自动扩展 - MCPX_REGISTRY_BASE_URL:来自配置的注册表基URL(作业级别>全局>默认) - MCPX_*:从服务器配置中提取的包参数
脚本执行三个阶段:
- 显示MCP服务器:显示所选服务器
- 显示包参数:列出所有
MCPX_*环境变量 - 运行MCP服务器:获取服务器详细信息,根据注册表类型构建命令并执行
支持的注册表类型:
- 码头工人:构造
docker run带标志的命令(-p,-v,--network,-e)、环境变量和参数
- 支持两种HTTP模式(通过端口映射 -p)以及STDIO模式(通过以下方式进行卷映射 -v) - 脚本会根据包的 transport 类型和 runtimeArguments 配置
- 二进制:使用运行时参数直接执行二进制文件
- npm:用途
npx运行npm包 - pypi/轮子:使用Python运行Python包
Shell作业中的示例用法:
# The script automatically:
# 1. Reads MCP_SERVER and MCPX_* environment variables
# 2. Fetches server details using mcpx-cli
# 3. Parses package configuration
# 4. Builds and executes the appropriate command
# No additional configuration needed - just run the script!配置优先级:
该脚本对CLI路径和注册表URL使用以下优先级:
- CLI路径:由插件自动设置优先级:
- 用户参数(如果在“使用参数构建”中设置) - 作业级别配置(如果在作业设置中配置) - 全局配置(来自Manage Jenkins→ 系统) - 违约: mcpx-cli - 脚本会自动展开 ~ (波浪号)位于用户主目录的路径中
- 注册表基URL:由插件自动设置优先级:
- 用户参数(如果在“使用参数构建”中设置) - 作业级别配置(如果在作业设置中配置) - 全局配置(来自Manage Jenkins→ 系统) - 违约: https://mcpx.example.com
注: 两者 MCPX_CLI_PATH 和 MCPX_REGISTRY_BASE_URL 由插件自动注入,因此您不需要手动配置它们。但是,您可以通过以下方式覆盖它们:
- 将它们作为字符串参数添加到作业配置中,使其在“使用参数构建”中可用
- 或者在构建环境中设置它们→ 使用自定义环境变量
通过Jenkins API触发
您可以启动构建并通过参数化的API传递选定的MCP服务器。默认参数名称为 MCP_SERVER 除非在添加参数时更改了它。
传递包参数
通过API触发生成时,您可以选择传递包参数以覆盖服务器包配置中的默认值:
# Basic trigger with MCP_SERVER only
curl "${BASE_URL}/job/${JOB_NAME}/buildWithParameters?MCP_SERVER=io.modelcontextprotocol.anonymous%2Fgerrit-mcp-server&token=YOUR_TOKEN"
# Trigger with MCP_SERVER and package parameter overrides (HTTP mode)
curl "${BASE_URL}/job/${JOB_NAME}/buildWithParameters?MCP_SERVER=io.modelcontextprotocol.anonymous%2Fgerrit-mcp-server&MCPX_REGISTRY_TYPE=docker&MCPX_PORT=9000&MCPX_PORT_MAPPING=9000:8000&MCPX_MCP_LOG_LEVEL=DEBUG&token=YOUR_TOKEN"
# Trigger with MCP_SERVER and package parameter overrides (STDIO mode)
curl "${BASE_URL}/job/${JOB_NAME}/buildWithParameters?MCP_SERVER=io.modelcontextprotocol.anonymous%2Fgerrit-mcp-server&MCPX_REGISTRY_TYPE=docker&MCPX_VOLUME_MAPPING=%24%7BPWD%7D%3A%2Fworkspace&MCPX_GERRIT_BASE_URL=https%3A%2F%2Fcustom-gerrit.example.com%2F&token=YOUR_TOKEN"注: 当发生以下情况时,会从服务器的包中自动设置包参数 MCP_SERVER 提供。显式传递它们将覆盖默认值。
笔记:
- 如果启用了CSRF保护,请在POST请求中包含一个面包屑。
- 对于文件夹内的作业,重复
/job/部分:/job//job//buildWithParameters. - 如果服务器值包含以下内容,则对其进行URL编码
/(例如,更换/随着%2F). - URL对包参数值进行适当编码(空格为
%20,根据需要使用特殊字符)。
启用“远程触发器构建”(作业配置)
要从脚本触发作业,请在作业上配置远程触发令牌:
- 打开你的工作→ 配置
- 在“构建触发器”下,选中“远程构建触发器(例如,从脚本)”
- 输入令牌值,例如:
mcpx.jenkins - 保存
如何使用:
- 启用后,Jenkins接受以下请求
.../job//buildWithParameters额外的token=参数。
安全和CSRF注意事项:
- 在许多Jenkins实例中,使用GET
token=是足够的,并返回一个201和一个Location指向队列项的标头。 - 某些实例(安全配置、反向代理)可能需要POST。如果启用了CSRF,可能还需要一个面包屑。
- 如果你的Jenkins拒绝匿名访问,即使使用令牌,你也必须包含Basic auth。
测试脚本: test/jenkins/jenkins.sh
一个使用curl在Ubuntu上触发Jenkins作业的简单测试脚本。此脚本演示了触发参数化构建、轮询队列、获取构建结果以及在作业完成后转储完整控制台输出的基本工作流程。
该脚本支持测试包参数,允许您可选地覆盖服务器包配置中的默认值。
配置
编辑脚本以设置Jenkins配置:
BASE_URL='http://:
'
AUTH='USER:API_TOKEN'
JOB_NAME='mcpx.jenkins'
MCP_SERVER='io.modelcontextprotocol.anonymous/gerrit-mcp-server'
# Package parameters (optional - these will override defaults from packages)
# Uncomment and set values to test parameter overrides:
# MCPX_PORT='8005' # Named runtime argument: --port (for HTTP mode)
# MCPX_HOST='0.0.0.0' # Named runtime argument: --host (for HTTP mode)
# MCPX_PORT_MAPPING='8004:8000' # Named runtime argument with valueHint: -p -> port_mapping (for HTTP mode)
# MCPX_VOLUME_MAPPING='${PWD}:/workspace' # Positional runtime argument: volume_mapping (for STDIO mode)
# MCPX_NETWORK_MODE='host' # Positional runtime argument: network_mode (for HTTP mode)
# MCPX_MCP_LOG_LEVEL='DEBUG' # Environment variable: MCP_LOG_LEVEL
# MCPX_MCP_DATA_DIR='/custom/data' # Environment variable: MCP_DATA_DIR
# MCPX_GERRIT_BASE_URL='https://custom-gerrit.example.com/' # Environment variable: GERRIT_BASE_URL
#
# Note: For STDIO mode (transport type "stdio"), port mappings and network mode are not needed.
# Volume mappings are commonly used for STDIO mode to provide configuration access.
# Set to 'true' to enable DEBUG output, 'false' to disable
DEBUG_ENABLED='true'BASE_URL:您的Jenkins服务器URLAUTH:格式为的基本身份验证凭据USER:API_TOKENJOB_NAME:要触发的Jenkins作业的名称MCP_SERVER:作为传递的MCP服务器标识符MCP_SERVER参数(例如。,io.modelcontextprotocol.anonymous/gerrit-mcp-server).脚本自动对该值进行URL编码(例如。,/成为%2F)当进行API请求时。- 包装参数 (可选):设置任意
MCPX_*环境变量来覆盖服务器包中的默认值。如果设置了它们,脚本将自动将其包含在构建请求中。示例:
- MCPX_REGISTRY_TYPE:从中重写注册表类型 registryType 在包装中(例如。, docker, binary, npm, pypi, wheel) - MCPX_PORT:从以下位置覆盖端口 --port 运行时参数(用于HTTP模式) - MCPX_PORT_MAPPING:覆盖端口映射(从 -p 随着 valueHint: "port_mapping" 或HTTP模式的位置参数) - MCPX_VOLUME_MAPPING:重写卷映射(从位置参数开始,使用 valueHint: "volume_mapping",用于STDIO模式) - MCPX_NETWORK_MODE:覆盖网络模式(从位置参数开始,用 valueHint: "network_mode",对于HTTP模式) - MCPX_MCP_LOG_LEVEL:从以下位置覆盖日志记录级别 MCP_LOG_LEVEL 环境变量 - MCPX_MCP_DATA_DIR:从以下位置覆盖数据目录 MCP_DATA_DIR 环境变量 - MCPX_GERRIT_BASE_URL:从以下位置覆盖Gerrit URL GERRIT_BASE_URL 环境变量
DEBUG_ENABLED:设置为'true'启用详细的DEBUG输出,或'false'抑制所有DEBUG消息以获得更清晰的输出
用法
# Make the script executable
chmod +x test/jenkins/jenkins.sh
# Run the script with default MCP_SERVER only
./test/jenkins/jenkins.sh
# Run with package parameter overrides (set variables before running)
MCPX_PORT='9000' MCPX_MCP_LOG_LEVEL='DEBUG' ./test/jenkins/jenkins.sh
# Or edit the script to set package parameters permanently测试包参数:
- 仅使用默认值进行测试:仅使用以下命令运行脚本
MCP_SERVER集。包参数将自动从服务器的包配置中提取。
- 使用覆盖进行测试:在运行脚本之前设置包参数变量以覆盖默认值:
# For HTTP mode:
MCPX_REGISTRY_TYPE='docker' \
MCPX_PORT='9000' \
MCPX_MCP_LOG_LEVEL='DEBUG' \
MCPX_PORT_MAPPING='9000:8000' \
./test/jenkins/jenkins.sh
# For STDIO mode:
MCPX_REGISTRY_TYPE='docker' \
MCPX_MCP_LOG_LEVEL='DEBUG' \
MCPX_VOLUME_MAPPING='${PWD}:/workspace' \
MCPX_GERRIT_BASE_URL='https://custom-gerrit.example.com/' \
./test/jenkins/jenkins.sh- 检查控制台输出:作业(管道或外壳)将显示所有
MCPX_*环境变量,显示默认值和覆盖值。
输出
该脚本输出一个合并的JSON对象,其中包含构建元数据和控制台输出:
- 构建元数据:
number,result,builtOn,fullDisplayName,timestamp,duration,queueId - 控制台输出:
consoleOutput-完整控制台日志(仅当作业已完成时,否则为空字符串)
作业完成后,控制台输出会自动获取并合并。不进行流媒体播放;构建完成后,将检索整个控制台日志,并将其合并到JSON输出中以便于解析。
输出格式示例:
{
"number": 39,
"result": "SUCCESS",
"builtOn": "mcpx.jenkins",
"fullDisplayName": "mcpx.jenkins #39",
"timestamp": 1762416127226,
"duration": 34,
"queueId": 38,
"consoleOutput": "Started by remote host...\nRunning as SYSTEM\n..."
}注意:如果作业仍在构建中或无法获取控制台输出, consoleOutput 将是一个空字符串。DEBUG消息(如果启用)将发送到stderr,而JSON输出将发送到stdout。
先决条件
curl安装jq已安装(sudo apt-get install jq在Ubuntu上)- Jenkins作业配置了启用“远程触发器构建”和令牌集
- 基本身份验证凭据(用户:API_TOKEN)
发展
- Java 11+
- Jenkins 2.414.3+基线
运行测试
运行测试:
mvn -ntp -Dspotbugs.skip package故障排除
- 在作业配置页面上测试CLI失败
- 确保目标节点(控制器或标记的代理)上的路径正确 - 您可以使用绝对路径(例如。, /usr/local/bin/mcpx-cli 或 /home/jenkins/.local/bin/mcpx-cli)或路径 ~ (例如。, ~/.local/bin/mcpx-cli)-bash脚本将自动展开 ~ 到用户的主目录 - 如果作业字段为空,则使用全局CLI路径 - 既适用于自由式项目,也适用于流水线作业
- 在参数配置中单击“刷新”后,预览中不会显示服务器
- 确保控制器上安装了mcpx cli,或者在配置的路径上至少安装了一个联机代理 - 对于自由式项目:插件更喜欢作业的标记代理;如果没有人在线,它会尝试任何在线代理,然后只尝试控制器 - 对于流水线作业:插件尝试任何在线代理,然后退回到控制器(Jenkins对标签限制的处理方式不同) - 确认注册表基URL已在Manage Jenkins中设置→ 系统→ MCPX注册表 - 在参数配置中单击“Probe”,查看它在哪里运行以及CLI返回了什么JSON;然后再次检查 - 查看Jenkins日志中以“通过mcpx cli获取失败”开头的行以获取详细信息
许可证
该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。
