mcp-lint

mcp-lint

检查 MCP 服务工具架构，确保跨客户端兼容。

MCP 服务会公开供 Claude、Cursor、Gemini、VS Code Copilot、Windsurf、Cline、OpenAI Agents SDK 和 Continue.dev 使用的工具架构。每个客户端对 JSON Schema 的支持程度和行为细节各不相同——在 Claude 中可用的架构，可能会在 Cursor 或 OpenAI 中悄无声息地失效。mcp-lint 会在用户发现这些问题之前将它们找出来。

$ npx mcp-lint check tools.json

search-tool
  ✖ Schema node at "inputSchema.properties.query" has `required: false` which is not valid JSON Schema.
    inputSchema.properties.query  [no-required-false]
  ⚠ Parameter "limit" in tool "search-tool" is missing a description.
    inputSchema.properties.limit  [description-exists]

1 error, 1 warning

---

安装

# One-time use (no install)
npx mcp-lint check tools.json

# Global
npm install -g mcp-lint

# Per-project dev dependency
npm install --save-dev mcp-lint

---

快速开始

# Check a JSON or YAML file
mcp-lint check tools.json

# See compatibility across all clients at a glance
mcp-lint compat tools.json

# Learn what a rule does
mcp-lint explain openai/no-additional-properties

# Auto-fix what can be fixed
mcp-lint fix tools.json --in-place

# Generate a config file
mcp-lint init

# Run as an MCP server
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 tools have compatibility issues. Run `mcp-lint check` for details.

mcp-lint compat tools.json --format markdown         # for PRs and GitHub Step Summary
mcp-lint compat tools.json --format json             # machine-readable
mcp-lint compat tools.json --client openai           # single client column
mcp-lint compat --server stdio -- node server.js

---

mcp-lint explain — 规则文档

$ mcp-lint explain openai/no-additional-properties

Rule: openai/no-additional-properties
Severity:  error
Clients:   openai
Fixable:   yes

Description
OpenAI Agents SDK strict mode requires `additionalProperties: false` on the root inputSchema.

Why
OpenAI's strict function calling mode rejects schemas that don't explicitly set
`additionalProperties: false` at the root level.

Bad example
{
  "type": "object",
  "properties": { "q": { "type": "string" } }
}

Good example
{
  "type": "object",
  "properties": { "q": { "type": "string" } },
  "additionalProperties": false
}

Auto-fix
Add `"additionalProperties": false` to the root inputSchema.

---

CLI 参考

mcp-lint check [input]

mcp-lint check tools.json

# Output formats
mcp-lint check tools.json --format terminal   # default, colored output
mcp-lint check tools.json --format json       # machine-readable (CI/CD)
mcp-lint check tools.json --format markdown   # for PRs and GitHub summaries

# Filters
mcp-lint check tools.json --clients claude,cursor,openai   # only these clients' rules
mcp-lint check tools.json --severity error                 # errors only
mcp-lint check tools.json --quiet                          # same as --severity error
mcp-lint check tools.json --ignore "debug-tool,internal-tool"

# Config
mcp-lint check tools.json --config path/to/.mcplintrc.json
mcp-lint check tools.json --no-color

# Quality score (0–100 per tool with A-F grades)
mcp-lint check tools.json --score

# Watch mode (re-lints on file change)
mcp-lint check tools.json --watch

# Live servers
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 中发现回归问题。

mcp-lint diff tools-v1.json tools-v2.json
mcp-lint diff tools-v1.json tools-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]

自动修复可安全修复的问题（不会改变语义）。

mcp-lint fix tools.json                            # fixed output to stdout
mcp-lint fix tools.json --output fixed-tools.json  # write to file
mcp-lint fix tools.json --in-place                 # overwrite original
mcp-lint fix tools.json --dry-run                  # show what would be fixed
mcp-lint fix tools.json --rules no-required-false,no-empty-enum  # specific rules only

---

mcp-lint init

在当前目录中创建默认的 .mcplintrc.json。

mcp-lint init          # fails if file already exists
mcp-lint init --force  # overwrite existing

---

规则

通用（适用于所有客户端）

规则	严重程度	可修复	描述
no-required-false	🔴 错误	✅	属性上的 required: false 不符合有效的 JSON Schema
no-content-encoding	🔴 错误	✅	MCP 客户端不支持 contentEncoding
no-empty-enum	🔴 错误	✅	空的 enum: [] 会导致参数无法满足
no-recursive-refs	🔴 错误	❌	循环 $ref 会导致大多数客户端崩溃
valid-json-schema-subset	🔴 错误	❌	不支持的关键字：oneOf、anyOf、allOf、if/then/else、not、patternProperties…
description-exists	🟡 警告	❌	工具和参数应提供描述
max-depth	🟡 警告	❌	架构嵌套超过 5 层会影响大模型的理解
no-unsupported-formats	🟡 警告	✅	不常见的 format 值（iri、json-pointer、regex…）未得到广泛支持

Claude 专属

规则	严重程度	可修复	描述
claude/no-type-array	🟡 警告	✅	"type": ["string", "null"] 这种数组语法在 Claude 中可能无法正常工作

Cursor 专属

规则	严重程度	可修复	描述
cursor/no-default-without-type	🔴 错误	✅	存在 default 值时，Cursor 要求明确指定 type
cursor/no-missing-title	🟡 警告	❌	Cursor 会在工具选择器中显示工具和参数的标题

Gemini 专属

规则	严重程度	可修复	描述
gemini/no-optional-without-default	🟡 警告	❌	明确指定 default 时，Gemini 能更好地处理可选参数
gemini/no-nested-objects	🟡 警告	❌	Gemini 对嵌套超过 2 层的对象属性支持有限

VS Code Copilot 专用

规则	严重级别	可修复	描述
vscode/max-params	🟡 警告	❌	参数超过 15 个时，VS Code Copilot 的性能会下降

Windsurf 专用

规则	严重级别	可修复	描述
windsurf/no-union-types	🟡 警告	❌	不支持包含超过 2 个变体的 anyOf

Cline 专用

规则	严重级别	可修复	描述
cline/description-max-length	🟡 警告	✅	Cline 会截断超过 200 个字符的描述

OpenAI Agents SDK 专用

规则	严重级别	可修复	描述
openai/no-additional-properties	🔴 错误	✅	严格模式要求根级输入架构中的 additionalProperties: false
openai/strict-types	🔴 错误	❌	仅允许 string、number、boolean、object、array、null

Continue.dev 专用

规则	严重级别	可修复	描述
continue/no-default-values	🟡 警告	❌	Continue.dev 会忽略 default 字段；请改为在描述中注明默认值

---

配置

mcp-lint 会从当前目录开始，向上搜索到主目录，自动发现 .mcplintrc.json。使用 --config 可覆盖配置。

{
  "rules": {
    "no-required-false": "error",
    "description-exists": "warning",
    "max-depth": "off",
    "claude/no-type-array": "error"
  },
  "clients": ["claude", "cursor", "gemini", "vscode", "windsurf", "cline", "openai", "continue"],
  "ignore": ["internal-debug-tool"],
  "maxDepth": 5
}

预设

使用 "extends" 从内置预设开始配置：

{ "extends": "recommended" }

{
  "extends": "strict",
  "rules": {
    "description-exists": "warning"
  }
}

预设	描述
recommended	启用全部 8 个客户端，使用默认严重级别
strict	将所有规则设为 error，并将 maxDepth 设为 3

规则严重级别："error" | "warning" | "info" | "off"

---

CI/CD — GitHub Actions

使用官方 Action

name: MCP Schema Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: robert19001-cmyk/[email protected]
        with:
          input: tools.json
          severity: warning
          score: 'true'
          fail_on: error

Action 输入：

输入	默认值	描述
input	(必填)	MCP 工具 JSON 文件的路径
format	terminal	terminal|json|markdown
severity	info	要报告的最低严重级别
clients	all	以逗号分隔的客户端筛选条件
fail_on	error	发现此严重级别的问题时，使 CI 失败
score	false	显示质量评分

手动配置工作流

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      # Fail the build on errors
      - run: npx mcp-lint check ./src/tools.json

      # Post compatibility matrix to PR summary
      - run: npx mcp-lint compat ./src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY
        if: always()

      # Diff against previous version
      - run: npx mcp-lint diff tools-before.json tools-after.json --format markdown >> $GITHUB_STEP_SUMMARY
        if: always()

---

插件 API

通过 npm 包分享和复用规则集。

使用插件

npm install mcp-lint-config-nextjs

{
  "plugins": ["mcp-lint-config-nextjs"],
  "extends": "recommended"
}

编写插件

插件是一个 npm 包，它会导出一个包含 Rule 对象的 rules 数组：

// mcp-lint-config-myserver/index.ts
import type { Rule } from 'mcp-lint';

const myRule: Rule = {
  id: 'myserver/no-large-params',
  severity: 'warning',
  description: 'My server limits param count to 10',
  clients: ['claude', 'cursor'],
  check(tool) {
    const count = Object.keys(tool.inputSchema.properties ?? {}).length;
    if (count > 10) return [{
      toolName: tool.name,
      ruleId: 'myserver/no-large-params',
      severity: 'warning',
      message: `Too many params (${count})`,
      path: 'inputSchema.properties',
    }];
    return [];
  },
};

export const rules = [myRule];

---

编程 API

import { LintEngine } from 'mcp-lint';
import { allRules } from 'mcp-lint/rules';
import { loadFile } from 'mcp-lint/loaders';
import { applyFixes } from 'mcp-lint/fixer';

// Check
const tools = await loadFile('tools.json');
const engine = new LintEngine(allRules, {
  clients: ['claude', 'cursor', 'openai'],
  ignore: ['debug-tool'],
});
const diagnostics = engine.lint(tools);

// Fix
const fixed = applyFixes(tools, diagnostics);

---

mcp-lint preflight — 运行时决策防火墙

Lint 可捕获不良架构，Preflight 可捕获不当操作。

运行时，Agent 即将调用工具——删除文件、发送请求、扣款。Preflight 会在 Agent 与操作之间进行拦截，并回答以下问题：

• 是否允许？
• 风险有多高？（0.0–1.0 的确定性评分）
• 是否可撤销？
• 是否需要人工审批？
• 是否存在更安全的替代方案？

$ mcp-lint preflight action.json --policy preflight.yml

Preflight Decision
────────────────────────────────────────
Decision:      DENY
Risk score:    1.00
Reversibility: irreversible
Policies:      block-destructive-prod
Reasons:       base_shell, destructive_pattern, sensitive_target, irreversible_operation

操作格式

{
  "tool_type": "shell",
  "tool_name": "bash",
  "action": "rm -rf /prod/data",
  "target": "/prod/data",
  "context": { "environment": "prod" }
}

策略文件（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 服务或 Agent 运行时

import { preflight, loadPolicy } from 'mcp-lint/preflight';

const policy = await loadPolicy('./preflight.yml');

const decision = preflight(
  {
    tool_type: 'shell',
    tool_name: 'bash',
    action: '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，以及 Glama 等目录扫描器。

npx -y mcp-lint@latest mcp-lint-server

客户端配置：

{
  "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	为拟议的 Agent 操作评分，并返回允许／拒绝／需审批／改写的决定

从宿主端的角度来看，所有服务工具都是只读的：它们返回诊断结果、修复后的 JSON 或策略决定，不会执行正在评估的操作。

Docker

docker build -t mcp-lint-server .
docker run --rm -i mcp-lint-server

此仓库包含 glama.json 和生产用 Dockerfile，便于 MCP 目录构建、启动和检查该服务。

---

许可证

MIT © Robert