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