@proplandev/mcp 1.0.0

package/tools/exportToCloud.js

@@ -0,0 +1,90 @@
+// mcp-server/tools/exportToCloud.js
+import { SqliteAdapter } from '../adapters/SqliteAdapter.js';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+export async function exportToCloud({ mcp_token, api_url }) {
+  const resolvedApiUrl = api_url || process.env.PROPLAN_API_URL || 'https://project-planner-7zw4.onrender.com';
+
+  if (!mcp_token) {
+    throw new Error('mcp_token is required. Generate one at app.proplan.dev → Settings → Claude Code Integration.');
+  }
+
+  const dbPath = join(process.cwd(), '.project-planner', 'db.sqlite');
+  if (!existsSync(dbPath)) {
+    return { inserted: 0, updated: 0, skipped: 0, message: 'No local database found. Nothing to sync.' };
+  }
+
+  const local = new SqliteAdapter(dbPath);
+  const projects = local.getProjectsSyncStatus();
+
+  if (projects.length === 0) {
+    return { inserted: 0, updated: 0, skipped: 0, message: 'No local projects found. Create a project first with create_project or scan_repo.' };
+  }
+
+  // Determine which projects need syncing
+  const toSync = [];
+  const stats = { inserted: 0, updated: 0, skipped: 0 };
+
+  for (const project of projects) {
+    if (!project.last_synced_at) {
+      toSync.push({ ...project, _action: 'insert' });
+    } else if (new Date(project.updated_at) > new Date(project.last_synced_at)) {
+      toSync.push({ ...project, _action: 'update' });
+    } else {
+      stats.skipped++;
+    }
+  }
+
+  if (toSync.length === 0) {
+    return {
+      inserted: 0,
+      updated: 0,
+      skipped: stats.skipped,
+      dashboardUrl: 'https://project-planner-7zw4.onrender.com/dashboard',
+      message: 'All projects are already up to date.',
+    };
+  }
+
+  // Push to backend
+  const res = await fetch(`${resolvedApiUrl}/api/mcp/sync`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${mcp_token}`,
+    },
+    body: JSON.stringify({
+      projects: toSync.map(p => ({
+        id: p.id,
+        title: p.title,
+        content: p.content,
+        created_at: p.created_at || p.updated_at,  // use actual created_at, fall back to updated_at if null
+        updated_at: p.updated_at,
+      })),
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
+    throw new Error(err.error || `Sync failed: ${res.status}`);
+  }
+
+  const data = await res.json();
+  const now = new Date().toISOString();
+
+  // Mark synced projects in local DB
+  for (const project of toSync) {
+    local.markSynced(project.id, now);
+    if (project._action === 'insert') stats.inserted++;
+    else stats.updated++;
+  }
+
+  return {
+    inserted: stats.inserted,
+    updated: stats.updated,
+    skipped: stats.skipped,
+    dashboardUrl: data.dashboardUrl,
+    message: data.message,
+    nextStep: `Sign in at ${data.dashboardUrl} to view your projects.`,
+  };
+}

package/tools/getNextTasks.js

@@ -0,0 +1,43 @@
+// mcp-server/tools/getNextTasks.js
+
+export async function getNextTasks(adapter, args) {
+  if (!args.project_id) throw new Error('project_id is required');
+  const limit = Math.min(args.limit ?? 5, 20);
+
+  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 results = [];
+
+  const phases = [...(roadmap.phases || [])].sort((a, b) => a.order - b.order);
+  for (const phase of phases) {
+    if (results.length >= limit) break;
+    const milestones = [...(phase.milestones || [])].sort((a, b) => a.order - b.order);
+    for (const milestone of milestones) {
+      if (results.length >= limit) break;
+      const tasks = [...(milestone.tasks || [])].sort((a, b) => a.order - b.order);
+      for (const task of tasks) {
+        if (results.length >= limit) break;
+        if (task.status === 'pending' || task.status === 'in_progress') {
+          results.push({
+            taskId: task.id,
+            title: task.title,
+            description: task.description ?? '',
+            status: task.status,
+            technology: task.technology ?? null,
+            phaseTitle: phase.title,
+            milestoneTitle: milestone.title,
+          });
+        }
+      }
+    }
+  }
+
+  return results;
+}

package/tools/getProjectRoadmap.js

@@ -0,0 +1,27 @@
+// mcp-server/tools/getProjectRoadmap.js
+
+export async function getProjectRoadmap(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.summary_only) return roadmap;
+
+  // summary_only: strip descriptions and notes from every task
+  return {
+    ...roadmap,
+    phases: (roadmap.phases || []).map(phase => ({
+      ...phase,
+      milestones: (phase.milestones || []).map(milestone => ({
+        ...milestone,
+        tasks: (milestone.tasks || []).map(({ description, notes, ...task }) => task),
+      })),
+    })),
+  };
+}

package/tools/getProjectStatus.js

@@ -0,0 +1,102 @@
+// mcp-server/tools/getProjectStatus.js
+
+function countTasks(phases) {
+  let total = 0, completed = 0, inProgress = 0;
+  for (const phase of phases) {
+    for (const milestone of (phase.milestones || [])) {
+      for (const task of (milestone.tasks || [])) {
+        total++;
+        if (task.status === 'completed') completed++;
+        else if (task.status === 'in_progress') inProgress++;
+      }
+    }
+  }
+  return { total, completed, inProgress };
+}
+
+function buildHandoff(data, roadmap, limit = 5) {
+  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,
+        });
+      }
+    }
+  }
+
+  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 sessions = Array.isArray(roadmap.sessions) ? roadmap.sessions : [];
+  return {
+    projectGoal: roadmap.projectGoal || null,
+    lastSession: sessions.length > 0 ? sessions[sessions.length - 1] : null,
+    recentTasks: allTasks.slice(0, limit).map(({ _lastNoteTime, ...t }) => t),
+  };
+}
+
+export async function getProjectStatus(adapter, args) {
+  if (args.project_id) {
+    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 { total, completed, inProgress } = countTasks(roadmap.phases || []);
+    const currentPhase = (roadmap.phases || []).find(p =>
+      (p.milestones || []).some(m => (m.tasks || []).some(t => t.status !== 'completed'))
+    );
+
+    const status = {
+      id: data.id,
+      title: data.title,
+      totalPhases: (roadmap.phases || []).length,
+      totalTasks: total,
+      completedTasks: completed,
+      inProgressTasks: inProgress,
+      completionPercent: total === 0 ? 0 : Math.round((completed / total) * 100),
+      currentPhase: currentPhase?.title ?? null,
+      tech_metadata: roadmap.tech_metadata ?? null,
+    };
+
+    if (args.include_handoff) {
+      const handoff = buildHandoff(data, roadmap, args.last_n_tasks ?? 5);
+      status.projectGoal = handoff.projectGoal;
+      status.lastSession = handoff.lastSession;
+      status.recentTasks = handoff.recentTasks;
+    }
+
+    return status;
+  }
+
+  const rows = await adapter.listProjects();
+  return rows.map(row => {
+    let roadmap;
+    try { roadmap = JSON.parse(row.content); }
+    catch { return { id: row.id, title: row.title, totalTasks: 0, completedTasks: 0, completionPercent: 0, error: 'corrupted roadmap data' }; }
+    const { total, completed } = countTasks(roadmap.phases || []);
+    return {
+      id: row.id,
+      title: row.title,
+      totalTasks: total,
+      completedTasks: completed,
+      completionPercent: total === 0 ? 0 : Math.round((completed / total) * 100),
+      tech_metadata: roadmap.tech_metadata ?? null,
+    };
+  });
+}

package/tools/getSessionHandoff.js

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

@@ -0,0 +1,60 @@
+// mcp-server/tools/getTasks.js
+//
+// Filter tasks by status, phase_id, and/or keyword.
+// Returns a flat list of matching tasks with their phase/milestone context.
+
+export async function getTasks(adapter, args) {
+  if (!args.project_id) throw new Error('project_id 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`);
+  }
+
+  const { status, phase_id, keyword } = args;
+  const limit = Math.min(args.limit ?? 100, 500);
+  const kwLower = keyword ? keyword.toLowerCase() : null;
+
+  const results = [];
+  const phases = [...(roadmap.phases || [])].sort((a, b) => a.order - b.order);
+
+  outer: for (const phase of phases) {
+    if (phase_id && phase.id !== phase_id) continue;
+
+    const milestones = [...(phase.milestones || [])].sort((a, b) => a.order - b.order);
+    for (const milestone of milestones) {
+      const tasks = [...(milestone.tasks || [])].sort((a, b) => a.order - b.order);
+      for (const task of tasks) {
+        if (results.length >= limit) break outer;
+        if (status && task.status !== status) continue;
+
+        if (kwLower) {
+          const haystack = [task.title, task.description ?? '', task.technology ?? '']
+            .join(' ')
+            .toLowerCase();
+          if (!haystack.includes(kwLower)) continue;
+        }
+
+        results.push({
+          taskId: task.id,
+          title: task.title,
+          description: task.description ?? '',
+          status: task.status,
+          technology: task.technology ?? null,
+          phaseId: phase.id,
+          phaseTitle: phase.title,
+          milestoneId: milestone.id,
+          milestoneTitle: milestone.title,
+          notes: task.notes ?? [],
+        });
+      }
+    }
+  }
+
+  return { total: results.length, tasks: results, limit };
+}

package/tools/renameProject.js

@@ -0,0 +1,17 @@
+// mcp-server/tools/renameProject.js
+
+export async function renameProject(adapter, args) {
+  if (!args.new_title || !args.new_title.trim()) {
+    throw new Error('new_title 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`);
+
+  const oldTitle = data.title;
+  const newTitle = args.new_title.trim();
+
+  await adapter.renameProject(args.project_id, newTitle, new Date().toISOString());
+
+  return { old_title: oldTitle, new_title: newTitle };
+}

package/tools/scanRepo.js

@@ -0,0 +1,215 @@
+// mcp-server/tools/scanRepo.js
+import { readdirSync, statSync, readFileSync, existsSync } from 'fs';
+import { join, relative, extname, basename } from 'path';
+import { canAnalyze, analyzeFile } from '../lib/fileAnalyzer.js';
+
+// djb2 hash — fast, no dependencies
+function djb2(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+    hash = hash >>> 0; // keep unsigned 32-bit
+  }
+  return hash.toString(16);
+}
+
+const EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '__pycache__', '.cache', '.turbo', 'out', '.vercel',
+]);
+
+const KEY_FILE_NAMES = ['package.json', 'README.md', 'readme.md', 'README.txt'];
+
+function buildTree(dir, rootDir, lines = [], depth = 0) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return lines;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry.name)) continue;
+    if (entry.name.startsWith('.') && entry.name !== '.env.example') continue;
+
+    const indent = '  '.repeat(depth);
+    lines.push(`${indent}${entry.isDirectory() ? entry.name + '/' : entry.name}`);
+
+    if (entry.isDirectory()) {
+      buildTree(join(dir, entry.name), rootDir, lines, depth + 1);
+    }
+  }
+  return lines;
+}
+
+function findSourceFiles(dir, found = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+    if (entry.isDirectory()) {
+      findSourceFiles(join(dir, entry.name), found);
+    } else if (canAnalyze(entry.name)) {
+      found.push(join(dir, entry.name));
+    }
+  }
+  return found;
+}
+
+function findMarkdownFiles(dir, found = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    if (EXCLUDED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+    if (entry.isDirectory()) {
+      findMarkdownFiles(join(dir, entry.name), found);
+    } else if (extname(entry.name).toLowerCase() === '.md') {
+      found.push(join(dir, entry.name));
+    }
+  }
+  return found;
+}
+
+function readFileSafe(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function scanRepo(args) {
+  const scanPath = args?.path || process.cwd();
+
+  // If a specific file path is provided (not a directory), read just that file
+  let isSingleFile = false;
+  try {
+    const stat = statSync(scanPath);
+    isSingleFile = stat.isFile();
+  } catch {
+    // path doesn't exist — fall through to treat as directory
+  }
+
+  if (isSingleFile) {
+    const content = readFileSafe(scanPath);
+    return {
+      tree: basename(scanPath),
+      keyFiles: content ? [{ path: basename(scanPath), content }] : [],
+    };
+  }
+
+  // Full directory scan
+  const treeLines = buildTree(scanPath, scanPath);
+  const tree = treeLines.join('\n');
+
+  const keyFiles = [];
+  const seen = new Set();
+
+  // Always include root-level key files first
+  for (const name of KEY_FILE_NAMES) {
+    const filePath = join(scanPath, name);
+    if (existsSync(filePath)) {
+      const rel = relative(scanPath, filePath);
+      if (!seen.has(rel)) {
+        const content = readFileSafe(filePath);
+        if (content) { keyFiles.push({ path: rel, content }); seen.add(rel); }
+      }
+    }
+  }
+
+  // Markdown files — capped at 15 files, each truncated to 30KB
+  // Enough for large repos with extensive docs, without token blowout
+  const MD_FILE_LIMIT = 15;
+  const MD_FILE_MAX_BYTES = 30 * 1024;
+  const mdFiles = findMarkdownFiles(scanPath);
+  let mdCount = 0;
+  for (const filePath of mdFiles) {
+    if (mdCount >= MD_FILE_LIMIT) break;
+    const rel = relative(scanPath, filePath);
+    if (!seen.has(rel)) {
+      let content = readFileSafe(filePath);
+      if (content) {
+        // Truncate individual file if over 30KB
+        if (Buffer.byteLength(content, 'utf8') > MD_FILE_MAX_BYTES) {
+          content = content.slice(0, MD_FILE_MAX_BYTES) + '\n[truncated]';
+        }
+        keyFiles.push({ path: rel, content });
+        seen.add(rel);
+        mdCount++;
+      }
+    }
+  }
+
+  // Size guard: truncate file contents if total payload exceeds 200KB
+  const SIZE_LIMIT = 200 * 1024;
+  let totalSize = Buffer.byteLength(tree, 'utf8');
+  let truncated = false;
+  const guardedFiles = [];
+
+  for (const file of keyFiles) {
+    const fileSize = Buffer.byteLength(file.content, 'utf8');
+    if (totalSize + fileSize > SIZE_LIMIT) {
+      truncated = true;
+      break;
+    }
+    guardedFiles.push(file);
+    totalSize += fileSize;
+  }
+
+  const treeHash = djb2(tree);
+  const result = { tree, treeHash, keyFiles: guardedFiles };
+  if (truncated) result.truncated = true;
+
+  // Structural analysis for source files (JS/TS/Python/Go/Rust)
+  // Returns summaries (functions, classes, imports, exports) instead of raw content
+  const sourceFiles = findSourceFiles(scanPath);
+  const sourceAnalysis = [];
+  const SOURCE_LIMIT = 150 * 1024; // 150KB cap for structural analysis
+  let sourceSize = 0;
+
+  for (const filePath of sourceFiles) {
+    const content = readFileSafe(filePath);
+    if (!content) continue;
+    const fileSize = Buffer.byteLength(content, 'utf8');
+    if (sourceSize + fileSize > SOURCE_LIMIT) break;
+    const analysis = analyzeFile(relative(scanPath, filePath), content);
+    if (analysis) {
+      sourceAnalysis.push(analysis);
+      sourceSize += fileSize;
+    }
+  }
+
+  if (sourceAnalysis.length > 0) {
+    result.sourceAnalysis = sourceAnalysis;
+
+    // fileMap — hierarchical tree of source files with their structural summaries
+    // Stored in tech_metadata for the dashboard to render as a code map
+    const fileMap = {};
+    for (const entry of sourceAnalysis) {
+      const parts = entry.path.split('/');
+      const fileName = parts.pop();
+      const dir = parts.join('/') || '.';
+      if (!fileMap[dir]) fileMap[dir] = [];
+      fileMap[dir].push({
+        file: fileName,
+        language: entry.language,
+        functions: entry.functions,
+        classes: entry.classes,
+        exports: entry.exports,
+      });
+    }
+    result.fileMap = fileMap;
+  }
+
+  return result;
+}

package/tools/setProjectGoal.js

@@ -0,0 +1,24 @@
+// mcp-server/tools/setProjectGoal.js
+
+export async function setProjectGoal(adapter, args) {
+  if (!args.goal || !args.goal.trim()) {
+    throw new Error('goal 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`);
+  }
+
+  const oldGoal = roadmap.projectGoal || null;
+  roadmap.projectGoal = args.goal.trim();
+
+  await adapter.saveProject(args.project_id, data.title, JSON.stringify(roadmap), new Date().toISOString());
+
+  return { old_goal: oldGoal, new_goal: roadmap.projectGoal };
+}