+ 发布产品

mcp-server-lint Skill 技能

MCP 服务器工具声明合规性检查器

AI编程开发
查看 Skill ↗
认领产品

技能简介

mcp-server-lint 是给 Model Context Protocol（MCP）服务器开发者用的静态合规性检查器。在你把 MCP server 的 tools 暴露给 Claude / OpenAI 之前，先用它扫描一遍，看哪些 tool 声明会被 Antrhopic / OpenAI 的兼容性规则直接打回。零运行时依赖（zero runtime deps），规则集与真实违规计数全部基于 2026-09-08 抓取的 2,283 个独立 MCP server / 29,574 个 tool 声明 语料。规则集被"冻结"且带实测违规计数，开发者可以判断每条规则命中多少"已知不兼容"。当前版本 0.1.0（2026-09-30）。

  • 一句话定位：Lint a live MCP server's tool declarations before connecting them to an agent.
  • 核心价值：上线前用真实违规频次预演每条规则的影响，省掉后期排查"为什么我的 tool 没被调用"

核心能力

  • Live HTTP 探测 + Local file 输入双模式：npx mcp-server-lint@0.1.0 lint https://YOUR_SERVER/mcp（Streamable HTTP + JSON / SSE framing，支持 MCP session header；paginated tools/list）；或 lint --file tools.json（接受 { "tools":[...] } / JSON-RPC result.tools 包装）。
  • 冻结 6 条规则（带真实计数）：
    • R1 ERROR：^[a-zA-Z0-9_-]{1,64}$ name 校验（OpenAI function definition 字符集与上限；真实 821 / 821 / 26）
    • R2 ERROR：description 缺失/空白（启发式；27 / 27 / 2）
    • R3 ERROR：inputSchema 缺失或根非 object（OpenAI Structured Outputs；0 / 0 / 0）
    • R4 WARNING：属性无 description 或 enum 关键词（OpenAI 文档质量启发式；34,510 / 8,191 / 1,019）
    • R5 ERROR：根 oneOf/anyOf/allOf/not/patternProperties 或外部 $ref（OpenAI Structured Outputs 不支持；111 / 111 / 40）
    • R6 ERROR：重复 tool name（歧义路由；0 / 0 / 0）
  • JSON 输出 + 退出码语义：0=clean/benchmark 完成；1=lint ERROR；2=transport/input/verification 失败；3=需要付费 benchmark；WARNING 单条 exit 0。
  • Schema 智能遍历：跳过 examples/defaults/enums，不 dereference 链接；R5 把任何非 fragment ref（含相对路径）判外部 ref。
  • Benchmark 付费子命令（5 USDT once）：一次性 TRC20 USDT 转账（地址 TLwka4h5Rje4cKTTFyitgBzuouG、合约 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t），提供 per-rule corpus percentile ranking；本地 honor-system gate（无密码学身份保护，buyer 自行 review）。
  • 复现一切计数：自带 data/tool-surfaces.jsonl.gz 与 data/counts.json；node scripts/count-corpus.mjs ... 在本地复算与官方一致；原始 data/tool-surfaces.jsonl SHA-256 7a4596a95d845828681b6dfe64ee580b9e11bf15a5534ad4a3821b55f3865aea 可做完整性校验。
  • 透明抽样说明：4,609 个候选 server 中 2,283 个产出保留 tools，11,835 未被探测；抽样偏差是 schema-presence 计数偏高，但诚实地写在 README。
  • 流量与隐私边界：Live 模式只发 initialize / notifications/initialized / tools/list（不做任何 tool 调用）；responses 限 32 MiB + 1,000 页；local file 不发任何网络包；零 telemetry。

安装配置

  • Node.js 前置：要求 Node.js 22 或更高。
  • npx 临时运行：npx --yes mcp-server-lint@0.1.0 lint https://YOUR_SERVER/mcp。
  • 全局安装：npm install --global mcp-server-lint@0.1.0 后用 mcp-server-lint lint https://YOUR_SERVER/mcp。
  • 本地文件 lint：mcp-server-lint lint --file tools.json（无需起 server）。
  • Benchmark 命令：mcp-server-lint benchmark https://YOUR_SERVER/mcp --payer YOUR_TRON_SENDING_ADDRESS；需先向 TLwka4h5Rje4cKTTFyitgBzuouG 转 ≥ 5 USDT（TRC20），网络费自付；自动从 TronGrid 公开账本读取入账。
  • Token 合约要求：仅接受 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t（USDT 官方合约）；用交易所出金请确认发送地址与命令行传入一致。
  • Legacy 传输说明：GET/SSE transport、stdio、需鉴权的端点在 0.1.0 暂不支持；建议用导出 JSON 的方式喂 --file。

使用步骤

  1. 准备 server URL 或 tools.json：把 MCP server 起在可访问的 URL（或把 tools/list 响应写成 JSON 文件）。
  2. 第一次扫描：npx --yes mcp-server-lint@0.1.0 lint https://YOUR_SERVER/mcp；观察每条规则的 findings 数。
  3. 复现官方计数：cd node_modules/mcp-server-lint && node scripts/count-corpus.mjs data/tool-surfaces.jsonl.gz /tmp/recount.json，对比 data/counts.json 验证数据集完整性。
  4. 修正违规：按 R1/R2/R3/R5/R6 ERROR 修 name、description、inputSchema、移除 oneOf/外部 ref、消重；R4 WARNING 视情清理。
  5. 本地离线 lint：CI 中可 mcp-server-lint lint --file tools.json，避免调用真实 server。
  6. 可选 Benchmark：5 USDT 转账后用 benchmark --payer <address> 获取 percentile 排名；Tied 分数单独给出。
  7. 集成进 CI：在 PR pipeline 跑 mcp-server-lint lint --file exported-tools.json；exit code 1 时阻断合并。

适用场景

  • MCP server 上线前合规审查：每次发布前 lint 一遍，避免上线后才发现 tool 不被调用。
  • 第三方 MCP server 接入评估：采购前用 mcp-server-lint 评估供应商的 tool 声明质量。
  • CI 流水线合规校验：把 lint 加进 PR check，ERROR 即阻断合并。
  • Schema 演化实验：改完 JSON schema 后快速复算违规计数，看 R1/R5 命中变化。
  • MCP 协议课程教学：把规则与真实违规计数做成课堂案例。
  • AI 安全审计：与 Snyk / Sonar 类似思路，把 MCP 生态质量基线化。

适用人群

  • MCP server 开发者：在上线前自查工具声明是否会被 Claude / OpenAI 直接打回。
  • AI Agent 平台架构师：评估第三方 MCP server 接入质量。
  • CI / DevOps 工程师：把 MCP 工具质量检查纳入发布流水线。
  • AI 协议研究者：研究 MCP / OpenAI function 定义 / Structured Outputs 兼容性边界。
  • 企业 AI 治理：用 lint 的真实违规计数建立 MCP server 白名单机制。
  • AI 教育者：MCP 课程教材配套工具。

工作原理

mcp-server-lint 在 live 模式下按 MCP 规范发 initialize → notifications/initialized → paginated tools/list（仅读取声明，不调任何 tool），然后用自带的 frozen 规则集遍历 declarations。R4 检查包括嵌套 schema 的 description / enum keyword 存在性；R5 把任何非 fragment $ref（含相对路径）判定为外部 ref；schema 遍历跳 examples/defaults/enums，不解析 link 标签；R6 仅在单 endpoint tools/list 内查重，不跨 endpoint。Benchmark 子命令通过本地 honor-system 读取 TronGrid 入账历史（GET /v1/accounts/{addr}/transactions/trc20），本地按 sender/recipient/token/decimals/amount/type 匹配，把 affected-tool 比例与语料整体百分位排名（分母固定 2,283）。整个程序零运行时依赖，零 telemetry，原始语料 SHA-256 公开可验。

官方链接

  • npm 包：https://www.npmjs.com/package/mcp-server-lint
  • 维护者：npm user justaiagent
  • 协议：License 见仓库 LICENSE（lint 与语料重算可商用；benchmark 使用需 5 USDT TRC20 一次性付款）
  • 当前版本：v0.1.0（2026-09-30）
mcp-server-lint 网站预览

团队信息

AI产品库 官方
由 AI 猎手自动发现

评论与建议

0 条评论