AI导哈

NATS消息流管理工具

NatsMCP是一个用于与NATS交互的非官方服务器，提供流创建、消息发布、诊断分析和备份恢复等功能，适用于消息系统管理和监控。

  • by theworksofvon
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 theworksofvon/nats-mcp

使用说明

NatsMCP

非官方的Nats MCP服务器与Nats交互。

特性

  • 按需创建流
    只需一个提示即可启动完全配置的JetStream流（存储、限制、副本）。

  • 添加或更新主题过滤器
    在不停机的情况下将新主题添加到任何现有流中。

  • 一次性消息发布
    将JSON或纯文本有效载荷发送给任何受试者，供烟雾测试生产者或消费者使用。

  • 集群库存概览
    列出当前JetStream域中的每个流，包括消息/字节计数和副本信息。

  • 流健康诊断
    获取一份涵盖保留限制、利用率和常见错误配置的丰富报告。

  • 消费者滞后和状态分析
    检查任何消费者的已交付、待处理、重新交付的计数和实时延迟。

  • 详细的消费者诊断
    深入了解消费者的配置（ack策略、交付策略、过滤器），并发现危险信号。

  • 人性化的错误和指导
    直接的解释和补救技巧，而不是神秘的堆栈痕迹。

  • 按需添加采购 在现有流的源代码中添加新流。

  • 流备份和还原 将流配置和状态备份到Google Cloud Storage，具有基于智能日期的还原功能。

  • 灵活的NATS身份验证 使用令牌、creds文件、creds字符串或根本不进行身份验证连接到NATS。有关详细信息，请参阅用法/配置。

  • 高级消息工具 按主题、标题或大小列出、过滤和检查邮件，并查看邮件详细信息。

安装

先决条件

  • Node.js（v16或更高版本）
  • npm或纱线
  • 谷歌云存储桶（可选，仅备份/还原功能需要）
  • Express（可选，仅SSE/远程模式需要）
  • Docker（可选，用于通过容器运行）

使用Docker运行（快速入门）

您可以使用最新的Docker镜像立即运行NatsMCP：

docker pull theworksofvon915/nats-mcp:latest

然后，在您的AI助手配置中，您可以使用：

{
  "mcpServers": {
    "NatsMCP": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NATS_SERVER_URL=YOUR_NATS_URL",
        "theworksofvon915/nats-mcp:latest"
      ]
    }
  }
}

替换 YOUR_NATS_URL 使用您的NATS服务器URL（例如。， nats://localhost:4222).

您还可以传递其他环境变量（请参阅下面的选项）

从源代码构建

# Clone the repository
git clone https://github.com/theworksofvon/nats-mcp/nats-mcp.git
cd nats-mcp

# Install dependencies
npm install

# If you want to use SSE (remote) mode, install express:
npm install express
npm install --save-dev @types/express

# If you want to use backup/restore features, install Google Cloud Storage:
npm install @google-cloud/storage

# Build the project
npm run build

用法

设置

  1. 构建项目以生成 build 文件夹
npm run build
  1. 通过创建配置文件（例如。， claude_desktop_config.json):
{
  "mcpServers": {
    "NatsMCP": {
      "command": "node",
      "args": [
        "/path/to/your/nats-mcp/build/index.js"
      ],
      "env": {
        "NATS_SERVER_URL": "YOUR_NATS_SERVER_URL",
        "NATS_DOMAIN": "YOUR_JS_DOMAIN",
        // gcloud
        // "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID",
        // "GOOGLE_CLOUD_CLIENT_EMAIL": "YOUR_SERVICE_ACCOUNT_EMAIL",
        // "GOOGLE_CLOUD_PRIVATE_KEY": "YOUR_SERVICE_ACCOUNT_PRIVATE_KEY"

        // Http
        // "MCP_TRANSPORT": <sse or exclude for local>
        // "PORT": < define port # or exclude for local>

        // Optional Nats
        // "NATS_CONNECTION_NAME": "YOUR_CONNECTION_NAME"
        // "NATS_TOKEN": "YOUR_NATS_TOKEN"
        // "NATS_CREDS_FILE": "PATH_TO_NATS_CREDS_FILE"
        // "NATS_CREDS": "NATS_CREDS_FILE_CONTENTS"
      }
    }
  }
}

替换占位符：

  • /path/to/your/nats-mcp/build/index.js -构建的index.js文件的完整路径
  • NATS_SERVER_URL -指向nats服务器的URL（例如。， nats@localhost:4222)
  • NATS_DOMAIN -你的JS域名
  • GOOGLE_CLOUD_PROJECT -您的Google Cloud项目ID（可选）
  • GOOGLE_CLOUD_CLIENT_EMAIL -服务帐户电子邮件（可选）
  • GOOGLE_CLOUD_PRIVATE_KEY -服务帐户私钥（可选）
  • NATS_TOKEN -用于身份验证的NATS令牌（可选）
  • NATS_CREDS_FILE -NATS creds文件的路径（可选）
  • NATS_CREDS -NATS将文件内容创建为字符串（可选）

灵活的NATS身份验证

NatsMCP支持连接到NATS服务器的多种身份验证方法：

  • 代币：设置 NATS_TOKEN 在您的环境或配置中。
  • 凭据文件：设置 NATS_CREDS_FILE 走向你的道路 .creds 文件。
  • 凭据字符串：设置 NATS_CREDS 到您的creds文件的内容（作为字符串）。
  • 无身份验证：如果未设置上述任何一项，则NatsMCP将在不进行身份验证的情况下连接。

运行服务器

  • 本地（stdio）模式（默认，不需要express）：

    npm start

    服务器将在本地运行，并通过stdio（用于桌面/本地AI助手）进行通信。

  • 远程（SSE）模式（需要快速）：

    MCP_TRANSPORT=sse PORT=8080 npm start

    服务器将侦听指定端口（默认8080）并公开两个端点：

    • /sse （用于SSE连接）
    • /messages （用于消息POS）

    注： 如果在没有安装express的情况下以SSE模式运行，服务器将退出并显示错误和说明。

  • 备份/还原（需要@google云/存储）： 如果你想使用备份和还原工具，你必须安装谷歌云存储库：

    npm install @google-cloud/storage

    如果在没有此库的情况下运行备份/还原命令，服务器将显示错误和说明。

使用您的AI助手

配置后，您可以要求您的AI助手：

  1. 发布消息：
"Can you publish this message {"message" : "test" } to subject test.subject"
  1. 诊断流/消费者问题：
"What's going wrong with stream-2 and consumer-1?"
  1. 创建流：
"Can you create me a new stream, stream-7 with all default values ?"
  1. 添加来源：
"Can you add stream-1 to source-stream-2 sourcing list ?"
  1. 备份流：
"Can you backup stream-1 to my-backups-bucket?"
  1. 恢复流：
"Can you restore stream-1 from the backup closest to May 30th?"
  1. 列出最近的消息：
"Show me the 5 most recent messages in stream-1."
  1. 按主题筛选邮件：
"List the last 10 messages in stream-1 with subject 'foo.bar'."
  1. 按邮件标题搜索邮件：
"Find messages in stream-1 with header 'x-request-id'."
  1. 显示邮件大小分布：
"Show the size distribution of the last 100 messages in stream-1."
  1. 查看特定消息：
"Show me message 42 in stream-1."

可用的MCP工具

NatsMCP向您的AI助手公开了以下以JetStream为中心的工具：

  • createStream：使用给定的名称、主题集、存储类型、限制等创建新流。
  • addSubjects：将一个或多个附加主题附加到现有流中。
  • publish：将任意文本有效负载发布到集群中的任何主题（便于烟雾测试）。
  • listStreams：列出配置的JetStream域中的每个流以及基本统计数据。
  • diagnoseStream：为流生成详细的运行状况报告——消息/字节、限制、潜在问题。
  • checkConsumerLag：显示特定消费者的挂起、重新交付和延迟指标。
  • diagnoseConsumer：深入了解一个消费者的配置和运行时状态，突出显示危险信号。
  • addStreamSource：将流添加到SourceStream源列表中。
  • checkStreamSources：检查流中列出的源。
  • removeStreamSource：从另一个流源列表中删除一个流。
  • deleteStream：完全删除流。
  • backupStream：使用Google Cloud Storage备份或还原流的配置和状态。
  • listBackups：列出流的可用备份，并查找距离特定日期最近的备份。
  • listRecentMessages：列出流中最近的N条消息。
  • listMessagesBySubject：列出流中与主题筛选器匹配的N条最新消息。
  • searchMessagesByHeader：在流中查找包含特定标头键（以及可选值）的消息。
  • messageSizeDistribution：显示流中消息大小的最小值、最大值、平均值和直方图。
  • viewMessage：按序列号查看流中的特定消息。

可用MCP资源

NatsMCP还提供以下用于监视和诊断的资源：

  • /streams/health：提供所有流的实时健康指标和状态，包括：

    • 消息计数和字节大小
    • 序列号（第一个和最后一个）
    • 消费者数量
    • 删除统计
    • 流配置详细信息（最大年龄、字节数、消息、存储类型、副本）

  • /consumers/status：提供所有流中所有消费者的当前状态，包括：

    • 传递状态（已传递和已确认的消息）
    • 待处理邮件计数
    • 重新交付统计
    • 消费者配置（ack策略、交付策略等）

  • /cluster/stats：提供集群范围内的统计数据和指标，包括：

    • 流总数
    • 所有流中的消息和字节总数
    • 按存储类型划分的流分布
    • 按副本数量分布流
    • 消费者总数

这些资源返回可用于监视、警报和诊断的JSON数据。它们可以通过MCP协议访问，并可以与您的监控系统集成。

相关 MCP