NATS

Um servidor MCP para integração com o sistema de mensagens NATS.

GitHub
50
Experimente este MCPPatrocinado

Documentação

mcp-nats

Install MCP Server Install in VS Code

Um servidor Model Context Protocol (MCP) para integração com o sistema de mensageria NATS

MCP Review Certified

Este servidor MCP é certificado pelo MCP Review.

Visão Geral

Este projeto fornece um servidor Model Context Protocol (MCP) para NATS, permitindo que modelos de IA e aplicações interajam com sistemas de mensageria NATS por meio de uma interface padronizada. Ele expõe um conjunto abrangente de ferramentas para interagir com servidores NATS, tornando-o ideal para aplicações com tecnologia de IA que precisam trabalhar com sistemas de mensageria.

O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicações fornecem contexto para Modelos de Linguagem de Grande Escala (LLMs). Este servidor implementa a especificação MCP para fornecer capacidades de mensageria NATS para LLMs e aplicações de IA, permitindo que eles:

  • Interajam com sistemas de mensageria NATS de forma padronizada
  • Inspecionem e monitorem com segurança servidores e streams NATS
  • Realizem operações somente leitura por meio de uma interface segura
  • Integrem-se com outros clientes e hosts compatíveis com MCP

Recursos

  • Gerenciamento de Servidores (Operações Somente Leitura)
    • Listar e inspecionar servidores NATS
    • Monitoramento de saúde do servidor e ping
    • Recuperação de informações do servidor
    • Medição de tempo de ida e volta (RTT)
  • Operações de Stream (Operações Somente Leitura)
    • Visualizar e inspecionar streams NATS
    • Consultas de estado e informações do stream
    • Visualização e recuperação de mensagens
    • Inspeção de assuntos
  • Operações de Object Store
    • Criar e gerenciar buckets de object store
    • Colocar e obter arquivos de object stores
    • Listar buckets e seus conteúdos
    • Excluir objetos e buckets
    • Observar buckets para alterações
    • Selar buckets para evitar atualizações
  • Operações de Key-Value
    • Criar e gerenciar buckets KV
    • Armazenar e recuperar pares chave-valor
    • Observar atualizações de KV
    • Excluir chaves e buckets
  • Operações de Publicação
    • Publicar mensagens em assuntos NATS
    • Suporte para diferentes formatos de mensagem
    • Publicação assíncrona de mensagens
  • Operações de Conta
    • Visualizar informações e métricas da conta
    • Gerar relatórios de conta (conexões e estatísticas)
    • Criar e restaurar backups de conta
    • Inspecionar cadeia TLS para servidores conectados
  • Suporte Multi-Conta
    • Lidar com múltiplas contas NATS simultaneamente
    • Gerenciamento seguro de credenciais
  • Integração MCP
    • Implementa a especificação do servidor MCP
    • Compatível com clientes MCP como Claude Desktop
    • Definições de ferramentas padronizadas para interação com LLM
    • Operações seguras e somente leitura para interação de IA com NATS

Requisitos

  • Go 1.25 ou posterior
  • Servidor NATS (acessível via URL)
  • Credenciais NATS para autenticação
  • Cliente compatível com MCP (ex.: Claude Desktop ou outros clientes MCP)

Instalação

Usando Go

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

Compilando a partir do Código Fonte

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

Chart Helm (Kubernetes)

O chart está em deploy/charts/mcp-nats. Guias de instalação (incluindo OCI / GHCR e dependencies de umbrella-chart), visão geral de valores, probes e o exemplo de HashiCorp Vault Agent Injector estão em deploy/charts/mcp-nats/README.md.

Início rápido a partir da raiz do repositório:

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

As versões publicadas também podem ser instaladas a partir de OCI, por exemplo:

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

Consulte o README do chart para trechos de dependência Chart.yaml e login no registro.

Assinaturas de imagem de contêiner

As versões com tag publicam ghcr.io/sinadarbouy/mcp-nats e assinam o índice multi-arquitetura (e cada manifesto de plataforma) com Sigstore Cosign usando GitHub OIDC sem chave.

Verifique uma tag 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

Tags históricas publicadas antes da adição da assinatura podem ser assinadas em Actions → sign-image (executado a partir de main).

Teste de Integração Tilt (Docker Desktop Kubernetes)

Use Tilt para implantar tanto o NATS oficial quanto o chart mcp-nats local para testes de autenticação de ponta a ponta.

Pré-requisitos:

  • Tilt instalado
  • Helm instalado
  • Docker Desktop Kubernetes habilitado
  • Contexto kube atual definido para docker-desktop

Inicie a stack de integração:

tilt up

Isso usa:

  • Tiltfile
  • deploy/tilt/nats-values.yaml
  • deploy/tilt/mcp-nats-values.yaml
  • uma compilação de imagem local com deploy/tilt/Dockerfile.tilt antes da implantação via Helm

Pare e limpe:

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

Comandos rápidos de verificação:

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

Teste rápido de autenticação:

  • O NATS é configurado com mcpuser / mcppassword em deploy/tilt/nats-values.yaml.
  • mcp-nats usa as mesmas credenciais por meio de segredo gerenciado pelo chart em deploy/tilt/mcp-nats-values.yaml.
  • Se as credenciais não corresponderem, os logs de mcp-nats mostrarão falhas de conexão/autenticação.

Configuração

Variáveis de Ambiente

  • NATS_URL: A URL do seu servidor NATS (ex.: localhost:4222)
  • NATS_<ACCOUNT>_CREDS: Credenciais NATS codificadas em Base64 para cada conta
    • Exemplo: NATS_SYS_CREDS, NATS_A_CREDS
  • NATS_NO_AUTHENTICATION: Defina como "true" para habilitar conexões anônimas (sem credenciais necessárias)
  • NATS_USER: Nome de usuário ou token para autenticação usuário/senha
  • NATS_PASSWORD: Senha para autenticação usuário/senha

Flags de Linha de Comando

  • --transport: Tipo de transporte (stdio, sse ou streamable-http), padrão: streamable-http
  • --address: Endereço para o transporte HTTP escutar, padrão: 0.0.0.0:8000
  • --endpoint-path: Caminho do endpoint para transporte streamable-http, padrão: /mcp
  • --sse-address: Alias obsoleto de --address
  • --log-level: Nível de log (debug, info, warn, error), padrão: info
  • --json-logs: Saída de logs em formato JSON, padrão: false
  • --no-authentication: Permitir conexões anônimas sem credenciais
  • --user: Nome de usuário ou token NATS (também pode ser definido via variável de ambiente NATS_USER)
  • --password: Senha NATS (também pode ser definida via variável de ambiente NATS_PASSWORD)

Endpoints de Saúde (transportes HTTP)

  • GET /livez: verificação de vivacidade do processo (não valida a dependência NATS)
  • GET /readyz: verificação de prontidão (valida conectividade TCP com NATS_URL)
  • GET /healthz: alias de compatibilidade para vivacidade

Esses endpoints estão disponíveis quando executados com transporte sse ou streamable-http.

Probes do chart Helm

Probes padrão e lifecycle.preStop estão documentados em deploy/charts/mcp-nats/README.md.

Métodos de Autenticação

O servidor MCP NATS suporta três métodos de autenticação:

  1. Autenticação baseada em Credenciais (padrão): Usa arquivos de credenciais NATS

    • Defina as variáveis de ambiente NATS_<ACCOUNT>_CREDS
    • Requer o parâmetro account_name em todas as ferramentas

  2. Autenticação Usuário/Senha: Usa nome de usuário e senha

    • Defina as variáveis de ambiente NATS_USER e NATS_PASSWORD ou use as flags --user e --password

  3. Autenticação Anônima: Nenhuma autenticação necessária

    • Defina a variável de ambiente NATS_NO_AUTHENTICATION=true ou use a flag --no-authentication

Exemplo 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 com servidor MCP remoto

Certifique-se de que seu .vscode/settings.json inclua:

"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"
    }
  }
}

Autenticação Anônima:

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

Autenticação Usuário/Senha:

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

Se estiver usando o binário:

{
  "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>"
      }
    }
  }
}

Autenticação Anônima com Binário:

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

Autenticação Usuário/Senha com Binário:

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

Configuração 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>"
      }
    }
  }
}

Desenvolvimento

Pré-requisitos

  • Go 1.25+
  • Docker (opcional)
  • CLI NATS
  • Compreensão da especificação MCP

Comandos Make Disponíveis

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

Testando com Transporte stdio

Para instruções detalhadas sobre como testar o servidor MCP usando transporte stdio, consulte nosso Guia de Exemplo Stdio.

Recursos