Awesome-MCP-Scaffold

# 🎯 Cursor IDE 使用指南 本指南详细介绍如何在 Cursor IDE 中充分利用 **Awesome MCP Scaffold** 的功能和配置。 ## 🌟 为什么选择 Cursor？ Cursor 是专为 AI 辅助开发设计的现代 IDE，与 MCP 协议完美集成： - **原生 MCP 支持**：直接连接和使用 MCP 服务器 - **智能代码补全**：基于上下文的 AI 建议 - **自然语言编程**：用自然语言描述需求，AI 生成代码 - **实时协作**：与 AI 助手无缝协作 ## 📁 项目配置 ### Cursor Rules 配置 项目包含预配置的 Cursor 规则文件： ``` .cursor/ ├── rules/ │ ├── mcp-development-guide.mdc # MCP 开发指南 │ ├── mcp-testing-patterns.mdc # 测试模式指南 │ └── streamable-http-production.mdc # 生产部署指南 ``` 这些规则会自动告诉 Cursor： - MCP 最佳实践 - 代码结构规范 - 测试策略 - 部署模式 ### 自动应用的规则 当您在 Cursor 中打开项目时，以下规则会自动生效： 1. **MCP 服务器开发规范** 2. **FastMCP 框架使用指导** 3. **Streamable HTTP 传输优化** 4. **测试驱动开发模式** 5. **生产部署最佳实践** ## 🔧 配置 MCP 服务器 ### 1. 在 Cursor 设置中添加 MCP 服务器 打开 Cursor 设置 (`Cmd/Ctrl + ,`)，找到 MCP 配置部分，添加： ```json { "mcpServers": { "awesome-mcp-scaffold": { "command": "python", "args": ["-m", "server.main"], "cwd": "/path/to/your/Awesome-MCP-Scaffold", "env": { "TRANSPORT": "stdio", "ENVIRONMENT": "development", "DEBUG": "true" } } } } ``` ### 2. 验证连接 在 Cursor 中按 `Cmd/Ctrl + Shift + P`，搜索 "MCP"，您应该看到： - **MCP: Connect to Server** - **MCP: List Tools** - **MCP: List Resources** ## 🛠️ 使用 MCP 功能 ### 计算器工具 在 Cursor 中，您可以直接要求 AI 进行计算： ``` 用户: "帮我计算 BMI，体重 70kg，身高 1.75m" AI: 我来帮您计算 BMI... [调用 calculate_bmi 工具] 结果: BMI = 22.86 (正常体重) ``` ### 文本处理 ``` 用户: "分析这段文本的统计信息：'Hello World! This is a test.'" AI: 我来分析文本统计... [调用 text_statistics 工具] 结果: - 单词数: 6 - 字符数: 29 - 句子数: 2 - 平均单词长度: 4.83 ``` ### 文件操作 ``` 用户: "在 workspace 目录下创建一个 JSON 文件，包含用户数据" AI: 我来创建 JSON 文件... [调用 write_json_file 工具] 结果: 文件已创建在 workspace/users.json ``` ### 系统信息 ``` 用户: "显示当前系统的内存使用情况" AI: 我来获取系统信息... [读取 system://memory 资源] 结果: 内存使用率 45%，可用内存 8.2GB ``` ## 🎨 开发工作流 ### 1. 创建新工具 使用 Cursor 的自然语言编程： ``` 用户: "创建一个新的 MCP 工具，用于生成随机密码" AI 会自动： 1. 在 server/tools/ 下创建新文件 2. 实现密码生成逻辑 3. 注册工具到主模块 4. 添加相应的测试 ``` ### 2. 代码审查 ``` 用户: "审查这个函数的代码质量" AI 会使用内置的 code_review 提示模板，提供： - 代码质量分析 - 性能优化建议 - 安全性检查 - 最佳实践建议 ``` ### 3. 测试生成 ``` 用户: "为这个工具生成单元测试" AI 会： 1. 分析工具功能 2. 生成测试用例 3. 包含边界条件测试 4. 添加错误处理测试 ``` ## 🚀 高级功能 ### 智能重构 Cursor 可以理解 MCP 架构，提供智能重构建议： ``` 用户: "重构这个工具，使其更符合 MCP 最佳实践" AI 会： - 分析当前代码结构 - 应用 MCP 开发规范 - 优化错误处理 - 改进文档字符串 ``` ### 自动测试 ``` 用户: "运行所有测试并修复失败的测试" AI 会： 1. 执行 make test 2. 分析测试结果 3. 自动修复简单的测试失败 4. 提供复杂问题的解决方案 ``` ### 部署优化 ``` 用户: "优化这个 MCP 服务器用于生产部署" AI 会： - 应用生产配置最佳实践 - 优化性能设置 - 添加监控和日志 - 配置安全设置 ``` ## 🎯 实际使用场景 ### 场景 1: API 集成 ``` 用户: "集成 OpenWeatherMap API 作为 MCP 工具" AI 工作流程： 1. 创建新的工具模块 2. 实现 API 调用逻辑 3. 添加错误处理和重试 4. 创建相应的测试 5. 更新文档 ``` ### 场景 2: 数据分析 ``` 用户: "创建一个数据分析工具，可以处理 CSV 文件" AI 会： 1. 实现 CSV 读取工具 2. 添加数据统计分析 3. 创建可视化建议 4. 集成到 MCP 框架 ``` ### 场景 3: 自动化任务 ``` 用户: "创建一个定时任务工具，可以定期清理临时文件" AI 会： 1. 设计任务调度系统 2. 实现文件清理逻辑 3. 添加配置管理 4. 创建监控功能 ``` ## 🔍 调试技巧 ### 1. MCP 连接调试 如果 MCP 连接有问题： ``` 用户: "MCP 服务器连接失败，帮我调试" AI 会检查： - 服务器进程状态 - 配置文件正确性 - 端口占用情况 - 日志错误信息 ``` ### 2. 工具调试 ``` 用户: "这个工具返回错误，帮我找出问题" AI 会： 1. 分析错误堆栈 2. 检查输入参数 3. 验证工具逻辑 4. 提供修复建议 ``` ### 3. 性能调试 ``` 用户: "服务器响应很慢，帮我优化性能" AI 会： 1. 分析性能瓶颈 2. 检查资源使用 3. 优化算法复杂度 4. 添加缓存机制 ``` ## 📚 学习资源 ### Cursor 特定功能 - **@** 符号：引用特定文件或函数 - **Tab 补全**：AI 驱动的代码补全 - **Cmd+K**：自然语言编辑 - **Cmd+L**：与 AI 对话 ### MCP 集成 - 使用 `@mcp` 前缀引用 MCP 功能 - 通过 Cursor Chat 直接调用工具 - 实时查看 MCP 服务器状态 ## 🎉 最佳实践 ### 1. 有效的提示 ``` ✅ 好的提示: "创建一个 MCP 工具，用于计算两个日期之间的天数，包含输入验证和错误处理" ❌ 模糊的提示: "做一个日期工具" ``` ### 2. 增量开发 ``` 1. 先创建基础功能 2. 添加错误处理 3. 完善文档 4. 添加测试 5. 性能优化 ``` ### 3. 利用上下文 ``` 用户: "基于刚才创建的工具，再创建一个相关的工具" AI 会理解上下文，创建相关功能 ``` ## 🚨 常见问题 ### Q: Cursor 无法识别 MCP 服务器？ **解决方案：** 1. 检查 MCP 服务器配置路径 2. 确认服务器正在运行 3. 重启 Cursor IDE 4. 查看 Cursor 日志 ### Q: AI 建议的代码不符合项目规范？ **解决方案：** 1. 确认 `.cursor/rules` 文件存在 2. 在提示中明确提及规范要求 3. 使用 `@rules` 引用特定规则 ### Q: 如何让 AI 更好地理解项目结构？ **解决方案：** 1. 使用 `@codebase` 引用整个项目 2. 在对话中提及相关文件 3. 保持清晰的项目文档