@nihalcastelino/project-brain-mcp 1.0.0

package/TESTING_GUIDE.md

@@ -0,0 +1,397 @@
+# Testing Guide - Project Brain MCP (Free Tier)
+
+**Before publishing to npm, test everything thoroughly.**
+
+---
+
+## Prerequisites
+
+- Node.js 16+ installed
+- npm or yarn
+- Claude Desktop (optional, for MCP testing)
+
+---
+
+## Step 1: Install Dependencies
+
+```bash
+cd project-brain-mcp
+npm install
+```
+
+**Expected output:**
+- `better-sqlite3` installed
+- `@modelcontextprotocol/sdk` installed
+- No errors
+
+---
+
+## Step 2: Build TypeScript
+
+```bash
+npm run build
+```
+
+**Expected output:**
+- `dist/` directory created
+- `dist/server.js` exists
+- `dist/tools/index.js` exists
+- `dist/storage/sqlite-local.js` exists
+- No TypeScript errors
+
+---
+
+## Step 3: Test Server Startup
+
+```bash
+npm run dev
+```
+
+**Expected output (stderr):**
+```
+Project Brain MCP Server (Free Tier) started
+Storage: Local SQLite (offline mode)
+
+🚀 Upgrade to Team Edition for:
+   ✨ Multi-agent collaboration
+   ✨ AI code review
+   ✨ Real-time dashboard
+   ✨ Unlimited tasks
+
+   Try free for 14 days → https://project-brain.io/upgrade
+```
+
+**Keep this running in a terminal for next steps.**
+
+---
+
+## Step 4: Test with MCP Client
+
+### Option A: Claude Desktop
+
+1. Update Claude Desktop config:
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add MCP server:
+```json
+{
+  "mcpServers": {
+    "project-brain": {
+      "command": "node",
+      "args": ["/absolute/path/to/project-brain-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+
+4. In Claude, try:
+```
+Use pb_ping to test connection
+```
+
+**Expected:** JSON response with `ok: true`, `tier: "free"`, `storage: "local"`
+
+### Option B: Manual Testing
+
+Use the MCP Inspector or write a simple test script.
+
+---
+
+## Step 5: Test Core Features
+
+### Test Project Creation
+
+```
+Use pb_create_project with name="Test Project" and description="My test"
+```
+
+**Expected:** Project created with ID
+
+### Test Task Creation
+
+```
+Use pb_create_task with projectId="..." and title="Test Task"
+```
+
+**Expected:** Task created successfully
+
+### Test Task Listing
+
+```
+Use pb_list_tasks with projectId="..."
+```
+
+**Expected:** Array with 1 task
+
+### Test 100 Task Limit
+
+Create 100 tasks, then try to create the 101st:
+
+```javascript
+// In a loop
+for (let i = 1; i <= 100; i++) {
+  pb_create_task(projectId="...", title=`Task ${i}`)
+}
+
+// This should fail
+pb_create_task(projectId="...", title="Task 101")
+```
+
+**Expected:**
+- First 100 tasks created successfully
+- 101st task fails with error message:
+  ```
+  FREE TIER LIMIT: Maximum 100 tasks per project reached.
+
+  🚀 Upgrade to Team Edition for unlimited tasks:
+     ✨ Unlimited tasks and projects
+     ✨ Multi-agent collaboration
+     ✨ AI code review
+     ✨ Real-time dashboard
+
+     Try free for 14 days → https://project-brain.io/upgrade
+  ```
+
+### Test Conversation Logging
+
+```
+1. pb_create_conversation with projectId="...", title="Test Conversation"
+2. pb_log_message with conversationId="...", role="user", content="Hello"
+3. pb_log_message with conversationId="...", role="assistant", content="Hi there!"
+4. pb_get_messages with conversationId="..."
+```
+
+**Expected:** 2 messages returned
+
+### Test Export
+
+```
+pb_export_project with projectId="...", format="markdown"
+```
+
+**Expected:** Markdown-formatted project with all tasks
+
+---
+
+## Step 6: Test Offline Mode
+
+1. Disconnect from internet
+2. Restart server
+3. Try creating project, task, conversation
+
+**Expected:** Everything works (no network calls)
+
+---
+
+## Step 7: Test Database Persistence
+
+1. Stop server (Ctrl+C)
+2. Restart server
+3. List projects
+
+**Expected:** Projects/tasks from previous session still exist
+
+---
+
+## Step 8: Check Database File
+
+```bash
+# macOS/Linux
+ls -lh ~/.project-brain/project-brain.db
+
+# Windows
+dir %USERPROFILE%\.project-brain\project-brain.db
+```
+
+**Expected:** SQLite database file exists
+
+---
+
+## Step 9: Test Error Handling
+
+### Invalid Project ID
+
+```
+pb_get_project with projectId="invalid-id"
+```
+
+**Expected:** `{ project: null }`
+
+### Invalid Task ID
+
+```
+pb_get_task with taskId="invalid-id"
+```
+
+**Expected:** `{ task: null }`
+
+### Missing Required Fields
+
+```
+pb_create_task with title="Test" (no projectId)
+```
+
+**Expected:** Error about missing projectId
+
+---
+
+## Step 10: Performance Test
+
+Create 100 tasks rapidly:
+
+```javascript
+const start = Date.now();
+for (let i = 0; i < 100; i++) {
+  await pb_create_task(projectId="...", title=`Task ${i}`);
+}
+const end = Date.now();
+console.log(`Created 100 tasks in ${end - start}ms`);
+```
+
+**Expected:**
+- All 100 tasks created
+- Time < 5 seconds (SQLite is fast)
+
+---
+
+## Step 11: Memory Leak Test
+
+Run server for extended period with activity:
+
+```bash
+# Terminal 1: Start server
+npm run dev
+
+# Terminal 2: Monitor memory
+# macOS/Linux
+while true; do ps aux | grep node | grep -v grep; sleep 5; done
+
+# Windows
+# Use Task Manager to monitor node.exe
+```
+
+**Expected:**
+- Memory usage stable (< 100MB)
+- No memory leaks over time
+
+---
+
+## Step 12: Cross-Platform Test
+
+Test on:
+- [ ] macOS
+- [ ] Windows
+- [ ] Linux (Ubuntu/Debian)
+
+**Expected:** Works on all platforms
+
+---
+
+## Common Issues & Fixes
+
+### Issue: "better-sqlite3 not found"
+**Fix:**
+```bash
+npm install better-sqlite3 --save
+npm run build
+```
+
+### Issue: "Cannot find module '@modelcontextprotocol/sdk'"
+**Fix:**
+```bash
+npm install @modelcontextprotocol/sdk --save
+npm run build
+```
+
+### Issue: TypeScript errors
+**Fix:**
+```bash
+npm install -D typescript @types/node @types/better-sqlite3
+npm run build
+```
+
+### Issue: Permission denied on database
+**Fix:**
+```bash
+chmod 755 ~/.project-brain
+chmod 644 ~/.project-brain/project-brain.db
+```
+
+### Issue: Server won't start
+**Fix:**
+```bash
+# Check Node version
+node --version  # Should be 16+
+
+# Check logs
+npm run dev 2>&1 | tee server.log
+```
+
+---
+
+## Success Criteria
+
+✅ All tests pass
+✅ No TypeScript errors
+✅ No runtime errors
+✅ Database persists data
+✅ Works offline
+✅ 100 task limit enforced
+✅ Upgrade messages display correctly
+✅ Memory usage stable
+✅ Cross-platform compatible
+
+---
+
+## Final Checklist Before Publishing
+
+- [ ] All tests pass
+- [ ] README.md accurate
+- [ ] LICENSE file correct (MIT)
+- [ ] package.json correct (version, license, etc.)
+- [ ] .npmignore configured (don't ship source)
+- [ ] TypeScript builds without errors
+- [ ] No console.log() left in production code
+- [ ] Upgrade CTAs in place
+- [ ] No secrets in code
+- [ ] No hardcoded paths (use homedir())
+
+---
+
+## Publishing to npm
+
+Once all tests pass:
+
+```bash
+# 1. Login to npm
+npm login
+
+# 2. Verify package.json
+cat package.json  # Check version, name, license
+
+# 3. Build production
+npm run build
+
+# 4. Test package locally
+npm pack
+# This creates a .tgz file you can test install:
+# npm install -g ./project-brain-mcp-1.0.0.tgz
+
+# 5. Publish (dry run first)
+npm publish --dry-run
+
+# 6. Publish for real
+npm publish --access public
+
+# 7. Verify
+npm info @project-brain/mcp
+```
+
+**Package URL:** https://www.npmjs.com/package/@project-brain/mcp
+
+---
+
+**Good luck with testing and launch! 🚀**

package/dist/formatter.d.ts

@@ -0,0 +1,48 @@
+export interface AIFormatter {
+    formatTaskContext(context: any): string;
+    formatConversation(conversation: any, messages: any[]): string;
+    formatTask(task: any, conversations?: any[], decisions?: any[]): string;
+    formatProject(project: any, tasks?: any[], conversations?: any[]): string;
+    formatDecisions(decisions: any[]): string;
+    formatHeading(text: string, level: number): string;
+    formatMetadata(metadata: Record<string, any>): string;
+}
+export declare class MarkdownFormatter implements AIFormatter {
+    formatTaskContext(context: any): string;
+    formatConversation(conversation: any, messages: any[]): string;
+    formatTask(task: any, conversations?: any[], decisions?: any[]): string;
+    formatProject(project: any, tasks?: any[], conversations?: any[]): string;
+    formatDecisions(decisions: any[]): string;
+    formatHeading(text: string, level: number): string;
+    formatMetadata(metadata: Record<string, any>): string;
+}
+export declare class ChatFormatter implements AIFormatter {
+    formatConversation(conversation: any, messages: any[]): string;
+    formatTaskContext(context: any): string;
+    formatTask(task: any, conversations?: any[], decisions?: any[]): string;
+    formatProject(project: any, tasks?: any[], conversations?: any[]): string;
+    formatDecisions(decisions: any[]): string;
+    formatHeading(text: string, level: number): string;
+    formatMetadata(metadata: Record<string, any>): string;
+}
+export declare class PlainTextFormatter implements AIFormatter {
+    formatTaskContext(context: any): string;
+    formatConversation(conversation: any, messages: any[]): string;
+    formatTask(task: any, conversations?: any[], decisions?: any[]): string;
+    formatProject(project: any, tasks?: any[], conversations?: any[]): string;
+    formatDecisions(decisions: any[]): string;
+    formatHeading(text: string, level: number): string;
+    formatMetadata(metadata: Record<string, any>): string;
+}
+export declare class HandoffReadyFormatter implements AIFormatter {
+    private markdownFormatter;
+    formatTaskContext(context: any): string;
+    formatConversation(conversation: any, messages: any[]): string;
+    formatTask(task: any, conversations?: any[], decisions?: any[]): string;
+    formatProject(project: any, tasks?: any[], conversations?: any[]): string;
+    formatDecisions(decisions: any[]): string;
+    formatHeading(text: string, level: number): string;
+    formatMetadata(metadata: Record<string, any>): string;
+}
+export declare function createFormatter(format?: "markdown" | "chat" | "plain" | "handoff_ready"): AIFormatter;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"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"}