使用说明

项目简介

Quarkus Backstage MCP CLI 是 Quarkus Backstage 扩展的一部分，它通过命令行界面 (CLI) 提供 MCP (Model Context Protocol) 服务器功能。此 MCP 服务器允许 LLM 客户端通过标准化的 JSON-RPC 协议，访问由 Backstage 管理的实体和模板信息，从而实现上下文感知和功能扩展。

主要功能点

实体查询：允许 LLM 客户端通过 MCP 协议请求查询 Backstage catalog 中的实体信息，例如组件、API 等。
模板实例化：支持 LLM 客户端通过 MCP 协议触发 Backstage Scaffolder 模板的实例化流程，从而自动化应用或组件的创建。
标准 MCP 协议：基于 JSON-RPC over Stdio 实现 MCP 服务器，方便集成到各种支持 MCP 协议的 LLM 应用或工具中。
CLI 插件形式：以 Quarkus CLI 插件的形式提供，易于安装和使用。

安装步骤

安装 Quarkus CLI 插件

打开终端，运行以下命令以安装 'quarkus-backstage-cli' 插件到 Quarkus CLI：

quarkus plug add io.quarkiverse.backstage:quarkus-backstage-cli:{版本号或最新快照版本，例如 999-SNAPSHOT}

请将 '{版本号或最新快照版本}' 替换为实际的版本号或快照版本。

配置 Backstage 后端连接

MCP CLI 需要连接到 Backstage 后端才能工作。您可以通过以下方式配置连接信息：
- 环境变量: 设置 'QUARKUS_BACKSTAGE_URL' 和 'QUARKUS_BACKSTAGE_TOKEN' 环境变量，分别指向 Backstage 后端 URL 和 Service to Service 通信令牌。
- application.properties: 在 'application.properties' 文件中配置 'quarkus.backstage.url' 和 'quarkus.backstage.token' 属性。

服务器配置

MCP 客户端需要配置以下 JSON 格式信息以连接到 Quarkus Backstage MCP CLI 服务器。以下是一个通用的配置示例：

{
  "serverName": "backstage-mcp-cli",
  "type": "stdio",
  "enabled": true,
  "cmd": "quarkus",
  "args": [
    "backstage",
    "mcp"
  ],
  "envs": {
    "QUARKUS_BACKSTAGE_URL": "{Backstage 后端 API URL}",
    "QUARKUS_BACKSTAGE_TOKEN": "{Backstage Service to Service Token}"
  }
}

参数说明:

'serverName': 服务器名称，客户端用于标识连接。例如: "backstage-mcp-cli"。
'type': 传输协议类型，固定为 "stdio" (标准输入输出流)。
'enabled': 是否启用该服务器连接，设置为 'true' 以启用。
'cmd': 启动 MCP 服务器的命令，这里是 'quarkus'，假设 'quarkus' 命令已添加到系统 PATH 环境变量中。
'args': 传递给 'quarkus' 命令的参数，'["backstage", "mcp"]' 用于启动 Backstage MCP CLI。
'envs': 环境变量配置，用于配置 MCP CLI 连接 Backstage 后端所需的 URL 和 Token。
- 'QUARKUS_BACKSTAGE_URL': [必填] Backstage 后端 API 的 URL 地址，例如 'http://localhost:7007'。
- 'QUARKUS_BACKSTAGE_TOKEN': [必填] 用于 Service to Service 身份验证的 Backstage 后端令牌。

注意:

请将 '{Backstage 后端 API URL}' 和 '{Backstage Service to Service Token}' 替换为实际的 Backstage 后端地址和令牌。
确保执行 MCP 客户端的运行环境可以访问 'quarkus' 命令。

基本使用方法

启动 MCP 服务器

当 MCP 客户端尝试连接时，Quarkus Backstage MCP CLI 服务器会通过标准输入输出流启动。无需手动启动服务器，它会根据客户端的连接请求自动启动。

客户端请求示例

LLM 客户端可以使用 JSON-RPC 协议通过标准输入流向 MCP 服务器发送请求。例如，列出所有组件类型的实体的 JSON-RPC 请求可能如下所示：

{
  "jsonrpc": "2.0",
  "method": "listEntities",
  "params": {
    "kind": "Component"
  },
  "id": 1
}

MCP 服务器会将响应通过标准输出流返回给客户端。

支持的 MCP Actions:

目前，Quarkus Backstage MCP CLI 服务器主要支持以下 actions：

'listEntities': 列出指定类型的实体。
'instantiateTemplate': 实例化指定的 Backstage 模板。

更多详细的 API 使用方法，请参考 Quarkus Backstage 扩展和 MCP 协议的官方文档。

关键词