planko-mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,3 @@
+Looks like there's already a license file for this project.
+[?25l? Do you want to replace it? › (y/N)✔ Do you want to replace it? … no
+[?25hExiting...

package/README.md

@@ -0,0 +1,123 @@
+# planko-mcp-server
+
+MCP server for syncing [Planko](https://planko.io) tasks with local Markdown files. Works with Claude Code, Cursor, and any MCP-compatible AI agent.
+
+## Features
+
+- **3 tools**: setup, sync preview, sync
+- **Multi-folder**: sync multiple projects to different local folders
+- **Bidirectional sync**: pull remote changes, push local changes
+- **Delete sync**: deleted local files remove tasks on server; deleted tasks remove local files
+- **User-scoped API key**: one key works across all your projects
+
+## Getting Started
+
+### Step 1 — Get your API key
+
+1. Open [app.planko.io/integrations](https://app.planko.io/integrations)
+2. Find the **Model Context Protocol (MCP)** card
+3. Click **"Ativar"** to generate your API key
+4. Copy the key (you can only see it once — regenerate if you lose it)
+
+### Step 2 — Add to your MCP client
+
+**Claude Code** — add to `.mcp.json` in your project root (or `~/.claude/settings.local.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "planko": {
+      "command": "npx",
+      "args": ["-y", "planko-mcp-server"],
+      "env": {
+        "PLANKO_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "planko": {
+      "command": "npx",
+      "args": ["-y", "planko-mcp-server"],
+      "env": {
+        "PLANKO_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+No `npm install` or cloning needed. Requires Node.js 18+.
+
+### Step 3 — Restart your tool
+
+Restart Claude Code, Cursor, or whichever MCP client you use so it picks up the new server.
+
+### Step 4 — Setup a project folder
+
+Ask your AI agent to run:
+
+```
+planko_setup(projectName: "My Project", folderPath: "/path/to/folder", email: "you@email.com")
+```
+
+This maps a Planko project to a local folder. You can set up multiple projects pointing to different folders.
+
+### Step 5 — Sync
+
+```
+planko_sync()
+```
+
+Tasks are pulled as `.md` files into your folder. Local changes are pushed back to Planko.
+
+## Tools
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `planko_setup` | Set up sync between a project and a local folder | `projectName`, `folderPath`, `email` |
+| `planko_sync_preview` | Preview what would be synced (read-only) | `projectName` (optional) |
+| `planko_sync` | Execute bidirectional sync with delete support | `projectName` (optional) |
+
+### Sync preview
+
+```
+planko_sync_preview()                           # Preview all projects
+planko_sync_preview(projectName: "My Project")  # Preview one project
+```
+
+### Sync
+
+```
+planko_sync()                           # Sync all projects
+planko_sync(projectName: "My Project")  # Sync one project
+```
+
+When `projectName` is omitted, all configured projects are synced.
+
+Sync order: delete, pull, push. Local changes overwrite remote on conflict.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PLANKO_API_KEY` | Yes | Your MCP API key from app.planko.io/integrations |
+| `PLANKO_API_BASE` | No | API base URL override (defaults to production) |
+
+## How it works
+
+- Each Planko task maps to a local `.md` file (task name becomes filename)
+- Task descriptions are converted between BlockNote and Markdown automatically
+- Sync state is tracked in `.planko-mcp-sync.json` per folder
+- Global config is stored at `~/.planko-mcp/config.json`
+- API keys are never written to any file
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+
+/**
+ * planko-mcp-server — MCP server for syncing Planko tasks with local .md files.
+ *
+ * Environment variables:
+ *   PLANKO_API_KEY  (required) — user-scoped MCP API key
+ *   PLANKO_API_BASE — optional API base URL override
+ *
+ * Tools:
+ *   planko_setup        — Configure sync for a project folder
+ *   planko_sync_preview — Preview what would be synced
+ *   planko_sync         — Execute bidirectional sync with delete support
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { createApiClient } from './src/api.js';
+import {
+  blockNoteToMarkdown,
+  markdownToBlockNote,
+  descriptionToMarkdown,
+} from './src/converters.js';
+import {
+  readConfig,
+  writeConfig,
+  readSyncState,
+  writeSyncState,
+  createSyncState,
+  listLocalFiles,
+  getFileMtimeMs,
+  deleteLocalFile,
+  toFileName,
+  toTaskName,
+  buildIndexes,
+  SYNC_FILE,
+} from './src/sync-state.js';
+
+// --- Startup validation ---
+
+const API_KEY = process.env.PLANKO_API_KEY;
+if (!API_KEY) {
+  console.error(
+    'Fatal: PLANKO_API_KEY environment variable is required.'
+  );
+  process.exit(1);
+}
+
+const api = createApiClient({ apiKey: API_KEY });
+
+// --- Tool helpers ---
+
+function toolOk(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function toolError(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+// --- Sync engine (shared by preview and sync) ---
+
+/**
+ * Compute sync diff for a single project folder.
+ * Returns { wouldPush, wouldPull, wouldDeleteLocal, wouldDeleteRemote, conflicts }
+ */
+async function computeSyncDiff(projectId, folder, sync) {
+  const localFiles = listLocalFiles(folder);
+  const { byFileName, byId } = buildIndexes(sync.tasks);
+
+  // Get ALL tasks from server (no mcpLastSyncDate filter) to detect deletions
+  const statusData = await api.status(projectId);
+  const remoteTasks = statusData.tasks || [];
+  const remoteIdSet = new Set(remoteTasks.map((t) => t._id.toString()));
+
+  // --- Local changes (would be pushed) ---
+  const wouldPush = [];
+  const localMtimes = {};
+
+  for (const fname of localFiles) {
+    const filePath = join(folder, fname);
+    const mtimeMs = Math.floor(getFileMtimeMs(filePath));
+    localMtimes[fname] = mtimeMs;
+
+    if (fname in byFileName) {
+      const task = sync.tasks[byFileName[fname]];
+      const lastKnownMtime = task.mcpLastLocalUpdate;
+      let isModified = false;
+      if (task._id == null) {
+        isModified = true; // new task
+      } else if (lastKnownMtime != null) {
+        isModified = mtimeMs > lastKnownMtime;
+      } else if (sync.mcpLastSyncDate == null || mtimeMs > sync.mcpLastSyncDate) {
+        isModified = true;
+      }
+      if (isModified) {
+        wouldPush.push({ name: toTaskName(fname), fileName: fname, _id: task._id });
+      }
+    } else {
+      // New local file — will be created on server
+      wouldPush.push({ name: toTaskName(fname), fileName: fname, _id: null });
+    }
+  }
+
+  // --- Remote changes (would be pulled) ---
+  const wouldPull = [];
+  for (const rt of remoteTasks) {
+    if (
+      rt.mcpSyncDate &&
+      sync.mcpLastSyncDate &&
+      new Date(rt.mcpSyncDate).getTime() > sync.mcpLastSyncDate
+    ) {
+      wouldPull.push({ name: rt.name, _id: rt._id.toString() });
+    } else if (!sync.mcpLastSyncDate) {
+      // First sync — pull everything not already local
+      const fname = toFileName(rt.name);
+      if (fname && !(fname in byFileName)) {
+        wouldPull.push({ name: rt.name, _id: rt._id.toString() });
+      }
+    }
+  }
+
+  // --- Detect deletions ---
+  const localFileSet = new Set(localFiles);
+
+  // Tasks in sync state that have an _id but are no longer on the server → deleted remotely
+  const wouldDeleteLocal = [];
+  for (const task of sync.tasks) {
+    if (task._id && !remoteIdSet.has(task._id.toString())) {
+      wouldDeleteLocal.push({ name: task.name, fileName: task.fileName, _id: task._id });
+    }
+  }
+
+  // Tasks in sync state that have an _id and fileName but the local file is gone → deleted locally
+  const wouldDeleteRemote = [];
+  for (const task of sync.tasks) {
+    if (task._id && task.fileName && !localFileSet.has(task.fileName)) {
+      // Only if the task still exists on server
+      if (remoteIdSet.has(task._id.toString())) {
+        wouldDeleteRemote.push({ name: task.name, fileName: task.fileName, _id: task._id });
+      }
+    }
+  }
+
+  // --- Conflicts ---
+  const conflicts = [];
+  const pushNames = new Set(wouldPush.map((p) => p.name));
+  for (const pull of wouldPull) {
+    if (pushNames.has(pull.name)) {
+      conflicts.push({
+        name: pull.name,
+        localMtime: localMtimes[toFileName(pull.name)]
+          ? new Date(localMtimes[toFileName(pull.name)]).toISOString()
+          : 'unknown',
+      });
+    }
+  }
+
+  return { wouldPush, wouldPull, wouldDeleteLocal, wouldDeleteRemote, conflicts };
+}
+
+/**
+ * Execute sync for a single project folder.
+ */
+async function executeSync(projectId, folder, sync) {
+  const localFiles = listLocalFiles(folder);
+  const prePullSyncDate = sync.mcpLastSyncDate;
+  const results = [];
+
+  // Get ALL tasks to detect deletions
+  const allStatusData = await api.status(projectId);
+  const allRemoteTasks = allStatusData.tasks || [];
+  const remoteIdSet = new Set(allRemoteTasks.map((t) => t._id.toString()));
+
+  // --- DELETE phase (remote → local): remove local files for tasks deleted on server ---
+  const localFileSet = new Set(localFiles);
+  let deletedLocalCount = 0;
+  const tasksToRemoveFromState = [];
+
+  for (const task of sync.tasks) {
+    if (task._id && !remoteIdSet.has(task._id.toString())) {
+      // Task was deleted on server — remove local file
+      if (task.fileName && deleteLocalFile(folder, task.fileName)) {
+        deletedLocalCount++;
+      }
+      tasksToRemoveFromState.push(task._id);
+    }
+  }
+
+  // Remove deleted tasks from sync state
+  if (tasksToRemoveFromState.length > 0) {
+    const removeSet = new Set(tasksToRemoveFromState.map((id) => id.toString()));
+    sync.tasks = sync.tasks.filter((t) => !t._id || !removeSet.has(t._id.toString()));
+  }
+
+  if (deletedLocalCount > 0) {
+    results.push(`Deleted locally: ${deletedLocalCount} file(s) (removed on server)`);
+  }
+
+  // --- DELETE phase (local → remote): delete tasks on server for locally deleted files ---
+  const currentLocalFiles = new Set(listLocalFiles(folder));
+  const toDeleteRemote = [];
+
+  for (const task of sync.tasks) {
+    if (task._id && task.fileName && !currentLocalFiles.has(task.fileName)) {
+      if (remoteIdSet.has(task._id.toString())) {
+        toDeleteRemote.push({ _id: task._id, name: task.name, deleted: true });
+      }
+    }
+  }
+
+  if (toDeleteRemote.length > 0) {
+    const deleteResponse = await api.push(projectId, toDeleteRemote);
+    const deletedRemote = (deleteResponse.tasks || []).filter((t) => t.deleted);
+    // Remove deleted tasks from sync state
+    const deletedIds = new Set(deletedRemote.map((t) => t._id.toString()));
+    sync.tasks = sync.tasks.filter((t) => !t._id || !deletedIds.has(t._id.toString()));
+    results.push(`Deleted remotely: ${deletedRemote.length} task(s) (removed locally)`);
+  }
+
+  // --- PULL phase ---
+  const pullData = await api.pull(projectId, prePullSyncDate);
+  const pulledTasks = pullData.tasks || [];
+
+  const { byId } = buildIndexes(sync.tasks);
+  const pulledNames = [];
+
+  for (const pt of pulledTasks) {
+    const fileName = toFileName(pt.name);
+    const fileContent = descriptionToMarkdown(pt.description);
+
+    const entry = {
+      _id: pt._id,
+      mcpSyncDate: pt.mcpSyncDate || null,
+      fileName,
+      name: pt.name,
+      mcpLastLocalUpdate: null,
+    };
+
+    if (pt._id in byId) {
+      sync.tasks[byId[pt._id]] = entry;
+    } else {
+      sync.tasks.push(entry);
+    }
+    pulledNames.push(pt.name);
+
+    if (fileName) {
+      writeFileSync(join(folder, fileName), fileContent);
+    }
+  }
+
+  sync.mcpLastSyncPullChanges = pulledNames;
+  results.push(`Pulled: ${pulledTasks.length} task(s)`);
+  if (pulledNames.length > 0) {
+    pulledNames.forEach((n) => results.push(`  - ${n}`));
+  }
+
+  // --- PUSH phase ---
+  const { byFileName: fnIdx2 } = buildIndexes(sync.tasks);
+  const refreshedFiles = listLocalFiles(folder);
+
+  for (const fname of refreshedFiles) {
+    const filePath = join(folder, fname);
+    const mtimeMs = Math.floor(getFileMtimeMs(filePath));
+
+    if (fname in fnIdx2) {
+      sync.tasks[fnIdx2[fname]].mcpLastLocalUpdate = mtimeMs;
+    } else {
+      sync.tasks.push({
+        _id: null,
+        mcpSyncDate: null,
+        fileName: fname,
+        name: toTaskName(fname),
+        mcpLastLocalUpdate: mtimeMs,
+      });
+    }
+  }
+
+  const tasksToPush = sync.tasks.filter((t) => {
+    if (t.mcpLastLocalUpdate == null) return false;
+    if (t._id == null) return true;
+    if (prePullSyncDate == null) return true;
+    return t.mcpLastLocalUpdate > prePullSyncDate;
+  });
+
+  if (tasksToPush.length === 0) {
+    results.push('Pushed: 0 task(s) (no local changes)');
+  } else {
+    const pushItems = [];
+    for (const t of tasksToPush) {
+      if (!t.fileName) continue;
+      const filePath = join(folder, t.fileName);
+      const content = existsSync(filePath)
+        ? readFileSync(filePath, 'utf-8')
+        : null;
+      const description = content
+        ? JSON.stringify(markdownToBlockNote(content))
+        : null;
+
+      pushItems.push({
+        _id: t._id,
+        name: toTaskName(t.fileName),
+        description,
+      });
+    }
+
+    const pushResponse = await api.push(projectId, pushItems);
+    const responseTasks = (pushResponse.tasks || []).filter((t) => !t.deleted);
+
+    const { byId: pushIdIdx, byFileName: pushFnIdx } = buildIndexes(sync.tasks);
+    const pushedNames = [];
+
+    for (const rt of responseTasks) {
+      pushedNames.push(rt.name);
+      const rtFileName = toFileName(rt.name);
+
+      if (rt._id in pushIdIdx) {
+        const idx = pushIdIdx[rt._id];
+        sync.tasks[idx].mcpSyncDate = rt.mcpSyncDate;
+        sync.tasks[idx].name = rt.name;
+        if (rtFileName) sync.tasks[idx].fileName = rtFileName;
+      } else if (rtFileName && rtFileName in pushFnIdx) {
+        const idx = pushFnIdx[rtFileName];
+        sync.tasks[idx]._id = rt._id;
+        sync.tasks[idx].mcpSyncDate = rt.mcpSyncDate;
+        sync.tasks[idx].name = rt.name;
+        sync.tasks[idx].fileName = rtFileName;
+      }
+    }
+
+    sync.mcpLastSyncPushChanges = pushedNames;
+    results.push(`Pushed: ${responseTasks.length} task(s)`);
+    if (pushedNames.length > 0) {
+      pushedNames.forEach((n) => results.push(`  - ${n}`));
+    }
+
+    const errors = pushResponse.errors || [];
+    if (errors.length > 0) {
+      results.push(
+        `${errors.length} push error(s):`,
+        ...errors.map((e) => `  - Task ${e._id || e.index}: ${e.reason}`)
+      );
+    }
+  }
+
+  sync.mcpLastSyncDate = Date.now();
+  writeSyncState(folder, sync);
+
+  return results;
+}
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: 'planko-mcp-server',
+  version: '0.2.0',
+});
+
+// ---- planko_setup ----
+server.tool(
+  'planko_setup',
+  'Set up sync between a Planko project and a local folder. Supports multiple project-folder mappings. The user must provide the project name, local folder path, and email.',
+  {
+    projectName: z.string().describe('Name of the Planko project to sync'),
+    folderPath: z.string().describe('Absolute path to the local folder for .md task files'),
+    email: z.string().email().describe('User email for task attribution'),
+  },
+  async ({ projectName, folderPath, email }) => {
+    try {
+      // List user's projects to find the matching one
+      const { projects } = await api.projects();
+
+      const match = projects.find(
+        (p) => p.name.toLowerCase() === projectName.toLowerCase()
+      );
+
+      if (!match) {
+        const available = projects.map((p) => `  - ${p.name}`).join('\n');
+        return toolError(
+          `Project "${projectName}" not found.\n\nAvailable projects:\n${available}`
+        );
+      }
+
+      // Ensure folder exists
+      if (!existsSync(folderPath)) {
+        mkdirSync(folderPath, { recursive: true });
+      }
+
+      // Save to global config
+      const config = readConfig();
+      config.projects = config.projects || {};
+      config.projects[match.name] = {
+        projectId: match._id,
+        folder: folderPath,
+        email,
+        isWorkspace: match.isWorkspace,
+      };
+      writeConfig(config);
+
+      // Initialize sync state for this folder
+      const syncState = createSyncState(match._id, match.name);
+      writeSyncState(folderPath, syncState);
+
+      return toolOk(
+        `Setup complete for project "${match.name}".\n` +
+          `  Project ID: ${match._id}\n` +
+          `  Folder: ${folderPath}\n` +
+          `  Email: ${email}\n` +
+          `  Workspace: ${match.isWorkspace ? 'Yes' : 'No (personal)'}\n\n` +
+          `Run planko_sync to pull tasks into this folder.`
+      );
+    } catch (err) {
+      return toolError(`Setup failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_sync_preview ----
+server.tool(
+  'planko_sync_preview',
+  'Preview what would be synced (read-only, no writes). Shows files that would be pushed, pulled, deleted, and any conflicts. If projectName is omitted, previews all configured projects.',
+  {
+    projectName: z.string().optional().describe('Project name to preview (optional — omit to preview all)'),
+  },
+  async ({ projectName }) => {
+    try {
+      const config = readConfig();
+      const projectEntries = config.projects || {};
+
+      if (Object.keys(projectEntries).length === 0) {
+        return toolError('No projects configured. Run planko_setup first.');
+      }
+
+      // Filter to specific project or all
+      let targets;
+      if (projectName) {
+        const key = Object.keys(projectEntries).find(
+          (k) => k.toLowerCase() === projectName.toLowerCase()
+        );
+        if (!key) {
+          const available = Object.keys(projectEntries).map((k) => `  - ${k}`).join('\n');
+          return toolError(
+            `Project "${projectName}" not configured.\n\nConfigured projects:\n${available}`
+          );
+        }
+        targets = [{ name: key, ...projectEntries[key] }];
+      } else {
+        targets = Object.entries(projectEntries).map(([name, cfg]) => ({ name, ...cfg }));
+      }
+
+      const allLines = ['Sync Preview (read-only, no changes made)', ''];
+
+      for (const target of targets) {
+        const sync = readSyncState(target.folder);
+        if (!sync) {
+          allLines.push(`--- ${target.name} ---`);
+          allLines.push('No sync state found. Run planko_sync to initialize.', '');
+          continue;
+        }
+
+        let diff;
+        try {
+          diff = await computeSyncDiff(target.projectId, target.folder, sync);
+        } catch (err) {
+          allLines.push(`--- ${target.name} ---`);
+          allLines.push(`Error: ${err.message}`, '');
+          continue;
+        }
+
+        allLines.push(`--- ${target.name} (${target.folder}) ---`);
+        allLines.push('');
+        allLines.push(`Would push: ${diff.wouldPush.length} task(s)`);
+        diff.wouldPush.forEach((p) => allLines.push(`  - ${p.name}${p._id ? '' : ' (new)'}`));
+
+        allLines.push(`Would pull: ${diff.wouldPull.length} task(s)`);
+        diff.wouldPull.forEach((p) => allLines.push(`  - ${p.name}`));
+
+        allLines.push(`Would delete locally: ${diff.wouldDeleteLocal.length} file(s) (removed on server)`);
+        diff.wouldDeleteLocal.forEach((d) => allLines.push(`  - ${d.name}`));
+
+        allLines.push(`Would delete remotely: ${diff.wouldDeleteRemote.length} task(s) (removed locally)`);
+        diff.wouldDeleteRemote.forEach((d) => allLines.push(`  - ${d.name}`));
+
+        if (diff.conflicts.length > 0) {
+          allLines.push('');
+          allLines.push(`Conflicts: ${diff.conflicts.length} (modified both locally and remotely)`);
+          diff.conflicts.forEach((c) => allLines.push(`  - ${c.name} (local: ${c.localMtime})`));
+          allLines.push('Note: sync uses pull-then-push order — local changes overwrite remote on conflict.');
+        }
+
+        allLines.push('');
+      }
+
+      return toolOk(allLines.join('\n'));
+    } catch (err) {
+      return toolError(`Sync preview failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_sync ----
+server.tool(
+  'planko_sync',
+  'Execute bidirectional sync with delete support: deletes, then pulls remote changes, then pushes local changes. If projectName is omitted, syncs all configured projects.',
+  {
+    projectName: z.string().optional().describe('Project name to sync (optional — omit to sync all)'),
+  },
+  async ({ projectName }) => {
+    try {
+      const config = readConfig();
+      const projectEntries = config.projects || {};
+
+      if (Object.keys(projectEntries).length === 0) {
+        return toolError('No projects configured. Run planko_setup first.');
+      }
+
+      // Filter to specific project or all
+      let targets;
+      if (projectName) {
+        const key = Object.keys(projectEntries).find(
+          (k) => k.toLowerCase() === projectName.toLowerCase()
+        );
+        if (!key) {
+          const available = Object.keys(projectEntries).map((k) => `  - ${k}`).join('\n');
+          return toolError(
+            `Project "${projectName}" not configured.\n\nConfigured projects:\n${available}`
+          );
+        }
+        targets = [{ name: key, ...projectEntries[key] }];
+      } else {
+        targets = Object.entries(projectEntries).map(([name, cfg]) => ({ name, ...cfg }));
+      }
+
+      const allResults = [];
+
+      for (const target of targets) {
+        let sync = readSyncState(target.folder);
+        if (!sync) {
+          sync = createSyncState(target.projectId, target.name);
+        }
+
+        allResults.push(`--- ${target.name} (${target.folder}) ---`);
+
+        try {
+          const results = await executeSync(target.projectId, target.folder, sync);
+          allResults.push(...results);
+        } catch (err) {
+          allResults.push(`Error: ${err.message}`);
+        }
+        allResults.push('');
+      }
+
+      return toolOk('Sync complete.\n\n' + allResults.join('\n'));
+    } catch (err) {
+      return toolError(`Sync failed: ${err.message}`);
+    }
+  }
+);
+
+// --- Start server ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "planko-mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for syncing Planko tasks with local Markdown files",
+  "type": "module",
+  "bin": {
+    "planko-mcp-server": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "prepublishOnly": "node --check index.js && node --check src/api.js && node --check src/converters.js && node --check src/sync-state.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  },
+  "keywords": [
+    "planko",
+    "mcp",
+    "model-context-protocol",
+    "task-sync",
+    "markdown"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/planko-io/planko-mcp-server"
+  }
+}

package/src/api.js

@@ -0,0 +1,85 @@
+/**
+ * API client for Planko MCP Project Sync endpoints.
+ * Uses native fetch (Node 18+).
+ *
+ * All external endpoints require projectId (user-scoped API key, PL012).
+ */
+
+const DEFAULT_API_BASE = 'https://planko-426622.ue.r.appspot.com/v1';
+
+export function createApiClient({ apiKey, apiBase }) {
+  const base = apiBase || process.env.PLANKO_API_BASE || DEFAULT_API_BASE;
+
+  async function request(method, path, body) {
+    const url = `${base}${path}`;
+    const headers = { 'x-api-key': apiKey };
+
+    const options = { method, headers };
+
+    if (body) {
+      headers['Content-Type'] = 'application/json';
+      options.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(url, options);
+    const text = await res.text();
+
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+
+    if (!res.ok) {
+      const msg =
+        typeof data === 'object' && data.message
+          ? data.message
+          : `API returned HTTP ${res.status}`;
+      throw new Error(msg);
+    }
+
+    return data;
+  }
+
+  return {
+    /**
+     * GET /mcp-project-sync/projects — list all projects accessible by the user
+     */
+    async projects() {
+      return request('GET', '/mcp-project-sync/projects');
+    },
+
+    /**
+     * GET /mcp-project-sync/status?projectId=...&mcpLastSyncDate=...
+     */
+    async status(projectId, mcpLastSyncDate) {
+      let qs = `projectId=${projectId}`;
+      if (mcpLastSyncDate != null) {
+        qs += `&mcpLastSyncDate=${mcpLastSyncDate}`;
+      }
+      return request('GET', `/mcp-project-sync/status?${qs}`);
+    },
+
+    /**
+     * GET /mcp-project-sync/pull?projectId=...&mcpLastSyncDate=...
+     */
+    async pull(projectId, mcpLastSyncDate) {
+      let qs = `projectId=${projectId}`;
+      if (mcpLastSyncDate != null) {
+        qs += `&mcpLastSyncDate=${mcpLastSyncDate}`;
+      }
+      return request('GET', `/mcp-project-sync/pull?${qs}`);
+    },
+
+    /**
+     * POST /mcp-project-sync/push
+     */
+    async push(projectId, tasks) {
+      return request('POST', '/mcp-project-sync/push', {
+        projectId,
+        tasks,
+      });
+    },
+  };
+}

package/src/converters.js

@@ -0,0 +1,330 @@
+/**
+ * BlockNote <-> Markdown converters.
+ *
+ * Key fix from POC: markdownToBlockNote handles indented lines as nested
+ * children instead of flattening them into top-level paragraphs.
+ */
+
+// --- HTML entity decoding and tag conversion ---
+
+const HTML_ENTITIES = {
+  '&lt;': '<',
+  '&gt;': '>',
+  '&amp;': '&',
+  '&quot;': '"',
+  '&#39;': "'",
+  '&apos;': "'",
+  '&nbsp;': ' ',
+};
+
+function decodeHtmlEntities(text) {
+  return text.replace(/&(?:lt|gt|amp|quot|#39|apos|nbsp);/g, (match) => HTML_ENTITIES[match] || match);
+}
+
+/**
+ * Convert HTML tags embedded in BlockNote text content to Markdown.
+ * Handles common tags: h1-h6, p, strong, em, code, a, br, ul/ol/li, table.
+ */
+function htmlToMarkdown(html) {
+  let md = html;
+
+  // Headings
+  md = md.replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h[1-6]>/gi, (_, level, content) => {
+    return '#'.repeat(Number(level)) + ' ' + content.trim();
+  });
+
+  // Bold
+  md = md.replace(/<strong[^>]*>([\s\S]*?)<\/strong>/gi, '**$1**');
+  md = md.replace(/<b[^>]*>([\s\S]*?)<\/b>/gi, '**$1**');
+
+  // Italic
+  md = md.replace(/<em[^>]*>([\s\S]*?)<\/em>/gi, '*$1*');
+  md = md.replace(/<i[^>]*>([\s\S]*?)<\/i>/gi, '*$1*');
+
+  // Code
+  md = md.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, '`$1`');
+
+  // Links
+  md = md.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, '[$2]($1)');
+
+  // Line breaks
+  md = md.replace(/<br\s*\/?>/gi, '\n');
+
+  // List items
+  md = md.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, '- $1');
+
+  // Table conversion (basic)
+  md = md.replace(/<thead>([\s\S]*?)<\/thead>/gi, (_, content) => {
+    const headers = [];
+    content.replace(/<th[^>]*>([\s\S]*?)<\/th>/gi, (_, cell) => {
+      headers.push(cell.trim());
+    });
+    if (headers.length === 0) return '';
+    return '| ' + headers.join(' | ') + ' |\n| ' + headers.map(() => '---').join(' | ') + ' |';
+  });
+  md = md.replace(/<tr[^>]*>([\s\S]*?)<\/tr>/gi, (_, content) => {
+    const cells = [];
+    content.replace(/<td[^>]*>([\s\S]*?)<\/td>/gi, (_, cell) => {
+      cells.push(cell.trim());
+    });
+    if (cells.length === 0) return '';
+    return '\n| ' + cells.join(' | ') + ' |';
+  });
+
+  // Strip remaining tags
+  md = md.replace(/<\/?(?:p|div|span|ul|ol|table|tbody|thead|tr|th|td|section|article|header|footer|nav|main|aside|figure|figcaption|blockquote)[^>]*>/gi, '');
+
+  return md.trim();
+}
+
+/**
+ * Check if text contains HTML tags (after entity decoding).
+ */
+function containsHtmlTags(text) {
+  return /<[a-z][a-z0-9]*[\s>\/]/i.test(text);
+}
+
+// --- BlockNote -> Markdown ---
+
+export function inlineToMarkdown(content) {
+  if (!content || !Array.isArray(content)) return '';
+  return content
+    .map((item) => {
+      let text = item.text || '';
+      if (!text) return '';
+
+      // Decode HTML entities first
+      text = decodeHtmlEntities(text);
+
+      // If text contains HTML tags, convert them to Markdown
+      if (containsHtmlTags(text)) {
+        text = htmlToMarkdown(text);
+      }
+
+      const s = item.styles || {};
+      if (s.code) text = `\`${text}\``;
+      if (s.strikethrough) text = `~~${text}~~`;
+      if (s.italic) text = `*${text}*`;
+      if (s.bold) text = `**${text}**`;
+      return text;
+    })
+    .join('');
+}
+
+export function blockNoteToMarkdown(blocks, indent = 0) {
+  if (!blocks || !Array.isArray(blocks)) return '';
+  const prefix = '  '.repeat(indent);
+  const lines = [];
+
+  for (const block of blocks) {
+    const text = inlineToMarkdown(block.content);
+
+    switch (block.type) {
+      case 'heading': {
+        const level = block.props?.level || 1;
+        lines.push(`${prefix}${'#'.repeat(level)} ${text}`);
+        break;
+      }
+      case 'bulletListItem':
+        lines.push(`${prefix}- ${text}`);
+        break;
+      case 'numberedListItem':
+        lines.push(`${prefix}1. ${text}`);
+        break;
+      case 'checkListItem': {
+        const checked = block.props?.checked ? 'x' : ' ';
+        lines.push(`${prefix}- [${checked}] ${text}`);
+        break;
+      }
+      case 'paragraph':
+      default:
+        lines.push(`${prefix}${text}`);
+        break;
+    }
+
+    if (block.children && block.children.length > 0) {
+      const childMd = blockNoteToMarkdown(block.children, indent + 1);
+      lines.push(childMd);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// --- Markdown -> BlockNote ---
+
+export function parseInlineMarkdown(text) {
+  const content = [];
+  // Order: bold (**), italic (*), strikethrough (~~), code (`)
+  const regex = /(\*\*(.+?)\*\*|\*(.+?)\*|~~(.+?)~~|`(.+?)`|([^*~`]+))/g;
+  let match;
+  while ((match = regex.exec(text)) !== null) {
+    if (match[2]) {
+      content.push({ type: 'text', text: match[2], styles: { bold: true } });
+    } else if (match[3]) {
+      content.push({ type: 'text', text: match[3], styles: { italic: true } });
+    } else if (match[4]) {
+      content.push({
+        type: 'text',
+        text: match[4],
+        styles: { strikethrough: true },
+      });
+    } else if (match[5]) {
+      content.push({ type: 'text', text: match[5], styles: { code: true } });
+    } else if (match[6]) {
+      content.push({ type: 'text', text: match[6], styles: {} });
+    }
+  }
+  return content.length > 0 ? content : [{ type: 'text', text, styles: {} }];
+}
+
+function makeBlock(type, text, props = {}) {
+  return {
+    type,
+    props: {
+      backgroundColor: 'default',
+      textColor: 'default',
+      textAlignment: 'left',
+      ...props,
+    },
+    content: parseInlineMarkdown(text),
+    children: [],
+  };
+}
+
+/**
+ * Determine the indentation level of a line (number of 2-space indents).
+ */
+function indentLevel(line) {
+  const match = line.match(/^( *)/);
+  if (!match) return 0;
+  return Math.floor(match[1].length / 2);
+}
+
+/**
+ * Parse a trimmed line into a block (without children).
+ */
+function parseLine(trimmed) {
+  const headingMatch = trimmed.match(/^(#{1,6})\s+(.*)$/);
+  if (headingMatch) {
+    return makeBlock('heading', headingMatch[2], {
+      level: headingMatch[1].length,
+      isToggleable: false,
+    });
+  }
+
+  const checkMatch = trimmed.match(/^-\s+\[([ xX])\]\s+(.*)$/);
+  if (checkMatch) {
+    return makeBlock('checkListItem', checkMatch[2], {
+      checked: checkMatch[1] !== ' ',
+    });
+  }
+
+  const bulletMatch = trimmed.match(/^-\s+(.*)$/);
+  if (bulletMatch) {
+    return makeBlock('bulletListItem', bulletMatch[1]);
+  }
+
+  const numberedMatch = trimmed.match(/^\d+\.\s+(.*)$/);
+  if (numberedMatch) {
+    return makeBlock('numberedListItem', numberedMatch[1]);
+  }
+
+  return makeBlock('paragraph', trimmed);
+}
+
+/**
+ * Convert markdown string to BlockNote blocks, preserving nesting.
+ *
+ * Indented lines (2-space increments) become children of the preceding
+ * block at the parent indent level. This fixes the POC which flattened
+ * all lines into top-level blocks.
+ */
+export function markdownToBlockNote(md) {
+  if (!md) return [];
+  const lines = md.split('\n');
+
+  // Recursive helper: parse lines[start..end) at the given base indent level.
+  function parseRange(start, end, baseIndent) {
+    const blocks = [];
+    let i = start;
+
+    while (i < end) {
+      const line = lines[i];
+      const level = indentLevel(line);
+      const trimmed = line.trimStart();
+
+      if (trimmed === '') {
+        // Empty lines become empty paragraphs at base level
+        blocks.push(makeBlock('paragraph', ''));
+        i++;
+        continue;
+      }
+
+      if (level < baseIndent) {
+        // Shouldn't happen in well-formed input, but handle gracefully
+        break;
+      }
+
+      if (level > baseIndent) {
+        // This line is indented deeper than expected — attach as children
+        // of the last block at baseIndent level.
+        const childStart = i;
+        while (i < end) {
+          const currentTrimmed = lines[i].trim();
+          const currentLevel = currentTrimmed === '' ? -1 : indentLevel(lines[i]);
+
+          if (currentTrimmed === '') {
+            // Blank line: look ahead to determine if nesting continues
+            let nextNonBlank = i + 1;
+            while (nextNonBlank < end && lines[nextNonBlank].trim() === '') nextNonBlank++;
+            if (nextNonBlank >= end || indentLevel(lines[nextNonBlank]) <= baseIndent) {
+              break; // blank line(s) followed by non-indented or EOF = end of nesting
+            }
+            i++; // blank line within nested content — include it
+          } else if (currentLevel <= baseIndent) {
+            break; // back to parent level
+          } else {
+            i++;
+          }
+        }
+
+        if (blocks.length > 0) {
+          blocks[blocks.length - 1].children = parseRange(childStart, i, baseIndent + 1);
+        } else {
+          // No parent block — create blocks at the deeper level as top-level
+          const deeper = parseRange(childStart, i, level);
+          blocks.push(...deeper);
+        }
+        continue;
+      }
+
+      // level === baseIndent
+      blocks.push(parseLine(trimmed));
+      i++;
+    }
+
+    return blocks;
+  }
+
+  return parseRange(0, lines.length, 0);
+}
+
+// --- Convenience helpers ---
+
+export function descriptionToMarkdown(description) {
+  if (!description) return '';
+  try {
+    const blocks =
+      typeof description === 'string' ? JSON.parse(description) : description;
+    return blockNoteToMarkdown(blocks);
+  } catch (_) {
+    return typeof description === 'string' ? description : '';
+  }
+}
+
+export function markdownToDescription(md) {
+  if (!md) return null;
+  const blocks = markdownToBlockNote(md);
+  return JSON.stringify(blocks);
+}

package/src/sync-state.js

@@ -0,0 +1,128 @@
+/**
+ * Sync state management for planko-mcp-server.
+ *
+ * Two types of state:
+ * 1. Global config (~/.planko-mcp/config.json) — maps project names to folders
+ * 2. Per-folder sync state (planko-mcp-sync.json) — task mappings and timestamps
+ *
+ * Credentials are NEVER written to any state file.
+ * Task names are stored WITHOUT the .md extension.
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync, mkdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const SYNC_FILE = '.planko-mcp-sync.json';
+export const CONFIG_DIR = join(homedir(), '.planko-mcp');
+export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const IGNORED_FILES = ['.DS_Store', 'Thumbs.db', '.gitkeep'];
+
+export function isIgnoredFile(filename) {
+  return IGNORED_FILES.includes(filename) || filename.startsWith('.');
+}
+
+// --- File name / task name conversion ---
+
+export function toFileName(name) {
+  if (!name) return null;
+  return name.endsWith('.md') ? name : `${name}.md`;
+}
+
+export function toTaskName(fileName) {
+  if (!fileName) return null;
+  return fileName.endsWith('.md') ? fileName.slice(0, -3) : fileName;
+}
+
+// --- Global config (multi-folder) ---
+
+export function readConfig() {
+  if (!existsSync(CONFIG_FILE)) return { projects: {} };
+  try {
+    const raw = JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    // Strip any accidentally-stored credentials
+    delete raw.apiKey;
+    return raw;
+  } catch {
+    return { projects: {} };
+  }
+}
+
+export function writeConfig(config) {
+  const safe = { ...config };
+  delete safe.apiKey;
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(safe, null, 2));
+}
+
+// --- Per-folder sync state ---
+
+export function readSyncState(folder) {
+  const syncPath = join(folder, SYNC_FILE);
+  if (!existsSync(syncPath)) return null;
+  const raw = JSON.parse(readFileSync(syncPath, 'utf-8'));
+  delete raw.apiKey;
+  delete raw.userEmail;
+  return raw;
+}
+
+export function writeSyncState(folder, data) {
+  const safe = { ...data };
+  delete safe.apiKey;
+  delete safe.apiSecret;
+  delete safe.password;
+  delete safe.userEmail;
+  writeFileSync(join(folder, SYNC_FILE), JSON.stringify(safe, null, 2));
+}
+
+export function createSyncState(projectId, projectName) {
+  return {
+    project: {
+      _id: projectId,
+      name: projectName,
+    },
+    mcpLastSyncDate: null,
+    mcpLastSyncPullChanges: [],
+    mcpLastSyncPushChanges: [],
+    tasks: [],
+  };
+}
+
+// --- Local file operations ---
+
+export function listLocalFiles(folder) {
+  if (!existsSync(folder)) return [];
+  return readdirSync(folder).filter((f) => {
+    if (f === SYNC_FILE) return false;
+    if (isIgnoredFile(f)) return false;
+    const fullPath = join(folder, f);
+    return statSync(fullPath).isFile() && f.endsWith('.md');
+  });
+}
+
+export function getFileMtimeMs(filePath) {
+  return statSync(filePath).mtimeMs;
+}
+
+export function deleteLocalFile(folder, fileName) {
+  const filePath = join(folder, fileName);
+  if (existsSync(filePath)) {
+    unlinkSync(filePath);
+    return true;
+  }
+  return false;
+}
+
+// --- Index helpers ---
+
+export function buildIndexes(tasks) {
+  const byId = {};
+  const byFileName = {};
+  tasks.forEach((t, i) => {
+    if (t._id) byId[t._id] = i;
+    if (t.fileName) byFileName[t.fileName] = i;
+  });
+  return { byId, byFileName };
+}