@nihalcastelino/project-brain-mcp 1.0.0

package/README.md

@@ -0,0 +1,356 @@
+# 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 @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/project-brain/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/project-brain/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/project-brain/project-brain-mcp/issues](https://github.com/project-brain/project-brain-mcp/issues)
+- Discussions: [github.com/project-brain/project-brain-mcp/discussions](https://github.com/project-brain/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/project-brain/project-brain-mcp](https://github.com/project-brain/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.*

package/SETUP_GUIDE.md

@@ -0,0 +1,251 @@
+# Project Brain Free Tier - Setup Guide
+
+## 🎯 Zero-Config Installation
+
+Project Brain Free Tier is designed to be **completely frictionless**. No manual configuration needed.
+
+## Installation Methods
+
+### Method 1: NPM Global Install (Recommended)
+
+```bash
+npm install -g @project-brain/mcp
+```
+
+**That's it!** This single command will:
+
+1. ✅ Install the package globally
+2. ✅ Build the TypeScript source
+3. ✅ Auto-detect Claude Desktop and Cursor
+4. ✅ Configure them automatically
+5. ✅ Create database directory at `~/.project-brain/`
+6. ✅ Show you what was configured
+
+### Method 2: Install from Source
+
+```bash
+git clone https://github.com/project-brain/project-brain-mcp.git
+cd project-brain-mcp
+npm install  # postinstall hook handles everything
+```
+
+### Method 3: NPM Local Install
+
+```bash
+npm install @project-brain/mcp
+npx project-brain-mcp setup  # Manual setup if needed
+```
+
+## What Happens During Installation?
+
+### 1. Build Phase
+```bash
+npm run build
+```
+- Compiles TypeScript to JavaScript
+- Creates `dist/` folder with compiled code
+- Takes ~10-20 seconds
+
+### 2. Auto-Configuration Phase
+```bash
+npm run setup
+```
+- Scans for AI tools (Claude Desktop, Cursor)
+- Detects config file locations based on OS
+- Updates MCP server configuration
+- Creates database directory
+- Shows what was configured
+
+## Supported AI Tools
+
+### Claude Desktop
+- **Windows**: `%APPDATA%\Roaming\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/claude/claude_desktop_config.json`
+
+### Cursor
+- **Windows**: `%APPDATA%\Roaming\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- **Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+## Configuration Added
+
+The setup script adds this to your AI tool's config:
+
+```json
+{
+  "mcpServers": {
+    "project-brain": {
+      "command": "node",
+      "args": ["/path/to/@project-brain/mcp/dist/server.js"],
+      "env": {
+        "PROJECT_BRAIN_DB_PATH": "/home/user/.project-brain/tasks.db"
+      }
+    }
+  }
+}
+```
+
+## Manual Setup (if auto-setup fails)
+
+If the automatic setup doesn't detect your AI tool, run:
+
+```bash
+npm run setup
+```
+
+This will show you the configuration to add manually.
+
+## Verify Installation
+
+### 1. Check your AI tool's config file
+
+**Claude Desktop (macOS):**
+```bash
+cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+**Cursor (macOS):**
+```bash
+cat ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
+```
+
+### 2. Restart your AI tool
+
+Close and reopen Claude Desktop or Cursor.
+
+### 3. Test the MCP server
+
+In your AI tool, try:
+```
+"Create a task called 'Test Project Brain'"
+```
+
+If it works, you'll see a response confirming the task was created!
+
+## Database Location
+
+All your data is stored locally at:
+
+- **Windows**: `C:\Users\<you>\.project-brain\tasks.db`
+- **macOS/Linux**: `~/.project-brain/tasks.db`
+
+This is a SQLite database file. You can:
+- Back it up by copying the file
+- Delete it to start fresh
+- Move it to another machine
+
+## Troubleshooting
+
+### "postinstall script failed"
+
+This usually means:
+1. Node.js version is too old (need 16+)
+2. TypeScript compilation failed
+3. File permissions issue
+
+**Fix:**
+```bash
+node --version  # Should be 16+
+npm run build   # Try building manually
+npm run setup   # Try setup manually
+```
+
+### "Could not auto-configure"
+
+The setup script couldn't find your AI tool's config directory.
+
+**Fix:**
+1. Check if your AI tool is installed
+2. Run `npm run setup` to see the manual config
+3. Add the config manually to your AI tool
+
+### "MCP server not showing up"
+
+**Fix:**
+1. Verify config file has the `project-brain` entry
+2. Restart your AI tool completely
+3. Check the AI tool's MCP server logs
+
+### "Error: Cannot find module"
+
+**Fix:**
+```bash
+cd project-brain-mcp
+npm run build
+```
+
+## Uninstall
+
+### NPM Global Install
+```bash
+npm uninstall -g @project-brain/mcp
+```
+
+### From Source
+```bash
+cd project-brain-mcp
+npm uninstall
+```
+
+### Remove Database (Optional)
+```bash
+rm -rf ~/.project-brain/
+```
+
+### Remove from AI Tool Config
+
+Open your AI tool's config file and remove the `"project-brain"` entry from `mcpServers`.
+
+## Upgrading
+
+### NPM Global Install
+```bash
+npm update -g @project-brain/mcp
+```
+
+### From Source
+```bash
+cd project-brain-mcp
+git pull
+npm install  # Rebuilds and reconfigures
+```
+
+## FAQ
+
+### Q: Do I need API keys?
+**A:** No! The free tier works 100% offline with no API keys required.
+
+### Q: Where is my data stored?
+**A:** Locally in `~/.project-brain/tasks.db`. No cloud, no tracking.
+
+### Q: Can I use multiple AI tools?
+**A:** Yes! The setup script configures all detected tools automatically.
+
+### Q: What if I already have an MCP server configured?
+**A:** The setup script preserves existing configurations and adds Project Brain alongside them.
+
+### Q: Does it work on Windows?
+**A:** Yes! Windows, macOS, and Linux are all supported.
+
+### Q: Can I customize the database location?
+**A:** Yes! Edit the `PROJECT_BRAIN_DB_PATH` in your AI tool's config file.
+
+### Q: How do I upgrade to paid tier?
+**A:** The paid tier is a separate backend service. Visit https://projectbrain.ai/pricing
+
+## Support
+
+- **Issues**: https://github.com/project-brain/project-brain-mcp/issues
+- **Discussions**: https://github.com/project-brain/project-brain-mcp/discussions
+- **Documentation**: https://github.com/project-brain/project-brain-mcp
+
+## Next Steps
+
+1. ✅ Install complete
+2. ✅ Restart your AI tool
+3. ✅ Try: "Create a task to test Project Brain"
+4. ✅ Try: "List all my tasks"
+5. ✅ Try: "Search for tasks containing 'test'"
+
+**You're all set! Happy coding! 🚀**