Kong Konnect MCP 服务器

这是一个用于与 Kong Konnect API 交互的 Model Context Protocol (MCP) 服务器，允许 AI 助手查询和分析 Kong Gateway 的配置、流量和分析数据。

https://github.com/user-attachments/assets/19c2f716-49b5-46c3-9457-65b3784e2111

目录

• 概述
• 项目结构
• 安装
• 配置
• 可用工具
  • 分析工具
  • 配置工具
  • 控制平面工具
• 与 Claude 使用
• 示例工作流
• 开发
• 故障排除

概述

该项目提供了一个 Model Context Protocol (MCP) 服务器，使像 Claude 这样的 AI 助手能够与 Kong Konnect 的 API 网关进行交互。它提供了一组工具，可以通过自然语言对话来查询分析数据、检查配置细节以及管理控制平面。

主要功能：

• 通过可自定义的过滤器查询 API 请求分析
• 列出并检查网关服务、路由、消费者和插件
• 管理控制平面和控制平面组
• 与 Claude 和其他支持 MCP 的 AI 助手集成

Konnect MCP 是一个正在进行中的工作，我们将在每次发布中添加更多功能和改进。

项目结构

src/
├── index.ts              # Main entry point
├── api.ts                # Kong API client
├── tools.ts              # Tool definitions
├── parameters.ts         # Zod schemas for tool parameters
├── prompts.ts            # Detailed tool documentation
├── operations/
│   ├── analytics.ts      # API request analytics operations
│   ├── configuration.ts  # Services, routes, consumers, plugins
│   └── controlPlanes.ts  # Control plane management
└── types.ts              # Common type definitions

安装

前提条件

• Node.js 20 或更高版本
• 具有 API 访问权限的 Kong Konnect 账户
• 支持 MCP 的客户端（例如 Claude Desktop, Cursor 等）

设置

# Clone the repository
git clone https://github.com/Kong/mcp-konnect.git
cd mcp-konnect

# Install dependencies
npm install

# Build the project
npm run build

配置

设置以下环境变量以配置 MCP 服务器：

# Required: Your Kong Konnect API key
export KONNECT_ACCESS_TOKEN=kpat_api_key_here

# Optional: The API region to use (defaults to US)
# Possible values: US, EU, AU, ME, IN
export KONNECT_REGION=us

可用工具

服务器提供的工具分为三类：

分析工具

查询 API 请求

通过可自定义的过滤器查询和分析 Kong API 网关请求。

Inputs:
- timeRange: Time range for data retrieval (15M, 1H, 6H, 12H, 24H, 7D)
- statusCodes: Filter by specific HTTP status codes
- excludeStatusCodes: Exclude specific HTTP status codes
- httpMethods: Filter by HTTP methods
- consumerIds: Filter by consumer IDs
- serviceIds: Filter by service IDs
- routeIds: Filter by route IDs
- maxResults: Maximum number of results to return

获取消费者请求

分析特定消费者发出的 API 请求。

Inputs:
- consumerId: ID of the consumer to analyze
- timeRange: Time range for data retrieval
- successOnly: Show only successful (2xx) requests
- failureOnly: Show only failed (non-2xx) requests
- maxResults: Maximum number of results to return

配置工具

列出服务

列出与控制平面关联的所有服务。

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of services to return
- offset: Pagination offset token

列出路由

列出与控制平面关联的所有路由。

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of routes to return
- offset: Pagination offset token

列出消费者

列出与控制平面关联的所有消费者。

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of consumers to return
- offset: Pagination offset token

列出插件

列出与控制平面关联的所有插件。

Inputs:
- controlPlaneId: ID of the control plane
- size: Number of plugins to return
- offset: Pagination offset token

控制平面工具

列出控制平面

列出组织中的所有控制平面。

Inputs:
- pageSize: Number of control planes per page
- pageNumber: Page number to retrieve
- filterName: Filter control planes by name
- filterClusterType: Filter by cluster type
- filterCloudGateway: Filter by cloud gateway capability
- labels: Filter by labels
- sort: Sort field and direction

获取控制平面

获取特定控制平面的详细信息。

Inputs:
- controlPlaneId: ID of the control plane to retrieve

列出控制平面组成员

列出属于特定组的所有控制平面。

Inputs:
- groupId: Control plane group ID
- pageSize: Number of members to return per page
- pageAfter: Cursor for pagination

检查控制平面组成员资格

检查控制平面是否属于任何组。

Inputs:
- controlPlaneId: Control plane ID to check

与 Claude 使用

要将此 MCP 服务器与 Claude for Desktop 一起使用：

1. 安装 Claude for Desktop

2. 创建或编辑 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"
      }
    }
  }
}

1. 重启 Claude for Desktop
2. Kong Konnect 工具现在可供 Claude 使用

示例工作流

分析 API 流量

1. 首先，列出所有控制平面：

   请列出我 Kong Konnect 组织中的所有控制平面。
   

2. 然后，为特定的控制平面列出服务：

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

3. 查询特定服务的 API 请求：

   显示过去一小时内服务 [SERVICE_NAME/ID] 中状态码为 5xx 的所有 API 请求。
   

解决消费者问题

1. 列出控制平面的消费者：

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

2. 分析特定消费者的请求：

   显示过去 24 小时内由消费者 [CONSUMER_NAME/ID] 发起的所有请求。
   

3. 检查常见的错误或模式：

   这个消费者遇到的最常见的错误是什么？
   

开发

添加新工具

1. 在 parameters.ts 中定义参数
2. 在 prompts.ts 中添加文档
3. 在 operations/ 目录下的适当文件中创建操作逻辑
4. 在 tools.ts 中注册工具
5. 在 index.ts 中处理工具执行

故障排除

常见问题

连接错误

• 确认您的 API 密钥有效且具有必要的权限
• 检查是否正确指定了 API 区域
• 确保您的网络可以连接到 Kong Konnect API

认证错误

• 在 Kong Konnect 门户中重新生成您的 API 密钥
• 检查环境变量是否设置正确

找不到数据

• 确认请求中使用的 ID 是正确的
• 检查指定控制平面中是否存在资源
• 确保分析查询的时间范围有效

致谢

由 Kong 构建。受到 Stripe 的 Agent Toolkit 启发。