NATS

Un servidor MCP para integrarse con el sistema de mensajería NATS.

GitHub
50
Prueba este MCPPatrocinado

Documentación

mcp-nats

Install MCP Server Install in VS Code

Un servidor de Model Context Protocol (MCP) para la integración con el sistema de mensajería NATS

MCP Review Certified

Este servidor MCP está certificado por MCP Review.

Resumen

Este proyecto proporciona un servidor de Model Context Protocol (MCP) para NATS, que permite a modelos de IA y aplicaciones interactuar con sistemas de mensajería NATS a través de una interfaz estandarizada. Expone un conjunto completo de herramientas para interactuar con servidores NATS, lo que lo hace ideal para aplicaciones impulsadas por IA que necesitan trabajar con sistemas de mensajería.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los Modelos de Lenguaje Grande (LLMs). Este servidor implementa la especificación MCP para proporcionar capacidades de mensajería NATS a LLMs y aplicaciones de IA, permitiéndoles:

  • Interactuar con sistemas de mensajería NATS de manera estandarizada
  • Inspeccionar y monitorear de forma segura servidores y streams de NATS
  • Realizar operaciones de solo lectura a través de una interfaz segura
  • Integrarse con otros clientes y hosts compatibles con MCP

Características

  • Gestión de Servidores (Operaciones de Solo Lectura)
    • Listar e inspeccionar servidores NATS
    • Monitoreo de salud del servidor y ping
    • Recuperación de información del servidor
    • Medición de tiempo de ida y vuelta (RTT)
  • Operaciones de Streams (Operaciones de Solo Lectura)
    • Ver e inspeccionar streams de NATS
    • Consultas de estado e información de streams
    • Visualización y recuperación de mensajes
    • Inspección de subjects
  • Operaciones de Object Store
    • Crear y gestionar buckets de object store
    • Poner y obtener archivos de object stores
    • Listar buckets y su contenido
    • Eliminar objetos y buckets
    • Observar buckets para detectar cambios
    • Sellar buckets para prevenir actualizaciones
  • Operaciones de Key-Value
    • Crear y gestionar buckets KV
    • Almacenar y recuperar pares clave-valor
    • Observar actualizaciones de KV
    • Eliminar claves y buckets
  • Operaciones de Publicación
    • Publicar mensajes a subjects de NATS
    • Soporte para diferentes formatos de mensaje
    • Publicación asíncrona de mensajes
  • Operaciones de Cuenta
    • Ver información de cuenta y métricas
    • Generar reportes de cuenta (conexiones y estadísticas)
    • Crear y restaurar copias de seguridad de cuentas
    • Inspeccionar la cadena TLS de servidores conectados
  • Soporte Multi-Cuenta
    • Manejar múltiples cuentas NATS simultáneamente
    • Gestión segura de credenciales
  • Integración MCP
    • Implementa la especificación del servidor MCP
    • Compatible con clientes MCP como Claude Desktop
    • Definiciones de herramientas estandarizadas para interacción con LLM
    • Operaciones seguras de solo lectura para interacción de IA con NATS

Requisitos

  • Go 1.25 o posterior
  • Servidor NATS (accesible vía URL)
  • Credenciales NATS para autenticación
  • Cliente compatible con MCP (por ejemplo, Claude Desktop u otros clientes MCP)

Instalación

Usando Go

go install github.com/sinadarbouy/mcp-nats/cmd/mcp-nats@latest

Compilando desde el Código Fuente

git clone https://github.com/sinadarbouy/mcp-nats.git
cd mcp-nats
go build -o mcp-nats ./cmd/mcp-nats

Chart de Helm (Kubernetes)

El chart está en deploy/charts/mcp-nats. Las guías de instalación (incluyendo OCI / GHCR y el chart umbrella dependencies), la descripción general de valores, los probes y el ejemplo de HashiCorp Vault Agent Injector están en deploy/charts/mcp-nats/README.md.

Inicio rápido desde la raíz del repositorio:

helm install mcp-nats ./deploy/charts/mcp-nats --namespace mcp-nats --create-namespace

Las versiones publicadas también se pueden instalar desde OCI, por ejemplo:

helm install mcp-nats oci://ghcr.io/sinadarbouy/charts/mcp-nats --version "0.1.4" --namespace mcp-nats --create-namespace

Consulte el README del chart para ver los fragmentos de dependencia de Chart.yaml y el inicio de sesión en el registro.

Firmas de imágenes de contenedor

Las versiones etiquetadas publican ghcr.io/sinadarbouy/mcp-nats y firman el índice multi-arquitectura (y cada manifiesto de plataforma) con Sigstore Cosign usando GitHub OIDC sin clave.

Verifique una etiqueta publicada:

cosign verify ghcr.io/sinadarbouy/mcp-nats:0.1.4 \
  --certificate-identity-regexp 'https://github.com/sinadarbouy/mcp-nats/.github/workflows/(release\.yml@refs/tags/v.*|sign-image\.yml@refs/heads/main)' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Las etiquetas históricas publicadas antes de que se agregara la firma se pueden firmar desde Actions → sign-image (ejecutar desde main).

Prueba de Integración con Tilt (Docker Desktop Kubernetes)

Use Tilt para implementar tanto el NATS oficial como el chart local de mcp-nats para pruebas de autenticación de extremo a extremo.

Requisitos previos:

  • Tilt instalado
  • Helm instalado
  • Docker Desktop Kubernetes habilitado
  • Contexto kube actual configurado en docker-desktop

Inicie el stack de integración:

tilt up

Esto utiliza:

  • Tiltfile
  • deploy/tilt/nats-values.yaml
  • deploy/tilt/mcp-nats-values.yaml
  • una compilación de imagen local con deploy/tilt/Dockerfile.tilt antes del despliegue con Helm

Detener y limpiar:

tilt down
helm uninstall -n mcp-nats-tilt nats mcp-nats
kubectl delete namespace mcp-nats-tilt --ignore-not-found

Comandos rápidos de verificación:

kubectl get pods,svc -n mcp-nats-tilt
kubectl logs -n mcp-nats-tilt deploy/mcp-nats-mcp-nats
kubectl logs -n mcp-nats-tilt statefulset/nats
kubectl port-forward -n mcp-nats-tilt svc/mcp-nats-mcp-nats 8000:8000

Prueba rápida de autenticación:

  • NATS está configurado con mcpuser / mcppassword en deploy/tilt/nats-values.yaml.
  • mcp-nats usa las mismas credenciales a través del secreto gestionado por el chart en deploy/tilt/mcp-nats-values.yaml.
  • Si las credenciales no coinciden, los registros de mcp-nats mostrarán fallos de conexión/autenticación.

Configuración

Variables de Entorno

  • NATS_URL: La URL de su servidor NATS (por ejemplo, localhost:4222)
  • NATS_<ACCOUNT>_CREDS: Credenciales NATS codificadas en Base64 para cada cuenta
    • Ejemplo: NATS_SYS_CREDS, NATS_A_CREDS
  • NATS_NO_AUTHENTICATION: Configúrelo en "true" para habilitar conexiones anónimas (sin credenciales requeridas)
  • NATS_USER: Nombre de usuario o token para autenticación de usuario/contraseña
  • NATS_PASSWORD: Contraseña para autenticación de usuario/contraseña

Banderas de Línea de Comandos

  • --transport: Tipo de transporte (stdio, sse o streamable-http), predeterminado: streamable-http
  • --address: Dirección para que el transporte HTTP escuche, predeterminado: 0.0.0.0:8000
  • --endpoint-path: Ruta del endpoint para el transporte streamable-http, predeterminado: /mcp
  • --sse-address: Alias obsoleto de --address
  • --log-level: Nivel de registro (debug, info, warn, error), predeterminado: info
  • --json-logs: Salida de registros en formato JSON, predeterminado: false
  • --no-authentication: Permitir conexiones anónimas sin credenciales
  • --user: Nombre de usuario o token de NATS (también se puede configurar mediante la variable de entorno NATS_USER)
  • --password: Contraseña de NATS (también se puede configurar mediante la variable de entorno NATS_PASSWORD)

Endpoints de Salud (Transportes HTTP)

  • GET /livez: verificación de actividad del proceso (no valida la dependencia de NATS)
  • GET /readyz: verificación de preparación (valida la conectividad TCP con NATS_URL)
  • GET /healthz: alias de compatibilidad para la verificación de actividad

Estos endpoints están disponibles cuando se ejecuta con transporte sse o streamable-http.

Probes del chart de Helm

Los probes predeterminados y lifecycle.preStop están documentados en deploy/charts/mcp-nats/README.md.

Métodos de Autenticación

El servidor MCP NATS admite tres métodos de autenticación:

  1. Autenticación basada en Credenciales (predeterminado): Usa archivos de credenciales NATS

    • Configure las variables de entorno NATS_<ACCOUNT>_CREDS
    • Requiere el parámetro account_name en todas las herramientas

  2. Autenticación de Usuario/Contraseña: Usa nombre de usuario y contraseña

    • Configure las variables de entorno NATS_USER y NATS_PASSWORD o use las banderas --user y --password

  3. Autenticación Anónima: No se requiere autenticación

    • Configure la variable de entorno NATS_NO_AUTHENTICATION=true o use la bandera --no-authentication

Ejemplo de Uso

# Run with Streamable HTTP transport (default) and debug logging
./mcp-nats --log-level debug

# Run with custom Streamable HTTP endpoint path
./mcp-nats --transport streamable-http --address localhost:9000 --endpoint-path /mcp

# Run with JSON logging
./mcp-nats --json-logs

# Run with SSE transport
./mcp-nats --transport sse --address localhost:9000

# Run with anonymous authentication
./mcp-nats --no-authentication

# Run with user/password authentication
./mcp-nats --user myuser --password mypass

# Run with environment variables for authentication
NATS_NO_AUTHENTICATION=true ./mcp-nats
NATS_USER=myuser NATS_PASSWORD=mypass ./mcp-nats

Usando VSCode con servidor MCP remoto

Asegúrese de que su .vscode/settings.json incluya:

"mcp": {
  "servers": {
    "nats": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cursor (mcpServers):

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_SYS_CREDS": "<base64 of SYS account creds>",
        "NATS_A_CREDS": "<base64 of A account creds>"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

Autenticación Anónima:

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_NO_AUTHENTICATION": "true"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

Autenticación de Usuario/Contraseña:

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_USER": "myuser",
        "NATS_PASSWORD": "mypass"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

Si usa el binario:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio"
      ],
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_SYS_CREDS": "<base64 of SYS account creds>",
        "NATS_A_CREDS": "<base64 of A account creds>"
      }
    }
  }
}

Autenticación Anónima con Binario:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio",
        "--no-authentication"
      ],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}

Autenticación de Usuario/Contraseña con Binario:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio",
        "--user",
        "myuser"
      ],
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_PASSWORD": "mypass"
      }
    }
  }
}

Configuración de Docker:

{
  "mcpServers": {
    "nats": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "NATS_URL",
        "-e",
        "NATS_SYS_CREDS",
        "ghcr.io/sinadarbouy/mcp-nats:0.1.4",
        "--transport",
        "stdio"
      ],
      "env": {
        "NATS_SYS_CREDS": "<base64 of SYS account creds>",
        "NATS_URL": "<nats url>"
      }
    }
  }
}

Desarrollo

Requisitos Previos

  • Go 1.25+
  • Docker (opcional)
  • CLI de NATS
  • Comprensión de la especificación MCP

Comandos Make Disponibles

make help      # Print help message
make build     # Build the binary
make run       # Run in stdio mode
make run-sse   # Run with SSE transport
make lint      # Run linters

Pruebas con Transporte stdio

Para instrucciones detalladas sobre cómo probar el servidor MCP usando el transporte stdio, consulte nuestra Guía de Ejemplo Stdio.

Recursos