使用说明
🛠️ 可用的MCP工具
总计:22个工具 分为7类
📁 主题(4个工具)
| 工具 | 描述 | 参数 |
|---|---|---|
listTopics |
列出所有主题 | - |
describeTopic |
描述一个特定话题 | topic (字符串) |
createTopic |
创建一个新主题 | topic, partitions, replicationFactor |
deleteTopic |
删除主题 | topic (字符串) |
💬 消息(2个工具)
| 工具 | 描述 | 参数 |
|---|---|---|
consumeMessages |
从主题中消费消息 | topic, maxMessages?, timeout? |
produceMessage |
向主题发送消息 | topic, key?, value |
👥 消费者群体(2个工具)
| 工具 | 描述 | 参数 |
|---|---|---|
listConsumerGroups |
列出所有消费者组 | - |
describeConsumerGroup |
描述一个消费者组 | group (字符串) |
📊 集群监控(5种工具)
| 工具 | 描述 | 参数 |
|---|---|---|
getClusterInfo |
集群信息(代理服务器,控制器) | - |
describeBroker |
配置代理服务器 | brokerId (数字) |
getClusterMetrics |
集群健康指标 | - |
analyzeTopicPartitions |
带偏移量的分区分析 | topic (字符串) |
checkClusterHealth |
完整诊断及建议 | - |
🔍 集群模式与平台(1个工具)🆕
| 工具 | 描述 | 参数 |
|---|---|---|
detectClusterMode |
检测KRaft/Zookeeper + 平台(Strimzi/Confluent/Apache/MSK) | - |
📈 Prometheus 指标(2个工具)🆕
| 工具 | 描述 | 参数 |
|---|---|---|
getPrometheusMetrics |
从Prometheus获取Kafka指标 | - |
getBrokerPrometheusMetrics |
代理指标(吞吐量、CPU、RAM) | brokerId (数字) |
📋 模式注册表(8个工具)🆕
| 工具 | 描述 | 参数 |
|---|---|---|
getSchemaRegistryInfo |
Schema Registry 信息 | - |
listSchemaSubjects |
列出所有主题 | - |
getSchemaDetails |
图案的详细信息 | subject, version? |
listSchemaVersions |
主题的所有版本 | subject |
registerSchema |
记录新方案 | subject, schema, schemaType? |
checkSchemaCompatibility |
检查兼容性 | subject, schema, version? |
deleteSchemaVersion |
删除版本 | subject, version |
deleteSchemaSubject |
删除整个主题 | subject |
⚠️ 常见错误:“JSON输入意外结束”
症状 :
SyntaxError: Unexpected token '.', " . ____ "... is not valid JSON
原因 Spring Boot 的横幅或日志会污染标准输出。
解决方案 ✅ 已在此项目中通过以下方式修正:
spring.main.banner-mode: off在`application# Kafka MCP Server v2.0 - Spring Boot 版本中
一个用于Kafka的现代MCP(模型上下文协议)服务器,开发采用 Spring Boot 3.2 和 Spring AI MCP(注:MCP在此处可能是一个特定上下文或项目中的缩写,没有直接的中文对应,因此保持原样).
🚀 版本2.0新特性
- ✅(对号,表示正确、确认或完成) Spring Boot 3.2 - 现代且高性能的架构
- ✅ Spring AI MCP(注:此处“MCP”可能是一个特定上下文中的缩写或术语,没有具体上下文难以给出确切翻译,但一般可理解为“Machine Learning/Model Configuration Pipeline”等类似含义的缩写,具体需根据上下文确定。若“MCP”在此处为专有名词或特定项目名,则应保留原样或根据官方翻译进行调整。) - 注释
@Tool以实现原生集成 - ✅ 自动配置 - 通过简化配置
application.yml - ✅ 类型安全的DTO(数据传输对象) - 使用Lombok进行结构化响应
- ✅ 高级日志记录 - 操作的全程可追溯性
- ✅(这个符号在中文中通常表示“正确”、“对”或“确认”的意思,但直接翻译时没有对应的中文文字,因此保留原符号或根据上下文解释其含义) 优化后的容器 - 多阶段构建以实现轻量级Docker
📋 先决条件
- Java 17及以上版本 (用于地方发展)
- Maven 3.9+ (用于本地构建)
- Docker (用于容器化部署)
- 网络访问 在Kafka/Strimzi集群上
🏗️ 项目架构
文件夹结构
kafka-mcp-server/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/
│ │ │ └── carrefour/
│ │ │ └── kafka/
│ │ │ └── mcp/
│ │ │ ├── KafkaMcpServerApplication.java # Point d'entrée Spring Boot
│ │ │ ├── config/
│ │ │ │ └── KafkaConfig.java # Configuration Kafka (Admin, Producer, Consumer)
│ │ │ ├── tools/
│ │ │ │ └── KafkaMcpTools.java # Services MCP avec @Tool annotations
│ │ │ └── dto/
│ │ │ └── *.java # DTOs pour les réponses (Lombok)
│ │ └── resources/
│ │ └── application.yml # Configuration Spring Boot
│ └── test/
│ └── java/
│ └── com/carrefour/kafka/mcp/
│ └── KafkaMcpToolsTest.java # Tests unitaires
├── Dockerfile # Multi-stage Docker build
├── pom.xml # Dépendances Maven
├── docker-compose.yml # Configuration Docker Compose
└── README.md
分层架构
┌─────────────────────────────────────────┐
│ Claude Desktop / API │
│ (Client MCP via stdio) │
└────────────────┬────────────────────────┘
│ JSON-RPC over stdio
▼
┌─────────────────────────────────────────┐
│ Spring AI MCP Framework │
│ - Protocol handling (initialize, etc) │
│ - Tool discovery & invocation │
│ - JSON serialization │
└────────────────┬────────────────────────┘
│ @Tool methods
▼
┌─────────────────────────────────────────┐
│ KafkaMcpTools Service │
│ @Tool kafka_list_topics() │
│ @Tool kafka_describe_topic() │
│ @Tool kafka_create_topic() │
│ @Tool kafka_consume_messages() │
│ @Tool kafka_produce_message() │
│ etc... │
└────────────────┬────────────────────────┘
│ Uses
▼
┌─────────────────────────────────────────┐
│ Spring Kafka Components │
│ - KafkaAdmin (topic management) │
│ - KafkaTemplate (producing) │
│ - KafkaConsumer (consuming) │
│ - AdminClient (admin operations) │
└────────────────┬────────────────────────┘
│ Kafka Protocol
▼
┌─────────────────────────────────────────┐
│ Kafka/Strimzi Cluster │
│ bootstrap.dev.kafkahub...9431 │
└─────────────────────────────────────────┘
🔧 主要部件
1. KafkaMcpServer应用程序
使用注解的Spring Boot入口点:
@SpringBootApplication- 自动配置@EnableKafka- 启用Kafka支持
2. Kafka配置(KafkaConfig)
集中式Kafka配置:
- KafkaAdmin(可译为“Kafka管理器”或保持原样,具体取决于上下文是否需要更具体的翻译) 管理操作(创建/删除主题,描述组)
- 生产者工厂 消息生产者的工厂
- 消费者工厂 消息消费者工厂
- KafkaTemplate 简化生产的Spring模板
- 支持 SASL/SSL(简单认证安全层/安全套接字层) 通过属性进行安全配置
3. KafkaMcpTools(可译为“Kafka MCP工具”或根据具体上下文调整为更贴切的表述,如“Kafka多组件处理工具”等,但“KafkaMcpTools”本身作为专有名词或工具名称,直接保留原样在中文中也是可接受的)
带有注释的主要服务 @Tool Spring AI:
@Tool(name = "kafka_list_topics",
description = "Liste tous les topics Kafka disponibles")
public TopicListResponse listTopics() { ... }
@Tool(name = "kafka_consume_messages",
description = "Consomme des messages d'un topic")
public MessageListResponse consumeMessages(
@ToolParameter(description = "Nom du topic", required = true) String topic,
@ToolParameter(description = "Max messages", required = false) Integer maxMessages
) { ... }
特点 :
- 通过自动注入依赖项
@RequiredArgsConstructor - 使用SLF4J进行详细日志记录
- 使用try-catch实现强大的错误处理
- 结构化DTO的返回
4. DTOs(数据传输对象)
使用Lombok创建不可变类:
@Data- 自动的getter/setter方法@Builder- 流畅的模式构建器@NoArgsConstructor/@AllArgsConstructor- 建筑商
示例:
TopicListResponse- 主题列表MessageInfo- 消息详情ConsumerGroupDescriptionResponse- 消费者组的状态
🚀 安装与构建
⚠️ 重要提示 - MCP 协议和 stdout
MCP协议使用 仅用于JSON-RPC的标准输出所有日志都应发送至 标准错误输出(stderr)。
✅ 已在项目中配置 :
- Banner Spring Boot 已禁用(
banner-mode: off) - 日志重定向到 stderr 通过
logback-spring.xml - 没有在标准输出(stdout)上显示控制台输出
选项1:使用Docker构建(推荐)
# Clone le repository
git clone <your-repo>
cd kafka-mcp-server
# Build l'image Docker
docker build -t kafka-mcp-server:2.0.0 .
# L'image finale fait ~150MB (optimisée avec Alpine)
选项2:构建测试
# Exécuter le script de test (Linux/Mac)
chmod +x test-mcp-server.sh
./test-mcp-server.sh
# Le script vérifie:
# ✅ stdout contient uniquement du JSON
# ✅ 8 outils MCP sont exposés
# ✅ Connexion Kafka fonctionne
选项3:使用Maven构建
# Build le projet
mvn clean package
# Le JAR sera dans target/kafka-mcp-server-2.0.0.jar
java -jar target/kafka-mcp-server-2.0.0.jar
选项4:地方发展
# Avec Maven Wrapper
./mvnw spring-boot:run
# Ou avec Maven installé
mvn spring-boot:run
📦 配置
环境变量
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
KAFKA_BOOTSTRAP_SERVERS |
Kafka 代理的地址 | localhost:9092 |
✅ |
KAFKA_SECURITY_PROTOCOL |
安全协议 | PLAINTEXT |
❌ |
KAFKA_SASL_MECHANISM |
SASL 机制 | - | ❌ |
KAFKA_SASL_JAAS_CONFIG |
JAAS 配置 | - | ❌ |
application.yml
kafka:
bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVERS}
security-protocol: ${KAFKA_SECURITY_PROTOCOL:PLAINTEXT}
sasl-mechanism: ${KAFKA_SASL_MECHANISM:}
sasl-jaas-config: ${KAFKA_SASL_JAAS_CONFIG:}
spring:
ai:
mcp:
server:
enabled: true
transport: stdio
name: kafka-carrefour
🎯 使用
1. 使用Docker启动
基本配置(PLAINTEXT)
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431 \
kafka-mcp-server:2.0.0
使用SASL/SSL的配置
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=broker.prod.kafka.com:9093 \
-e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
-e KAFKA_SASL_MECHANISM=SCRAM-SHA-512 \
-e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="pass";' \
kafka-mcp-server:2.0.0
2. 配置Claude桌面版
编辑 ~/.config/Claude/claude_desktop_config.json (Linux/Mac) 或者 %APPDATA%\Claude\claude_desktop_config.json (Windows):
Linux/Mac 配置
{
"mcpServers": {
"kafka-carrefour": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--network=host",
"-e",
"KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431",
"kafka-mcp-server:2.0.0"
]
}
}
}
在Windows上配置WSL(Windows Subsystem for Linux)
{
"mcpServers": {
"kafka-carrefour": {
"command": "wsl",
"args": [
"--",
"docker",
"run",
"-i",
"--rm",
"--network=host",
"-e",
"KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431",
"kafka-mcp-server:2.0.0"
]
}
}
}
3. 重启Claude Desktop
# Sur Linux
killall claude
claude &
# Sur Mac
killall Claude
open -a Claude
# Sur Windows - relancer l'application manuellement
4. 检查连接
在Claude中,询问:
Quels sont les outils Kafka disponibles ?
您应该会看到列出的8个MCP工具。
🛠️ 可用的MCP工具
主题/话题
1. kafka_list_topics(Kafka列出主题)
列出集群中的所有主题。
参数 没有
示例 克劳德 :
Liste-moi tous les topics Kafka
回答 :
{
"topics": ["000", "002", "010", "transactions"],
"count": 4
}
2. Kafka描述主题(或:Kafka主题描述)
描述一个具有分区、副本和配置的主题。
参数 :
topic(字符串,必需):主题名称
示例 克劳德 :
Décris-moi le topic '000' en détail
回答 :
{
"name": "000",
"partitions": [
{
"partition": 0,
"leader": 1,
"replicas": [1, 2, 3],
"isr": [1, 2, 3]
}
],
"partitionCount": 3,
"isInternal": false,
"configurations": {
"retention.ms": "604800000",
"segment.bytes": "1073741824"
}
}
3. 创建Kafka主题
创建一个新主题。
参数 :
topic(字符串,必需):主题名称partitions(数字,可选):分区数量(默认:1)replicationFactor(数字,可选):复制因子(默认:1)
示例 克劳德 :
Crée un topic 'test-events' avec 3 partitions et un facteur de réplication de 2
回答 :
{
"topic": "test-events",
"created": true,
"partitions": 3,
"replicationFactor": 2,
"message": "Topic created successfully"
}
4. 删除Kafka主题
删除一个现有主题。
参数 :
topic(字符串,必填):主题名称
示例 克劳德 :
Supprime le topic 'old-logs'
信息
5. Kafka消费消息
从主题中消费消息。
参数 :
topic(字符串,必需):主题名称maxMessages(数字,可选):最大消息数(默认:10)timeout(数字,可选):毫秒超时时间(默认:5000)
示例 克劳德 :
Consomme 20 messages du topic 'transactions'
回答 :
{
"topic": "transactions",
"messages": [
{
"topic": "transactions",
"partition": 0,
"offset": 1234,
"key": "user-123",
"value": "{\"amount\": 99.99}",
"timestamp": 1698765432000
}
],
"count": 20
}
6. Kafka消息生产
向主题发布一条消息。
参数 :
topic(字符串,必需):主题名称key(字符串,可选):消息密钥value(字符串,必需):消息的值
示例 克劳德 :
Envoie un message de test avec la clé 'test-1' et la valeur '{"status":"ok"}' vers le topic 'events'
回答 :
{
"topic": "events",
"partition": 2,
"offset": 5678,
"timestamp": 1698765432000,
"success": true,
"message": "Message produced successfully"
}
消费者团体
7. kafka_list_consumer_groups(Kafka 列出消费者组)
列出所有消费者群体。
参数 :没有
示例 克劳德 :
Quels sont les consumer groups actifs ?
回答 :
{
"groups": ["app-consumer", "analytics-group"],
"count": 2
}
8. Kafka描述消费者组
描述一个消费者组及其成员。
参数 :
group(字符串,必填):消费者组的名称
示例 克劳德 :
Décris le consumer group 'app-consumer'
回答 :
{
"groupId": "app-consumer",
"state": "Stable",
"members": [
{
"memberId": "consumer-1-abc123",
"clientId": "consumer-1",
"host": "/192.168.1.10",
"assignment": ["events-0", "events-1"]
}
],
"memberCount": 1,
"coordinator": 1
}
🧪 测试与调试
使用JSON-RPC进行手动测试
# Test d'initialisation
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}' | \
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
kafka-mcp-server:2.0.0
# Test de listing des tools
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' | \
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
kafka-mcp-server:2.0.0
# Test d'appel d'un tool
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"kafka_list_topics","arguments":{}},"id":3}' | \
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
kafka-mcp-server:2.0.0
详细日志
# Capture des logs dans un fichier
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
kafka-mcp-server:2.0.0 2>&1 | tee mcp-server.log
# Les logs incluent :
# - Connexion au cluster Kafka
# - Découverte des tools MCP
# - Exécution des commandes
# - Erreurs détaillées
单元测试
# Exécution des tests
mvn test
# Tests avec couverture
mvn test jacoco:report
Kafka 连接性验证
# Test avec kafka-broker-api-versions
docker run --rm confluentinc/cp-kafka:latest \
kafka-broker-api-versions \
--bootstrap-server bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431
# Test avec kafka-topics
docker run --rm confluentinc/cp-kafka:latest \
kafka-topics --list \
--bootstrap-server bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431
🔐 安全
配置 SASL/PLAIN
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
-e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
-e KAFKA_SASL_MECHANISM=PLAIN \
-e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="secret";' \
kafka-mcp-server:2.0.0
SASL/SCRAM 配置
docker run -i --rm \
-e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
-e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
-e KAFKA_SASL_MECHANISM=SCRAM-SHA-512 \
-e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.scram.ScramLoginModule required username="admin" password="secret";' \
kafka-mcp-server:2.0.0
带有SSL证书(卷安装)
docker run -i --rm \
-v /path/to/certs:/certs:ro \
-e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
-e KAFKA_SECURITY_PROTOCOL=SSL \
-e KAFKA_SSL_TRUSTSTORE_LOCATION=/certs/truststore.jks \
-e KAFKA_SSL_TRUSTSTORE_PASSWORD=trustpass \
-e KAFKA_SSL_KEYSTORE_LOCATION=/certs/keystore.jks \
-e KAFKA_SSL_KEYSTORE_PASSWORD=keypass \
kafka-mcp-server:2.0.0
🐳 Docker Compose(中文可译为“Docker 组合”或保持原名,因其为专有名词,直接使用“Docker Compose”更为常见)
创建 docker-compose.yml 为了简化部署:
version: '3.8'
services:
kafka-mcp-server:
build: .
image: kafka-mcp-server:2.0.0
stdin_open: true
tty: true
environment:
- KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431
- KAFKA_SECURITY_PROTOCOL=PLAINTEXT
networks:
- kafka-network
networks:
kafka-network:
driver: bridge
docker-compose up -d
docker-compose logs -f kafka-mcp-server
📊 监控与可观测性
Spring Boot Actuator 指标
加入到 pom.xml :
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
加入到 application.yml :
management:
endpoints:
web:
exposure:
include: health,info,metrics
metrics:
export:
prometheus:
enabled: true
结构化日志
配置 Logbacklogback-spring.xml) :
<configuration>
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
</appender>
<root level="INFO">
<appender-ref ref="JSON"/>
</root>
</configuration>
🚀 高级用例
1. 集群健康状况监测
Claude, analyse l'état de santé du cluster Kafka :
1. Liste tous les topics
2. Pour chaque topic, vérifie s'il a des partitions offline
3. Liste les consumer groups et leur état
4. Identifie les groupes en erreur
2. 数据迁移
Claude, copie les 1000 derniers messages du topic 'prod-events' vers 'backup-events'
3. 消息分析
Claude, consomme 100 messages du topic 'logs', analyse les erreurs et donne-moi un résumé
4. 创建测试环境
Claude, crée 5 topics de test (test-1 à test-5) avec 3 partitions chacun, puis envoie 10 messages de test dans chacun
🔄 路线图
- [ ] 支持Kafka Streams
- [ ] 模式注册表管理(Avro/Protobuf)
- [ ] 使用Prometheus进行高级监控
- [ ] 支持Kafka事务
- [ ] 额外的REST接口
- [ ] 支持 Kubernetes/Helm 模板
🤝 贡献
# Fork le projet
git checkout -b feature/ma-fonctionnalite
mvn test
git commit -m "Ajout de ma fonctionnalité"
git push origin feature/ma-fonctionnalite
# Créer une Pull Request
📝 许可证
这个项目采用MIT许可证。
🆘 支持
- GitHub上的问题 对于错误报告和功能请求
- 文档 此README文件和JavaDoc
- 日志 启用DEBUG级别以获取更多详细信息
