mcp-lint

mcp-lint [](https://www.npmjs.com/package/mcp-lintnpm 下载量](https://img.shields.io/npm/dmint)](https://www.npmjs.com/package/mcp-lint) [ [](https://nodejs.org) CP 服务器准备就绪](https://img.shields.io/badge/MCP-server_ready-42c1)](#-server) [](https://glama.ai/mcp/servers/robert19001-cmyk/mcp-lint) **检查 MCP 服务器工具模式以确保跨客户端兼容性。** MCP 服务器公开由 **Claude**、**Cursor**、**Gemini**、** Copilot**、**Windsurf**、**Cline**、**OpenAI 代理 SDK**Continue.dev** 等客户端使用的工具模式。每个客户端都具有不同的 JSON 模式支持和特殊情况 - 在 Claude 中有效的模式可能会在 Cursor 或 OpenAI 中无声无息地崩溃。`m` 可以在用户遇到这些问题之前捕获``` $ npx mcp-lint check toolssearch-tool ✖ 模式节点inputSchema.properties.query" 处有 `required:，这不是有效的 JSON 模式。 inputSchema.properties.query [no-required-false] 工具 "search-tool" 中的参数 "limit" 缺少描述。 inputSchema.properties.limit [description-exists] 1 个错误，1 个警告 ``` --- ## 安装 # 一次性使用（无需安装） npx mcp-lint check tools.json # 全局安装 npm install -g mcp-lint # 作为项目开发依赖安装 npm install --save-dev mcp-lint ``` --- ## 快速入门 ```bash # 检查 JSON 或 YAML 文件 mcp-lint check tools.json # 一览的兼容性 mcp-lint compat tools.json # 了解规则的作用 mcp-lint explain openai/no-additional-properties # 自动修复可以修复的问题 mcp-lint fix tools.json --in-place # mcp-lint init # 作为 MCP mcp-lint-server ``` --- ## `mcp-lint compat` — 兼容性矩阵 查看哪些工具与哪些客户端兼容： ``` $ mcp-lint compat tools.json claude cursor gemini vscode windsurf cline openai continue search-tool ✓ ✗ ✓ ✓ ✓ ✓ ✓ ✓ file-reader ✓ ✓ ✗ ✓ ✓ ✓ ✓ ✗ database-query ✓ ✓ ✓ ✓ ✓ ✓ ✗ ✓ 2 个工具性问题。运行 `mcp-lint check` 获取详细信息。 ``` ```bash mcp-lint compat tools.json --format markdown # 用于 PR 和 GitHub Step Summary mcp-lint compat tools.json --format json # 读 mcp compat tools.json --client openai # 单列 mcp-lint compat --server -- node server.js ``` --- ## `mint explain` — 规则文档 ``` $-lint explain openai/no-additional-properties 规则：openai/no-additional-properties 严重程度：错误 客户端：openai 可修复：是 OpenAI 代理 SDK 严格模式要求在根 inputSchema 上设置 `additionalProperties: false`。 原因 OpenAI 的严格函数调用模式拒绝未在根级别显式设置 `additionalProperties: false` 的模式。 错误示例 { "type":", "properties": { "q "type": "string" } } } 正确{ "type": "object", "properties": { "q": { "type": " } }, "additionalProperties": false } 自动修复 在根 inputSchema 中添加 `"additionalProperties": false`。 ``` --- ## 命令行参考 ### `mcp-lint check [input]` ```bash mcp-lint check tools.json # 输出格式 mcp-lint check tools.json --format terminal # 默认，彩色输出 mcp-lint check tools.json --format json # 机器可读（CI/CD） mcp-lint check tools.json --format markdown # 用于 PR 和 GitHub 摘要 # 过滤器 mcp-lint check tools.json --clients claude,cursor,openai # 仅这些客户端的规则 mcp-lint check tools.json --severity error # 仅错误 mcp-lint check tools.json --quiet # 与 --severity error 相同 mcp-lint check tools.json --ignore "debug-tool,internal-tool" # 配置 mcp-lint check tools.json --config path/to/.mcplintrc.json mcp-lint check tools.json --no-color # 质量评分（0-100，每个工具的 A-F 等级） mcp-lint check tools.json --score # 监视模式（文件更改时重新检查） mcp-lint check tools.json --watch 实时服务器 mcp-lint check --server stdio -- node my-server.js mcp-lint check --server stdio -- python my_server.py arg1 arg2 mcp-lint check --server sse --url http://localhost:3000/sse ``` **退出代码：** | 代码 | 含义 | |------|---------| | `0` | 无错误（警告不计） | | `1` | 找到一个或多个错误 | | `2` | 无效输入或配置错误 | --- ### `mcp-lint diff <before> <after>` 比较两个版本的模式的检查结果 - 在 CI 中很有用，可以捕获回归。 ```bashcp-lint diff tools-v1.json tools-v mcp-lint diff tools-v1-v2.json --format markdown >> $GITHUB_STEP_SUMMARY mcp-lint diff tools-v1.json tools-v2.json --format json ``` **退出代码：** `0` = 没有引入新的错误1` = 错误，`2 错误 --- ### `mcp-lint fix [input]` 自动修复可以安全修复的问题（无语义更改）。 ```bash mcp-lint fix tools.json # 修复后的输出到 stdout mcp-lint fix tools.json --output fixed-tools.json # 写入文件 mcp-lint fix tools.json --in-place # 覆盖原始文件 -lint fix toolsdry-run # 显示将要修复的内容 -lint fix tools.json --rules no-required-f-empty-enum 仅特定规则 ``` --- ### `mint init` 在当前目录中创建默认的plintrc.json```bash mint init # 如果文件已存在则失败 mcp-lint init --force # 覆盖现有文件 ``` --- ## 规则 ### 通所有客户端） | 规则 | 严重程度 | 可修复 | 描述------|----------|---------|------------- `no-required-f | 错误 | 是上的 `required: false` 不是有效的 JSON 模式 | | `no-content-encoding` | 错误 | `contentEncoding` 不受 MCP 客户端支持 | | `no-empty-enum` | 错误 | 是 | 空 `enum: []` 使参数无法满足 | | `no-recursive-refs` | 错误 | 否 | 循环 `$ref` 在大多数客户端中导致崩溃 | | `valid-json-schema-subset` | 错误 | 否 | 不支持的关键字：`one、`anyOf`、`allOf`、`if/then/else`、`、`patternProperties | | `description | 警告 | 否 | 工具和参数应该有描述 | | `max-depth` | 警告 | 否 | 模式嵌套超过 5 级会损害 LLM 的理解 | | `no-unsupported-formats` | 警告 | 是 | 不常见的 `format` 值（`、`json-pointer`、`regex`...）不支持 Claude 特定 | 规则 | 严重程度 | 可修复 | 描述 | |------|----------|---------|-------------| | `claude/no-type-array` | 警告 | 是 | `" ["string", "null"]` 数组语法在 Claude 中可能无法正确工作 Cursor 特定 | 规则 | 严重程度 | 可修复 | 描述 | |------|----------|---------|-------------| | `cursor/no-default-without-type` | 错误 | 是 | Cursor式 `type`存在 `default` | | `cursor/no-missing-title` | 警告 | 否 | Cursor 在工具选择器中显示工具和参数标题 | ### Gemini 特定 | 规则 | 严重程度 | 可修复 | 描述 | |------|----------|---------|-------------| | `gemini/no-optional-without-default` | 警告 | 否 | Gemini 更好地处理可选参数，当 `default` 显式时 | | `gemini/no-nested-objects` | 警告 | Gemini 对嵌套超过 2 级支持有限 | ### VS Code Copilot 特| 规则 | 严重程度 | 可修复|------|----------|---------|-------------| | `vscode/max-params` | 警告 | 否 | VS Code Copilot 的性能随着参数增加而下降 | ### Windsurf 特定 | 规则 | 严重程度 | 可修复 | 描述 | |------|| | `windsurf/no-union-types 警告 | 否 | 具有超过 2 个变体的 `anyOf` 不受支持 Cline 特| 规则 | 严重程度 | 可修复 | 描述 | ----------|---------|-------------| | `cline/description-max-length` | 警告 | 是 | Cline 截断超过 200 个字符的描述 | AI 代理 SDK 特定 | 规则 | 严重程度 | 可修复 | 描述 | |------|----------|---------|-------------openai/no-additional-properties` | 错误 | 是 | 严格模式要求在根 inputSchema 上设置 `: false` | |ai/strict-types` | 错误 | 否 | 仅允许 `string`、`number`、`boolean`、`object`、`array`、`null` | ### Continue定 | 规则 | 严重程度 | 可修复 | 描述 | |------|----------|---------|| `continue/no-default-values` | 警告 | 否 | Continue.dev 忽略 `default` 字段 - 而是在描述中记录默认值 | --- ## 配置 `mcp-lint` 从当前目录开始自动发现 `.mcplintrc.json`，直到您的主目录。使用 `--config` ```json { "rules "no-required-false": "error", description-exists": "warning", "max-depth": "off", "claude/no-type-array": "error" }, "clients": ["claude", "cursor", "gemini", "vscode", "windsurf", "cline", "open "continue"], "ignore": ["internal-debug-tool"], maxDepth": 5 } ``` ### 使用 `"extends"` 从内置预设开始： ```json { " "recommended" } ``` ```json { "extends": "strict", "rules": { "description-exists": "warning" } } ``` | 预设 | 描述 | |--------|-------------| | `recommended` | 所有 8 个客户端启用，默认严重程度 | | `strict` | 所有规则设置为 `error`，`maxDepth: 3` | 规则严重程度：`"error"` | `"warning"` | `"info"` | `"off"` --- ## CI/CD — GitHub Actions ### 使用官方操作 ```yaml name: MCP 模式检查 on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 : robert19001-cmyk/mcp-lint@v0.5.3 with: input: tools.json severity: warning score: 'true' fail_on: error ``` 输入：** | 输入 | 默认值 | 描述 | |-------|---------|-------------| | `input` | （必填） | MCP 工具的路径 | | `format` | `terminal` | `terminal\|json\|markdown` | | `severity` | `info` | 要报告的程度 | |` | all号分隔的客户端过滤器 | | `fail_on`error` | 在此严重程度下找到的问题时失败 CI `score` | `false` | 显示质量评分 | ### 手动工作流 ```jobs: : runs-on: ubuntu-latest steps: - uses: actions/checkout - uses: actions/setup-node with: { node-version: 20 } # 在错误时使构建失败 - run: npx mcp-lint check ./src/tools.json # 将兼容性矩阵发布 摘要 run: npx mcp-l ./src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY if: always() # 与以前的版本进行差异 - run: npx mcp-lint diff tools-before.json tools --format markdown >> $GITHUB_STEP_SUMMARY if: always() ``` --- ## 插件 API 通过共享和重用规则集。 ### 使用插件 ```bash npm install mcp-l-nextjs ``` ```json { "plugins": ["mcp-lint-config-nextjs"], "extends": "recommended" } ``` ### 编写插件 npm 包，它导rules` `Rule` 对象： ```typescript cp-lintserver/index.ts { Rule } from 'mcp-lconst myRule: Rule = { id: 'myserver/no-large-params', 'warning', : '我的服务器限制参数数量为 10', clients:aude', 'cursor'], check(tool) { const count =(tool.inputSchema {}).length if (count > 10) return [{ toolName: tool.name, ruleId: 'myserver-params', severity: 'warning', `参数过多 (${count})`, pathinputSchema.properties', }]; }, }; export const rules = [my``` --- ## 编程 API ```typescript import { LintEngine } from 'mcp-lint'; import { allRules } from 'mcp-lint/rules'; import { loadFile } from 'mcp-lint/loaders'; import { applyFixes } from 'mcp-lint/fixer'; // 检查 const tools = await loadFile('tools.json'); const engine = new LintEngine(allRules, { clients: ['claude', 'cursor', 'openai'], ignore: ['debug-tool'], }); const diagnostics = engine.lint(tools); // 修复 const fixed = applyFixes(tools, diagnostics); ``` --- ## `mcp-lint preflight` — 运行时决策防火墙 **不良模式。检查捕获不良操作。运行时，您的代理即将调用一个工具 - 删除文件、发送请求、充值卡。检查和操作之间运行，并回答： - 是否允许？ - 风险有多大？（0.0-1.0 确定性评分） - 是否可逆？ - 是否需要人工审批？ - 是否有更安全的替代方案？ ```bash $ mcp-lint preflight action.json --policy preflight.yml 检查决策 ──────────────────────────────────────── 决策： 拒绝 风险评分： 1.00 可逆性： 逆 策略-destructive原因： base_shell, destructive_pattern_target, irreversible_operation### 操作格式 ```json { "tool_type": "shell", "tool_name": "bash", "action": "rm -rf /prod/data", "target": "/prod/data", "context": { "environment": "prod" } } ``` ### 策略文件（YAML） ```yaml version: 1 defaults: approval_threshold: 0.70 block_threshold: 0.92 rules: - id: block-prod-delete when: tool_type: shell action_matches: ["rm -rf"] target_matches: ["/prod", "/etc"] effect: deny - id: rewrite-tmp-delete when: tool_type: shell action_matches: ["rm -rf ./tmp"] effect: allow_with_rewrite rewrite: tool_type: file_delete action: move_to_trash target: ./tmp - id: approval-payments when: tool_type: payment effect: require_approval ``` 样本策略位于 `examples/policies/`：`default.yml`、`strict.yml`、`permissive-dev.yml`。 ### SDK — 嵌入到您的 MCP 服务器或代理运行时 ```typescript import { preflight, loadPolicy } from 'mcp-lint/preflight'; const policy = await loadPolicy('./preflight.yml'); const decision = preflight( { tool_type: 'shell', tool_name: 'bash', : 'rm -rf /tmp', target: '/tmp', }, policy, ); if (decision.decision === 'deny throw new Error(`Blocked: ${decision.reasons.join(', ')}`); } if (decision.decision === 'require_approval') { await askUser(decision); } if (decision.decision === 'allow_with_rewrite') { return executeSafer(decision.safe_alternative); } ``` ### 退出代码 | 代码 | 含义 | |------|---------| | `0` | 允许 / 允许重写 | | `1` | 需要审批 | | `2` | 拒绝 / 错误 | 在 shell 包装器或 CI 门中直接使用它们。 --- ## MCP 服务器 `mcp-lint` 也 stdio MCP 服务器提供给 Claude Desktop、Claude Code、Cursor、VS Code 和 registry scanners，如 Glama。 ```bash npx -y mcp-lint@latest mcp-lint-server ``` 客户端配置： ```json { "mcpServers": { "mcp-lint": { "command": "npm", "args": ["exec", "--yes", "--package", "mcp-lint@latest", "--", "mcp-lint-server"] } } } ``` 可用的 MCP 工具： | 工具 | 用途 | |------|| `mcp_lint_list_rules`出内置规则、客户端、严重程度和性 | | `mcp_lint_explain_rule` | 用示例和自动修复说明解释一条规则 | | `mcp_lint_check_tools` | 检查作为 JSON 传递的 MCP 工具模式 | | `mcp_lint_fix_tools` | 返回安全自动修复的工具模式，而不写入文件 | | `mcp_lint_preflight_action` | 议的操作并返回允许/拒绝/审批/重写 | 所有服务器工具从主机角度都是只：它们返回诊断、修复的 JSON 或策略从不执行被评估的操作。 ### Docker ```bash docker build -t mcp-lint-server . docker run --rm -i mcp-lint-server ``` 存储库包括 `glama.json` 和生产 Dockerfile，以便 MCP 目录可以构建、启动并自省服务器。 --- ## 许可证 MIT © Robert