Claude Project Coordinator

🚀 Claude项目协调器

Claude项目协调器是一个MCP（模型上下文协议）服务器，用于管理和协调多个Xcode/Swift项目。该服务器提供了跟踪项目状态、搜索代码模式以及维护开发见解知识库等工具。

🚀 快速开始

关键更新

如果您使用的是v1.3.0及以上版本，且遇到项目创建日期显示错误（所有日期均显示为今天）的问题，请运行以下命令：

./scripts/repair-analytics-dates.sh

此命令可修复一个在每次重启时都会重新迁移分析数据的错误。该问题已在v1.3.2版本中修复。

✨ 主要特性

项目管理特性

• 🚀 项目管理：跟踪多个Xcode项目，包括项目状态、备注和元数据。
• 🔍 智能搜索：在项目和文档中搜索代码模式。
• 📚 知识库：维护代码模式、模板和故障排除指南。
• 🤖 自动检测：自动检测SwiftUI、UIKit、SPM等技术。
• 💾 持久存储：所有数据以结构化JSON格式本地存储。
• 🔐 安全至上：全面验证所有用户输入，并提供路径遍历保护。
• 📊 项目分析（v1.3.0+）：支持时间跟踪、活动热力图和健康评分。
• 📈 技术趋势分析（v1.3.0+）：分析框架使用情况和采用模式。

安全特性（v1.2.0+）

• 🛡️ 输入验证：全面验证所有用户输入。
• 🚫 路径遍历保护：阻止恶意路径，如 ../../../etc/passwd。
• 📁 目录访问控制：可配置项目允许访问的目录。
• 🚨 注入防范：验证搜索模式，防止命令注入。
• ⚖️ 合理限制：设置输入长度限制，防止缓冲区溢出攻击。
• 📝 清晰的错误消息：安全验证失败时提供有用的指导。
• ⚙️ 硬编码安全策略：安全策略编译到二进制文件中，确保可靠性。

📦 安装指南

前提条件

• 安装了Swift 5.9及以上版本的macOS系统。
• 安装Claude桌面应用程序。

从源代码构建

1. 克隆仓库：

git clone https://github.com/M-Pineapple/Claude-Project-Coordinator.git
cd Claude-Project-Coordinator

2. 构建项目：

swift build -c release

3. 记录构建后的可执行文件路径：

.build/release/project-coordinator

配置Claude桌面应用

1. 打开Claude桌面应用。
2. 导航至：设置 → 开发者 → 模型上下文协议。
3. 添加以下配置：

{
  "mcpServers": {
    "project-coordinator": {
      "command": "/path/to/Claude-Project-Coordinator/.build/release/project-coordinator",
      "args": []
    }
  }
}

4. 重启Claude桌面应用。

💻 使用示例

基本命令

• 列出项目：“Show me all my tracked projects”
• 添加项目：“Add my WeatherApp project at ~/Developer/WeatherApp”
• 更新状态：“Update WeatherApp status to 'Implementing API integration'”
• 搜索模式：“Find all SwiftUI patterns”
• 获取项目详情：“What's the status of my TodoApp?”

分析命令（v1.3.0+）

• 时间跟踪：“How long has Ubermania been in development?”
• 活动热力图：“Show me my project activity this week”
• 技术趋势：“What technologies am I using most?”
• 健康检查：“Which projects need my attention?”

📊 详细输出示例和实用提示请参考 ANALYTICS-EXAMPLES.md！

示例工作流程

You: "Add my new SwiftUI project called FinanceTracker at ~/Developer/FinanceTracker"
Claude: "Successfully added project: FinanceTracker..."

You: "Update FinanceTracker status to 'Working on Core Data models'"
Claude: "Successfully updated FinanceTracker"

You: "Which of my projects use Core Data?"
Claude: [Shows all projects with Core Data in their tech stack or notes]

分析输出示例

You: "Show my project activity this week"

Claude:
## Project Activity Heat Map (Past 7 Days)

🔥🔥🔥 **TodoApp** (15 activity points - 6 events)
🔥🔥 **WeatherStation** (8 activity points - 3 events)
🔥 **PortfolioSite** (3 activity points - 2 events)
💤 **OldBlogEngine** (0 activity points)

### Daily Activity Breakdown:
- Monday: 4 events
- Tuesday: 8 events
- Wednesday: 3 events

📚 详细文档

安全配置

安全设置硬编码在Swift源代码中，以确保可靠性和安全性。默认配置包括：

默认安全设置

自定义安全设置

若要修改安全设置，请按以下步骤操作：

1. 编辑源代码：打开 Sources/ProjectCoordinator/SecurityValidator.swift。
2. 修改配置值：

// 添加/删除允许的基础路径
static let allowedBasePaths = [
    NSHomeDirectory() + "/Developer",
    NSHomeDirectory() + "/Documents", 
    NSHomeDirectory() + "/GitHub",
    NSHomeDirectory() + "/Projects",
    NSHomeDirectory() + "/Desktop/Development",
    NSHomeDirectory() + "/Xcode"
    // 在此处添加自定义路径
]

// 调整长度限制
static let maxProjectNameLength = 100
static let maxDescriptionLength = 2000
static let maxNotesLength = 10000
static let maxSearchPatternLength = 300

3. 重新构建项目：

swift build -c release

4. 重启Claude桌面应用，以使用更新后的二进制文件。

为何采用硬编码配置？

• 安全性：运行时无法篡改配置。
• 可靠性：不存在配置文件损坏或被篡改的风险。
• 简单性：无需额外的文件管理或解析复杂性。
• 性能：设置编译到二进制文件中，无运行时解析开销。

MCP工具

list_projects

列出所有跟踪的项目及其元数据。

add_project

添加一个新项目进行跟踪。

• 参数：name、path、description（可选）
• 安全：验证项目名称、路径和描述。

get_project_status

获取特定项目的详细信息。

• 参数：projectName
• 安全：验证项目名称。

update_project_status

更新项目状态和/或备注。

• 参数：projectName、status（可选）、notes（可选）
• 安全：验证所有文本输入。

search_code_patterns

在项目和知识库中搜索代码模式。

• 参数：pattern
• 安全：验证搜索模式，防止注入攻击。

项目结构

Claude-Project-Coordinator/
├── Sources/
│   └── ProjectCoordinator/
│       ├── main.swift              # 入口点
│       ├── MCPServer.swift         # MCP协议实现
│       ├── ProjectManager.swift    # 项目管理逻辑
│       └── SecurityValidator.swift # 输入验证和安全配置
├── KnowledgeBase/
│   ├── projects/                  # 项目数据存储
│   ├── patterns/                  # 代码模式
│   ├── templates/                 # 项目模板
│   └── tools/                     # 开发工具/指南
├── scripts/
│   └── build.sh                   # 构建脚本
├── Package.swift                  # Swift包清单
├── CHANGELOG.md                   # 版本历史
└── README.md                      # 本文件

知识库

知识库预先填充了以下内容：

• SwiftUI模式和最佳实践
• Xcode键盘快捷键
• 故障排除指南
• 项目模板

您可以通过在相应目录中创建Markdown文件来添加自己的内容。

项目分析（v1.3.0+）

分析系统在后台自动运行，跟踪以下内容：

时间跟踪

• 自动跟踪每个项目状态下花费的时间。
• 无需手动设置计时器，正常更新状态即可。
• 使用 get_project_timeline 查看完整时间线。

活动监控

• 记录所有交互：状态更改、备注、搜索等。
• 生成热力图，显示项目活动水平。
• 识别最活跃和最不活跃的项目。

技术分析

• 跟踪所有项目中框架和工具的使用情况。
• 识别您正在尝试的新兴技术。
• 显示技术采用趋势随时间的变化。

健康评分

• 对项目健康状况进行多因素分析（评分范围0 - 100）。
• 因素包括：活动水平、陈旧性、文档完整性、任务完成情况。
• 提供可操作的改进建议。

注意：分析结果以格式化文本形式显示在Claude聊天中，便于阅读和快速获取见解。详细输出示例请参考 ANALYTICS-EXAMPLES.md。

🔧 技术细节

• 使用Swift构建，无需外部依赖。
• 使用JSON-RPC进行MCP通信。
• 采用Async/await实现现代Swift并发。
• 基于Actor的架构确保线程安全。
• 全面的输入验证和安全加固。

📄 许可证

本项目采用MIT许可证，您可以自由在自己的项目中使用！

变更日志

详细的版本历史和安全改进请参考 CHANGELOG.md。

致谢

本项目是探索模型上下文协议（MCP）生态系统以增强AI辅助开发工作流程的一部分。

Made with ❤️ from 🍍 Pineapple

贡献

欢迎贡献代码！您可以：

• 报告Bug
• 提出新功能建议
• 提交拉取请求
• 改进文档
• 分享您的代码模式和模板

安全考虑

个人开发者

• 默认安全设置适用于个人开发工作流程。
• 在保证可用性的同时，防范常见攻击向量。
• 可通过修改源代码并重新构建来自定义安全设置。

组织用户

• 组织应评估自身的安全需求。
• 生产环境可能需要额外的安全措施。
• 考虑为共享使用场景实施额外的身份验证和审计日志记录。
• 硬编码配置可防止运行时篡改。

示例文件和文档

• ANALYTICS-EXAMPLES.md - 实际输出示例和实用提示
• CHANGELOG.md - 详细的版本历史
• 安全特性 - 请参阅上述安全配置部分