MCP Server Plugin

Jenkins的MCP服务器插件

Jenkins的MCP（模型上下文协议）服务器插件实现了模型上下文协议的服务器端组件。此插件使Jenkins能够充当MCP服务器，为MCP客户端（如LLM驱动的应用程序或IDE）提供上下文、工具和功能。

特性

• MCP服务器实现：实现模型上下文协议的服务器端。
• Jenkins集成：将Jenkins功能作为MCP工具和资源公开。
• 可扩展架构：允许通过以下方式轻松扩展MCP功能 McpServerExtension 界面。

关键组件

1. 端点：MCP通信的主要入口点，处理MCP传输连接和消息路由。
2. 默认McpServer：实施 McpServerExtension，提供与Jenkins作业和构建交互的默认工具。
3. McpToolWrapper：将Java方法包装为MCP工具，处理参数解析和结果格式化。
4. McpServerExtension：用于扩展MCP服务器功能的接口。

MCP SDK版本

此MCP服务器基于MCP Java SDK版本0.17.2，该版本实现了MCP规范版本2025-06-18。

入门指南

先决条件

• Jenkins（2.533或更高版本）

配置

MCP服务器插件在安装时会自动设置必要的端点和工具，不需要额外的配置。

从系统属性

以下系统属性可用于配置MCP服务器插件：

• 返回的最大日志行数的硬限制 io.jenkins.plugins.mcp.server.extensions.BuildLogsExtension.limit.max=10000 （默认值为10000）
• 使用禁用无状态终结点 io.jenkins.plugins.mcp.server.Endpoint.disableMcpStateless=true （默认为false）
• 使用禁用SSE终结点 io.jenkins.plugins.mcp.server.Endpoint.disableMcpSse=true （默认为false）
• 使用禁用可流式传输的HTTP端点 io.jenkins.plugins.mcp.server.Endpoint.disableMcpStreamable=true （默认为false）

源标头验证

MCP规格标记为 MUST 验证 Origin 传入请求的标头。 默认情况下，MCP服务器插件不会强制执行此验证，以方便不提供标头的AI代理使用。 您可以启用不同级别的验证，如果请求中有可用的标头，您可以使用 系统属性 io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch=true 在执行验证时，标头值必须与配置的Jenkins根url匹配。

如果必须接收标头，则系统属性 io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader=true 也将使其成为强制性的。

连接弹性

MCP服务器插件包括几个提高连接可靠性的功能：

保持消息有效

服务器定期发送保持活动消息以检测断开的连接。默认情况下，保活消息每30秒发送一次。

您可以使用系统属性配置此间隔：

io.jenkins.plugins.mcp.server.Endpoint.keepAliveInterval=30

设为 0 禁用保持活动消息（不推荐）。

健康端点

轻量级的MCP特定健康端点可用于以下位置的连接监控：

/mcp-health

此端点：

• 返回MCP服务器状态和活动连接计数
• 无需身份验证即可实现最大的可访问性
• 立即返回，无需MCP协议开销
• 正常时返回HTTP 200，关机时返回HTTP 503
• 包含 Retry-After 停机期间的集管

响应格式：

{
  "mcpServerStatus": "ok",
  "activeConnections": 5,
  "shuttingDown": false,
  "timestamp": "2025-01-28T10:30:00Z"
}

建议客户端使用：

• 定期轮询健康端点（例如，每10-30秒一次）
• 当端点返回503或变得无法访问时，准备重新连接
• 使用 Retry-After 标头值（如果可用）

指标端点

度量端点可用于监视以下位置的连接统计信息：

/mcp-server/metrics

此端点需要身份验证（标准Jenkins权限），并提供：

{
  "sseConnectionsTotal": 42,
  "sseConnectionsActive": 3,
  "streamableRequestsTotal": 150,
  "connectionErrorsTotal": 2,
  "uptimeSeconds": 3600,
  "startTime": "2025-01-28T10:00:00Z"
}

优雅关闭

当Jenkins关闭时，健康端点将返回 503 Service Unavailable 在完全终止之前有一段短暂的宽限期。这允许客户端检测关机并准备重新连接。

交通建议

为了提高连接可靠性，我们建议使用 流式HTTP (/mcp-server/mcp)而不是 上海证券交易所 (/mcp-server/sse).流式HTTP更优雅地处理连接问题，是大多数MCP客户端的首选传输方式。

生产部署

在反向代理后或生产环境中部署时，配置这些超时设置以防止过早断开连接：

Jenkins/Jetty配置

Jenkins使用默认的Winstone（嵌入式Jetty） httpKeepAliveTimeout 至30秒。由于MCP保持活动ping也每30秒发送一次，这会产生一种竞争条件，Jetty可能会在下一个ping到达之前关闭连接。

将此参数添加到Jenkins启动命令中：

--httpKeepAliveTimeout=600000

对于Docker部署，请在Docker-compose.yml中添加：

services:
  jenkins:
    image: jenkins/jenkins:lts
    command: ["--httpKeepAliveTimeout=600000"]

反向代理配置（Nginx）

对于Nginx，扩展MCP端点的超时：

location ~ ^/(mcp-server|mcp-health)/ {
    proxy_pass http://jenkins;
    proxy_http_version 1.1;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_set_header Connection "";
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

传输端点

MCP服务器插件提供了三个传输端点，默认情况下都已启用：

可以使用系统属性独立禁用每个传输：

-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpSse=true
-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStreamable=true
-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStateless=true

何时使用无国籍交通工具

无状态端点(/mcp-server/stateless)适用于：

• 不需要会话管理开销的简单部署
• 客户端在不维护持久连接的情况下发出独立请求的环境
• 测试和调试场景
• 不支持基于会话的协议的客户端

用法

连接到MCP服务器

MCP客户端可以使用以下方式连接到服务器：

• 可流式传输HTTP端点： /mcp-server/mcp
• SSE端点： /mcp-server/sse
• 消息终结点： /mcp-server/message
• 无状态终结点： /mcp-server/stateless

身份验证和凭据

MCP服务器插件需要与它运行的Jenkins实例相同的凭据。要验证您的MCP查询：

1. Jenkins API代币：从您的Jenkins用户帐户生成API令牌。
2. 基本身份验证：在HTTP基本身份验证标头中使用API令牌。

生成个人访问令牌

要生成个人访问令牌，请执行以下操作：

• 登录Jenkins。
• 选择右上角的用户图标，然后选择 Security.
• 选择 Add new token.
• 输入一个名称以区分令牌，然后选择 Generate.
• 复制令牌并将其存储在安全位置以供以后使用。

\[！警告\] 一旦离开页面，您将无法再次查看或复制令牌。

• 选择 Done 添加令牌。
• 选择 Save 保存您的更改。

对HTTP基本身份验证的凭据进行编码

通过使用个人访问令牌对MCP代理进行编码，使用基本的HTTP身份验证。

要在Linux、macOS或Windows上对凭据进行编码，请执行以下操作：

打开终端并运行以下命令，替换 ` 和 ` 使用您的实际用户名和您在Jenkins中生成的个人访问令牌

• Linux或macOS

echo -n ":" | base64

• Windows（PowerShell）

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(":"))

如果成功，则输出Base64编码的凭据，类似于以下内容：

dXNlcm5hbWU6dG9rZW4=

将编码的凭据存储在安全位置以供以后使用。

\[！注意\] Base64编码不是加密。 任何有权访问编码字符串的人都可以对其进行解码并获得您的凭据。 始终保护编码的凭据，就像它们是原始用户名和令牌一样。

客户端配置示例

临床配置

{
  "mcpServers": {
    "jenkins": {
      "autoApprove": [
        
      ],
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://jenkins-host/mcp-server/mcp",
      "headers": {
        "Authorization": "Basic "
      }
    }
  }
}

副驾驶配置

截至目前，Copilot与Streamable传输不太兼容，我仍在调查这些问题。请继续使用SSE终结点。

{
  "mcp": {
    "servers": {
      "jenkins": {
        "type": "sse",
        "url": "https://jenkins-host/mcp-server/sse",
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

流媒体示例：

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

风帆配置

{
  "servers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://jenkins-host/mcp-server/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Basic "
      }
    }
  }
}

光标配置

{
  "mcpServers": {
    "jenkins": {
      "type": "http",
      "url": "https://jenkins-host/mcp-server/mcp",
      "headers": {
        "Authorization": "Basic "
      }
    }
  }
}

克劳德

claude mcp add jenkins http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic "

无状态配置示例

对于喜欢无会话管理的无状态通信的客户端：

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/stateless",
      "requestInit": {
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

鹅

• 点击 *“添加自定义扩展名”*
• 给它起一个有意义的名字
• 在类型Dropdown中，选择 *“流式HTTP”*
• 输入端点URL。这应该类似于 http://jenkins-host/mcp-server/mcp
• 滚动到 *“请求标头”*
• 在空白字段中，键入 Authorization 正如其名。然后在“值”字段中，键入 “Basic ”
• 点击 *“添加”*
• 点击 *“添加扩展名”*

可用工具

该插件提供了以下与Jenkins交互的内置工具：

作业管理

• getJob：在Jenkins上找到一份完整的工作。

• getJobs：获取按名称排序的Jenkins作业分页列表。

• triggerBuild：触发作业的构建。

此工具支持参数化构建。您可以将参数作为JSON对象提供，其中每个键都是参数名称。例如：

  {
    "jobFullName": "my-job",
    "parameters": {
      "BRANCH": "main",
      "DEBUG_MODE": "true"
    }
  }

参数说明：

- 核心Jenkins参数：完全支持（字符串、布尔值、选项、文本、密码、运行） - 插件参数：使用反射自动检测和处理 - 文件参数：不支持通过MCP（需要文件上传） - 多选参数：支持数组或列表 - 自定义插件参数：自动尝试使用基于反射的检测 - 回退行为：不支持的参数会在日志记录时恢复为默认值 如果作业已成功调度，此工具将返回一个队列项。您可以将返回的队列项ID与 getQueueItem 工具。

• getQueueItem：使用排队项目的ID获取有关排队项目的信息。

构建信息

• getBuild：检索Jenkins作业的特定版本或最后一个版本。
• updateBuild：更新构建显示名称和/或描述。
• getBuildLog：检索特定版本或上一个版本的带分页的日志行。
• searchBuildLog：在构建日志中搜索与模式（字符串或正则表达式）匹配的日志行。
• rebuildBuild：使用相同的参数重新运行构建。对于支持Replay的Pipeline作业，使用原始脚本；对于其他参数化作业，使用相同的参数安排新的构建。可选的 buildNumber；默认为上次构建。返回新生成的队列项。
• getReplayScripts：返回可回放Pipeline构建的主脚本和加载的脚本。使用此选项在调用之前检查或修改脚本 replayBuild非管道作业失败。可选的 buildNumber；默认为上次构建。
• replayBuild：使用修改后的脚本再次运行Pipeline构建。提供 mainScript （必填）和可选 loadedScripts.可选 buildNumber；默认为上次构建。如果构建不可重放或不允许重放（例如权限或沙盒），则失败。
• getTestResults：检索特定版本或上次版本的测试结果。

SCM集成

• getJobScm：检索Jenkins作业的SCM配置。
• getBuildScm：检索特定版本的SCM配置。
• getBuildChangeSets：检索特定版本的更改日志集。
• findJobsWithScmUrl：使用特定的SCM（git）存储库URL查找作业

管理信息

• whoAmI：获取当前用户的信息。
• getStatus：检查Jenkins实例的运行状况和就绪状态。使用此工具评估Jenkins实例运行状况，而不是简单的向上/向下状态。

每个工具都接受特定的参数来定制其行为。有关详细的使用说明和参数说明，请参阅API文档或使用MCP自省功能。

要使用这些工具，请连接到MCP服务器端点，并使用MCP客户端实现进行工具调用。

增强的参数支持

MCP服务器插件现在为Jenkins参数提供了全面的支持：

支持的参数类型

• 字符串参数：具有默认值的文本输入
• 布尔参数：具有自动类型转换的真/假值
• 选择参数：带验证的下拉选择
• 文本参数：多行文本输入
• 密码参数：使用秘密处理进行安全输入
• 运行参数：版本号参考
• 插件参数：自动检测和处理

参数处理特性

• 类型转换JSON类型和Jenkins参数类型之间的自动转换
• 验证：选择参数根据可用选项验证输入
• 后备方案：不支持的参数将优雅地恢复为默认值
• 反思：插件参数类型自动检测和处理
• 日志记录：调试参数问题的全面日志记录

示例用法

{
  "jobFullName": "my-parameterized-job",
  "parameters": {
    "BRANCH": "main",
    "DEBUG_MODE": true,
    "ENVIRONMENT": "production",
    "FEATURES": ["feature1", "feature2"],
    "NOTES": "Build triggered via MCP"
  }
}

扩展MCP功能

要添加新的MCP工具或功能：

1. 创建一个类来实现 McpServerExtension.
2. 使用 @Tool 将方法作为MCP工具公开。
3. 使用 @ToolParam 定义和描述刀具参数。

例子：

@Extension
public class MyCustomMcpExtension implements McpServerExtension {
	@Tool(description = "My custom tool")
	public String myCustomTool(@ToolParam(description = "Input parameter") String input) {
		// Tool implementation
	}
}

结果处理

MCP服务器插件使用以下方法处理各种结果类型：

• 列出结果：列表中的每个元素在响应中都转换为单独的文本内容项。
• 单个对象：整个对象转换为单个文本内容项。

对于文本内容的序列化：

• @ExportedBean注释：如果结果对象被注释为 @ExportedBean （从 org.kohsuke.stapler.export)詹金斯 org.kohsuke.stapler.export.Flavor.JSON 使用导出机制。
• 其他对象：对于没有 @ExportedBean 注释，Jackson用于JSON序列化。

这种方法确保了灵活高效地处理不同的结果类型，既能容纳Jenkins特定的导出对象，也能容纳标准Java对象。 这种灵活的方法确保了工具结果在MCP响应中得到一致和准确的表示，无论其复杂性如何。

与GitHub Copilot集成

MCP服务器插件与GitHub Copilot无缝集成，通过在IDE中提供对Jenkins信息的直接访问来增强您的开发体验。这种集成允许您使用自然语言查询与Jenkins作业和构建进行交互。

如截图所示：

1. 你可以向Copilot询问使用自然语言的Jenkins作业，例如“在根目录下列出Jenkins作业”。
2. Copilot使用MCP服务器获取和显示有关Jenkins作业的信息，在根目录下列出作业。
3. 您还可以请求特定信息，例如“获取作业a的最后一个构建状态”，Copilot将提供相关详细信息，包括构建号、状态和URL。

这种集成简化了您的工作流程，允许您在不离开开发环境的情况下访问Jenkins信息。

更多信息

有关模型上下文协议及其Java SDK的更多详细信息：

• MCP简介
• MCP Java SDK服务器组件

贡献

欢迎对MCP服务器插件做出贡献。请参阅 Jenkins贡献指南 了解更多信息。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。