MCP工具链兼容性检查与安全防护：mcp-lint工具全解析

1. 项目概述：MCP工具链的“质检员”

如果你正在开发或维护一个MCP服务器，那么你肯定遇到过这样的场景：你精心设计的工具在Claude Desktop里运行得丝滑流畅，但一到Cursor或者VS Code Copilot里，要么调用失败，要么返回的结果驴唇不对马嘴。更头疼的是，这些客户端通常不会给你一个清晰的错误提示，它们只是默默地“不工作”了。这种跨客户端的兼容性问题，就像是为不同品牌的手机开发充电器，接口看着都一样，但内部的协议和电压要求千差万别。mcp-lint就是为了解决这个痛点而生的。

简单来说，mcp-lint是一个专门用于检查和修复MCP服务器工具模式（Tool Schema）的静态分析工具。它的核心使命是确保你定义的JSON Schema，能够在所有主流的MCP客户端（包括Claude、Cursor、Gemini、VS Code Copilot、Windsurf、Cline、OpenAI Agents SDK和Continue.dev）中稳定、一致地工作。它不仅仅是一个语法检查器，更是一个“兼容性专家”，能洞察每个客户端对JSON Schema的独特“癖好”和限制。

想象一下，你定义了一个搜索工具，其中有一个可选的查询参数query。在标准的JSON Schema Draft-07中，你可能会习惯性地写成"required": false。但这个写法在MCP的上下文中是无效的，因为required是一个数组，用于列出必需的属性名。mcp-lint的no-required-false规则会立刻揪出这个错误。又比如，为了确保数据结构的纯净，你在根inputSchema上设置了"additionalProperties": true，这本身是合法的JSON Schema，但OpenAI Agents SDK的严格模式会直接拒绝它，要求必须是false。mcp-lint的openai/no-additional-properties规则就是为这个场景准备的。

这个工具适合所有MCP生态的参与者：无论是刚开始接触MCP，正在构建第一个服务器的新手，还是维护着复杂工具集、需要确保每次更新都不破坏现有客户端兼容性的资深开发者。它通过命令行、配置文件、CI/CD集成乃至编程API，为你提供从开发到部署的全流程质量保障。

2. 核心设计思路：规则引擎与客户端矩阵

mcp-lint的设计非常清晰，它围绕两个核心概念构建：规则和客户端。理解这两者是如何协同工作的，是高效使用这个工具的关键。

2.1 规则：从通用校验到客户端特例

规则是mcp-lint进行诊断的基本单元。每条规则都定义了三个关键要素：问题描述、严重级别和作用范围。

通用规则是面向所有MCP客户端的。它们检查的是那些被广泛接受为最佳实践，或者是在MCP规范层面可能存在歧义的地方。例如：

• no-required-false：这是一个“必杀级”错误。如前所述，required字段的值必须是一个字符串数组（如["query", "limit"]），用来声明哪些属性是必填的。将一个属性标记为required: false是毫无意义的，并且会导致解析错误。这条规则之所以是error级别，是因为它几乎肯定会导致工具无法被任何客户端正确识别。
• valid-json-schema-subset：MCP工具模式基于JSON Schema，但并非所有JSON Schema特性都被支持。这条规则会检查并禁止使用一些高级或复杂的组合关键字，如oneOf、anyOf、allOf、if/then/else、not、patternProperties等。这些结构虽然强大，但会显著增加LLM理解参数的难度，且客户端支持度不一，容易引发不可预测的行为。最佳实践是使用扁平化的、结构清晰的object定义。
• description-exists：这是一条warning级别的规则。虽然缺少描述不会导致工具崩溃，但它极大地影响了可用性。一个清晰的描述能帮助LLM（和最终用户）理解这个工具或参数是做什么的，从而更准确地调用它。为每个工具和其参数添加描述，是提升工具链质量性价比最高的投入。

客户端特定规则是mcp-lint的精华所在。它封装了各个客户端实现中的“坑”。这些规则不是JSON Schema标准问题，而是特定客户端解析器或运行时环境的限制。

• openai/no-additional-properties：OpenAI Agents SDK在严格模式下，要求根对象的inputSchema必须显式设置"additionalProperties": false。如果不设置，它可能会拒绝整个模式，或者允许传入任意未定义的参数，这可能导致安全或逻辑问题。这条规则可以自动修复。
• cursor/no-default-without-type：Cursor要求，如果一个参数提供了default值，那么它必须同时显式声明type。这可能是Cursor内部用于类型推断或验证的逻辑需要。缺少type的default会导致工具在Cursor中行为异常。
• gemini/no-nested-objects：Gemini对深层嵌套的对象属性支持有限（通常建议不超过2层）。如果你的参数结构是一个“对象套对象再套对象”的复杂树，Gemini可能无法正确渲染或处理它，导致调用失败或结果错误。
• vscode/max-params：VS Code Copilot的UI和性能可能会在单个工具参数超过15个时受到影响。这条规则提醒你考虑是否应该拆分工具，或者将一些相关参数组合成一个子对象，以提升用户体验。

注意：客户端特定规则的触发，依赖于你在配置或命令行中指定了哪些客户端。如果你只检查--clients claude,openai，那么cursor/或gemini/开头的规则就不会运行。这让你可以针对你的目标部署环境进行精准检查。

2.2 客户端矩阵：一目了然的兼容性视图

理解了规则之后，“我的工具到底能在哪些客户端上用？”这个问题就变得具体了。mcp-lint compat命令提供的兼容性矩阵，就是这个问题的直观答案。

它不仅仅是对所有规则检查结果的简单汇总。其底层逻辑是：针对矩阵中的每一个单元格（例如，“search-tool” 与 “Cursor”），mcp-lint会运行所有针对该客户端的规则（包括通用规则和该客户端特定规则）。如果任何一条规则报告了error级别的诊断，该单元格就会标记为✗；如果只有warning，则可能标记为⚠（取决于输出格式）；全部通过则标记为✓。

这个矩阵的价值在于：

1. 快速评估：在开发初期或重构后，一眼就能看出工具集的整体兼容性状况。
2. 问题定位：如果某个工具在某个客户端上失败，你可以立刻知道需要关注该客户端的哪些特定规则。
3. 发布决策：比如，如果你主要用户群使用Claude和Cursor，而一个工具只在Gemini上不兼容，你可能可以选择性忽略或稍后处理；但如果它在Claude上就不兼容，这就是一个必须修复的阻塞性问题。

在CI/CD流程中，将mcp-lint compat --format markdown的输出追加到GitHub Step Summary，能为代码审查者提供极其有价值的上下文信息，让兼容性状态成为每次PR的可见部分。

3. 从安装到上手：完整的工具链集成

mcp-lint提供了多种安装和使用方式，以适应不同的工作场景。作为一线开发者，我的建议是根据你的使用频率和场景来选择。

3.1 安装策略选择

• 临时尝鲜/一次性检查：使用npx是最佳选择。无需安装，直接运行npx mcp-lint check tools.json。这对于快速验证一个现有文件，或者在陌生环境中进行诊断非常方便。
• 频繁使用的开发环境：通过npm install -g mcp-lint进行全局安装。安装后，你可以在任何项目的目录下直接使用mcp-lint命令。这适合需要经常检查多个不同MCP服务器项目的开发者。
• 项目级依赖（推荐）：通过npm install --save-dev mcp-lint将mcp-lint作为开发依赖添加到你的MCP服务器项目中。这是我最推荐的方式，因为它：
  • 版本锁定：确保团队每个成员使用相同版本的mcp-lint，避免因规则更新导致的检查结果不一致。
  • 集成便捷：可以方便地在package.json的scripts中定义检查命令，如"lint:mcp": "mcp-lint check ./src/tools.json"。
  • CI/CD就绪：GitHub Actions等CI环境可以自然地通过npm ci或npm install获取该工具。

3.2 配置文件：团队协作与规则定制

对于任何严肃的项目，使用配置文件.mcplintrc.json都是必须的。它保证了代码库中代码质量检查标准的一致性。

运行mcp-lint init会在当前目录生成一个默认配置。这个文件的核心是rules对象，你可以在这里覆盖任何规则的严重级别。

{ "rules": { "description-exists": "warning", // 保持警告，提醒但不阻塞 "max-depth": "off", // 我们的工具结构复杂，暂时关闭深度检查 "openai/no-additional-properties": "error", // 我们面向OpenAI，此规则必须为错误 "vscode/max-params": "off" // 我们的工具参数多，且VS Code用户少，关闭 }, "clients": ["claude", "cursor", "openai"], // 只检查我们明确支持的客户端 "ignore": ["internal-debug-tool", "admin-*"] // 忽略内部调试工具和所有管理员工具 }

配置的继承是一个强大功能。mcp-lint提供了recommended和strict两个内置预设。

• "extends": "recommended"：启用所有8个客户端，并使用默认的严重级别（错误/警告）。这是一个很好的起点。
• "extends": "strict"：将所有规则都设置为error级别，并将模式最大深度maxDepth限制为3。这对于追求最高质量、希望零警告的项目非常有用。

你可以基于预设进行扩展和覆盖：

{ "extends": "strict", "rules": { "description-exists": "warning" // 在严格模式下，仍将描述缺失视为警告而非错误 }, "maxDepth": 5 // 放宽严格模式的深度限制 }

实操心得：我建议团队在项目初期采用strict预设，快速暴露所有潜在问题。在迭代过程中，如果某些规则确实与业务逻辑冲突（比如必须使用深层嵌套对象），再通过配置将其降级为warning或off。这比一开始就放任不管要好得多。

3.3 核心命令详解与工作流

mcp-lint的CLI设计得非常直观。下面是一个典型的开发工作流：

1. 初始检查与修复：

   # 1. 首次检查，查看所有问题 mcp-lint check src/tools.json # 2. 尝试自动修复那些可以安全修复的问题（如 no-required-false） mcp-lint fix src/tools.json --dry-run # 先预览会修改什么 mcp-lint fix src/tools.json --in-place # 确认无误后，原地修改文件 # 3. 再次检查，处理剩余需要手动修复的问题 mcp-lint check src/tools.json

2. 兼容性评估：

   # 生成兼容性矩阵，了解整体支持度 mcp-lint compat src/tools.json --format markdown > COMPATIBILITY.md

3. 集成到开发循环：

   # 使用 --watch 模式，在修改文件时自动重新检查 mcp-lint check src/tools.json --watch

   将上述命令与你的编辑器（如VS Code）的任务系统结合，或者使用onchange这样的npm包，可以实现保存文件后自动lint，获得即时反馈。

4. 版本对比： 在重构或升级工具模式时，diff命令无比珍贵。

   # 比较旧版本和新版本的检查结果，确保没有引入新的错误 mcp-lint diff tools-v1.2.json tools-v1.3.json

   如果输出为空，说明没有新增错误（警告的变化会被忽略，除非使用--severity warning）。这个命令可以很容易地集成到CI中，作为PR的关卡。

4. 进阶应用：CI/CD集成与Preflight安全门

当你的MCP服务器从个人项目走向团队协作和生产环境时，自动化检查和安全防护就变得至关重要。mcp-lint在这两个场景下提供了强大的支持。

4.1 无缝集成GitHub Actions

官方提供的GitHub Actionrobert19001-cmyk/mcp-lint让集成变得非常简单。以下是一个功能完整的示例工作流文件.github/workflows/mcp-lint.yml：

name: MCP Schema Lint on: [push, pull_request] jobs: lint-schema: name: Lint MCP Tool Schemas runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Lint MCP schemas uses: robert19001-cmyk/mcp-lint@v0.3.0 # 使用固定版本 with: input: 'src/tools.json' # 你的工具模式文件路径 severity: 'warning' # 报告警告及以上级别的问题 fail_on: 'error' # 只有当发现错误时才使工作流失败 score: 'true' # 输出质量评分（A-F） - name: Upload compatibility report if: always() # 即使lint失败，也生成报告 run: | npx mcp-lint compat src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY

这个工作流会在每次推送或创建PR时运行。fail_on: 'error'是关键配置，它确保只有破坏性的错误会阻止合并，而警告则作为提示出现在检查结果中，供开发者参考。

质量评分(--score) 是一个很好的量化指标。它会为每个工具计算一个0-100的分数（并转换为A-F等级），基于触发的规则严重性和数量。在PR评论中看到一个工具从“C”提升到“A”，是非常有成就感的。

4.2 Preflight：运行时安全决策防火墙

如果说lint是“代码层面的静态安检”，那么preflight就是“执行前的动态安全许可”。这是一个革命性的特性，它将安全左移到了运行时。

它解决什么问题？你的AI助手（Agent）通过MCP工具获得了强大的能力，比如执行Shell命令、操作文件、调用API。一个恶意的提示词或一个错误的推理，可能导致Agent执行rm -rf /或向生产数据库发送错误查询。preflight在工具被真正执行前介入，根据预定义的安全策略，决定是放行、阻止、重写操作，还是要求人工审批。

核心概念解析：

1. 动作：一个即将发生的具体操作，用结构化的JSON描述。它包含了工具类型、名称、原始动作指令、目标、上下文等信息。

   { "tool_type": "sql", "tool_name": "execute_query", "action": "DELETE FROM users WHERE id = 123", "target": "production_database", "context": { "environment": "prod", "user_role": "assistant" } }

2. 策略：一组用YAML定义的规则，用于评估动作。每条规则定义了触发条件 (when) 和处置效果 (effect)。
3. 决策：preflight引擎的评估结果，包含最终裁决 (allow,deny,require_approval,allow_with_rewrite)、风险评分 (0.0-1.0)、原因和可能的替代方案。

一个完整的策略文件示例(preflight-prod.yml)：

version: 1 defaults: approval_threshold: 0.70 # 风险分>=0.7需要审批 block_threshold: 0.92 # 风险分>=0.92直接阻止 rules: # 1. 绝对阻止对生产环境的破坏性操作 - id: block-prod-destructive when: environment: prod tool_type: [shell, file_system] action_matches: ["rm -rf", "format", "shutdown", "> /dev/null"] target_matches: ["/", "/etc", "/var", "/prod/*"] effect: deny risk_score: 1.0 reasons: [destructive_prod_operation] # 2. 重写开发环境的删除操作为安全操作 - id: rewrite-dev-delete when: environment: dev tool_type: shell action_matches: ["rm -rf ./*"] effect: allow_with_rewrite rewrite: tool_type: file_system action: move_to_trash target: ./* reasons: [safer_alternative_available] # 3. 对支付类操作要求人工审批 - id: require-approval-payments when: tool_type: payment effect: require_approval reasons: [financial_operation] # 4. 允许低风险的查询操作 - id: allow-safe-queries when: tool_type: [sql, api] action_matches: ["^SELECT", "^GET ", "^POST /api/query"] effect: allow risk_score: 0.1

如何集成到你的MCP服务器中？你不需要重写你的工具实现。通常，在你的MCP服务器代码中，在执行工具的核心逻辑之前，插入一个preflight检查点。

// 在你的MCP服务器工具处理函数中 import { preflight, loadPolicy } from 'mcp-lint/preflight'; const policy = await loadPolicy('./config/preflight-prod.yml'); async function handleToolCall(toolName: string, arguments: any) { // 1. 根据工具名和参数，构造一个 action 对象 const action = { tool_type: mapToToolType(toolName), // 如 "shell", "sql" tool_name: toolName, action: generateActionString(arguments), // 如 "rm -rf /tmp/logs" target: extractTarget(arguments), context: { environment: process.env.NODE_ENV, userId: currentUser.id } }; // 2. 执行Preflight检查 const decision = preflight(action, policy); // 3. 根据决策采取行动 switch (decision.decision) { case 'deny': throw new Error(`Action blocked by policy: ${decision.reasons.join(', ')}`); case 'require_approval': // 触发一个审批流程，例如发送消息到审批频道，暂停并等待响应 const approved = await requestHumanApproval(action, decision); if (!approved) throw new Error('Action not approved by human.'); break; // 审批通过，继续执行 case 'allow_with_rewrite': // 使用引擎提供的更安全的替代方案来执行 return await executeAction(decision.safe_alternative); case 'allow': // 安全放行，执行原始动作 break; } // 4. 执行实际的工具逻辑 return await executeOriginalToolLogic(toolName, arguments); }

Preflight的退出码设计得非常巧妙，可以直接在Shell脚本或简单的包装器中使用：

#!/bin/bash # 一个简单的Shell命令包装器 ACTION_JSON=$(cat <<EOF { "tool_type": "shell", "tool_name": "bash", "action": "$*", "target": "$PWD" } EOF ) # 运行preflight检查 mcp-lint preflight <(echo "$ACTION_JSON") --policy ./policy.yml EXIT_CODE=$? case $EXIT_CODE in 0) echo "允许执行: $*"; eval "$*" ;; 1) echo "需要人工审批: $*"; send_for_approval "$*" ;; 2) echo "拒绝执行: $*"; exit 1 ;; *) echo "Preflight检查错误"; exit 1 ;; esac

重要警告：preflight是一个强大的安全层，但它不是银弹。策略规则的质量决定了安全性的上限。你需要仔细定义什么操作是危险的，风险评分如何计算。切勿因为配置了preflight就对工具的实现逻辑放松警惕。它应该是深度防御策略中的一环，而不是唯一的一环。

5. 扩展与定制：插件与编程接口

当内置规则和策略无法满足你的特定需求时，mcp-lint提供了两种强大的扩展机制：插件系统和编程API。

5.1 插件系统：共享与复用规则集

插件机制允许你将一套自定义的lint规则打包成npm包进行分发和复用。这对于大型组织或框架开发者特别有用。

使用一个插件： 假设社区有一个针对“Next.js项目MCP工具”的规则包mcp-lint-config-nextjs。

1. 安装它：npm install --save-dev mcp-lint-config-nextjs
2. 在你的.mcplintrc.json中声明：

   { "plugins": ["mcp-lint-config-nextjs"], "extends": "recommended", "rules": { // 你仍然可以覆盖插件中的规则 "nextjs/no-ssr-tools": "warning" } }

   插件提供的规则会与内置规则合并。如果规则ID冲突，配置文件中显式定义的规则优先级最高。

开发一个插件： 一个插件就是一个导出了rules数组的Node.js模块。

// mcp-lint-config-mycompany/index.ts import type { Rule, Tool } from 'mcp-lint'; // 规则1：确保工具名称符合公司命名规范 (kebab-case，且以部门前缀开头) const namingConventionRule: Rule = { id: 'mycompany/naming-convention', severity: 'error', description: 'Tool names must be in kebab-case and start with department prefix.', clients: ['*'], // 适用于所有客户端 check(tool: Tool) { const violations = []; if (!/^[a-z]+(-[a-z]+)*$/.test(tool.name)) { violations.push({ toolName: tool.name, ruleId: 'mycompany/naming-convention', severity: 'error', message: `Tool name "${tool.name}" must be in kebab-case (lowercase letters and hyphens).`, path: 'name', }); } if (!tool.name.startsWith('dept-')) { violations.push({ toolName: tool.name, ruleId: 'mycompany/naming-convention', severity: 'warning', message: `Tool name "${tool.name}" should start with department prefix 'dept-'.`, path: 'name', }); } return violations; }, }; // 规则2：禁止工具使用某些高风险的关键字 const noHighRiskKeywordsRule: Rule = { id: 'mycompany/no-high-risk-keywords', severity: 'error', description: 'Tools cannot contain high-risk keywords in description or parameter names.', clients: ['*'], check(tool: Tool) { const highRiskWords = ['delete', 'drop', 'format', 'shutdown', 'password']; const violations = []; // 检查工具描述 if (tool.description && highRiskWords.some(word => tool.description.toLowerCase().includes(word))) { violations.push({ toolName: tool.name, ruleId: 'mycompany/no-high-risk-keywords', severity: 'error', message: `Tool description contains high-risk keyword.`, path: 'description', }); } // 检查参数名 const params = tool.inputSchema?.properties || {}; for (const [paramName] of Object.entries(params)) { if (highRiskWords.includes(paramName.toLowerCase())) { violations.push({ toolName: tool.name, ruleId: 'mycompany/no-high-risk-keywords', severity: 'error', message: `Parameter name "${paramName}" is a high-risk keyword.`, path: `inputSchema.properties.${paramName}`, }); } } return violations; }, }; export const rules = [namingConventionRule, noHighRiskKeywordsRule];

开发完成后，发布到npm，你的团队就可以通过插件来统一代码规范了。

5.2 编程API：深度集成与自定义工作流

对于需要将mcp-lint深度集成到自定义构建流程、开发工具或测试框架中的场景，编程API提供了最大的灵活性。

import { LintEngine } from 'mcp-lint'; import { allRules } from 'mcp-lint/rules'; import { loadFile } from 'mcp-lint/loaders'; import { applyFixes } from 'mcp-lint/fixer'; import { generateCompatibilityMatrix } from 'mcp-lint/compat'; import type { Tool, Diagnostic } from 'mcp-lint/types'; // 1. 加载并检查工具定义 async function analyzeMyTools(toolFilePath: string) { const tools: Tool[] = await loadFile(toolFilePath); // 自定义规则引擎配置 const engine = new LintEngine(allRules, { clients: ['claude', 'openai'], // 只关注这两个客户端 rules: { 'description-exists': 'error', // 将描述缺失提升为错误 'vscode/max-params': 'off', // 忽略此规则 }, ignore: ['internal-*'], // 忽略所有内部工具 }); const diagnostics: Diagnostic[] = engine.lint(tools); // 2. 处理诊断结果 if (diagnostics.some(d => d.severity === 'error')) { console.error('发现错误级别的lint问题:'); diagnostics.filter(d => d.severity === 'error').forEach(err => { console.error(` [${err.ruleId}] ${err.toolName}: ${err.message}`); }); // 可以在这里抛出异常，中断构建流程 throw new Error('MCP schema validation failed.'); } // 3. 尝试自动修复 const fixedTools = applyFixes(tools, diagnostics.filter(d => d.fixable)); // 4. 生成兼容性报告（编程方式） const matrix = generateCompatibilityMatrix(tools, { clients: ['claude', 'cursor', 'openai'] }); console.log('兼容性矩阵:', matrix); return { tools: fixedTools, diagnostics, matrix }; } // 5. 集成到单元测试中 import { describe, it, expect } from 'vitest'; // 或 jest/mocha describe('MCP Tools Schema', () => { it('should have no lint errors for production clients', async () => { const { diagnostics } = await analyzeMyTools('./tools.prod.json'); const errors = diagnostics.filter(d => d.severity === 'error'); expect(errors).toHaveLength(0); }); it('should be compatible with Claude and OpenAI', async () => { const { matrix } = await analyzeMyTools('./tools.prod.json'); // 检查所有工具对Claude和OpenAI都是兼容的 const allCompatible = matrix.every(row => row.claude === '✓' && row.openai === '✓' ); expect(allCompatible).toBe(true); }); });

通过编程API，你可以：

• 将lint检查作为构建流水线的一个强制步骤。
• 在测试套件中自动验证工具模式的质量。
• 开发自定义的IDE插件或编辑器集成，在保存文件时提供实时反馈。
• 构建更复杂的质量门禁，例如将质量评分与发布流程挂钩。

6. 常见问题、排查技巧与最佳实践

在实际使用mcp-lint的过程中，你可能会遇到一些典型问题。以下是我根据经验总结的排查清单和最佳实践。

6.1 常见问题速查表

6.2 最佳实践与经验心得

1. 将mcp-lint作为项目标配：在项目初始化时，就运行mcp-lint init创建配置文件，并将其加入package.json的scripts中。让检查工具模式成为和运行单元测试一样自然的开发步骤。

2. 在CI中同时使用check和compat：

   - name: Lint and Report run: | # 严格检查，错误则失败 npx mcp-lint check src/tools.json --severity error # 生成详细的兼容性报告，供人工查阅 npx mcp-lint compat src/tools.json --format markdown >> $GITHUB_STEP_SUMMARY

   这样既保证了基本质量，又提供了丰富的上下文信息。

3. 为Preflight策略编写测试：你的安全策略本身也需要测试。可以创建一系列代表安全、可疑、危险操作的Action JSON文件，然后编写脚本或测试用例，验证preflight对它们能做出预期的决策（允许、审批、拒绝）。

   # test_preflight.sh # 测试一个应该被允许的查询 if mcp-lint preflight test-actions/select-query.json --policy policy.yml; then echo "PASS: Safe query allowed." else echo "FAIL: Safe query was denied." exit 1 fi # 测试一个应该被拒绝的删除操作 if mcp-lint preflight test-actions/delete-prod.json --policy policy.yml; then echo "FAIL: Dangerous delete was allowed." exit 1 else echo "PASS: Dangerous delete correctly denied." fi

4. 谨慎使用自动修复：mcp-lint fix非常方便，但务必理解它做了什么。对于no-required-false这类规则，修复是明确的（删除无效字段）。但对于一些规则，自动修复可能只是应用一个“最安全”的默认值，这可能不符合你的业务逻辑。始终在修复后人工复查，或者将修复后的文件进行diff比较。

5. 描述是免费的文档：不要忽略description-exists警告。为每个工具和参数编写清晰、简洁的描述。这不仅能提高lint分数，更能极大地提升LLM调用工具的准确性和用户体验。好的描述应该说明“做什么”和“为什么”，例如"limit": "Maximum number of results to return. Helps manage response size and performance."。

6. 从严格预设开始，再按需放宽：项目初期采用"extends": "strict"预设。当遇到确实无法避免的规则冲突时（例如业务逻辑需要复杂的嵌套对象，触发了max-depth或gemini/no-nested-objects），再在配置文件中将其显式地调整为warning或off，并最好在代码附近添加注释说明原因。这比一开始就放任不管能建立起更强的质量意识。

7. 关注社区与更新：MCP协议和各客户端都在快速发展。定期更新mcp-lint版本，关注其Changelog，了解新增了哪些规则或对哪些客户端的支持发生了变化。这能帮助你提前适应生态系统的演进。