topiclint

Name: topiclint
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords开发工具01 周前更新

代码仓库

关于 topiclint

topiclint 是本地离线的命令行工具和 stdio MCP 服务，用于按 Sparkplug B 语法检查 MQTT 主题，并审查 Unified Namespace 路径的命名一致性。它报告语法问题和命名模式，不连接代理。

主要功能

01检查 Sparkplug B 主题语法
02检查 UNS 路径一致性
03发现重复路径和空层级
04标记通配符与空白问题
05报告命名和层级深度模式

适用场景

01发布到代理前验证主题
02设计命名空间时审查 UNS 路径
03查找大小写或层级深度不一致

MCP 相关

向 MCP 客户端提供两个工具：一个解析并检查 Sparkplug 主题，另一个检查一组路径中的 UNS 命名问题。两者均在本地运行，不访问网络。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-topiclint": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/topiclint"
      ]
    }
  }
}

启动命令npx -y @reneturcios/topiclint

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/topiclint0.1.0stdio

ocighcr.io/cloudcorprecords/topiclint:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
topics	any	是	要根据 Sparkplug B 主题语法进行验证或检查 UNS 命名一致性的 MQTT 主题字符串。

详细介绍

topiclint

topiclint 会在 MQTT 主题字符串到达代理或进入命名空间设计评审之前对其进行检查。它会根据 Sparkplug B 主题语法（Sparkplug 3.0）检查单个主题，并审核整组 Unified Namespace（UNS）主题路径的命名一致性——例如大小写混用、层级深度不一、相似的同级路径等偏差，这些问题会让命名空间难以浏览、查询和交接。一个二进制文件同时提供命令行接口和 stdio MCP 服务。

所有操作都在本地离线完成。无需连接代理、无需网络访问、无需 API 密钥，也无需账户。此检查器仅验证语法：不会解码负载，也不会检查设备是否存在。命名检查只评估一致性：它不了解你的工厂，也不会为你设计命名空间。

安装

npx @reneturcios/topiclint lint spBv1.0/Plant1/NBIRTH/Edge1

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/topiclint

容器默认启动 MCP 服务（见下文）；传入 CLI 参数即可将其用作 CLI。

CLI

topiclint lint spBv1.0/Plant1/NBIRTH/Edge1 spBv1.0/Plant1/DDATA/Edge1/Dev1
topiclint check enterprise/site1/line1 enterprise/site1/line2

topiclint --version

每个主题或路径都是一个参数；单个参数也可以是以换行符分隔的列表。两条命令都会输出 JSON 报告。即使报告中包含大量问题，运行仍然成功——问题就是输出内容，并非错误。退出代码：成功时为 0，运行时错误时为 1，用法错误时为 2。

Sparkplug 检查内容

对每个主题检查：spBv1.0 命名空间层级；消息类型（NBIRTH、NDEATH、DBIRTH、DDEATH、NDATA、DDATA、NCMD、DCMD 之一，以及 STATE）；层级数量（节点消息和 STATE 恰好有四层，设备消息恰好有五层）；旧版 Sparkplug 2.2 STATE 格式（不含命名空间的 STATE/<host_id>），并将其作为单独的问题报告；发布端 MQTT 通配符（+ / #）；空层级；以及 group、node 和 device 层级中的标识符字符——空白字符会导致失败，[A-Za-z0-9_-] 以外的字符会发出警告，因为两者都会影响下游使用者拆分、引用或映射主题。

每个结果都包含解析后的主题部分（命名空间、group id、消息类型、edge node id、device id），以及按顺序排列的问题项，级别为 fail / warn / pass / info。

UNS 检查内容

对整组路径检查：重复路径、空层级、段中的空白字符以及多余的 MQTT 通配符都会导致失败。同一父级下名称仅大小写不同的同级路径会因大小写冲突而失败——它们看起来像一个节点，实际却是两个。层级深度不一致以及大小写风格混用（lower、upper、snake_case、kebab-case、PascalCase、camelCase）会发出警告。报告以一行摘要开头，随后列出每项问题。

MCP 服务

一个二进制文件同时提供两种接口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/topiclint mcp

MCP 客户端配置：

{
  "mcpServers": {
    "topiclint": {
      "command": "npx",
      "args": ["-y", "@reneturcios/topiclint", "mcp"]
    }
  }
}

工具

两个工具都接收单个 topics 参数：单个字符串、以换行符分隔的字符串，或主题字符串数组。

工具	输入	返回内容
`lint_sparkplug_topic`	`topics`（字符串或字符串数组）	每个主题解析后的部分及按顺序排列的问题项，并附带通过／失败计数和摘要。
`check_uns_namespace`	`topics`（字符串或字符串数组）	整组路径的摘要行及每项问题的详细信息。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx