MCP服务器插件

Name: MCP服务器插件
Author: jenkinsci

作者：jenkinsci41 星标更新：2025-11-09

安装使用来源：spider==github.com

项目介绍

MCP Server Plugin for Jenkins

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

功能

MCP服务器实现：实现了模型上下文协议的服务器端。
Jenkins集成：暴露Jenkins功能作为MCP工具和资源。
可扩展架构：通过McpServerExtension接口轻松扩展MCP功能。

关键组件

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

MCP SDK 版本

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

快速开始

先决条件

Jenkins（版本2.479或更高）

配置

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

系统属性

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

最大日志行数限制：io.jenkins.plugins.mcp.server.extensions.BuildLogsExtension.limit.max=10000（默认值10000）

Origin头验证

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

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

使用

连接到MCP服务器

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

Streamable HTTP Endpoint: <jenkins-url>/mcp-server/mcp
SSE Endpoint: <jenkins-url>/mcp-server/sse
消息端点: <jenkins-url>/mcp-server/message

认证和凭证

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

Jenkins API Token：从您的Jenkins用户账户生成一个API令牌。
基本认证：在HTTP基本认证头中使用API令牌。

生成个人访问令牌

要生成个人访问令牌：

登录Jenkins。
在右上角选择您的用户图标，然后选择安全。
选择添加新令牌。
输入一个名称以区分令牌，然后选择生成。
复制令牌并将其存储在一个安全的位置以备后用。

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

选择完成以添加令牌。
选择保存以保存更改。

对HTTP基本认证进行编码

使用个人访问令牌通过基本HTTP认证与MCP代理进行认证。

要在Linux、macOS或Windows上进行编码：

打开终端并运行以下命令，将<username>和<token>替换为您实际的用户名和在Jenkins中生成的个人访问令牌。

Linux或macOS

echo -n "<username>:<token>" | base64

Windows (PowerShell)

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("<username>:<token>"))

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

dXNlcm5hbWU6dG9rZW4=

将编码的凭证存储在一个安全的位置以备后用。

[!注意] Base64编码不是加密。任何人都可以解码并获取您的凭证。始终像对待原始用户名和令牌一样保护编码的凭证。

示例客户端配置

客户端配置

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

Copilot配置

目前，Copilot与Streamable传输配合不佳，我仍在调查问题。请继续使用SSE端点。

{
  "mcp": {
    "servers": {
      "jenkins": {
        "type": "sse",
        "url": "https://jenkins-host/mcp-server/sse",
        "headers": {
          "Authorization": "Basic <user:token base64>"
        }
      }
    }
  }
}

Streamable示例：

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Basic <user:token base64>"
        }
      }
    }
  }
}

Windsurf配置

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

Claude

claude mcp add http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic <user:token base64>"

Goose

点击*“添加自定义扩展”*
给它一个有意义的名字
在类型下拉菜单中选择*“Streamable HTTP”*
输入端点URL。这应该是类似http://jenkins-host/mcp-server/mcp的内容
滚动到*“请求头”*
在空白字段中输入Authorization作为名称。然后在值字段中输入“Basic <user:token base64>”
点击*"添加"*
点击*“添加扩展”*

可用工具

插件提供了以下内置工具，用于与Jenkins交互：

作业管理

getJob：通过其完整路径获取Jenkins作业。
getJobs：获取按名称排序的Jenkins作业分页列表。
triggerBuild：触发作业的构建。此工具支持参数化构建。您可以提供参数作为JSON对象，其中每个键都是参数名称。例如：
```
{
  "jobFullName": "my-job",
  "parameters": {
    "BRANCH": "main",
    "DEBUG_MODE": "true"
  }
}
```
参数说明：
- 核心Jenkins参数：完全支持（字符串、布尔值、选择、文本、密码、运行）
- 插件参数：自动检测并使用反射处理
- 文件参数：不支持通过MCP（需要文件上传）
- 多选参数：支持数组或列表
- 自定义插件参数：尝试使用基于反射的检测
- 回退行为：不支持的参数回退到默认值，并记录日志

构建信息

getBuild：检索特定构建或Jenkins作业的最后一个构建。
updateBuild：更新构建显示名称和/或描述。
getBuildLog：为特定构建或最后一个构建检索带分页的日志行。
searchBuildLog：搜索与模式（字符串或正则表达式）匹配的日志行。

SCM集成

getJobScm：检索Jenkins作业的SCM配置。
getBuildScm：检索特定构建的SCM配置。
getBuildChangeSets：检索特定构建的变更集。

管理信息

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": "通过MCP触发构建"
  }
}

扩展MCP功能

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

创建一个实现McpServerExtension的类。
使用@Tool将方法暴露为MCP工具。
使用@ToolParam定义和描述工具参数。

示例：

@Extension
public class MyCustomMcpExtension implements McpServerExtension {
	@Tool(description = "我的自定义工具")
	public String myCustomTool(@ToolParam(description = "输入参数") String input) {
		// 工具实现
	}
}

结果处理

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

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

对于序列化为文本内容：

@ExportedBean注解：如果结果对象被@ExportedBean（来自org.kohsuke.stapler.export）注解，则使用Jenkins的org.kohsuke.stapler.export.Flavor.JSON导出机制。
其他对象：对于没有@ExportedBean注解的对象，使用Jackson进行JSON序列化。

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

与GitHub Copilot的集成

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

如截图所示：

您可以使用自然语言询问Copilot关于Jenkins作业的问题，例如，“列出根目录下的Jenkins作业”。
Copilot使用MCP服务器获取并显示Jenkins作业信息，列出根目录下的作业。
您还可以请求特定信息，例如，“获取作业a的最新构建状态”，Copilot将提供相关细节，包括构建编号、状态和URL。

此集成简化了您的工作流程，让您无需离开开发环境即可访问Jenkins信息。

贡献

欢迎对MCP服务器插件进行贡献。请参阅Jenkins贡献指南以获取更多信息。

许可

本项目根据MIT许可发布 - 详情见LICENSE文件。