mcp-confluent

Una implementación de servidor MCP que permite a los asistentes de IA interactuar con las API REST de Confluent Cloud. Este servidor permite que herramientas de IA como Claude Desktop y Goose CLI gestionen temas, conectores y sentencias SQL de Flink de Kafka mediante interacciones en lenguaje natural.

Manifestación

Goose CLI

Escritorio de Claude

Tabla de contenido

• mcp-confluent

  • Manifestación

    • Goose CLI

    • Escritorio de Claude

  • Tabla de contenido

  • Guía del usuario

    • Empezando

    • Configuración

    • Referencia de variables de entorno

    • Uso

    • Configuración de Claude Desktop

    • Configuración de Goose CLI

    • Uso de la CLI de mcp-confluent

      • Uso básico

      • Ejemplo: Implementar utilizando todos los transportes

      • Ejemplo: Permitir solo herramientas específicas

      • Ejemplo: Bloquear ciertas herramientas

      • Ejemplo: utilizar listas de herramientas desde archivos

      • Ejemplo: enumerar todas las herramientas disponibles

  • Guía para desarrolladores

    • Estructura del proyecto

    • Construyendo y funcionando

    • Pruebas

      • Inspector de MCP

    • Agregar una nueva herramienta

    • Generando tipos

    • Contribuyendo

Guía del usuario

Empezando

1. Cree un archivo copie la estructura de archivo .env de ejemplo (que se muestra a continuación) en un nuevo archivo llamado .env en la raíz de su proyecto.

2. Rellene el archivo Introduzca los valores necesarios para su entorno de Confluent Cloud. Consulte la sección "Configuración" para obtener más información sobre cada variable.

3. Instalar Node.js (si aún no está instalado)

   • Recomendamos utilizar NVM (Node Version Manager) para administrar las versiones de Node.js

   • Instalar y utilizar Node.js:

   nvm install 22 nvm use 22

Configuración

Cree un archivo .env en el directorio raíz de su proyecto con la siguiente configuración:

Referencia de variables de entorno

Uso

Este servidor MCP está diseñado para usarse con varios clientes MCP, como Claude Desktop o Goose CLI/Desktop. La configuración y la interacción específicas dependerán del cliente que utilice. Sin embargo, los pasos generales son:

1. Iniciar el servidor: puede ejecutar el servidor MCP de una de dos maneras:

   • Desde el código fuente: Siga las instrucciones de la Guía del desarrollador para compilar y ejecutar el servidor desde el código fuente. Esto suele implicar:

     • Instalación de dependencias ( npm install )

     • Construyendo el proyecto ( npm run build o npm run dev )

   • Con npx: puedes iniciar el servidor directamente usando npx (no se requiere compilación):

     npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env

2. Configura tu cliente MCP: Cada cliente tiene su propia forma de especificar la dirección del servidor MCP y las credenciales requeridas. Deberás configurar tu cliente (p. ej., Claude, Goose) para que se conecte a la dirección donde se ejecuta este servidor (probablemente localhost con un puerto específico). El puerto en el que se ejecuta el servidor puede configurarse mediante una variable de entorno.

3. Iniciar el cliente MCP: Una vez configurado el cliente para conectarse al servidor MCP, puede iniciarlo. Al iniciarse, se creará una instancia de este servidor MCP localmente. Esta instancia se encargará de administrar los esquemas de datos e interactuar con Confluent Cloud en su nombre.

4. Interactúe con Confluent a través del cliente: Una vez conectado el cliente, puede usar su interfaz para interactuar con los recursos de Confluent Cloud. El cliente enviará solicitudes a este servidor MCP, que interactuará con Confluent Cloud en su nombre.

Configuración de Claude Desktop

Consulte aquí para obtener más detalles sobre la instalación de Claude Desktop y los servidores MCP.

Para configurar Claude Desktop para utilizar este servidor MCP:

1. Abrir la configuración del escritorio de Claude

   • En Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   • En Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Editar archivo de configuración

   • Abra el archivo de configuración en su editor de texto preferido

   • Agregue o modifique la configuración utilizando uno de los siguientes métodos:

   { "mcpServers": { "confluent": { "command": "node", "args": [ "/path/to/confluent-mcp-server/dist/index.js", "--env-file", "/path/to/confluent-mcp-server/.env", ] } } }
   { "mcpServers": { "confluent": { "command": "npx", "args": [ "-y" "@confluentinc/mcp-confluent", "-e", "/path/to/confluent-mcp-server/.env" ] } } }

   Reemplace /path/to/confluent-mcp-server/ con la ruta real donde ha instalado este servidor MCP.

3. Reiniciar Claude Desktop

   • Cierre y vuelva a abrir Claude Desktop para que los cambios surtan efecto.

   • El servidor MCP se iniciará automáticamente cuando se inicie Claude Desktop

Ahora Claude Desktop estará configurado para utilizar su servidor MCP local para las interacciones de Confluent.

Configuración de Goose CLI

Consulte aquí para obtener instrucciones detalladas sobre cómo instalar Goose CLI.

Una vez instalado, siga estos pasos:

1. Ejecute el comando de configuración:

   goose configure

2. Siga las indicaciones interactivas:

   • Seleccione Add extension

   • Elija Command-line Extension

   • Introduzca mcp-confluent como nombre de la extensión

   • Elija uno de los siguientes métodos de configuración:

   node /path/to/confluent-mcp-server/dist/index.js --env-file /path/to/confluent-mcp-server/.env
   npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env

Reemplace /path/to/confluent-mcp-server/ con la ruta real donde ha instalado este servidor MCP.

Uso de la CLI de mcp-confluent

El servidor MCP proporciona una interfaz de línea de comandos (CLI) flexible para una configuración y un control avanzados. La CLI permite especificar archivos de entorno y transportes, y ajustar las herramientas que se habilitan o bloquean.

Uso básico

Puede ver todas las opciones de CLI y obtener ayuda con:

Ejemplo: Implementar utilizando todos los transportes

Ejemplo: Permitir solo herramientas específicas

Ejemplo: Bloquear ciertas herramientas

Ejemplo: utilizar listas de herramientas desde archivos

Ejemplo: enumerar todas las herramientas disponibles

Consejo: La lista de permitidos se aplica antes que la de bloqueados. Si no se proporciona ninguna, todas las herramientas estarán habilitadas por defecto.

Guía para desarrolladores

Estructura del proyecto

Construyendo y funcionando

1. Dependencias de instalación:

   npm install

2. Modo de desarrollo (esté atento a los cambios):

   npm run dev

   Este comando compila el código TypeScript a JavaScript y lo reconstruye automáticamente cuando se detectan cambios en el directorio src/ .

3. Versión de producción (compilación única):

   npm run build

4. Iniciar el servidor:

   npm run start

Pruebas

Inspector de MCP

Para probar servidores MCP, puede utilizar MCP Inspector , que es una herramienta de desarrollo interactiva para probar y depurar servidores MCP.

Agregar una nueva herramienta

1. Agregue una nueva enumeración a la clase de enumeración ToolName .

2. Agregue su nueva herramienta al mapa de controladores en la clase ToolFactory .

3. Crea un nuevo archivo, exportando la clase que extiende BaseToolHandler .

   1. Implementar el método handle de la clase base.

   2. Implementar el método getToolConfig de la clase base.

4. Una vez satisfecho, agréguelo al conjunto de enabledTools en index.ts .

Generando tipos

Contribuyendo

Se agradecen los informes de errores y los comentarios en forma de problemas de Github. Para obtener instrucciones sobre cómo contribuir, consulte CONTRIBUTING.md.