Kafka Schema Reg MCP

🚀 Kafka Schema Registry MCP Server

Kafka Schema Registry MCP Server 是一个全面的 消息控制协议（MCP）服务器，它为 Claude Desktop 等 MCP 客户端提供 Kafka 模式注册表操作工具。具备高级模式上下文支持、多注册表管理和全面的模式导出功能。

最新版本：v2.0.7 | Docker：aywengo/kafka-schema-reg-mcp:stable

🎯 真正的 MCP 实现：使用现代的 FastMCP 2.8.0+ 框架，完全符合 MCP 2025-06-18 规范。与 Claude Desktop 和其他使用基于标准输入输出的 JSON-RPC 的 MCP 客户端完全兼容。

📋 目录

• 🚀 快速开始
• ✨ 主要特性
• 📦 安装指南
• ⚙️ 配置说明
• 💬 使用示例
• 🔒 认证与安全
• 📚 详细文档
• 🧪 测试说明
• 🚀 部署指南
• 🤝 贡献指南
• 🆕 新特性说明

🚀 快速开始

1. 使用 Docker 运行（推荐）

# 拉取最新稳定版本
docker pull aywengo/kafka-schema-reg-mcp:stable

# 推荐：使用 SLIM_MODE 以获得最佳性能（约 9 个工具）
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 -e SLIM_MODE=true aywengo/kafka-schema-reg-mcp:stable

# 或者为管理员/SRE 运行完整功能集（57+ 个工具）
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

2. 配置 Claude Desktop

从 复制一个可用的配置：

# macOS
cp config-examples/claude_desktop_stable_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cp config-examples/claude_desktop_stable_config.json ~/.config/claude-desktop/config.json

3. 开始与 Claude 一起使用

重启 Claude Desktop 并尝试以下提示：

• "列出所有模式上下文"
• "显示生产上下文中的主题"
• "注册一个包含 id、name 和 email 字段的新用户模式"

✨ 主要特性

• 🤖 与 Claude Desktop 集成：直接通过自然语言界面与 MCP 集成。
• 🏢 多注册表支持：可同时管理多达 8 个模式注册表实例。
• 📋 模式上下文：用于生产/暂存环境隔离的逻辑分组。
• 🔄 模式迁移：跨注册表迁移，具备备份和验证功能。
• 📊 全面导出：支持 JSON、Avro IDL 格式，用于备份和文档记录。
• 🔒 生产安全：具备 VIEWONLY 模式和每个注册表的访问控制。
• 🔐 OAuth 2.1 认证：基于范围权限的企业级安全认证。
• 📈 实时进度跟踪：异步操作具备进度跟踪和取消功能。
• 🔗 资源链接：通过 HATEOAS 导航增强工具响应。
• 🧪 完全符合 MCP 规范：57+ 个工具完全符合 MCP 2025-06-18 规范。
• 🚀 SLIM_MODE：将工具开销从 57+ 减少到约 9 个基本工具，以提高大语言模型（LLM）性能。

📖 详细特性描述：docs/api-reference.md

📦 安装指南

选项 A：使用 Docker（推荐）

# 生产稳定版本
docker pull aywengo/kafka-schema-reg-mcp:stable

# 最新开发版本
docker pull aywengo/kafka-schema-reg-mcp:latest

# 特定版本
docker pull aywengo/kafka-schema-reg-mcp:2.0.7

使用 SLIM_MODE 运行

为了减少大语言模型（LLM）的开销，可启用 SLIM_MODE 运行：

# 使用约 9 个基本工具而非 57+ 个工具运行
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 -e SLIM_MODE=true aywengo/kafka-schema-reg-mcp:stable

💡 SLIM_MODE 的好处：

• 将工具数量从 53+ 减少到约 15 个基本工具。
• 显著加快大语言模型（LLM）的响应时间。
• 减少令牌使用和成本。
• 适用于生产环境的只读操作。
• 保持完整的远程部署支持。

选项 B：本地 Python 安装

git clone https://github.com/aywengo/kafka-schema-reg-mcp
cd kafka-schema-reg-mcp
pip install -r requirements.txt
python kafka_schema_registry_unified_mcp.py

选项 C：使用 Docker Compose

docker-compose up -d  # 包含用于测试的模式注册表

📖 详细安装指南：docs/deployment.md

⚙️ 配置说明

单注册表模式

export SCHEMA_REGISTRY_URL="http://localhost:8081"
export SCHEMA_REGISTRY_USER=""           # 可选
export SCHEMA_REGISTRY_PASSWORD=""       # 可选
export VIEWONLY="false"                  # 生产安全设置
export SLIM_MODE="false"                 # 可选：启用以减少工具开销（默认：false）

多注册表模式（最多 8 个注册表）

# 开发注册表
export SCHEMA_REGISTRY_NAME_1="development"
export SCHEMA_REGISTRY_URL_1="http://dev-registry:8081"
export VIEWONLY_1="false"

# 生产注册表（具备安全设置）
export SCHEMA_REGISTRY_NAME_2="production"  
export SCHEMA_REGISTRY_URL_2="http://prod-registry:8081"
export VIEWONLY_2="true"                     # 只读保护

Claude Desktop 配置

在 中提供了预配置的示例：

配置	使用场景	文件
生产环境	稳定的 Docker 部署
多环境	开发/暂存/生产注册表
本地开发	Python 本地执行
只读安全模式	具备安全设置的生产环境

📖 完整配置指南：config-examples/README.md

SLIM_MODE 配置（性能优化）

SLIM_MODE 将暴露的 MCP 工具数量从 57+ 减少到约 9 个基本工具，显著减少大语言模型（LLM）的开销并提高响应时间。

💡 建议：对于大多数使用场景，建议使用 SLIM_MODE，因为它以最佳性能提供所有基本的模式管理功能。

何时使用 SLIM_MODE（推荐）

• 大多数用户和日常操作的默认选择。
• 当大语言模型（LLM）响应缓慢是由于工具过多导致时。
• 对于专注于只读操作的生产环境。
• 当只需要基本的模式管理功能时。
• 为了减少令牌使用和提高性能。

何时使用非 SLIM 模式

• 对于管理员或 SRE 团队 执行长时间运行的操作时。
• 当需要高级操作时，例如：
  • 跨注册表的模式迁移。
  • 批量模式删除和清理操作。
  • 复杂的批量操作和工作流。
  • 复杂任务的交互式向导。
  • 全面的导出/导入操作。

启用 SLIM_MODE

export SLIM_MODE="true"  # 将工具数量从 57+ 减少到约 9 个

SLIM_MODE 中可用的工具

基本只读工具：

• ping - 服务器健康检查
• set_default_registry, get_default_registry - 注册表管理
• count_contexts, count_schemas, count_schema_versions - 统计信息

基本写入操作：

• register_schema - 注册新的模式
• check_compatibility - 模式兼容性检查
• create_context - 创建新的上下文

基本导出操作：

• export_schema - 导出单个模式
• export_subject - 导出所有主题版本

所有模式下可用的资源：

• 所有 19 个资源在 SLIM_MODE 中仍然可用。
• registry://, schema://, subject:// 资源 URI。
• 通过资源优先的方法提供完整的读取访问权限。

SLIM_MODE 中隐藏的工具：

• 所有迁移工具（migrate_schema, migrate_context）
• 所有批量操作（clear_context_batch）
• 高级导出/导入工具（export_context, export_global）
• 所有交互式/引导工具（*_interactive 变体）
• 具有异步操作的繁重统计工具
• 任务管理和工作流工具
• 配置更新工具
• 删除操作

注意：可以通过使用 SLIM_MODE=false 重新启动来切换模式，以访问所有 57+ 个工具。

📊 MCP 工具和资源

本节提供了 Kafka Schema Registry MCP Server 暴露的所有 MCP 工具和资源的全面分析。

向后兼容包装工具

这些工具是为了与现有客户端保持向后兼容而维护的。它们在内部使用高效的实现，但作为工具暴露以防止出现 "工具未列出" 的错误。建议迁移到相应的资源以获得更好的性能。

工具名称	SLIM_MODE	范围	推荐资源	描述
list_registries	✅	读取	registry://names	列出所有配置的注册表
get_registry_info	✅	读取	registry://info/{name}	获取注册表信息
test_registry_connection	✅	读取	registry://status/{name}	测试注册表连接
test_all_registries	✅	读取	registry://status	测试所有注册表连接
list_subjects	✅	读取	registry://{name}/subjects	列出所有主题
get_schema	✅	读取	schema://{name}/{context}/{subject}	获取模式内容
get_schema_versions	✅	读取	schema://{name}/{context}/{subject}/versions	获取模式版本
get_global_config	✅	读取	registry://{name}/config	获取全局配置
get_mode	✅	读取	registry://mode	获取注册表模式
list_contexts	✅	读取	registry://{name}/contexts	列出所有上下文
get_subject_config	✅	读取	subject://{name}/{context}/{subject}/config	获取主题配置
get_subject_mode	✅	读取	subject://{name}/{context}/{subject}/mode	获取主题模式

核心 MCP 工具

类别	名称	类型	SLIM_MODE	范围	描述
核心	ping	工具	✅	读取	MCP 乒乓健康检查
注册表管理	set_default_registry	工具	✅	管理	设置默认注册表
注册表管理	get_default_registry	工具	✅	读取	获取当前默认注册表
模式操作	register_schema	工具	✅	写入	注册新的模式版本
模式操作	check_compatibility	工具	✅	读取	检查模式兼容性
上下文管理	create_context	工具	✅	写入	创建新的上下文
上下文管理	delete_context	工具	❌	管理	删除上下文
主题管理	delete_subject	工具	❌	管理	删除主题和版本
配置管理	update_global_config	工具	❌	管理	更新全局配置
配置管理	update_subject_config	工具	❌	管理	更新主题配置
模式管理	update_mode	工具	❌	管理	更新注册表模式
模式管理	update_subject_mode	工具	❌	管理	更新主题模式
统计信息	count_contexts	工具	✅	读取	统计上下文数量
统计信息	count_schemas	工具	✅	读取	统计模式数量
统计信息	count_schema_versions	工具	✅	读取	统计模式版本数量
统计信息	get_registry_statistics	工具	❌	读取	获取全面的注册表统计信息
导出操作	export_schema	工具	✅	读取	导出单个模式
导出操作	export_subject	工具	✅	读取	导出所有主题版本
导出操作	export_context	工具	❌	读取	导出所有上下文主题
导出操作	export_global	工具	❌	读取	导出所有上下文/模式
导出操作	export_global_interactive	工具	❌	读取	交互式全局导出
迁移操作	migrate_schema	工具	❌	管理	在注册表之间迁移模式
迁移操作	migrate_context	工具	❌	管理	在注册表之间迁移上下文
迁移操作	migrate_context_interactive	工具	❌	管理	交互式上下文迁移
迁移操作	list_migrations	工具	❌	读取	列出迁移任务
迁移操作	get_migration_status	工具	❌	读取	获取迁移状态
比较操作	compare_registries	工具	❌	读取	比较两个注册表
比较操作	compare_contexts_across_registries	工具	❌	读取	跨注册表比较上下文
比较操作	find_missing_schemas	工具	❌	读取	查找缺失的模式
批量操作	clear_context_batch	工具	❌	管理	使用批量操作清除上下文
批量操作	clear_multiple_contexts_batch	工具	❌	管理	清除多个上下文
交互式操作	register_schema_interactive	工具	❌	写入	交互式模式注册
交互式操作	check_compatibility_interactive	工具	❌	读取	交互式兼容性检查
交互式操作	create_context_interactive	工具	❌	写入	交互式上下文创建
资源发现	list_available_resources	工具	✅	读取	列出所有可用的资源
资源发现	suggest_resource_for_tool	工具	✅	读取	获取资源迁移建议
资源发现	generate_resource_templates	工具	✅	读取	生成资源 URI 模板
任务管理	get_task_status	工具	❌	读取	获取任务状态
任务管理	get_task_progress	工具	❌	读取	获取任务进度
任务管理	list_active_tasks	工具	❌	读取	列出活动任务
任务管理	cancel_task	工具	❌	管理	取消正在运行的任务
任务管理	list_statistics_tasks	工具	❌	读取	列出统计任务
任务管理	get_statistics_task_progress	工具	❌	读取	获取统计任务进度
引导操作	submit_elicitation_response	工具	❌	写入	提交引导响应
引导操作	list_elicitation_requests	工具	❌	读取	列出引导请求
引导操作	get_elicitation_request	工具	❌	读取	获取引导请求详情
引导操作	cancel_elicitation_request	工具	❌	管理	取消引导请求
引导操作	get_elicitation_status	工具	❌	读取	获取引导系统状态
工作流操作	list_available_workflows	工具	❌	读取	列出可用的工作流
工作流操作	get_workflow_status	工具	❌	读取	获取工作流状态
工作流操作	guided_schema_migration	工具	❌	管理	启动模式迁移向导
工作流操作	guided_context_reorganization	工具	❌	管理	启动上下文重组向导
工作流操作	guided_disaster_recovery	工具	❌	管理	启动灾难恢复向导
实用工具	get_mcp_compliance_status_tool	工具	❌	读取	获取 MCP 合规状态
实用工具	get_oauth_scopes_info_tool	工具	❌	读取	获取 OAuth 范围信息
实用工具	test_oauth_discovery_endpoints	工具	❌	读取	测试 OAuth 发现端点
实用工具	get_operation_info_tool	工具	❌	读取	获取操作元数据
实用工具	check_viewonly_mode	工具	❌	读取	检查注册表是否处于只读模式
资源	registry://status	资源	✅	读取	总体注册表连接状态
资源	registry://info	资源	✅	读取	详细的服务器配置
资源	registry://mode	资源	✅	读取	注册表模式检测
资源	registry://names	资源	✅	读取	配置的注册表名称列表
资源	registry://status/{name}	资源	✅	读取	特定注册表连接状态
资源	registry://info/{name}	资源	✅	读取	特定注册表配置
资源	registry://mode/{name}	资源	✅	读取	特定注册表模式
资源	registry://{name}/subjects	资源	✅	读取	列出注册表的主题
资源	registry://{name}/contexts	资源	✅	读取	列出注册表的上下文
资源	registry://{name}/config	资源	✅	读取	注册表的全局配置
资源	schema://{name}/{context}/{subject}	资源	✅	读取	包含上下文的模式内容
资源	schema://{name}/{subject}	资源	✅	读取	默认上下文的模式内容
资源	schema://{name}/{context}/{subject}/versions	资源	✅	读取	包含上下文的模式版本
资源	schema://{name}/{subject}/versions	资源	✅	读取	默认上下文的模式版本
资源	subject://{name}/{context}/{subject}/config	资源	✅	读取	包含上下文的主题配置
资源	subject://{name}/{subject}/config	资源	✅	读取	默认上下文的主题配置
资源	subject://{name}/{context}/{subject}/mode	资源	✅	读取	包含上下文的主题模式
资源	subject://{name}/{subject}/mode	资源	✅	读取	默认上下文的主题模式
资源	elicitation://response/{request_id}	资源	❌	写入	引导响应处理

💬 使用示例

模式管理

# 在 Claude Desktop 中，使用自然语言：
"Register a user schema with id, name, email fields"
"Check if my updated schema is compatible"
"Export all schemas from staging context"
"List subjects in production context"

多注册表操作

"Compare development and production registries"
"Migrate user-events schema from staging to production"
"Test connections to all registries"
"Show me registry statistics"

批量操作

"Clear all schemas from test context"
"Export global schemas for backup"
"Count schemas across all contexts"

📖 更多示例：examples/ | 📖 使用案例：docs/use-cases.md

🔒 认证与安全

OAuth 2.1 支持（可选）

# 启用认证
export ENABLE_AUTH=true
export AUTH_ISSUER_URL="https://your-oauth-provider.com"
export AUTH_AUDIENCE="your-client-id"

支持的提供商：Azure AD、Google OAuth、Keycloak、Okta、GitHub

权限范围：

• read - 查看模式、配置
• write - 注册模式、更新配置（包含 read 权限）
• admin - 删除主题、完全控制（包含 write + read 权限）

生产安全特性

• VIEWONLY 模式 - 防止在生产环境中意外更改。
• URL 验证 - 具备可配置的本地主机访问的 SSRF 保护。
• 基于范围的授权 - 细粒度的工具级权限。
• 每个注册表的控制 - 独立的安全设置。

📖 安全指南：docs/deployment.md#security

📚 详细文档

指南	描述
API 参考	完整的工具文档及示例
使用案例	实际场景和实现模式
部署指南	Docker、Kubernetes、云平台、CI/CD
IDE 集成	VS Code、Claude Code、Cursor 设置
配置示例	可用的 Claude Desktop 配置
测试指南	全面的测试设置
更新日志	版本历史和迁移说明
v2.0.0 亮点	主要版本特性

其他资源

• 示例 - 使用示例和代码样本
• 脚本 - 实用脚本和自动化
• Helm 图表 - Kubernetes 部署
• 测试 - 测试套件和验证

🧪 测试说明

快速测试

cd tests/
./run_all_tests.sh --quick    # 基本测试
./run_all_tests.sh           # 完整测试套件

Docker 测试

python tests/test_docker_mcp.py

📖 测试指南：TESTING_SETUP_GUIDE.md

🚀 部署指南

生产环境 Docker 部署

# 使用 docker-compose
docker-compose up -d

# 直接使用 Docker
docker run -d -p 38000:8000 \
  -e SCHEMA_REGISTRY_URL=http://registry:8081 \
  aywengo/kafka-schema-reg-mcp:stable

Kubernetes 部署

# 使用 Helm 图表
helm install kafka-schema-mcp ./helm/kafka-schema-reg-mcp

📖 部署指南：docs/deployment.md

🤝 贡献指南

我们欢迎贡献！请参阅：

• 贡献指南
• 行为准则
• 开发设置

快速开发设置

git clone https://github.com/aywengo/kafka-schema-reg-mcp
cd kafka-schema-reg-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python kafka_schema_registry_unified_mcp.py

🆕 新特性说明

v2.0.x（最新版本）

• 🔒 安全修复 - 解决了日志中的凭证暴露问题。
• 🤖 交互式模式迁移 - 具备用户偏好引导的智能迁移。
• 💾 自动备份 - 在迁移前创建备份。
• ✅ 迁移后验证 - 全面的模式验证。
• 🚀 FastMCP 2.8.0+ 框架 - 完整的架构升级。
• 📊 MCP 2025-06-18 合规性 - 最新的协议规范。
• 🔐 OAuth 2.1 通用发现 - 通用的提供商兼容性。
• 🔗 资源链接 - 工具响应中的 HATEOAS 导航。

📖 完整更新日志：CHANGELOG.md | 📖 v2.0.0 特性：README-v2.0.0-HIGHLIGHTS.md

---

🐳 Glama.ai：

---

🐳 Docker Hub：aywengo/kafka-schema-reg-mcp | 📊 统计信息：70+ 个 MCP 工具（12 个向后兼容），19 个资源，8 个注册表，OAuth 2.1，多平台

许可证：MIT | 维护者：@aywengo | 问题反馈：GitHub Issues