Claude Project Coordinator

🚀 Claude Project Coordinator

An MCP (Model Context Protocol) server for managing and coordinating multiple Xcode/Swift projects. This server offers tools for tracking project status, searching code patterns, and maintaining a knowledge base of development insights.

🚀 Quick Start

🚨 Critical Update for v1.3.0+ Users

If you're experiencing incorrect project creation dates (all showing today's date), run:

./scripts/repair-analytics-dates.sh

This fixes a bug where analytics were re-migrated on every restart. Fixed in v1.3.2.

✨ Features

• 🚀 Project Management: Track multiple Xcode projects with status, notes, and metadata
• 🔍 Smart Search: Search across projects and documentation for code patterns
• 📚 Knowledge Base: Maintain patterns, templates, and troubleshooting guides
• 🤖 Auto-Detection: Automatically detects SwiftUI, UIKit, SPM, and other technologies
• 💾 Persistent Storage: All data stored locally in structured JSON format
• 🔐 Security First: Comprehensive input validation and path traversal protection
• 📊 Project Analytics (v1.3.0+): Time tracking, activity heat maps, and health scoring
• 📈 Technology Trends (v1.3.0+): Analyze framework usage and adoption patterns

✨ Security Features (v1.2.0+)

• 🛡️ Input Validation: Comprehensive validation of all user inputs
• 🚫 Path Traversal Protection: Blocks malicious paths like ../../../etc/passwd
• 📁 Directory Access Control: Configurable allowed directories for projects
• 🚨 Injection Prevention: Validates search patterns to prevent command injection
• ⚖️ Reasonable Limits: Input length limits to prevent buffer overflow attacks
• 📝 Clear Error Messages: Helpful guidance when security validation fails
• ⚙️ Hardcoded Security: Security policies are compiled into the binary for reliability

📦 Installation

Prerequisites

• macOS with Swift 5.9+
• Claude Desktop app

Build from Source

1. Clone the repository:

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

2. Build the project:

swift build -c release

3. Note the path to the built executable:

.build/release/project-coordinator

Configure Claude Desktop

1. Open Claude Desktop
2. Navigate to: Settings → Developer → Model Context Protocol
3. Add the configuration:

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

4. Restart Claude Desktop

💻 Usage Examples

Basic Usage

Once configured, you can interact with the Project Coordinator through Claude:

• List projects: "Show me all my tracked projects"
• Add project: "Add my WeatherApp project at ~/Developer/WeatherApp"
• Update status: "Update WeatherApp status to 'Implementing API integration'"
• Search patterns: "Find all SwiftUI patterns"
• Get project details: "What's the status of my TodoApp?"

Advanced Usage

Analytics Commands (v1.3.0+)

• Time tracking: "How long has Ubermania been in development?"
• Activity heat map: "Show me my project activity this week"
• Technology trends: "What technologies am I using most?"
• Health check: "Which projects need my attention?"

📊 See ANALYTICS-EXAMPLES.md for detailed output examples and productive prompts!

Example Workflow

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]

Analytics Output Example

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

📚 Documentation

Security Configuration

Security settings are hardcoded in the Swift source code for reliability and security. The default configuration includes:

Default Security Settings

Customizing Security Settings

To modify security settings:

1. Edit the source code: Open Sources/ProjectCoordinator/SecurityValidator.swift

2. Modify the configuration values:

   // Add/remove allowed base paths
   static let allowedBasePaths = [
       NSHomeDirectory() + "/Developer",
       NSHomeDirectory() + "/Documents", 
       NSHomeDirectory() + "/GitHub",
       NSHomeDirectory() + "/Projects",
       NSHomeDirectory() + "/Desktop/Development",
       NSHomeDirectory() + "/Xcode"
       // Add your custom paths here
   ]
   
   // Adjust length limits
   static let maxProjectNameLength = 100
   static let maxDescriptionLength = 2000
   static let maxNotesLength = 10000
   static let maxSearchPatternLength = 300
   

3. Rebuild the project:

   swift build -c release
   

4. Restart Claude Desktop to use the updated binary

Why Hardcoded Configuration?

• Security: Configuration cannot be tampered with at runtime
• Reliability: No risk of configuration file corruption or manipulation
• Simplicity: No additional file management or parsing complexity
• Performance: Settings are compiled in, no runtime parsing overhead

MCP Tools Available

list_projects

Lists all tracked projects with their metadata

add_project

Adds a new project to track

• Parameters: name, path, description (optional)
• Security: Validates project name, path, and description

get_project_status

Gets detailed information about a specific project

• Parameters: projectName
• Security: Validates project name

update_project_status

Updates project status and/or notes

• Parameters: projectName, status (optional), notes (optional)
• Security: Validates all text inputs

search_code_patterns

Searches through projects and knowledge base

• Parameters: pattern
• Security: Validates search pattern for injection attempts

Project Structure

Claude-Project-Coordinator/
├── Sources/
│   └── ProjectCoordinator/
│       ├── main.swift              # Entry point
│       ├── MCPServer.swift         # MCP protocol implementation
│       ├── ProjectManager.swift    # Project management logic
│       └── SecurityValidator.swift # Input validation and security configuration
├── KnowledgeBase/
│   ├── projects/                  # Project data storage
│   ├── patterns/                  # Code patterns
│   ├── templates/                 # Project templates
│   └── tools/                     # Development tools/guides
├── scripts/
│   └── build.sh                   # Build script
├── Package.swift                  # Swift package manifest
├── CHANGELOG.md                   # Version history
└── README.md                      # This file

Knowledge Base

The Knowledge Base comes pre-populated with:

• SwiftUI patterns and best practices
• Xcode keyboard shortcuts
• Troubleshooting guides
• Project templates

You can add your own content by creating markdown files in the appropriate directories.

Project Analytics (v1.3.0+)

The analytics system runs automatically in the background, tracking:

Time Tracking

• Automatically tracks time spent in each project status
• No manual timers needed - just update status normally
• View complete timeline with: get_project_timeline

Activity Monitoring

• Records all interactions: status changes, notes, searches
• Generates heat maps showing project activity levels
• Identify your most and least active projects

Technology Analysis

• Tracks framework and tool usage across all projects
• Identifies emerging technologies you're experimenting with
• Shows adoption trends over time

Health Scoring

• Multi-factor analysis of project health (0-100 score)
• Factors: activity level, staleness, documentation, task completion
• Provides actionable recommendations for improvement

Note: Analytics are presented as formatted text in Claude chat, optimized for readability and quick insights. See ANALYTICS-EXAMPLES.md for real output examples.

💖 Support This Project

If CPC has helped streamline your development workflow or saved you time managing projects, consider supporting its development:

Your support helps me:

• Maintain and improve CPC with new features
• Keep the project open-source and free for everyone
• Dedicate more time to addressing user requests and bug fixes
• Explore new tools that enhance developer productivity

Thank you for considering supporting my work! 🙏

🔧 Technical Details

• Built with Swift using no external dependencies
• Uses JSON-RPC for MCP communication
• Async/await for modern Swift concurrency
• Actor-based architecture for thread safety
• Comprehensive input validation and security hardening

📄 License

MIT License - feel free to use this in your own projects!

Changelog

See CHANGELOG.md for detailed version history and security improvements.

Acknowledgments

Built as part of exploring the Model Context Protocol (MCP) ecosystem for enhancing AI-assisted development workflows.

Made with ❤️ from 🍍 Pineapple