Supercoordination MCP Server

# 超协体MCP - 数据持久化说明 ## ✅ 功能已启用 **版本**: v1.1 (2026-01-20) **类型**: JSON文件持久化 **状态**: 生产可用 --- ## 📂 数据文件 **路径**: `data/store.json` **格式**: JSON **编码**: UTF-8 **数据结构**: ```json { "tasks": [ ["任务ID", {任务对象}], ... ], "members": [ ["成员ID", {成员对象}], ... ], "resources": [], "saved_at": "2026-01-20T17:41:21.279Z" } ``` --- ## 🔄 自动保存机制 **触发时机**: - ✅ 成员注册时 (`register_member`) - ✅ 任务创建时 (`create_task`) - ✅ 任务分配时 (`assign_task`) - ✅ 任务状态更新时 (`update_task_status`) **保存方式**: - 同步写入（确保数据安全） - 每次操作后立即保存 - 日志输出确认：`[数据持久化] 已保存: X 个任务, Y 个成员` --- ## 🚀 启动加载 **服务器启动时**: 1. 检查 `data/store.json` 是否存在 2. 如存在，加载所有数据到内存 3. 日志输出： ``` [数据持久化] 已加载: 1 个任务, 1 个成员 [数据持久化] 上次保存时间: 2026-01-20T17:41:21.279Z ``` 4. 如不存在，使用空存储 --- ## ✅ 数据不会丢失的场景 - ✅ **Mac关机** - 重启后数据自动恢复 - ✅ **服务器重启** - 所有成员和任务完整恢复 - ✅ **系统更新** - 数据文件独立保存 - ✅ **意外崩溃** - 最后一次保存的数据可恢复 - ✅ **代码更新** - 数据文件不受影响 --- ## ⚠️ 数据会丢失的场景 - ❌ **删除data目录** - 数据文件被删除 - ❌ **手动删除store.json** - 数据文件被删除 - ❌ **磁盘故障** - 物理损坏导致数据丢失 --- ## 🛡️ 数据安全建议 ### 1. 定期备份 **手动备份**: ```bash # 复制数据文件 cp data/store.json data/backups/store_$(date +%Y%m%d_%H%M%S).json ``` **自动备份**（可选）: ```bash # 添加到crontab，每天凌晨2点备份 0 2 * * * cd ~/ClaudeWorkspace/supercoordination-mcp && cp data/store.json data/backups/store_$(date +\%Y\%m\%d).json ``` ### 2. 云端同步（可选） **使用iCloud Drive**: ```bash # 软链接到iCloud ln -s ~/ClaudeWorkspace/supercoordination-mcp/data ~/Library/Mobile\ Documents/com~apple~CloudDocs/超协体数据 ``` **使用Git**: ```bash # 初始化Git仓库 cd ~/ClaudeWorkspace/supercoordination-mcp git init git add data/store.json git commit -m "备份数据" # 推送到远程仓库（私有仓库！） git remote add origin <你的私有仓库> git push ``` ### 3. 数据恢复 **从备份恢复**: ```bash # 停止服务器 pkill -f "node src/server.js" # 恢复数据 cp data/backups/store_20260120.json data/store.json # 重启服务器 cd ~/ClaudeWorkspace/supercoordination-mcp npm start ``` --- ## 📊 容量规划 ### 当前规模 (1成员 + 1任务) - **文件大小**: 568 bytes - **内存占用**: < 1 KB ### 预估规模 | 规模 | 成员数 | 任务数 | 文件大小 | 加载时间 | |------|--------|--------|----------|----------| | 小型 | 10 | 50 | ~30 KB | < 10ms | | 中型 | 50 | 500 | ~300 KB | < 50ms | | 大型 | 200 | 2000 | ~1.2 MB | < 200ms | **建议**: - < 50人：JSON持久化完全够用 ✅ - 50-200人：考虑升级SQLite - > 200人：建议PostgreSQL --- ## 🔧 故障排查 ### 问题1: 数据未保存 **症状**: 重启后数据丢失 **检查**: ```bash # 1. 检查数据文件是否存在 ls -lh data/store.json # 2. 查看服务器日志 tail -50 /private/tmp/claude/-Users-personalworkplacce/tasks/bb869f9.output | grep "数据持久化" # 3. 检查文件权限 ls -la data/ ``` **解决**: - 确保 `data/` 目录存在且可写 - 检查磁盘空间是否充足 - 查看日志中的错误信息 ### 问题2: 数据文件损坏 **症状**: 启动时提示"加载失败" **检查**: ```bash # 验证JSON格式 cat data/store.json | jq . ``` **解决**: ```bash # 从备份恢复 cp data/backups/最新备份.json data/store.json # 或手动修复JSON格式 nano data/store.json ``` ### 问题3: 数据不一致 **症状**: 成员存在但任务显示"成员不存在" **检查**: ```bash # 查看数据文件内容 cat data/store.json | jq '.members,.tasks' ``` **解决**: - 通常是ID引用错误 - 可通过API重新分配任务解决 --- ## 🚀 未来升级路径 ### 当前: JSON持久化 ✅ - 适用规模: 10-50人 - 优点: 简单、零依赖 - 限制: 并发写入、性能 ### 下一步: SQLite数据库 ```bash # 安装SQLite驱动 npm install better-sqlite3 # 优点: # - 事务支持 # - SQL查询 # - 更好的并发 # 升级时间: 2-3小时 ``` ### 长期: PostgreSQL数据库 ```bash # 适用规模: 200+人 # 优点: # - 工业级可靠性 # - 高并发支持 # - 丰富功能 # 升级时间: 1天 ``` --- ## 📝 变更日志 ### v1.1 (2026-01-20) - ✅ 添加JSON文件持久化 - ✅ 自动保存/加载机制 - ✅ 启动日志显示数据状态 - ✅ 数据文件路径: `data/store.json` ### v1.0 (2026-01-19) - ✅ 纯内存存储 - ❌ 重启后数据丢失 --- ## 💡 最佳实践 ### 日常运营 1. **定期检查数据文件** ```bash # 每周查看文件大小 du -h data/store.json ``` 2. **监控日志** ```bash # 确保每次操作都有保存日志 tail -f /private/tmp/claude/-Users-personalworkplacce/tasks/bb869f9.output | grep "数据持久化" ``` 3. **月度备份** ```bash # 每月1号手动备份 cp data/store.json data/backups/store_$(date +%Y%m).json ``` ### 数据迁移 **导出数据**: ```bash # 生成可读的JSON cat data/store.json | jq . > export_$(date +%Y%m%d).json ``` **导入数据**: ```bash # 停止服务器 pkill -f "node src/server.js" # 导入新数据 cp import.json data/store.json # 验证格式 cat data/store.json | jq . # 重启服务器 npm start ``` --- ## 📞 技术支持 **数据文件位置**: `~/ClaudeWorkspace/supercoordination-mcp/data/store.json` **监控窗口**: Terminal窗口实时显示日志 **当前服务器**: Task ID `bb869f9` **遇到问题**: 1. 查看服务器日志 2. 检查数据文件 3. 尝试从备份恢复 --- **数据持久化状态**: ✅ 已启用并测试通过 **下次重启**: 数据将自动恢复 **备份建议**: 每周手动备份一次 🎉 **现在可以放心使用，数据不会丢失了！**