Login
Kong/mcp-konnectPlease refer to the latest official releases for information GitHub Homepage

用於與 Kong Konnect API 互動的模型上下文協議 (MCP) 伺服器，允許 AI 助手查詢和分析 Kong 閘道配置、流量和分析數據

Apache-2.0TypeScript 32Kongmcp-konnect Last Updated: 2025-04-08

Kong MCP-Konnect 項目詳細介紹

項目概述

Kong MCP-Konnect 是一個基於模型上下文協議（Model Context Protocol, MCP）的伺服器項目，允許 AI 助手查詢和分析 Kong Gateway 配置、流量和分析數據。該項目使得像 Claude 這樣的 AI 助手能夠通過自然語言與 Kong Konnect 的 API 網關進行交互。

核心特性

  • API 請求分析查詢：支持自定義過濾器的 API 請求分析
  • 網關配置管理：列出和檢查網關服務、路由、消費者和插件
  • 控制平面管理：管理控制平面和控制平面組
  • AI 助手集成：與 Claude 和其他兼容 MCP 的 AI 助手集成

項目結構

src/
├── index.ts            # 主入口點
├── api.ts             # Kong API 客戶端
├── tools.ts           # 工具定義
├── parameters.ts      # 工具參數的 Zod 模式
├── prompts.ts         # 詳細的工具文檔
├── operations/
│   ├── analytics.ts   # API 請求分析操作
│   ├── configuration.ts # 服務、路由、消費者、插件
│   └── controlPlanes.ts # 控制平面管理
└── types.ts           # 通用類型定義

系統要求

  • Node.js 20 或更高版本
  • 具有 API 訪問權限的 Kong Konnect 賬戶
  • 支持 MCP 功能的客戶端（如 Claude Desktop、Cursor 等）

安裝和配置

1. 克隆和安裝

# 克隆倉庫
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# 安裝依賴
npm install

# 構建項目
npm run build

2. 環境配置

設置以下環境變量來配置 MCP 伺服器：

# 必需：您的 Kong Konnect API 密鑰
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# 可選：要使用的 API 區域（默認為 US）
# 可能的值：US, EU, AU, ME, IN
export KONNECT_REGION=us

可用工具

分析工具

1. API 請求分析（analyze-api-requests）

查詢和分析 Kong API 網關請求，支持自定義過濾器。

輸入參數：

  • timeRange: 數據檢索的時間範圍（15M, 1H, 6H, 12H, 24H, 7D）
  • statusCodes: 按特定 HTTP 狀態碼過濾
  • excludeStatusCodes: 排除特定 HTTP 狀態碼
  • httpMethods: 按 HTTP 方法過濾
  • consumerIds: 按消費者 ID 過濾
  • serviceIds: 按服務 ID 過濾
  • routeIds: 按路由 ID 過濾
  • maxResults: 返回的最大結果數

2. 消費者請求分析（analyze-consumer-requests）

分析特定消費者發出的 API 請求。

輸入參數：

  • consumerId: 要分析的消費者 ID
  • timeRange: 數據檢索的時間範圍
  • successOnly: 僅顯示成功的（2xx）請求
  • failureOnly: 僅顯示失敗的（非2xx）請求
  • maxResults: 返回的最大結果數

配置工具

1. 列出服務（list-services）

列出與控制平面關聯的所有服務。

輸入參數：

  • controlPlaneId: 控制平面 ID
  • size: 返回的服務數量
  • offset: 分頁偏移令牌

2. 列出路由（list-routes）

列出與控制平面關聯的所有路由。

3. 列出消費者（list-consumers）

列出與控制平面關聯的所有消費者。

4. 列出插件（list-plugins）

列出與控制平面關聯的所有插件。

控制平面管理工具

1. 列出控制平面（list-control-planes）

列出組織中的所有控制平面。

輸入參數：

  • pageSize: 每頁的控制平面數量
  • pageNumber: 要檢索的頁碼
  • filterName: 按名稱過濾控制平面
  • filterClusterType: 按集群類型過濾
  • filterCloudGateway: 按雲網關功能過濾
  • labels: 按標籤過濾
  • sort: 排序字段和方向

2. 獲取控制平面（get-control-plane）

獲取特定控制平面的詳細信息。

3. 列出控制平面組成員（list-control-plane-group-members）

列出特定組的所有控制平面成員。

4. 檢查控制平面組成員身份（check-control-plane-group-membership）

檢查控制平面是否為任何組的成員。

與 Claude 集成使用

1. 安裝 Claude for Desktop

從Claude 官網下載並安裝 Claude for Desktop。

2. 配置 Claude Desktop

創建或編輯 Claude Desktop 配置文件：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

3. 添加配置

{
  "mcpServers": {
    "kong-konnect": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-konnect/build/index.js"
      ],
      "env": {
        "KONNECT_ACCESS_TOKEN": "kpat_api_key_here",
        "KONNECT_REGION": "us"
      }
    }
  }
}

4. 重啟 Claude for Desktop

重啟後，Kong Konnect 工具將可供 Claude 使用。

示例工作流程

1. 列出所有控制平面

請列出我的 Kong Konnect 組織中的所有控制平面。

2. 列出特定控制平面的服務

列出控制平面[CONTROL_PLANE_NAME/ID]的所有服務。

3. 查詢特定服務的 API 請求

向我顯示服務[SERVICE_NAME/ID]在過去一小時內所有具有 5xx 狀態碼的 API 請求。

4. 列出控制平面的消費者

列出控制平面[CONTROL_PLANE_NAME/ID]的所有消費者。

5. 分析特定消費者的請求

向我顯示消費者[CONSUMER_NAME/ID]在過去 24 小時內發出的所有請求。

6. 檢查常見錯誤或模式

這個消費者遇到的最常見錯誤是什麼？

開發指南

要添加新工具，請按以下步驟操作：

  1. 在parameters.ts中定義參數
  2. 在prompts.ts中添加文檔
  3. 在operations/中的適當文件中創建操作邏輯
  4. 在tools.ts中註冊工具
  5. 在index.ts中處理工具執行

故障排除

連接錯誤

  • 驗證您的 API 密鑰有效且具有必要權限
  • 檢查 API 區域是否正確指定
  • 確保您的網絡可以連接到 Kong Konnect API

身份驗證錯誤

  • 在 Kong Konnect 門戶中重新生成您的 API 密鑰
  • 檢查環境變量是否正確設置

數據未找到

  • 驗證請求中使用的 ID 是否正確
  • 檢查資源是否存在於指定的控制平面中
  • 確保分析查詢的時間範圍有效

總結

Kong MCP-Konnect 是一個強大的工具，它橋接了 AI 助手和 Kong API 網關管理之間的差距。通過提供自然語言接口來查詢和分析 API 網關配置、流量和分析數據，它使得 API 管理變得更加直觀和高效。項目提供了豐富的功能集，從基本的配置查詢到高級的流量分析，是現代 API 基礎設施管理的重要工具。

Star History Chart