mcp-debezium

mcp-debezium

Um servidor Model Context Protocol para Debezium (via a API REST do Kafka Connect). Ele permite que um cliente compatível com MCP (Claude Desktop, Claude Code, etc.) monitore e gerencie conectores de captura de dados de mudança — status, configuração, reinicializações, ciclo de vida — com comportamento totalmente controlado por flags.

Seguro por padrão: inicia somente leitura, pode ser limitado a uma lista de conectores permitidos, protege conectores críticos de mutações, oculta credenciais nas configurações dos conectores e bloqueia exclusões atrás de uma aceitação explícita.

Recursos

• Monitoramento — informações do worker/cluster, lista de conectores, plugins, configuração por conector, status (com rastreios de tarefas com falha) e tópicos.
• Gerenciamento — criar/atualizar, pausar/retomar, reiniciar conector ou uma única tarefa.
• Ciclo de vida — excluir conectores (admin).
• Modos de acesso — read-only → read-write → admin, em camadas, de modo que um modo nunca exponha ferramentas acima do seu nível.
• Ocultação de credenciais — database.password e outros valores de configuração com formato de segredo são substituídos por ***REDACTED*** antes de os resultados serem retornados.
• Flags de segurança — lista de conectores permitidos, conectores protegidos, bloqueio de exclusão, simulação (dry-run) e registro de auditoria em JSON (veja abaixo).

Modelo de segurança

Preocupação	Flag	Padrão	Efeito
O que o servidor pode fazer?	DEBEZIUM_MODE	read-only	read-only expõe apenas monitoramento; read-write adiciona gerenciamento de ciclo de vida; admin adiciona exclusão. Ferramentas acima do modo nunca são registradas.
Quais conectores estão no escopo?	DEBEZIUM_CONNECTOR_ALLOWLIST	(todos)	Quando definido, operações em outros conectores são recusadas.
Quais conectores são somente leitura para sempre?	DEBEZIUM_PROTECTED_CONNECTORS	(nenhum)	Inspecionáveis, mas nunca pausados/reconfigurados/excluídos.
Pode excluir?	DEBEZIUM_ALLOW_DELETE	false	delete_connector precisa disso e do modo admin.
Pré-visualizar sem tocar no Connect	DEBEZIUM_DRY_RUN	false	Ferramentas de escrita/admin validam + registram a intenção e retornam.
Trilha de auditoria	DEBEZIUM_AUDIT_LOG	true	Emite uma linha JSON para stderr por operação protegida.
Ocultação de credenciais	(sempre ativo)	—	Valores de configuração com formato de segredo são ocultados antes do retorno.

Ferramentas

Leitura (read-only+): cluster_info, list_connectors, list_connector_plugins, get_connector, get_connector_config, get_connector_status, get_connector_topics

Escrita (read-write+): create_connector, update_connector_config, pause_connector, resume_connector, restart_connector, restart_task

Admin (admin): delete_connector (precisa de DEBEZIUM_ALLOW_DELETE)

Início rápido — adicione ao seu agente

Publicado no npm como @dockndevai/mcp-debezium. Sem necessidade de clone ou build — seu cliente MCP o executa sob demanda com npx. Comece no modo read-only; veja .env.example para todas as variáveis e docs/CLIENTS.md para o guia completo por cliente.

Claude Code (CLI)

claude mcp add debezium -e CONNECT_URL="http://localhost:8083" -e DEBEZIUM_MODE="read-only" -- npx -y @dockndevai/mcp-debezium

Claude Desktop · Cursor · Windsurf — mesmo bloco em claude_desktop_config.json, .cursor/mcp.json ou ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "debezium": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-debezium"
      ],
      "env": {
        "CONNECT_URL": "http://localhost:8083",
        "DEBEZIUM_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — em ~/.codex/config.toml:

[mcp_servers.debezium]
command = "npx"
args = ["-y", "@dockndevai/mcp-debezium"]
env = { CONNECT_URL = "http://localhost:8083", DEBEZIUM_MODE = "read-only" }

VS Code (GitHub Copilot, modo Agente) — em .vscode/mcp.json:

{
  "servers": {
    "debezium": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-debezium"
      ],
      "env": {
        "CONNECT_URL": "http://localhost:8083",
        "DEBEZIUM_MODE": "read-only"
      }
    }
  }
}

Exemplos de prompts

• "Quais conectores estão FAILED e por quê?"
• "Reinicie a tarefa com falha em pg-orders." (precisa de read-write)
• "Mostre a configuração de mysql-inventory." (credenciais retornam ocultas)

Executar a partir do código-fonte (desenvolvimento)

Prefira o pacote publicado acima. Para executar a partir de um clone:

npm install
npm run build
node dist/index.js   # with the environment variables set

Desenvolver

npm run dev
npm test          # security policy + config redaction
npm run typecheck

Publicação

Este servidor inclui um server.json para o registro oficial do MCP e um mcpName para validação de propriedade no npm. Veja PUBLISHING.md para publicar no npm e listar no registro do MCP, Smithery, Glama, Cursor e PulseMCP.

Licença

MIT