@proplandev/mcp 1.0.4 → 1.0.5

package/README.md

@@ -0,0 +1,96 @@
+# ProPlan MCP
+
+Persistent project memory and session continuity for Claude Code. Never lose context between sessions.
+
+## What it does
+
+- **Remembers your project** — phases, milestones, tasks, and progress survive across sessions
+- **Resumes automatically** — Claude picks up exactly where you left off
+- **Scans your repo** — run `scan_repo` once and Claude understands your codebase
+- **Works offline** — SQLite local mode, no account required
+- **Syncs to dashboard** — optional cloud sync to [proplan.dev](https://project-planner-7zw4.onrender.com)
+
+## Quick start
+
+```bash
+npx @proplandev/mcp init
+```
+
+That's it. The wizard:
+- Writes `.mcp.json` so Claude Code finds the server
+- Writes `CLAUDE.md` with session resume instructions
+- Updates `.gitignore` to protect local data
+- Auto-adds read-only tools to Claude settings (skips approval prompts)
+
+Then restart Claude Code, open your project, and type **start** or **continue**.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_project_status` | List projects or get full status + session handoff |
+| `create_project` | Create a new project with phases, milestones, tasks |
+| `scan_repo` | Analyze codebase structure and auto-generate a roadmap |
+| `get_project_roadmap` | Full roadmap JSON |
+| `get_tasks` | Tasks filtered by status, milestone, or phase |
+| `get_next_tasks` | What to work on next |
+| `update_task_status` | Mark tasks pending / in_progress / completed |
+| `add_note_to_task` | Attach notes to a task |
+| `add_task` | Add a task to a milestone |
+| `edit_task` | Edit task title or description |
+| `delete_task` | Delete a task |
+| `add_milestone` | Add a milestone to a phase |
+| `edit_milestone` | Rename a milestone |
+| `delete_milestone` | Delete a milestone and its tasks |
+| `add_phase` | Add a phase to the roadmap |
+| `edit_phase` | Rename a phase |
+| `delete_phase` | Delete a phase and its milestones |
+| `rename_project` | Rename a project |
+| `delete_project` | Permanently delete a project |
+| `set_project_goal` | Set the north-star goal for a project |
+| `add_session_summary` | Record what was done this session |
+| `export_to_cloud` | Sync local projects to the ProPlan dashboard |
+
+## Storage modes
+
+**Local (default)** — data stored in `.project-planner/db.sqlite` in your project. No account needed.
+
+**Cloud** — projects sync to [proplan.dev](https://project-planner-7zw4.onrender.com). Requires a free account and MCP token from Settings → Claude Code Integration.
+
+Switch modes anytime by re-running `npx @proplandev/mcp init`.
+
+## Manual setup
+
+If you prefer to configure `.mcp.json` yourself:
+
+```json
+{
+  "mcpServers": {
+    "project-planner": {
+      "command": "npx",
+      "args": ["-y", "@proplandev/mcp"]
+    }
+  }
+}
+```
+
+For cloud mode, add your token:
+
+```json
+{
+  "mcpServers": {
+    "project-planner": {
+      "command": "npx",
+      "args": ["-y", "@proplandev/mcp"],
+      "env": {
+        "MCP_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Claude Code (or any MCP-compatible client)

package/bin/init.js

@@ -68,6 +68,43 @@ function buildEntry(mode, mcpToken) {
   return entry;
 }
 
+function addToGitignore(projectDir, entries) {
+  const gitignorePath = path.join(projectDir, '.gitignore');
+  let content = '';
+  try { content = fs.readFileSync(gitignorePath, 'utf8'); } catch { /* new file */ }
+  const lines = content.split('\n');
+  const toAdd = entries.filter(e => !lines.some(l => l.trim() === e));
+  if (toAdd.length === 0) return false;
+  const addition = (content.endsWith('\n') || content === '' ? '' : '\n') +
+    '# ProPlan MCP\n' + toAdd.join('\n') + '\n';
+  fs.writeFileSync(gitignorePath, content + addition, 'utf8');
+  return true;
+}
+
+const CLAUDE_MD_BLOCK = `
+## ProPlan MCP — Session Instructions
+
+At the start of every session:
+1. Call \`get_project_status\` with \`include_handoff: true\` on the active project
+2. If projects exist: resume where things left off — say "I see we were working on X..."
+3. If no projects exist: call \`scan_repo\` to read the codebase, then ask "Want me to build a roadmap from this?"
+4. Never ask the user to re-explain context
+`;
+
+function writeClaudeMd(projectDir) {
+  const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+  const marker = 'ProPlan MCP — Session Instructions';
+  try {
+    const existing = fs.readFileSync(claudeMdPath, 'utf8');
+    if (existing.includes(marker)) return 'already';
+    fs.writeFileSync(claudeMdPath, existing.trimEnd() + '\n' + CLAUDE_MD_BLOCK, 'utf8');
+    return 'appended';
+  } catch {
+    fs.writeFileSync(claudeMdPath, CLAUDE_MD_BLOCK.trimStart(), 'utf8');
+    return 'created';
+  }
+}
+
 // ─── Main ─────────────────────────────────────────────────────────────────────
 
 print();
@@ -106,9 +143,10 @@ print(`  2. User-level     ${dim(userLevel)}  ${dim('(applies to all your projec
 print();
 const locChoice = (await ask('  Your choice [1/2, default 1]: ')).trim() || '1';
 const mcpPath = locChoice === '2' ? userLevel : projectLocal;
+const isProjectLocal = locChoice !== '2';
 print();
 
-// 3. Write
+// 3. Write .mcp.json
 const existing = readMcpJson(mcpPath);
 existing.mcpServers = existing.mcpServers || {};
 
@@ -126,14 +164,31 @@ if (alreadyHas) {
 
 existing.mcpServers['project-planner'] = buildEntry(mode, mcpToken);
 writeMcpJson(mcpPath, existing);
-
-// 4. Success
 print(green('  ✓ .mcp.json written') + '  ' + dim(mcpPath));
+
+// 4. CLAUDE.md — write or append session instructions
+const claudeResult = writeClaudeMd(process.cwd());
+if (claudeResult === 'created') {
+  print(green('  ✓ CLAUDE.md created') + '  ' + dim(path.join(process.cwd(), 'CLAUDE.md')));
+} else if (claudeResult === 'appended') {
+  print(green('  ✓ CLAUDE.md updated') + '  ' + dim('ProPlan session instructions appended'));
+} else {
+  print(dim('  ✓ CLAUDE.md already has ProPlan instructions — skipped'));
+}
+
+// 5. .gitignore — add relevant entries
+const gitignoreEntries = ['.project-planner/'];
+if (isProjectLocal && mode === 'cloud') gitignoreEntries.push('.mcp.json');
+const gitignoreUpdated = addToGitignore(process.cwd(), gitignoreEntries);
+if (gitignoreUpdated) {
+  print(green('  ✓ .gitignore updated') + '  ' + dim(gitignoreEntries.join(', ') + ' added'));
+}
+
 print();
 print(bold('  Next steps'));
 print(`  1. Restart Claude Code (or reload the MCP server)`);
-print(`  2. Open a project directory and start a new session`);
-print(`  3. Claude will call get_project_status automatically on session start`);
+print(`  2. Open your project directory in Claude Code`);
+print(`  3. Type ${bold('start')} or ${bold('continue')} — Claude will scan your project and get to work`);
 print();
 
 if (mode === 'local') {
@@ -145,7 +200,7 @@ if (mode === 'local') {
 }
 print();
 
-// 5. allowedTools — offer to auto-write
+// 6. allowedTools — offer to auto-write
 const ALLOWED_TOOLS = [
   'mcp__project-planner__get_project_status',
   'mcp__project-planner__get_next_tasks',

package/index.js

@@ -50,7 +50,7 @@ console.error(`[ProPlan MCP] Starting in ${isCloudMode ? 'CLOUD' : 'LOCAL'} mode
 // ─── Server ───────────────────────────────────────────────────────────────────
 const server = new McpServer({
   name: 'project-planner',
-  version: '1.0.0',
+  version: '1.0.5',
 });
 
 server.tool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proplandev/mcp",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "MCP server for Claude Code — persistent project memory, session continuity, and structural repo analysis",
   "type": "module",
   "main": "index.js",
@@ -22,8 +22,7 @@
     "adapters/",
     "tools/",
     "lib/",
-    "auth.js",
-    "supabase.js"
+    "README.md"
   ],
   "keywords": [
     "mcp",
@@ -45,7 +44,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@supabase/supabase-js": "^2.50.0",
     "better-sqlite3": "^12.8.0",
     "zod": "^3.23.0"
   },

package/tools/createProject.js

@@ -32,7 +32,6 @@ export async function createProject(adapter, args) {
           title: taskInput.title,
           status: 'pending',
           order: taskOrder,
-          resources: [],
           ...(taskInput.description && { description: cap(taskInput.description) }),
           ...(taskInput.technology && { technology: taskInput.technology }),
         };

package/tools/getNextTasks.js

@@ -28,9 +28,9 @@ export async function getNextTasks(adapter, args) {
           results.push({
             taskId: task.id,
             title: task.title,
-            description: task.description ?? '',
+            ...(task.description && { description: task.description }),
             status: task.status,
-            technology: task.technology ?? null,
+            ...(task.technology && { technology: task.technology }),
             phaseTitle: phase.title,
             milestoneTitle: milestone.title,
           });

package/adapters/SupabaseAdapter.js

@@ -1,76 +0,0 @@
-// mcp-server/adapters/SupabaseAdapter.js
-
-export class SupabaseAdapter {
-  constructor(supabase, userId) {
-    this._supabase = supabase;
-    this._userId = userId;
-  }
-
-  getUserId() {
-    return this._userId;
-  }
-
-  async listProjects() {
-    const { data, error } = await this._supabase
-      .from('roadmap')
-      .select('id, title, content')
-      .eq('user_id', this._userId);
-    if (error) throw new Error(`Failed to fetch projects: ${error.message}`);
-    return data || [];
-  }
-
-  async getProject(projectId) {
-    const { data, error } = await this._supabase
-      .from('roadmap')
-      .select('id, title, content')
-      .eq('user_id', this._userId)
-      .eq('id', projectId)
-      .single();
-    if (error || !data) return null;
-    return data;
-  }
-
-  async saveProject(projectId, title, content, updatedAt) {
-    const { error } = await this._supabase
-      .from('roadmap')
-      .update({ title, content, updated_at: updatedAt })
-      .eq('user_id', this._userId)
-      .eq('id', projectId);
-    if (error) throw new Error(`Failed to save: ${error.message}`);
-  }
-
-  async insertProject(title, content) {
-    const now = new Date().toISOString();
-    const { data, error } = await this._supabase
-      .from('roadmap')
-      .insert({
-        user_id: this._userId,
-        title,
-        content,
-        created_at: now,
-        updated_at: now,
-      })
-      .select('id')
-      .single();
-    if (error || !data) throw new Error(`Failed to insert: ${error?.message ?? 'unknown'}`);
-    return { id: data.id };
-  }
-
-  async deleteProject(projectId) {
-    const { error } = await this._supabase
-      .from('roadmap')
-      .delete()
-      .eq('user_id', this._userId)
-      .eq('id', projectId);
-    if (error) throw new Error(`Failed to delete project: ${error.message}`);
-  }
-
-  async renameProject(projectId, newTitle, updatedAt) {
-    const { error } = await this._supabase
-      .from('roadmap')
-      .update({ title: newTitle, updated_at: updatedAt })
-      .eq('user_id', this._userId)
-      .eq('id', projectId);
-    if (error) throw new Error(`Failed to rename project: ${error.message}`);
-  }
-}

package/auth.js

@@ -1,22 +0,0 @@
-// mcp-server/auth.js
-
-/**
- * Validates a Personal Access Token against the mcp_tokens table.
- * @param {object} supabase - Supabase client
- * @param {string} token - The MCP_TOKEN value from env
- * @returns {Promise<string>} userId
- * @throws if token not found
- */
-export async function validatePat(supabase, token) {
-  const { data, error } = await supabase
-    .from('mcp_tokens')
-    .select('user_id')
-    .eq('token', token)
-    .single();
-
-  if (error || !data) {
-    throw new Error('Invalid MCP_TOKEN. Generate a new one in Project Planner Settings.');
-  }
-
-  return data.user_id;
-}

package/supabase.js

@@ -1,4 +0,0 @@
-// mcp-server/supabase.js
-// Supabase direct access removed. Cloud mode now routes through the backend API.
-// See BackendApiAdapter.js.
-export const supabase = null;

package/tools/getSessionHandoff.js

@@ -1,67 +0,0 @@
-// mcp-server/tools/getSessionHandoff.js
-
-export async function getSessionHandoff(adapter, args) {
-  const data = await adapter.getProject(args.project_id);
-  if (!data) throw new Error(`Project ${args.project_id} not found`);
-
-  const limit = args.last_n_tasks ?? 5;
-
-  let roadmap;
-  try {
-    roadmap = JSON.parse(data.content);
-  } catch {
-    throw new Error(`Project ${data.id} has corrupted roadmap data`);
-  }
-
-  // Flatten all tasks with their phase/milestone context
-  const allTasks = [];
-  for (const phase of (roadmap.phases || [])) {
-    for (const milestone of (phase.milestones || [])) {
-      for (const task of (milestone.tasks || [])) {
-        const notes = Array.isArray(task.notes) ? task.notes : [];
-        const lastNote = notes.length > 0 ? notes[notes.length - 1] : null;
-        allTasks.push({
-          id: task.id,
-          title: task.title,
-          status: task.status || 'pending',
-          phase: phase.title,
-          milestone: milestone.title,
-          lastNote: lastNote ? { text: lastNote.text, createdAt: lastNote.createdAt } : null,
-          _lastNoteTime: lastNote ? new Date(lastNote.createdAt).getTime() : 0,
-        });
-      }
-    }
-  }
-
-  // Sort: in_progress first, then by most recent note descending
-  allTasks.sort((a, b) => {
-    if (a.status === 'in_progress' && b.status !== 'in_progress') return -1;
-    if (b.status === 'in_progress' && a.status !== 'in_progress') return 1;
-    return b._lastNoteTime - a._lastNoteTime;
-  });
-
-  const recentTasks = allTasks.slice(0, limit).map(({ _lastNoteTime, ...task }) => task);
-
-  // Summarise overall progress
-  const totalTasks = allTasks.length;
-  const completedTasks = allTasks.filter(t => t.status === 'completed').length;
-  const inProgressTasks = allTasks.filter(t => t.status === 'in_progress').length;
-
-  // Last session summary (most recent only)
-  const sessions = Array.isArray(roadmap.sessions) ? roadmap.sessions : [];
-  const lastSession = sessions.length > 0 ? sessions[sessions.length - 1] : null;
-
-  return {
-    projectGoal: roadmap.projectGoal || null,
-    project: {
-      id: data.id,
-      title: data.title,
-      totalTasks,
-      completedTasks,
-      inProgressTasks,
-      completionPercent: totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0,
-    },
-    lastSession,
-    recentTasks,
-  };
-}

package/tools/syncProjects.js

@@ -1,99 +0,0 @@
-// mcp-server/tools/syncProjects.js
-
-/**
- * Core incremental sync algorithm, extracted for testability.
- *
- * @param {import('../adapters/SqliteAdapter.js').SqliteAdapter} adapter
- * @param {object} supabase - Supabase client
- * @param {string} userId
- * @param {{ delete_removed?: boolean }} opts
- * @returns {Promise<{ inserted: number, updated: number, skipped: number, deleted: number, failed: Array<{title: string, error: string}>, warning?: string }>}
- */
-export async function syncProjects(adapter, supabase, userId, opts = {}) {
-  const { delete_removed = false } = opts;
-
-  adapter._applyMigrations();
-
-  const projects = adapter.getProjectsSyncStatus();
-  const now = new Date().toISOString();
-
-  let inserted = 0;
-  let updated = 0;
-  let skipped = 0;
-  let deleted = 0;
-  const failed = [];
-
-  for (const project of projects) {
-    if (project.last_synced_at === null) {
-      // Never synced → INSERT with local UUID as Supabase row id
-      const { error } = await supabase
-        .from('roadmap')
-        .insert({
-          id: project.id,
-          user_id: userId,
-          title: project.title,
-          content: project.content,
-          created_at: now,
-          updated_at: now,
-        })
-        .select('id')
-        .single();
-
-      if (error) {
-        failed.push({ title: project.title, error: error.message });
-      } else {
-        adapter.markSynced(project.id, now);
-        inserted++;
-      }
-    } else if (project.updated_at > project.last_synced_at) {
-      // Changed since last sync → UPDATE
-      const { error } = await supabase
-        .from('roadmap')
-        .update({ title: project.title, content: project.content, updated_at: now })
-        .eq('id', project.id)
-        .eq('user_id', userId);
-
-      if (error) {
-        failed.push({ title: project.title, error: error.message });
-      } else {
-        adapter.markSynced(project.id, now);
-        updated++;
-      }
-    } else {
-      skipped++;
-    }
-  }
-
-  if (delete_removed) {
-    try {
-      const localIds = new Set(projects.map(p => p.id));
-      const { data: cloudRows, error: fetchErr } = await supabase
-        .from('roadmap')
-        .select('id')
-        .eq('user_id', userId);
-
-      if (fetchErr) throw fetchErr;
-
-      const toDelete = cloudRows.map(r => r.id).filter(id => !localIds.has(id));
-      if (toDelete.length > 0) {
-        const { error: delErr } = await supabase
-          .from('roadmap')
-          .delete()
-          .in('id', toDelete);
-        if (delErr) throw delErr;
-        deleted = toDelete.length;
-      }
-    } catch (err) {
-      return {
-        inserted,
-        updated,
-        skipped,
-        deleted: 0,
-        failed,
-        warning: `Cloud cleanup failed: ${err.message}. Inserts/updates were committed.`,
-      };
-    }
-  }
-
-  return { inserted, updated, skipped, deleted, failed };
-}