Ilert MCP Connector

ilert MCP连接器

一个HTTP服务器，通过REST端点从内部工具（Kafka、MySQL）公开信息。设计用于ilert和MCP服务器。

特性

• 健康和准备终点：Kubernetes已准备就绪 /health 和 /ready 端点
• Kafka集成：列出主题、描述主题、管理消费者组和监控消费者延迟
• MySQL集成：查询数据库、表、模式和度量
• ClickHouse集成：查询数据库、表、模式和度量
• Redis集成：查询数据库、扫描密钥、获取密钥信息和监控指标
• 可配置的：通过环境变量单独启用/禁用工具
• 普罗米修斯指标: /metrics 监控端点（无需身份验证）
• 结构化日志记录：使用具有可配置日志级别和格式的zerolog
• Docker支持：容器化并准备好进行Kubernetes部署

端点

健康与准备

• GET /health -健康检查端点（公共-无需身份验证）
• GET /ready -就绪检查端点（验证与已启用工具的连接）- 需要身份验证
• GET /version -版本信息端点（返回版本和提交）（公共-无需身份验证）
• GET /metrics -Prometheus度量端点（公共-无需授权）

认证

以下端点需要通过身份验证 Authorization 头球

• /ready -就绪检查端点（包含连接状态和潜在错误消息）
• 全部 /kafka/* 端点
• 全部 /mysql/* 端点
• 全部 /clickhouse/* 端点
• 全部 /redis/* 端点

令牌可以通过两种方式提供：

1. 环境变量：设置 AUTH_TOKEN 带有所需令牌的环境变量
2. 自动生成：如果 AUTH_TOKEN 如果未设置，将在启动时生成并记录一个随机的64字符十六进制令牌

用途：

# Using Bearer token format
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8383/kafka/topics

# Or without Bearer prefix
curl -H "Authorization: YOUR_TOKEN" http://localhost:8383/kafka/topics

Kafka端点（当 KAFKA_ENABLED=true) - 需要身份验证

• GET /kafka/topics -列出所有Kafka主题
• GET /kafka/topics/:topic -描述一个特定的主题
• GET /kafka/consumers -列出所有消费者群体
• GET /kafka/consumers/:group -描述一个特定的消费者群体
• GET /kafka/consumers/:group/lag -获得某个消费群体的消费滞后

MySQL端点（当 MYSQL_ENABLED=true) - 需要身份验证

• GET /mysql/databases -列出所有数据库
• GET /mysql/databases/:database/tables -列出数据库中的表
• GET /mysql/databases/:database/tables/:table -描述表模式
• GET /mysql/metrics -获取MySQL指标（InnoDB统计数据、全局状态、变量）

ClickHouse端点（当 CLICKHOUSE_ENABLED=true) - 需要身份验证

• GET /clickhouse/databases -列出所有数据库
• GET /clickhouse/databases/:database/tables -列出数据库中的表
• GET /clickhouse/databases/:database/tables/:table -用列和表信息描述表模式
• GET /clickhouse/metrics -获取ClickHouse状态和关键指标（system.metrics、system.events、system.asynchronous_metrics、副本、进程、合并、突变）

Redis端点（当 REDIS_ENABLED=true) - 需要身份验证

• GET /redis/databases -列出所有Redis数据库
• GET /redis/databases/:database/keys -扫描数据库中的密钥（支持 pattern 和 cursor 查询参数）
• GET /redis/databases/:database/keys/:key/info -获取特定密钥的详细信息（类型、TTL、大小、编码）
• GET /redis/info -获取Redis INFO输出作为键值对
• GET /redis/metrics -获取Redis指标（从INFO命令解析）

配置

配置是通过环境变量完成的：

服务器配置

• PORT -服务器端口（默认值： 8383)
• LOG_LEVEL -日志级别： debug, info, warn, error, fatal, panic （默认值： info)
• LOG_FORMAT -日志格式： json 对于JSON输出，或者对于漂亮控制台输出为空/任何其他值（默认值：漂亮控制台）
• AUTH_TOKEN -用于保护端点的身份验证令牌。如果未设置，将在启动时生成并记录随机令牌（默认值：自动生成）

Kafka配置

• KAFKA_ENABLED -启用Kafka端点（默认值： false)
• KAFKA_BROKERS -Kafka代理的逗号分隔列表（默认值： localhost:9092)
• KAFKA_CLIENT_ID -Kafka客户端ID（默认值： ilert-mcp-connector)
• KAFKA_AUTH_TYPE -身份验证类型： NONE, PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, SSL, SASL_SSL （默认值： NONE).不区分大小写，但建议大写。

- 如果 KAFKA_USERNAME 和 KAFKA_PASSWORD 提供，但 KAFKA_AUTH_TYPE 未设置，默认为 PLAIN

• KAFKA_USERNAME -SASL身份验证的Kafka用户名（必需 PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, SASL_SSL)
• KAFKA_PASSWORD -SASL身份验证的Kafka密码（需要 PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, SASL_SSL)
• KAFKA_SSL_CERT_LOCATION -客户端证书文件的路径（必需 SSL 和 SASL_SSL)
• KAFKA_SSL_KEY_LOCATION -客户端私钥文件的路径（需要 SSL 和 SASL_SSL)
• KAFKA_SSL_CA_LOCATION -CA证书文件的路径（可选，推荐）
• KAFKA_SSL_KEY_PASSWORD -加密私钥密码（可选）
• KAFKA_SSL_INSECURE_SKIP_TLS -跳过TLS证书验证（默认值： false，不建议用于生产）
• KAFKA_LOG_LEVEL -librdkafka日志级别： 0 （紧急情况） 7 （调试）（默认值： 6 -信息）。librdkafka日志与zerolog集成，并以与应用程序日志相同的格式显示。

MySQL 配置

• MYSQL_ENABLED -启用MySQL终结点（默认值： false)
• MYSQL_HOST -MySQL主机（默认： localhost)
• MYSQL_PORT -MySQL端口（默认： 3306)
• MYSQL_USER -MySQL用户（默认值： root)
• MYSQL_PASSWORD -MySQL密码（默认值：空）
• MYSQL_DATABASE -MySQL数据库名称（默认值：空）

MySQL用户设置

MCP连接器需要具有特定只读权限的MySQL用户。连接器执行以下操作：

• SHOW DATABASES -列出所有数据库
• SHOW TABLES FROM -列出数据库中的表
• DESCRIBE . -获取表架构
• SHOW TABLE STATUS -获取表元数据
• SHOW STATUS / SHOW GLOBAL STATUS -获取MySQL状态变量
• SHOW VARIABLES / SHOW GLOBAL VARIABLES -获取MySQL配置变量
• SHOW PROCESSLIST -查看当前查询和连接
• SHOW SLAVE STATUS / SHOW MASTER STATUS -查看复制状态
• SHOW ENGINE INNODB STATUS -查看InnoDB状态和锁定信息

所需权限：

用户需要以下权限：

1. 过程 -需要 SHOW PROCESSLIST 和 SHOW ENGINE INNODB STATUS
2. 复制客户端 -需要 SHOW SLAVE STATUS 和 SHOW MASTER STATUS
3. 选择 -需要 SHOW DATABASES, SHOW TABLES, DESCRIBE，以及 SHOW TABLE STATUS 在要查询的数据库上

注： 以下操作无需额外权限即可工作：

• SHOW STATUS / SHOW GLOBAL STATUS -适用于所有用户
• SHOW VARIABLES / SHOW GLOBAL VARIABLES -适用于所有用户

重要提示： SHOW DATABASES 仅显示用户具有权限的数据库。要查看和查询数据库，您需要授予它们SELECT权限。

SQL脚本示例：

-- Create the user
CREATE USER IF NOT EXISTS 'ilert_mcp_connector'@'%' IDENTIFIED BY 'your_secure_password_here';

-- Grant global privileges for monitoring
GRANT PROCESS ON *.* TO 'ilert_mcp_connector'@'%';
GRANT REPLICATION CLIENT ON *.* TO 'ilert_mcp_connector'@'%';

-- Grant SELECT on all databases (read-only access)
-- Option 1: Grant on all databases
GRANT SELECT ON *.* TO 'ilert_mcp_connector'@'%';

-- Option 2: Grant on specific databases only (more secure)
-- GRANT SELECT ON `database1`.* TO 'ilert_mcp_connector'@'%';
-- GRANT SELECT ON `database2`.* TO 'ilert_mcp_connector'@'%';

-- Apply changes
FLUSH PRIVILEGES;

-- Verify grants
SHOW GRANTS FOR 'ilert_mcp_connector'@'%';

安全说明：

• SELECT 权限是只读的-用户无法修改数据
• 为了获得最大的安全性，仅在需要监视的特定数据库上授予SELECT
• 如果需要监视所有数据库，请使用 GRANT SELECT ON *.*

ClickHouse配置

• CLICKHOUSE_ENABLED -启用ClickHouse端点（默认值： false)
• CLICKHOUSE_HOST -ClickHouse主机（默认： localhost)
• CLICKHOUSE_PORT -ClickHouse端口（默认： 9000)
• CLICKHOUSE_USER -ClickHouse用户（默认值： default)
• CLICKHOUSE_PASSWORD -ClickHouse密码（默认值：空）
• CLICKHOUSE_DATABASE -ClickHouse数据库名称（默认值： default)

Redis 配置

• REDIS_ENABLED -启用Redis端点（默认值： false)
• REDIS_HOST -Redis主机（默认： localhost)
• REDIS_PORT -Redis端口（默认： 6379)
• REDIS_PASSWORD -Redis密码（默认为空）

建筑

使用Make（推荐）

# Build the application
make build

# Build and start the server
make start

# Run the application (without building)
make run

# Show all available commands
make help

手动构建

go build -o ilert-mcp-connector .

本地运行

# Set environment variables
export KAFKA_ENABLED=true
export KAFKA_BROKERS=localhost:9092
export KAFKA_AUTH_TYPE=PLAIN
export KAFKA_USERNAME=myuser
export KAFKA_PASSWORD=mypassword
export MYSQL_ENABLED=true
export MYSQL_HOST=localhost
export MYSQL_USER=root
export MYSQL_PASSWORD=password

# Run the server
./ilert-mcp-connector

码头工人

构建Docker镜像

使用Make：

make docker-build
# Or with custom version
make docker-build VERSION=1.0.0 DOCKER_TAG=1.0.0

手动构建：

docker build -t ilert-mcp-connector .

运行Docker容器

使用Make：

make docker-run
# Or with custom port
make docker-run PORT=8383

手动运行：

docker run -p 8383:8383 \
  -e KAFKA_ENABLED=true \
  -e KAFKA_BROKERS=kafka1:9092,kafka2:9092 \
  -e KAFKA_AUTH_TYPE=PLAIN \
  -e KAFKA_USERNAME=myuser \
  -e KAFKA_PASSWORD=mypassword \
  -e MYSQL_ENABLED=true \
  -e MYSQL_HOST=mysql \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=password \
  ilert-mcp-connector

Kubernetes部署

Kubernetes部署示例：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ilert-mcp-connector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ilert-mcp-connector
  template:
    metadata:
      labels:
        app: ilert-mcp-connector
    spec:
      containers:
      - name: ilert-mcp-connector
        image: ghcr.io/ilert/ilert-mcp-connector:latest
        ports:
        - containerPort: 8383
        env:
        - name: PORT
          value: "8383"
        - name: KAFKA_ENABLED
          value: "true"
        - name: KAFKA_BROKERS
          value: "kafka:9092"
        - name: KAFKA_AUTH_TYPE
          value: "PLAIN"
        - name: KAFKA_USERNAME
          valueFrom:
            secretKeyRef:
              name: kafka-secret
              key: username
        - name: KAFKA_PASSWORD
          valueFrom:
            secretKeyRef:
              name: kafka-secret
              key: password
        - name: MYSQL_ENABLED
          value: "true"
        - name: MYSQL_HOST
          value: "mysql"
        - name: MYSQL_USER
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: username
        - name: MYSQL_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: password
        livenessProbe:
          httpGet:
            path: /health
            port: 8383
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8383
          initialDelaySeconds: 5
          periodSeconds: 5
          # Note: /ready endpoint requires authentication and contains sensitive connection info
          # Use /health for Kubernetes probes, or configure httpHeaders with Authorization token
---
apiVersion: v1
kind: Service
metadata:
  name: ilert-mcp-connector
spec:
  selector:
    app: ilert-mcp-connector
  ports:
  - port: 8383
    targetPort: 8383

版本控制

服务器版本在构建时使用Go设置 -ldflags 并在启动时登录。该版本与GitHub标签和Docker镜像标签同步。

使用版本构建

在本地构建时，您可以设置版本：

使用Make：

make build VERSION=1.0.0

手动构建：

go build -ldflags "-X main.Version=1.0.0 -X main.Commit=$(git rev-parse --short HEAD)" -o ilert-mcp-connector .

Docker构建

Dockerfile接受版本信息的构建参数：

• VERSION -版本字符串（默认值： dev)
• COMMIT -Git提交哈希（默认值： unknown)

GitHub操作

该仓库包含一个GitHub Actions工作流，在以下情况下会自动构建Docker镜像并将其推送到GitHub容器注册表：

• 以开头的标签 v 被推动（例如。， v1.0.0)
• 使用自定义标记手动触发工作流

工作流会自动执行以下操作：

• 从Git标签中提取版本（删除 v 前缀（如果存在）
• 设置版本并将SHA作为构建参数提交
• 使用语义版本标签标记Docker镜像

图像标记为：

• 语义版本标签（例如。， v1.0.0, v1.0, v1)
• 分支推送的分支名称
• latest 对于默认分支

该版本在服务器启动时登录，可通过 /version 终点。

发展

测试

# Run all tests
make test

# Run tests without race detector (faster)
make test-short

# Run tests with coverage report
make test-coverage

代码质量

# Format code
make fmt

# Run go vet
make vet

# Run all checks (fmt, vet, test)
make check

# Run full CI pipeline locally
make ci

开发流程

# Download dependencies
make deps

# Format and check code
make fmt vet

# Run tests
make test

# Build and run locally
make start

# Or run without building first
make run