@proplandev/mcp 1.0.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@proplandev/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Claude Code — persistent project memory, session continuity, and structural repo analysis",
+  "type": "module",
+  "main": "index.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "proplan-init": "bin/init.js",
+    "proplan-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "init": "node bin/init.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --testPathPatterns=tests/"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "adapters/",
+    "tools/",
+    "lib/",
+    "auth.js",
+    "supabase.js"
+  ],
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "project-planner",
+    "session-memory",
+    "ai-tools"
+  ],
+  "author": "Solomon Agyire",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/King-Proplan/project-planner.git",
+    "directory": "mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@supabase/supabase-js": "^2.50.0",
+    "better-sqlite3": "^12.8.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {}
+  }
+}

package/supabase.js

@@ -0,0 +1,4 @@
+// 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/addMilestone.js

@@ -0,0 +1,38 @@
+// mcp-server/tools/addMilestone.js
+
+export async function addMilestone(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  const phase = (roadmap.phases || []).find(p => p.id === args.phase_id);
+  if (!phase) throw new Error(`Phase ${args.phase_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      preview: { id: '(will be generated)', title: args.title, tasks: [] },
+      target: `phase '${phase.title}'`,
+      action: 'add_milestone',
+    };
+  }
+
+  const milestones = phase.milestones || [];
+  const maxOrder = milestones.reduce((max, m) => Math.max(max, m.order || 0), 0);
+  const newMilestone = {
+    id: `milestone-${Date.now()}`,
+    title: args.title,
+    order: maxOrder + 1,
+    tasks: [],
+  };
+  phase.milestones = [...milestones, newMilestone];
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return newMilestone;
+}

package/tools/addNoteToTask.js

@@ -0,0 +1,35 @@
+// mcp-server/tools/addNoteToTask.js
+
+export async function addNoteToTask(adapter, args) {
+  if (!args.note || !args.note.trim()) throw new Error('Note text is required');
+
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+  let targetTask = null;
+
+  for (const phase of (roadmap.phases || [])) {
+    for (const milestone of (phase.milestones || [])) {
+      const task = (milestone.tasks || []).find(t => t.id === args.task_id);
+      if (task) {
+        if (!Array.isArray(task.notes)) task.notes = [];
+        task.notes.push({ text: args.note.trim(), createdAt: new Date().toISOString() });
+        targetTask = task;
+        break;
+      }
+    }
+    if (targetTask) break;
+  }
+
+  if (!targetTask) throw new Error(`Task ${args.task_id} not found in project ${args.project_id}`);
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return targetTask;
+}

package/tools/addPhase.js

@@ -0,0 +1,34 @@
+// mcp-server/tools/addPhase.js
+
+export async function addPhase(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  if (args.dry_run) {
+    return {
+      preview: { id: '(will be generated)', title: args.title, milestones: [] },
+      action: 'add_phase',
+    };
+  }
+
+  const phases = roadmap.phases || [];
+  const maxOrder = phases.reduce((max, p) => Math.max(max, p.order || 0), 0);
+  const newPhase = {
+    id: `phase-${Date.now()}`,
+    title: args.title,
+    order: maxOrder + 1,
+    milestones: [],
+  };
+  roadmap.phases = [...phases, newPhase];
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return newPhase;
+}

package/tools/addSessionSummary.js

@@ -0,0 +1,39 @@
+// mcp-server/tools/addSessionSummary.js
+
+const MAX_SESSIONS = 10;
+
+export async function addSessionSummary(adapter, args) {
+  if (!args.summary || !args.summary.trim()) {
+    throw new Error('summary is required and cannot be empty');
+  }
+
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  if (!Array.isArray(roadmap.sessions)) roadmap.sessions = [];
+
+  roadmap.sessions.push({
+    summary: args.summary.trim(),
+    createdAt: new Date().toISOString(),
+  });
+
+  // Keep only the most recent MAX_SESSIONS — drop oldest
+  if (roadmap.sessions.length > MAX_SESSIONS) {
+    roadmap.sessions = roadmap.sessions.slice(-MAX_SESSIONS);
+  }
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return {
+    saved: true,
+    totalSessions: roadmap.sessions.length,
+    summary: roadmap.sessions[roadmap.sessions.length - 1],
+  };
+}

package/tools/addTask.js

@@ -0,0 +1,52 @@
+// mcp-server/tools/addTask.js
+
+const DESC_MAX = 300;
+const cap = s => s ? s.slice(0, DESC_MAX) : s;
+
+export async function addTask(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  const phase = (roadmap.phases || []).find(p => p.id === args.phase_id);
+  if (!phase) throw new Error(`Phase ${args.phase_id} not found in project ${args.project_id}`);
+
+  const milestone = (phase.milestones || []).find(m => m.id === args.milestone_id);
+  if (!milestone) throw new Error(`Milestone ${args.milestone_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      preview: {
+        id: '(will be generated)',
+        title: args.title,
+        status: 'pending',
+        ...(args.description && { description: args.description }),
+        ...(args.technology && { technology: args.technology }),
+      },
+      target: `milestone '${milestone.title}' in phase '${phase.title}'`,
+      action: 'add_task',
+    };
+  }
+
+  const tasks = milestone.tasks || [];
+  const maxOrder = tasks.reduce((max, t) => Math.max(max, t.order || 0), 0);
+  const newTask = {
+    id: `task-${Date.now()}`,
+    title: args.title,
+    status: 'pending',
+    order: maxOrder + 1,
+    ...(args.description && { description: cap(args.description) }),
+    ...(args.technology && { technology: args.technology }),
+  };
+  milestone.tasks = [...tasks, newTask];
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return newTask;
+}

package/tools/createProject.js

@@ -0,0 +1,80 @@
+// mcp-server/tools/createProject.js
+
+const DESC_MAX = 300;
+const cap = s => s ? s.slice(0, DESC_MAX) : s;
+
+export async function createProject(adapter, args) {
+  if (!args.phases || args.phases.length === 0) {
+    throw new Error('Project must have at least one phase');
+  }
+
+  const now = new Date().toISOString();
+
+  let idCounter = 0;
+  let phaseOrder = 0;
+  let milestoneCount = 0;
+  let taskCount = 0;
+
+  const phases = args.phases.map(phaseInput => {
+    phaseOrder += 1;
+    let milestoneOrder = 0;
+
+    const milestones = (phaseInput.milestones || []).map(msInput => {
+      milestoneOrder += 1;
+      milestoneCount += 1;
+      let taskOrder = 0;
+
+      const tasks = (msInput.tasks || []).map(taskInput => {
+        taskOrder += 1;
+        taskCount += 1;
+        return {
+          id: `task-${Date.now()}-${++idCounter}`,
+          title: taskInput.title,
+          status: 'pending',
+          order: taskOrder,
+          resources: [],
+          ...(taskInput.description && { description: cap(taskInput.description) }),
+          ...(taskInput.technology && { technology: taskInput.technology }),
+        };
+      });
+
+      return {
+        id: `milestone-${Date.now()}-${++idCounter}`,
+        title: msInput.title,
+        order: milestoneOrder,
+        tasks,
+      };
+    });
+
+    return {
+      id: `phase-${Date.now()}-${++idCounter}`,
+      title: phaseInput.title,
+      order: phaseOrder,
+      milestones,
+    };
+  });
+
+  const roadmap = {
+    projectName: args.title,
+    summary: '',
+    metadata: {
+      scope: '',
+      version: '1.0',
+      ...(args.description && { description: args.description }),
+      ...(args.timeline && { timeline: args.timeline }),
+      ...(args.experienceLevel && { experienceLevel: args.experienceLevel }),
+      ...(args.technologies && { technologies: args.technologies }),
+    },
+    phases,
+  };
+
+  const { id } = await adapter.insertProject(args.title, JSON.stringify(roadmap));
+
+  return {
+    projectId: id,
+    title: args.title,
+    phaseCount: phases.length,
+    milestoneCount,
+    taskCount,
+  };
+}

package/tools/deleteMilestone.js

@@ -0,0 +1,39 @@
+// mcp-server/tools/deleteMilestone.js
+
+export async function deleteMilestone(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  let targetMilestone = null;
+  let targetPhase = null;
+
+  for (const phase of (roadmap.phases || [])) {
+    const ms = (phase.milestones || []).find(m => m.id === args.milestone_id);
+    if (ms) { targetMilestone = ms; targetPhase = phase; break; }
+  }
+
+  if (!targetMilestone) throw new Error(`Milestone ${args.milestone_id} not found in project ${args.project_id}`);
+
+  const taskCount = (targetMilestone.tasks || []).length;
+
+  if (args.dry_run) {
+    return {
+      item: { id: targetMilestone.id, title: targetMilestone.title },
+      warning: `This will permanently delete 1 milestone and ${taskCount} task${taskCount !== 1 ? 's' : ''}. This cannot be undone.`,
+      action: 'delete_milestone',
+    };
+  }
+
+  targetPhase.milestones = targetPhase.milestones.filter(m => m.id !== args.milestone_id);
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return { deleted: true, id: args.milestone_id };
+}

package/tools/deletePhase.js

@@ -0,0 +1,35 @@
+// mcp-server/tools/deletePhase.js
+
+export async function deletePhase(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  const targetPhase = (roadmap.phases || []).find(p => p.id === args.phase_id);
+  if (!targetPhase) throw new Error(`Phase ${args.phase_id} not found in project ${args.project_id}`);
+
+  const milestoneCount = (targetPhase.milestones || []).length;
+  const taskCount = (targetPhase.milestones || []).reduce(
+    (sum, m) => sum + (m.tasks || []).length, 0
+  );
+
+  if (args.dry_run) {
+    return {
+      item: { id: targetPhase.id, title: targetPhase.title },
+      warning: `This will permanently delete 1 phase, ${milestoneCount} milestone${milestoneCount !== 1 ? 's' : ''}, and ${taskCount} task${taskCount !== 1 ? 's' : ''}. This cannot be undone.`,
+      action: 'delete_phase',
+    };
+  }
+
+  roadmap.phases = roadmap.phases.filter(p => p.id !== args.phase_id);
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return { deleted: true, id: args.phase_id };
+}

package/tools/deleteProject.js

@@ -0,0 +1,35 @@
+// mcp-server/tools/deleteProject.js
+
+export async function deleteProject(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let taskCount = 0;
+  let phaseCount = 0;
+  let milestoneCount = 0;
+
+  try {
+    const roadmap = JSON.parse(data.content);
+    phaseCount = (roadmap.phases || []).length;
+    for (const phase of (roadmap.phases || [])) {
+      milestoneCount += (phase.milestones || []).length;
+      for (const milestone of (phase.milestones || [])) {
+        taskCount += (milestone.tasks || []).length;
+      }
+    }
+  } catch {
+    // corrupted content — still allow deletion
+  }
+
+  if (args.dry_run) {
+    return {
+      item: { id: data.id, title: data.title },
+      warning: `This will permanently delete the project "${data.title}" including ${phaseCount} phase${phaseCount !== 1 ? 's' : ''}, ${milestoneCount} milestone${milestoneCount !== 1 ? 's' : ''}, and ${taskCount} task${taskCount !== 1 ? 's' : ''}. This cannot be undone.`,
+      action: 'delete_project',
+    };
+  }
+
+  await adapter.deleteProject(args.project_id);
+
+  return { deleted: true, id: args.project_id, title: data.title };
+}

package/tools/deleteTask.js

@@ -0,0 +1,40 @@
+// mcp-server/tools/deleteTask.js
+
+export async function deleteTask(adapter, args) {
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  let targetTask = null;
+  let targetMilestone = null;
+
+  for (const phase of (roadmap.phases || [])) {
+    for (const milestone of (phase.milestones || [])) {
+      const task = (milestone.tasks || []).find(t => t.id === args.task_id);
+      if (task) { targetTask = task; targetMilestone = milestone; break; }
+    }
+    if (targetTask) break;
+  }
+
+  if (!targetTask) throw new Error(`Task ${args.task_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      item: { id: targetTask.id, title: targetTask.title, status: targetTask.status },
+      warning: 'This will permanently delete 1 task. This cannot be undone.',
+      action: 'delete_task',
+    };
+  }
+
+  targetMilestone.tasks = targetMilestone.tasks.filter(t => t.id !== args.task_id);
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return { deleted: true, id: args.task_id };
+}

package/tools/editMilestone.js

@@ -0,0 +1,39 @@
+// mcp-server/tools/editMilestone.js
+
+export async function editMilestone(adapter, args) {
+  if (args.title === undefined) {
+    throw new Error('Provide at least one field to update: title');
+  }
+
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  let targetMilestone = null;
+  for (const phase of (roadmap.phases || [])) {
+    const ms = (phase.milestones || []).find(m => m.id === args.milestone_id);
+    if (ms) { targetMilestone = ms; break; }
+  }
+
+  if (!targetMilestone) throw new Error(`Milestone ${args.milestone_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      before: { title: targetMilestone.title },
+      after: { title: args.title },
+      action: 'edit_milestone',
+    };
+  }
+
+  targetMilestone.title = args.title;
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return targetMilestone;
+}

package/tools/editPhase.js

@@ -0,0 +1,34 @@
+// mcp-server/tools/editPhase.js
+
+export async function editPhase(adapter, args) {
+  if (args.title === undefined) {
+    throw new Error('Provide at least one field to update: title');
+  }
+
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  const targetPhase = (roadmap.phases || []).find(p => p.id === args.phase_id);
+  if (!targetPhase) throw new Error(`Phase ${args.phase_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      before: { title: targetPhase.title },
+      after: { title: args.title },
+      action: 'edit_phase',
+    };
+  }
+
+  targetPhase.title = args.title;
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return targetPhase;
+}

package/tools/editTask.js

@@ -0,0 +1,51 @@
+// mcp-server/tools/editTask.js
+
+const DESC_MAX = 300;
+
+export async function editTask(adapter, args) {
+  const hasFields = args.title !== undefined || args.description !== undefined || args.technology !== undefined;
+  if (!hasFields) {
+    throw new Error('Provide at least one field to update: title, description, technology');
+  }
+
+  const data = await adapter.getProject(args.project_id);
+  if (!data) throw new Error(`Project ${args.project_id} not found`);
+
+  let roadmap;
+  try {
+    roadmap = JSON.parse(data.content);
+  } catch {
+    throw new Error(`Project ${data.id} has corrupted roadmap data`);
+  }
+
+  let targetTask = null;
+  for (const phase of (roadmap.phases || [])) {
+    for (const milestone of (phase.milestones || [])) {
+      const task = (milestone.tasks || []).find(t => t.id === args.task_id);
+      if (task) { targetTask = task; break; }
+    }
+    if (targetTask) break;
+  }
+
+  if (!targetTask) throw new Error(`Task ${args.task_id} not found in project ${args.project_id}`);
+
+  if (args.dry_run) {
+    return {
+      before: { title: targetTask.title, description: targetTask.description, technology: targetTask.technology },
+      after: {
+        title: args.title !== undefined ? args.title : targetTask.title,
+        description: args.description !== undefined ? args.description : targetTask.description,
+        technology: args.technology !== undefined ? args.technology : targetTask.technology,
+      },
+      action: 'edit_task',
+    };
+  }
+
+  if (args.title !== undefined) targetTask.title = args.title;
+  if (args.description !== undefined) targetTask.description = args.description.slice(0, DESC_MAX);
+  if (args.technology !== undefined) targetTask.technology = args.technology;
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return targetTask;
+}