npm package: @nihalcastelino/project-brain-mcp
Description: Multi-agent AI orchestration platform with 50+ MCP tools
Author: Project Brain
Latest version: 2.0.0

# Project Brain MCP (Free Tier)

**Coordinate multiple AI agents across your codebase**

> While Cursor handles one file and Claude Code helps with another, Project Brain tracks what each agent worked on, prevents conflicts, and makes it easy to hand off context between tools.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen)](https://nodejs.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)

---

## What is Project Brain?

When you use multiple AI coding agents (Claude Desktop, Cursor, GitHub Copilot), it's hard to track:
- ❌ What each agent is working on
- ❌ Which conversations led to which code changes
- ❌ Important decisions made during development
- ❌ How to hand off context between agents

**Project Brain solves this by:**
- ✅ **Task coordination** - Assign work to specific agents
- ✅ **Conversation search** - Find past discussions instantly 🆕
- ✅ **Decision tracking** - Record architectural choices
- ✅ **Context handoff** - Export/import complete project state 🆕
- ✅ **100% local** - Works offline, no cloud dependencies
- ✅ **No vendor lock-in** - Full import/export to JSON

**Free Tier:**
- ✅ Up to 100 tasks per project
- ✅ Full-text search across tasks, conversations, decisions
- ✅ Complete import/export for portability
- ✅ Works with any MCP-compatible AI tool

**Upgrade for Teams:**
- 🚀 Unlimited tasks and projects
- 🚀 Multi-agent coordination with task locking
- 🚀 Real-time collaboration dashboard
- 🚀 AI code review and analysis

---

## 🚀 Quick Start

### One-Command Installation

**That's it!** Setup is completely automated:

```bash
npm install -g @nihalcastelino/project-brain-mcp
```

This will:
1. ✅ Install dependencies
2. ✅ Build the MCP server
3. ✅ Auto-detect Claude Desktop and Cursor
4. ✅ Configure them automatically
5. ✅ Create local database

**Restart your AI tool and you're ready to go!**

### Alternative: Install from source

```bash
git clone https://github.com/nihalcastelino/project-brain-mcp.git
cd project-brain-mcp
npm install  # Automatically builds and configures
```

### Manual Configuration (if auto-setup fails)

<details>
<summary>Click to expand manual setup instructions</summary>

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "project-brain": {
      "command": "node",
      "args": ["/path/to/project-brain-mcp/dist/server.js"],
      "env": {
        "PROJECT_BRAIN_DB_PATH": "~/.project-brain/tasks.db"
      }
    }
  }
}
```

For Cursor, the config is at: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

</details>

### Usage

Once configured, use these MCP tools in your AI conversations:

```
# Create a project
pb_create_project(name="My App", description="Building a web app")

# Create a task
pb_create_task(projectId="...", title="Implement auth", priority="high")

# List tasks
pb_list_tasks(projectId="...")

# Complete a task
pb_complete_task(taskId="...")

# Export project to Markdown
pb_export_project(projectId="...", format="markdown")
```

---

## 📖 Features in Detail

### 🔍 Full-Text Search (NEW!)
- **Search tasks** - Find tasks by title, description, or notes
- **Search conversations** - Find past discussions instantly
- **Search decisions** - Locate architectural choices quickly
- **Project-scoped** - Search across all projects or filter by project
- **Fast SQLite search** - Up to 50 results per query

Example:
```
pb_search_conversations({ query: "JWT authentication error" })
// Returns all conversations mentioning JWT auth issues
```

### 💾 Import/Export (NEW!)
- **Complete project backup** - Export everything as JSON
- **Restore from backup** - Import projects with full history
- **No vendor lock-in** - Your data is portable
- **Respects limits** - Import stops at 100 tasks in free tier

Example:
```
// Export project
pb_export_project_json({ projectId: "proj-123" })

// Import to new environment
pb_import_project({ data: backupData })
```

### 📋 Task Management
- Create, read, update, delete tasks
- Set priority (low, medium, high) and due dates
- Track status (todo, in-progress, done, blocked)
- **Assign to specific AI agents** (claude, cursor, copilot)
- 100 tasks per project (free tier)

### 🗂️ Project Organization
- Group related tasks into projects
- Filter tasks by status, priority, assignee, due date
- Export entire projects to Markdown/JSON

### 💬 Conversation Logging
- Track AI discussions about tasks
- Log user, assistant, and system messages
- Attach structured metadata (code snippets, errors, etc.)
- **Searchable history** - Find any past conversation

### ✅ Decision Tracking
- Record important technical decisions
- Provide multiple choice options or free-form answers
- Track who decided and why
- Link decisions to tasks and conversations

---

## 💎 Upgrade to Team Edition

### Why Upgrade?

**You'll want Team Edition if you:**

- 👥 **Work with others** using different AI tools (Cursor + Claude + Copilot)
  - Team Edition adds **task locking** so agents don't conflict
  - **Real-time presence** - see who's working on what
  - **Live collaboration** - watch terminal output from team members

- 🤖 **Need AI-powered insights**
  - **AI code review** - Claude Sonnet 4 checks every commit
  - **Conversation analysis** - Automatic summarization and insights
  - **Prompt quality coaching** - Improve how you work with AI

- 🌿 **Want advanced Git features**
  - **Git worktrees** - Isolated branches per task automatically
  - **Quality gates** - Tests must pass before merging
  - **Conflict prevention** - Never overwrite each other's work

- 📊 **Need project visibility**
  - **Real-time dashboard** - Kanban board with drag & drop
  - **Activity feed** - See all team actions live
  - **Analytics** - Track team productivity and AI usage

- 🚀 **Hit the 100 task limit**
  - Team Edition has **unlimited tasks and projects**
  - Import your backups seamlessly

**Not just "more tasks" - it's about coordinating multiple agents and humans working together.**

### Pricing

- **Free Tier**: $0/month - 100 tasks/project, single user, local-only
- **Team Edition**: $20/user/month (annual) - Unlimited everything + collaboration
- **Trial**: 14 days free, no credit card required

[Start Free Trial →](https://project-brain.io/upgrade)

---

## 🛠️ Development

### Clone & Build

```bash
git clone https://github.com/nihalcastelino/project-brain-mcp.git
cd project-brain-mcp
npm install
npm run build
```

### Testing Locally

```bash
npm run dev
```

---

## 📚 MCP Tools Reference

### Projects
- `pb_create_project` - Create a new project
- `pb_list_projects` - List all projects
- `pb_get_project` - Get project details
- `pb_update_project` - Update project name/description
- `pb_delete_project` - Delete project

### Tasks
- `pb_create_task` - Create a new task (FREE LIMIT: 100/project)
- `pb_list_tasks` - List all tasks (with filters)
- `pb_get_task` - Get task details
- `pb_update_task` - Update task details
- `pb_complete_task` - Mark task as done
- `pb_delete_task` - Delete task

### Conversations
- `pb_create_conversation` - Start a conversation
- `pb_log_message` - Log a message (user/assistant/system)
- `pb_get_conversation` - Get conversation details
- `pb_get_messages` - Get all messages
- `pb_list_conversations` - List conversations
- `pb_delete_conversation` - Delete conversation

### Decisions
- `pb_create_decision` - Create a decision point
- `pb_answer_decision` - Answer a decision
- `pb_list_decisions` - List decisions

### 🔍 Search (NEW!)
- `pb_search_tasks` - Search tasks by keyword (title, description, notes)
- `pb_search_conversations` - Search conversations by keyword (title, messages)
- `pb_search_decisions` - Search decisions by keyword (question, answer, rationale)

### 💾 Import/Export
- `pb_export_project` - Export project to Markdown/Chat/Plain text
- `pb_export_task` - Export task with conversations
- `pb_export_conversation` - Export conversation
- `pb_export_project_json` - Export complete project backup as JSON (NEW!)
- `pb_import_project` - Import project from JSON backup (NEW!)

### Utility
- `pb_ping` - Test MCP connection

---

## 🗄️ Data Storage

**Free Tier:** All data stored locally in SQLite database at:
- macOS: `~/.project-brain/project-brain.db`
- Linux: `~/.project-brain/project-brain.db`
- Windows: `%USERPROFILE%\.project-brain\project-brain.db`

**No cloud sync.** Your data never leaves your machine.

---

## 🤝 Contributing

We welcome contributions! Note:
- This free tier is **100% open source** (MIT license)
- Team Edition features are in a separate commercial offering

To contribute:
1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Please ensure:
- Code follows existing style
- Tests pass (if applicable)
- README updated (if needed)

---

## 📄 License

**MIT License** - See [LICENSE](LICENSE) for details

This means you can:
- ✅ Use commercially
- ✅ Modify
- ✅ Distribute
- ✅ Use privately

---

## 🆘 Support

**Free Tier (Community Support):**
- GitHub Issues: [github.com/nihalcastelino/project-brain-mcp/issues](https://github.com/nihalcastelino/project-brain-mcp/issues)
- Discussions: [github.com/nihalcastelino/project-brain-mcp/discussions](https://github.com/nihalcastelino/project-brain-mcp/discussions)

**Paid Tier (Priority Support):**
- Email: support@project-brain.io
- Response time: < 24 hours
- Dedicated Slack channel

---

## 🔗 Links

- **Website:** [project-brain.io](https://project-brain.io)
- **Documentation:** [docs.project-brain.io](https://docs.project-brain.io)
- **Team Edition:** [project-brain.io/upgrade](https://project-brain.io/upgrade)
- **GitHub:** [github.com/nihalcastelino/project-brain-mcp](https://github.com/nihalcastelino/project-brain-mcp)

---

## ⭐ Star Us!

If you find Project Brain helpful, please star the repo!

It helps others discover the project and motivates us to keep improving it.

---

**Made with ❤️ by the Project Brain team**

*Helping AI agents collaborate, one task at a time.*