<div align="center">

<img src="assets/logo.svg" alt="Claude Project Coordinator logo" width="240"/>

# Claude Project Coordinator

**Your local project desk for Claude.** Track Xcode and Swift work across many repos, then ask Claude what is hot, stale, or next.

[![Licence: MIT](https://img.shields.io/github/license/M-Pineapple/Claude-Project-Coordinator)](LICENSE)
[![Swift](https://img.shields.io/badge/Swift-6-F05138?logo=swift&logoColor=white)](https://www.swift.org)
[![Stars](https://img.shields.io/github/stars/M-Pineapple/Claude-Project-Coordinator)](https://github.com/M-Pineapple/Claude-Project-Coordinator/stargazers)
[![M-Pineapple/Claude-Project-Coordinator MCP server](https://glama.ai/mcp/servers/M-Pineapple/Claude-Project-Coordinator/badges/score.svg)](https://glama.ai/mcp/servers/M-Pineapple/Claude-Project-Coordinator)

</div>

<img src="assets/demo.gif" alt="project-coordinator answering initialize and listing nine tools" width="720"/>

CPC is an MCP server that gives Claude a structured, **on-disk** view of your projects: status, notes, tech stack, activity, and health. It runs on macOS beside Claude Desktop, Cursor, or Claude Code. Data never leaves your machine.

**v1.4.2** · [official Swift MCP SDK](https://github.com/modelcontextprotocol/swift-sdk) · MIT · local JSON knowledge base

---

## Who is this for?

Pick the path that matches you. Same binary, different first questions.

### 1. Multi-project Swift hobbyist

You have several apps and packages. Context switches burn time, and you forget which repo was mid-refactor.

**Start with:**
- "Add my WeatherApp at ~/Developer/WeatherApp"
- "Show me all my tracked projects"
- "Which projects need my attention?"
- "Update WeatherApp status to 'Core Data models half done'"

**What you get:** a living roster with status, notes, auto-detected tech (SwiftUI, SPM, Xcode project/workspace), and a health score so quiet projects surface again.

### 2. Claude Desktop daily driver

Claude is your coding desk. You want continuity between chats without pasting the same project list.

**Start with:**
- "List my projects and their current status"
- "What's going on with TodoApp?"
- "Find all SwiftUI patterns we've stored"
- "Show my project activity this week"

**What you get:** Claude can call nine MCP tools against your KnowledgeBase instead of guessing from conversation memory.

### 3. Cursor or Claude Code agent user

Agents write code well but lose the portfolio view. You want the agent to know *which* project it is in and whether that project is healthy.

**Start with:**
- Wire CPC into Cursor / Claude Code MCP settings (see [Installation](#installation))
- "Get project status for Claude-Project-Coordinator"
- "Get technology trends across my tracked projects"
- "Show a 14-day activity heat map"

**What you get:** project health and timelines as tool results the agent can act on, next to the files it already sees.

### 4. Privacy-first / local-only setup

You will not send a project inventory to a cloud PM tool. Everything should live beside the binary.

**Start with:**
- Build from source, point MCP at `.build/release/project-coordinator`
- Optional: `CPC_KNOWLEDGE_BASE=~/Library/Application Support/CPC` for data outside the git tree
- Keep `KnowledgeBase/projects/*.json` out of public repos (already gitignored)

**What you get:** JSON on disk, path allowlisting, no account, no telemetry.

### 5. Already using a memory MCP

You store decisions and people in Memory Service (or similar). You do not want a second conversation dump.

**How they fit together:**

| | CPC | Memory MCP |
|---|---|---|
| Job | Project artefacts and status | Conversational context and decisions |
| Shape | Structured tools + JSON files | Notes, tags, search |
| Ask | "Which projects are stale?" | "What did we decide about onboarding?" |

Use both. Do not replace one with the other.

---

## Full feature list

### Project desk

| Capability | Detail |
|---|---|
| Track many projects | Name, path, description, status, notes, current tasks, last modified |
| Add from a path | Validates path, scans the folder, stores a JSON record |
| Update status / notes | Keeps the desk current without a separate app |
| List everything | One prompt → full roster with tech stack |
| Per-project deep dive | Status, notes, tasks, path, detected technologies |

### Auto-detection

When you add a project, CPC inspects the folder and tags what it finds:

- Swift Package Manager (`Package.swift`)
- Xcode project (`.xcodeproj`)
- Xcode workspace (`.xcworkspace`)
- SwiftUI (`import SwiftUI` in scanned Swift files)
- Falls back to `Swift` when nothing else matches

### Search and knowledge base

| Capability | Detail |
|---|---|
| Pattern search | Search across tracked projects and KnowledgeBase markdown |
| Built-in guides | Swift patterns, SwiftUI practices, Xcode shortcuts, troubleshooting |
| Templates | Starter docs under `KnowledgeBase/templates/` |
| Your own docs | Drop markdown into `patterns/`, `tools/`, or `templates/` and search will pick it up |

### Analytics (automatic)

No separate timer app. Status updates and tool use feed analytics in the background.

| Tool | What it answers |
|---|---|
| `get_project_timeline` | How long has this project been in each status? How old is it? |
| `get_activity_heatmap` | Which projects were hot in the last N days? |
| `get_technology_trends` | Which frameworks dominate? What is emerging? |
| `get_project_health` | 0–100 score plus recommendations (activity, freshness, docs, tasks) |

Sample chat output: [ANALYTICS-EXAMPLES.md](ANALYTICS-EXAMPLES.md).

### Safety and storage

| Capability | Detail |
|---|---|
| Local JSON | `KnowledgeBase/projects/` and analytics files on your Mac |
| Path allowlist | Only under configured roots (default: Developer, Documents, GitHub, Projects, …) |
| Input limits | Name, path, notes, and search length capped |
| Injection checks | Search patterns screened for shell-like payloads |
| Env override | `CPC_KNOWLEDGE_BASE` for a custom data directory |
| Stdio-safe logs | Diagnostics go to stderr only (MCP hosts own stdout) |

---

## All MCP tools

| Tool | Parameters | Purpose |
|---|---|---|
| `list_projects` | — | List every tracked project |
| `add_project` | `name`, `path`, optional `description` | Register a project and auto-detect tech |
| `get_project_status` | `projectName` | Full detail for one project |
| `update_project_status` | `projectName`, optional `status`, `notes` | Update the desk entry |
| `search_code_patterns` | `pattern` | Search projects + knowledge base |
| `get_project_timeline` | `projectName` | Status history and durations |
| `get_activity_heatmap` | optional `days` (default 7) | Activity heat map |
| `get_technology_trends` | — | Framework usage across the portfolio |
| `get_project_health` | — | Health scores and recommendations |

You talk in natural language. The host maps your words onto these tools.

---

## Example workflow

```text
You: Add my new SwiftUI project FinanceTracker at ~/Developer/FinanceTracker
Claude: Successfully added… Detected tech stack: Swift Package Manager, SwiftUI

You: Update FinanceTracker status to 'Working on Core Data models'
Claude: Updated.

You: Which of my projects use Core Data or SwiftUI?
Claude: [search + roster]

You: Which projects need my attention?
Claude: [health report with scores and recommendations]

You: Show my activity this week
Claude: [heat map]
```

---

## Prerequisites

- macOS 13+
- Swift 6.0+ (Xcode 16+)
- An MCP host: Claude Desktop, Cursor, or Claude Code

## Installation

### Build from source

```bash
git clone https://github.com/M-Pineapple/Claude-Project-Coordinator.git
cd Claude-Project-Coordinator
swift build -c release
```

Executable:

```text
.build/release/project-coordinator
```

### Claude Desktop

Settings → Developer → Model Context Protocol:

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

### Cursor

Add the same server entry to your Cursor MCP settings JSON, using the absolute path to `.build/release/project-coordinator`.

### Claude Code

Register the same `command` path in your Claude Code MCP config.

Optional: set `CPC_KNOWLEDGE_BASE` to a custom KnowledgeBase directory (useful if the clone is public and your project JSON should stay private).

Restart the host after changing the config.

---

## Security configuration

Defaults live in `Sources/ProjectCoordinator/SecurityValidator.swift` (compiled in).

**Allowed roots:** `~/Developer`, `~/Documents`, `~/GitHub`, `~/Projects`, `~/Desktop/Development`, `~/Xcode`

**Limits:** project name 100 · path 500 · description 2,000 · notes 10,000 · search pattern 300 characters

To change allowlists or limits, edit the source, rebuild (`swift build -c release`), and restart the host.

---

## Project structure

```text
Claude-Project-Coordinator/
├── Sources/
│   ├── ProjectCoordinator/     # Library (MCP, manager, analytics, security)
│   └── project-coordinator/    # Executable entry point
├── Tests/ProjectCoordinatorTests/
├── KnowledgeBase/              # Patterns, templates, local project/analytics data
├── scripts/                    # Build and repair helpers
├── ANALYTICS-EXAMPLES.md       # Sample analytics output
├── Package.swift
└── README.md
```

---

## Upgrading from v1.3.x

1. `git pull` and rebuild with Swift 6: `swift build -c release`
2. Point your MCP host at the new binary
3. If creation dates were corrupted by the old re-migration bug:

```bash
./scripts/repair-analytics-dates.sh
```

---

## More MCP servers by M-Pineapple

Other MCP servers in this portfolio:

- [CryptoAnalysisMCP](https://github.com/M-Pineapple/CryptoAnalysisMCP). Cryptocurrency technical analysis for Claude Desktop.
- [Warp Command Runner](https://github.com/M-Pineapple/warp-command-runner). Give any chat AI a real terminal.
- [Msty Admin MCP](https://github.com/M-Pineapple/msty-admin-mcp). Administer Msty Studio Desktop.
- [Member Berries](https://github.com/M-Pineapple/member-berries-apple-mcp). Apple Calendar, Notes and Reminders with personality.
- [SeaShell](https://github.com/M-Pineapple/seashell). Talk to Claude from any terminal block.
- [TextEdit MCP](https://github.com/M-Pineapple/TextEdit-MCP). Formatted RTF documents via macOS TextEdit.
- [HubSpot Auditor](https://github.com/M-Pineapple/hubspot-auditor). Read-only HubSpot portal audit.

---

## 💖 Support This Project

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

<a href="https://www.buymeacoffee.com/mpineapple" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

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! 🙏

---

## Contributing

Contributions are welcome. Report bugs, suggest features, open pull requests, or share patterns and templates under `KnowledgeBase/`.

## License

MIT License.

## Acknowledgments

Built for the MCP ecosystem. Protocol stack: [modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk).

---

Made with ❤️ from 🍍 Pineapple