Cursor MCP 工具使用规范

本文件用于在 Cursor 的 Rules 中约束 AI 助手如何调用本项目的数据库 MCP 工具。工具定义以 src/mcp/tools.py 为准；人类可读说明见 README.md 与 docs/MCP客户端调用说明.md。

核心原则

先查连接，再操作 — 不知道 connection_id 时必须先调 list_connections，禁止猜测 ID
逐层探索 — 按 list_connections → list_databases → list_tables → describe_table 的顺序探索
只读优先 — 查询用 execute_query，写入/DDL 用 execute_sql（需确认权限）
默认数据库 — 大部分工具的 database 参数可选，不传则使用连接的默认数据库
结果要可读 — execute_query 返回行数据时，优先以“摘要 + 示例行”展示，避免一次性铺满长表
大表慎用 — execute_query 必须带 LIMIT；不确定数据量时先 COUNT(*) 或先查主键范围
下载优先 — 文档/ER/数据流/报表等大结果优先用 OSS 下载链接，禁止在对话中粘贴超大内容
明确告知 — 每次工具调用后向用户说明：工具名、connection_id、database、关键参数与结果摘要

支持的数据库类型：mysql、postgresql（list_connections 的 search 可用 "mysql" / "postgres" / 连接名关键词）。

Cursor 会自动先调 tools/list：首次接入时需等工具列表返回后再继续后续动作；如果工具列表失败，先排查 MCP 连接与访问密钥权限
resource 类型结果不要复制 Base64：当工具返回 PDF/文件的 resource 时，只提示“已生成文件，可在 Cursor 的资源/下载处保存”
优先短响应：对 Cursor 的消息显示更友好的是“结构化短文 + 链接”，避免超长 Markdown 导致渲染卡顿
长任务要提示等待：如生成 ER 图、导出数据字典、执行长 SQL，先提示“正在执行，可能需要等待”，再给结果摘要或链接

工具	用途	必需参数	权限	备注
`list_connections`	列出可用连接	无	-	Cursor 会在会话开始频繁用到
`list_databases`	列出数据库	`connection_id`	读
`list_tables`	列出表	`connection_id`	读
`list_views`	列出视图	`connection_id`	读
`list_procedures`	列出存储过程	`connection_id`	读
`describe_table`	查看表结构	`connection_id`, `table`	读
`execute_query`	执行 SELECT	`connection_id`, `sql`	读	必须带 `LIMIT`
`execute_sql`	执行任意 SQL	`connection_id`, `sql`	写/DDL	高风险操作先确认
`export_db_doc`	导出数据字典	`connection_id`	读	大库优先上传 OSS
`generate_er_diagram`	生成 ER 图	`connection_id`	读	表多时 `include_columns=false`
`generate_data_flow`	生成数据流图	`connection_id`	读
`suggest_columns`	字段添加建议	`connection_id`, `table`	读	可选 LLM
`analyze_performance`	性能分析	`connection_id`	读	可选 LLM
`analyze_sql`	SQL 审查	`connection_id`, `sql`	读	可选 LLM
`analyze_db_config`	参数调优分析	`connection_id`	读	可选 LLM
`compare_schemas`	Schema 对比	`source_connection_id`, `target_connection_id`	读
`generate_mock_data`	生成测试 INSERT	`connection_id`, `table`	读
`backup_table`	表级 CTAS 备份	`connection_id`, `table`	DDL
`generate_db_rule`	生成 RULE.md	`connection_id`	读	会写入 rules/ 与管理库
`render_report_oss`	报表上传 OSS	`connection_id`, `source`, `fields`	读	必须给 `download_url`

先调用 list_connections，若用户提到系统名/库名，用 search 过滤。

{"search": "postgres"}

拿到连接后，明确告诉用户选中的 connection_id。

{"connection_id": 1}

然后列出库或表：

{"connection_id": 1, "database": "mydb"}

{"connection_id": 1, "database": "mydb", "table": "users"}

{"connection_id": 1, "sql": "SELECT * FROM users ORDER BY id DESC LIMIT 20"}