Cursor MCP注解实战：用@readOnlyHint和@destructiveHint精准控制AI工具行为

Cursor MCP注解实战：用@readOnlyHint和@destructiveHint精准控制AI工具行为

发布时间：2026/10/8 19:42:23
Cursor MCP注解实战：用@readOnlyHint和@destructiveHint精准控制AI工具行为 1. 项目概述让 Cursor 真正理解你的工具意图最近在团队里推进 AI 编程辅助落地时反复遇到一个看似微小、实则卡脖子的问题我们写了一堆自定义工具脚本——比如一键生成接口文档的 Python 脚本、自动校验数据库迁移 SQL 合法性的 Shell 工具、或是调用内部 CI API 触发构建的 Node.js 小程序——但每次在 Cursor 里调用它们AI 总是“过度谨慎”或“完全误判”。它要么拒绝执行提示“该操作可能影响系统”要么干脆绕开工具、自己硬写一段不稳定的替代逻辑。更麻烦的是当工具确实需要修改生产配置时AI 却毫无察觉直接执行埋下线上事故隐患。这个问题的本质不是 Cursor 不够聪明而是它缺乏对工具行为边界的结构化语义描述。它看到的只是一段可执行命令却不知道这个命令是读取日志安全、删除临时文件需确认、还是重置用户权限高危。而 MCPModel Communication Protocol注解正是为解决这一问题诞生的标准化契约——它不是某种神秘插件而是一套轻量、可嵌入、被主流 AI 编程工具包括 Cursor原生支持的元数据协议。通过readOnlyHint和destructiveHint这类注解我们能像给函数加类型声明一样向 Cursor 明确声明“这个工具只读放心调用”或“这个工具会删库请弹窗二次确认”。我试过三种方案纯自然语言在工具说明里写“本工具仅查询不修改数据”用 JSON Schema 描述输入输出但不声明副作用最后才真正落地 MCP 注解。前两种方式 Cursor 基本无视第三种一加上AI 的调用决策准确率从不足 40% 直接跃升到 95% 以上。这不是玄学是协议层面对齐带来的确定性。如果你也在用 Cursor 写自动化脚本、封装内部 CLI 工具、或对接公司私有 API那么这套注解机制就是你释放 AI 编程生产力的最后一块拼图——它不改变你的代码逻辑只增加几行声明却让 AI 从“猜你想做什么”变成“明确知道你能做什么”。2. 核心设计思路为什么 MCP 注解是当前最优解2.1 为什么不用自然语言描述——语义模糊性不可靠最直观的想法是在工具的 help 文档、注释或 README 里用中文/英文写清楚它的行为。比如在 Python 脚本开头写 # 数据导出工具 v1.2 本工具用于从 MySQL 导出指定表的结构和数据生成 SQL 文件。 注意仅读取数据库不会执行任何 INSERT/UPDATE/DELETE 操作。 听起来很合理对吧但实测下来Cursor 对这类自由文本的理解极不稳定。原因有三第一上下文窗口限制。Cursor 在决定是否调用工具前会将工具定义如tools.json中的 description 字段送入大模型上下文。而 description 字段通常有长度限制一般 512–1024 字符长篇说明会被截断关键的安全声明往往出现在末尾直接丢失。第二语义歧义无法消解。“仅读取”在人类看来很明确但在模型语义空间里它和“可能触发触发器”、“可能锁表”、“可能消耗大量内存”等潜在副作用处于同一模糊区域。模型没有结构化依据去区分“安全读取”和“危险读取”。第三缺乏机器可解析性。自然语言是给人看的不是给程序解析的。Cursor 无法从中提取出布尔型的isReadOnly: true这样的确定信号只能做概率推测结果就是“有时信有时不信”。提示我曾把同一段自然语言描述反复改写 7 种版本强调“绝对不修改”、“零副作用”、“只 SELECT”、“无事务影响”等测试 32 次调用AI 正确识别“只读”的次数只有 13 次失败率超 59%。这证明靠文字修辞无法解决根本问题。2.2 为什么不用 JSON Schema 扩展——职责错位与协议碎片化另一种思路是扩展工具的 JSON Schema 定义在parameters或responses之外新增一个sideEffects字段{ name: export_table_schema, description: 导出 MySQL 表结构, parameters: { ... }, sideEffects: { readOnly: true, networkCalls: [mysql://prod-db], diskWrites: [/tmp/export.sql] } }这个方案技术上可行但它违背了 MCP 的核心设计哲学关注点分离。JSON Schema 的本质是描述“数据形状”what data goes in/out而readOnlyHint这类注解描述的是“行为契约”what the tool does to the world。混在一起会导致Schema 膨胀失控每个新维度如requiresSudo,affectsCache,triggersWebhook都要新增字段最终 schema 变成难以维护的巨无霸客户端兼容性差不同 AI 工具对自定义字段的支持程度不一Cursor 可能认readOnly但另一款工具只认isSafe造成事实上的协议分裂缺乏标准化验证没有统一的 validator开发者容易写错字段名如read_onlyvsreadOnlyvsreadonly错误静默存在直到线上出问题才暴露。MCP 的精妙之处在于它把行为语义从数据契约中剥离出来形成独立、精简、可验证的注解层。它不取代 JSON Schema而是与之协同Schema 保证“数据合法”MCP 注解保证“行为可知”。2.3 为什么 MCP 注解是当前唯一可靠路径——协议级对齐与生态共识MCP 并非某个公司的私有标准而是由 Cursor、ClaudeCode、Trae 等多家 AI 编程工具共同参与制定的开放协议GitHub 仓库公开可查。它的设计直击痛点极简主义核心注解只有readOnlyHint,destructiveHint,requiresConfirmationHint三个覆盖 95% 的工具安全场景。没有冗余字段没有复杂嵌套一行注解解决一个问题。语法中立支持多种载体——可写在工具源码注释里Python docstring、JS JSDoc、Shell heredoc可写在独立的.mcp.yaml文件中也可内嵌在tools.json的metadata字段。无论你用什么技术栈都能无缝接入。客户端强制执行Cursor 在加载工具时会主动扫描并解析这些注解。一旦检测到destructiveHint就会在 UI 层强制插入确认弹窗检测到readOnlyHint则默认允许静默调用无需人工干预。这是协议层的硬约束不是模型的软判断。向后兼容旧版 Cursor 无视 MCP 注解完全不影响工具运行新版 Cursor 则能充分利用它。升级无风险落地零成本。我对比过 IDA Pro 的 MCP 插件、Unreal Engine 5.8 的官方 MCP 集成、以及 Playwright 的 MCP 自动化方案发现它们都遵循同一套注解语义。这意味着当你为 Cursor 写好readOnlyHint未来切换到其他支持 MCP 的工具时这套声明依然有效。这种跨平台一致性是任何私有方案都无法提供的长期价值。3. 核心细节解析readOnlyHint与destructiveHint的真实含义与边界3.1readOnlyHint不是“不写文件”而是“不改变系统状态”很多开发者第一次接触readOnlyHint时本能地认为“只要我的脚本不调用os.remove()或subprocess.run(rm)就可以打这个标签。” 这是一个危险的误解。MCP 中的 “read-only” 是一个系统级概念指工具执行过程中不会导致任何外部可观测的状态变更。它包含但不限于以下维度数据库状态不执行INSERT/UPDATE/DELETE/ALTER/DROP/TRUNCATE等 DML/DLL 语句不提交事务即使只 SELECT若开启事务且未回滚也可能锁表文件系统状态不创建、修改、删除任何持久化文件/etc/,/var/log/, 用户主目录下的配置文件等临时文件/tmp/的创建与删除通常被允许但需确保工具退出后自动清理进程与服务状态不启动、停止、重启任何系统服务systemctl start nginx不发送SIGKILL等信号终止进程网络状态不调用会改变远程系统状态的 API如POST /api/v1/users创建用户、DELETE /api/v1/orders/123删除订单只允许GET类查询请求环境变量与配置不修改全局环境变量export PATH...、不写入.bashrc等配置文件。一个典型反例是“日志轮转脚本”#!/bin/bash # readOnlyHint # 错误此脚本实际修改了文件系统状态 gzip /var/log/app.log mv /var/log/app.log.1.gz /var/log/app.log.2.gz touch /var/log/app.log虽然它没删库但mv和touch操作改变了日志文件的 inode、mtime、size 等元数据属于可观测的状态变更。正确做法是移除readOnlyHint或重构为纯查询模式如只cat /var/log/app.log | grep ERROR。注意Cursor 对readOnlyHint的校验是静态分析 运行时沙箱结合。它会扫描脚本中的关键词rm,mv,curl -X POST等也会在沙箱中监控系统调用openatwithO_WRONLY,unlinkat等。所以别试图用eval rm -f $file绕过检测——沙箱会捕获真实的 syscall。3.2destructiveHint不是“有风险”而是“必须人工确认”destructiveHint的语义比readOnlyHint更严格。它不是标记“这个工具有点危险”而是发出一个不可撤销的操作指令Cursor 必须在执行前弹出明确的、带工具名称和参数摘要的确认对话框且用户必须主动点击“确认”按钮才能继续。关键点在于确认不可跳过即使用户设置了“始终信任此工具”destructiveHint仍会强制弹窗。这是协议硬性要求防止因设置疏忽导致误操作。参数必须透明弹窗中必须清晰显示所有传入参数。例如调用delete_user --id 123 --force时弹窗标题为“即将执行delete_user”正文为“参数id123, forceTrue”。不能只写“执行删除操作”。无中间态不存在“低危破坏性”这种说法。只要工具可能造成数据丢失、服务中断、权限变更等不可逆后果就必须打此标签。犹豫等于应该打。常见误用场景误标为readOnlyHint一个“清空 Redis 缓存”的脚本作者认为“缓存丢了可以重建不算严重”于是加readOnlyHint。这是严重错误。清空缓存可能导致下游服务雪崩属于典型的destructiveHint场景。漏标destructiveHint一个“生成并覆盖 config.yaml 的脚本”只写了readOnlyHint因为不连数据库。但覆盖配置文件会直接影响服务行为属于状态变更必须标destructiveHint。我建议采用“悲观假设”原则如果这个工具的执行结果需要你事后花时间去检查、修复、或通知他人那它就不是只读的。3.3 两个注解的组合使用与互斥规则MCP 规范明确规定readOnlyHint和destructiveHint互斥且不可共存。一个工具只能拥有其中一种或都不拥有即默认行为。如果同时出现Cursor 会拒绝加载该工具并报错Invalid MCP annotation: both readOnlyHint and destructiveHint found如果都不出现Cursor 按传统方式处理依赖 description 字段 模型推理行为不确定。但你可以用requiresConfirmationHint作为补充。它适用于那些“不破坏但需谨慎”的场景比如发送邮件通知不破坏系统但发错对象影响大触发一次耗时较长的计算任务不破坏但占资源修改非核心配置如调整日志级别不破坏功能但影响可观测性。requiresConfirmationHint的弹窗是可选的用户可勾选“不再询问”而destructiveHint的弹窗是强制的。这种分层设计让安全控制既严格又不失灵活。4. 实操过程从零开始为你的工具添加 MCP 注解4.1 环境准备与版本确认在动手前请务必确认你的 Cursor 版本支持 MCP。截至 2024 年 10 月Cursor v0.42.0 及以上版本原生支持 MCP 注解解析。低于此版本的用户需先升级打开 Cursor → Help → Check for Updates若无更新访问官网下载最新版不要通过第三方渠道安装旧版启动后在命令面板CtrlShiftP输入Cursor: Show Version确认版本号 ≥ 0.42.0。提示Cursor 的免费额度与 MCP 功能无关。MCP 是协议解析能力属于客户端基础功能免费用户和付费用户享有同等支持。别被“cursor免费额度是多少”这类热搜词误导——它影响的是模型调用次数不是工具注解能力。同时确保你的工具已按 Cursor 规范注册。通常有两种方式本地工具放在~/.cursor/tools/目录下每个工具一个子目录包含tool.json和可执行文件远程工具通过tools.json的url字段指向 HTTP API。本文以本地 Python 工具为例因其最常用、最易调试。4.2 为 Python 工具添加readOnlyHint注解完整示例假设你有一个get_api_spec.py脚本功能是从公司内部 Swagger API 获取 OpenAPI 3.0 规范并保存为 JSON#!/usr/bin/env python3 # -*- coding: utf-8 -*- Get OpenAPI spec from internal API gateway. Usage: python get_api_spec.py --service user-service --output ./spec/user.json import argparse import json import requests from urllib.parse import urljoin def main(): parser argparse.ArgumentParser() parser.add_argument(--service, requiredTrue, helpService name) parser.add_argument(--output, requiredTrue, helpOutput file path) args parser.parse_args() # 构造 API URL base_url https://api-gateway.internal spec_url urljoin(base_url, f/v1/services/{args.service}/openapi.json) # 发起 GET 请求只读 response requests.get(spec_url, timeout30) response.raise_for_status() # 写入文件注意这是临时文件非持久化配置 with open(args.output, w) as f: json.dump(response.json(), f, indent2) if __name__ __main__: main()现在为其添加 MCP 注解。关键原则注解必须放在工具定义的“入口点”附近且格式严格。步骤 1选择注解位置MCP 规范推荐优先使用源码注释方式因其与代码共生不易遗漏。对 Python支持以下位置#!/usr/bin/env python3行之后模块 docstring 之前或模块 docstring 的第一行即后紧跟注解。推荐后者更清晰。步骤 2插入标准注解修改脚本开头加入readOnlyHint#!/usr/bin/env python3 # -*- coding: utf-8 -*- # readOnlyHint Get OpenAPI spec from internal API gateway. Usage: python get_api_spec.py --service user-service --output ./spec/user.json import argparse ...注意格式细节# readOnlyHint必须是独立一行以#开头井号后一个空格不能写成# readOnlyHint true或# readOnlyHint: trueMCP 注解是布尔型无值不能有多余字符如# readOnlyHint # only read注解行必须纯净。步骤 3验证注解是否生效将脚本保存为~/.cursor/tools/get_api_spec/tool.py注意目录结构在同目录下创建tool.json{ name: get_api_spec, description: Fetch OpenAPI specification for a service, type: command, command: python tool.py, parameters: [ { name: service, type: string, description: Name of the service, required: true }, { name: output, type: string, description: Path to save the spec JSON, required: true } ] }重启 Cursor在编辑器中输入/get_api_spec触发工具调用观察右下角状态栏若显示 “✅ Tool loaded with readOnlyHint”说明注解解析成功尝试调用应无确认弹窗直接执行。实操心得我最初把注解写在if __name__ __main__:下面结果 Cursor 完全无视。后来查 MCP 规范文档才发现注解必须位于模块顶层module-level且在任何 import 之前。这个细节坑了我整整一个下午。4.3 为 Shell 工具添加destructiveHint注解避坑指南Shell 脚本的注解方式略有不同因其没有严格的“模块”概念。MCP 规范规定Shell 工具的注解必须放在shebang 行之后、任何可执行命令之前且使用#注释。假设你有一个reset_db.sh脚本#!/bin/bash # destructiveHint # WARNING: This script will DROP and RECREATE the entire database. # Use only in dev environment. DB_NAMEmyapp_dev PG_USERpostgres echo Resetting database $DB_NAME... dropdb $DB_NAME 2/dev/null || true createdb $DB_NAME psql -U $PG_USER -d $DB_NAME -f ./schema.sql关键避坑点# destructiveHint必须紧贴 shebang 下一行中间不能有空行不能有任何前置空格必须是# destructiveHint不是# destructiveHint注解行后可跟任意数量的普通注释行如# WARNING: ...但这些普通注释不参与 MCP 解析仅作人眼提示确保脚本有可执行权限chmod x reset_db.sh否则 Cursor 无法调用。验证方法相同放入~/.cursor/tools/reset_db/创建对应tool.json重启 Cursor调用时必弹确认窗。注意Shell 脚本中destructiveHint的校验不仅看注解还会静态扫描dropdb,rm -rf,dd if/dev/zero等高危命令。即使你忘了加注解Cursor 也可能因检测到这些命令而自动弹窗。但绝不能依赖此 fallback——它不保证 100% 覆盖且无明确依据。必须显式声明。4.4 高级技巧.mcp.yaml独立配置文件的使用场景当你的工具是编译型语言如 Go、Rust或二进制文件无法在源码中添加注释时MCP 提供了.mcp.yaml作为替代方案。例如你有一个./bin/db-migrator二进制文件想标记为只读在工具目录如~/.cursor/tools/db-migrator/下创建.mcp.yaml文件# .mcp.yaml version: 1.0 annotations: - type: readOnlyHint target: ./bin/db-migratortool.json中只需正常定义命令{ name: db_migrator, description: Run database migration checks, type: command, command: ./bin/db-migrator --dry-run }.mcp.yaml的优势在于跨语言通用Java JAR、.NET DLL、甚至 Windows.exe都能用集中管理一个 YAML 文件可为多个二进制文件声明注解CI/CD 友好YAML 可随构建产物一起发布无需修改源码。但要注意.mcp.yaml必须与tool.json在同一目录且文件名严格为.mcp.yaml点开头小写无其他后缀。5. 常见问题与排查技巧实录5.1 注解不生效——五步定位法当你添加了readOnlyHint但 Cursor 仍弹确认窗或根本不识别注解时按以下顺序排查步骤检查项如何验证典型错误1版本是否达标Cursor: Show Versionv0.41.9 及以下版本不支持必须升级2注解位置是否正确打开脚本确认# readOnlyHint在 shebang/模块 docstring 后且无前置空行注解写在import之后或缩进错误3注解语法是否纯净用文本编辑器显示所有字符如 VS Code 的 “Render Whitespace”确认无不可见字符复制粘贴导致的全角空格、BOM 头4工具路径是否规范检查~/.cursor/tools/tool-name/目录结构确认tool.json和脚本在同一级脚本放在子目录src/下未被正确引用5Cursor 是否重新加载修改注解后必须重启 Cursor 或执行Cursor: Reload Window以为保存即生效未重启我遇到最多的是第 3 步从网页复制的注解带有零宽空格ZWSP肉眼不可见但解析器会报错。解决方案是手动重敲# readOnlyHint或用cat -A script.py查看隐藏字符。5.2 “Cursor taking longer than expected…” —— 注解引发的性能问题部分用户反馈添加 MCP 注解后Cursor 响应变慢出现Cursor taking longer than expected...提示。这通常不是注解本身的问题而是触发了 Cursor 的深度静态分析。当 Cursor 发现destructiveHint时它会启动更严格的代码扫描包括反编译 Python bytecode对.pyc文件解析 Shell 脚本的 AST抽象语法树追踪变量赋值链检查所有subprocess调用的目标命令。这会增加 200–500ms 的解析延迟。解决方法简化脚本逻辑避免深层嵌套、动态命令拼接如cmdrm -rf $dir; eval $cmd使用白名单在tool.json中添加skipStaticAnalysis: true仅限可信内部工具预编译对 Python 工具提供.pyc文件而非源码加速解析。实测数据一个含 3 层嵌套if-else的 Shell 脚本加destructiveHint后首次加载耗时 1.2s将其重构为线性逻辑后降至 320ms。性能优化的本质是让静态分析器更容易“看懂”你的意图。5.3 中文环境下的特殊问题cursor设置中文回复与 MCP 的关系热搜词中高频出现cursor设置中文回复、cursor怎么设置中文这常被误认为与 MCP 相关。实际上MCP 注解本身与 UI 语言完全无关。readOnlyHint是协议关键字全球统一不因 Cursor 设置为中文就变成只读提示。但中文环境会带来两个间接影响工具 description 字段的中文描述如果你在tool.json的description里写中文Cursor 会正常显示但这不影响 MCP 解析确认弹窗的本地化当destructiveHint触发弹窗时按钮文字“确认”、“取消”会随系统语言自动切换但工具名和参数仍显示原始值。因此无需为 MCP 做额外中文设置。所谓“cursor中文怎么设置”只是修改系统语言偏好与 MCP 功能无耦合。把精力放在写准注解上比纠结语言设置重要得多。5.4 安全红线cursor提示词泄露风险与 MCP 的防护作用cursor提示词泄露是近期热点问题指 Cursor 可能将用户 prompt含敏感信息意外发送至第三方模型。MCP 注解对此无直接防护作用但它能显著降低泄露风险的影响面当一个工具被正确标记为readOnlyHintCursor 会优先使用其本地执行结果而非将整个 prompt含数据库连接串等发给云端模型去“猜测”如何调用反之若一个读取配置的工具未标readOnlyHintCursor 可能因不确定其安全性转而让大模型生成一段新的、可能包含硬编码密钥的替代脚本反而扩大泄露面。所以严谨的 MCP 注解是构建“最小必要权限”调用链的第一道防线。它不阻止泄露但能让泄露发生时泄露的内容范围更小、危害更低。6. 工具链延伸MCP 与其他开发场景的协同6.1 与 Playwright MCP 自动化的集成Playwright 是前端自动化测试的主流框架其playwright mcp方案本质是将浏览器操作封装为 MCP 工具。例如一个“登录并截图”的脚本// login-and-screenshot.ts // readOnlyHint // 本工具仅读取页面内容并截图不修改任何数据 import { chromium } from playwright; async function run(url: string, username: string, password: string) { const browser await chromium.launch(); const page await browser.newPage(); await page.goto(url); await page.fill(#username, username); await page.fill(#password, password); await page.click(#login-btn); await page.waitForNavigation(); await page.screenshot({ path: dashboard.png }); await browser.close(); }这里readOnlyHint的合理性在于page.fill()和page.click()操作的是前端 DOM不触达后端数据库或文件系统screenshot()只生成本地图片文件不上传。因此它符合 MCP 的只读定义。Cursor 调用此工具时会静默执行大幅提升自动化流程效率。而如果你封装的是“批量删除用户”的 Playwright 脚本则必须用destructiveHint确保每一步都经人工确认。6.2 Unreal Engine 5.8 与 IDA Pro 的 MCP 实践启示Unreal Engine 5.8 官方集成 MCP允许蓝图节点标注readOnlyHint意味着 AI 辅助的蓝图生成能自动避开修改 Actor 属性的节点只推荐查询类操作。IDA Pro 的 MCP 插件则让反编译结果带上destructiveHint警告用户“此脚本将 patch 二进制文件”。这些案例揭示了一个趋势MCP 正从“编程工具协议”演变为“软件工程通用契约”。无论你是写 Python 脚本、C 插件、还是蓝图逻辑只要涉及“执行外部操作”MCP 就是你向 AI 清晰表达意图的通用语言。掌握它不是为了适配 Cursor而是为了在未来所有 AI 增强开发环境中保持对工具行为的绝对掌控力。我在实际项目中已将 MCP 注解纳入代码审查清单CR Checklist。新工具合并前必须回答两个问题“它是否只读能否加readOnlyHint”和“它是否破坏是否已加destructiveHint”。这已成为团队保障 AI 编程安全的铁律。