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基础设施管理的重要工具。