planko-mcp-server 0.2.1 → 0.4.0

package/README.md

@@ -4,10 +4,13 @@ MCP server for syncing [Planko](https://planko.io) tasks with local Markdown fil
 
 ## Features
 
-- **3 tools**: setup, sync preview, sync
+- **14 tools**: 3 folder-sync tools + 7 standalone task/note CRUD tools + 4 standalone read (list/view) tools
+- **Type-aware sync**: each folder syncs either **tasks** (type=1) or **notes** (type=2), chosen at setup
 - **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
+- **Standalone CRUD**: create/edit/complete/delete tasks and notes directly, no folder setup required
+- **Standalone read**: list and view tasks/notes with rich filters, no folder setup required
 - **User-scoped API key**: one key works across all your projects
 
 ## Getting Started
@@ -64,10 +67,15 @@ Restart Claude Code, Cursor, or whichever MCP client you use so it picks up the
 Ask your AI agent to run:
 
 ```
-planko_setup(projectName: "My Project", folderPath: "/path/to/folder", email: "you@email.com")
+planko_setup(projectName: "My Project", folderPath: "/path/to/folder", email: "you@email.com", syncType: "tasks")
 ```
 
-This maps a Planko project to a local folder. You can set up multiple projects pointing to different folders.
+This maps a Planko project to a local folder. `syncType` is **required** and must be `"tasks"` or `"notes"`:
+
+- `syncType: "tasks"` — the folder pulls/pushes only **tasks** (type=1). New local `.md` files are created as tasks.
+- `syncType: "notes"` — the folder pulls/pushes only **notes** (type=2). New local `.md` files are created as notes.
+
+A folder is bound to one type for its whole lifetime. To sync both tasks and notes for the same project, set up two folders. You can set up multiple projects pointing to different folders.
 
 ### Step 5 — Sync
 
@@ -79,12 +87,108 @@ Tasks are pulled as `.md` files into your folder. Local changes are pushed back
 
 ## Tools
 
+The server exposes 14 tools in three groups: **folder-sync** tools (bind a project to a local folder), **standalone CRUD** tools (create/edit/complete/delete directly via your API key, no folder needed), and **standalone read** tools (list/view directly via your API key, no folder needed).
+
+### Folder-sync tools
+
 | Tool | Description | Parameters |
 |---|---|---|
-| `planko_setup` | Set up sync between a project and a local folder | `projectName`, `folderPath`, `email` |
+| `planko_setup` | Set up sync between a project and a local folder | `projectName`, `folderPath`, `email`, `syncType` (`tasks`\|`notes`) |
 | `planko_sync_preview` | Preview what would be synced (read-only) | `projectName` (optional) |
 | `planko_sync` | Execute bidirectional sync with delete support | `projectName` (optional) |
 
+### Standalone CRUD tools
+
+These work with the **same API key** and require **no folder setup**. Notes are Planko tasks with `type=2`; tasks are `type=1`. They live in the same collection, so edit/delete work on both. `create_*` tools accept all task/note properties as optional params (only `name` is required); the Markdown `description` is converted to Planko's rich-text (BlockNote) format automatically.
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `planko_create_task` | Create a task (type=1) | `name` (required), `projectName` (optional), plus any properties below |
+| `planko_create_note` | Create a note (type=2) | `name` (required), `projectName` (optional), plus any properties below |
+| `planko_edit_task` | Edit an existing task by id | `taskId` (required), plus any properties to change |
+| `planko_edit_note` | Edit an existing note by id (shares the task edit endpoint) | `taskId` (required), plus any properties to change |
+| `planko_complete_task` | Mark a task complete (status=2) | `taskId` (required) |
+| `planko_delete_task` | Delete a task by id | `taskId` (required) |
+| `planko_delete_note` | Delete a note by id (shares the task delete endpoint) | `taskId` (required) |
+
+**Optional properties** accepted by the create/edit tools (all optional; omit to leave unchanged):
+
+| Property | Type | Notes |
+|---|---|---|
+| `description` | Markdown string | Converted to BlockNote JSON before saving |
+| `dueDate` | ISO 8601 string | |
+| `datePlain` | `YYYY-MM-DD` | |
+| `time` / `endTime` | `HH:MM` | Start / end time |
+| `alert` | boolean | Whether a reminder is enabled |
+| `alertLeadTime` | `null`\|`ontime`\|`15min`\|`30min`\|`1hour`\|`1day` | Reminder lead time |
+| `priority` | `1`\|`2`\|`3` | |
+| `repeat` | `null`\|`daily`\|`workdays`\|`weekly`\|`biweekly`\|`monthly`\|`custom_weekly`\|`yearly` | Recurrence rule |
+| `repeatDate` | ISO 8601 string | Recurrence anchor/end |
+| `selectedWeekdays` | array of `0`–`6` | For `custom_weekly` (0=Sunday) |
+| `parentId` | ObjectId | Parent task, for subtasks |
+| `tags` | array of ObjectId | Tag ids |
+| `kanbanColumnId` / `boardId` | ObjectId | Kanban placement |
+| `type` | `1`\|`2` | (edit tools only) switch task↔note |
+| `projectId` | ObjectId | (edit tools only) move to another project |
+
+Notes:
+
+- On create, `projectName` is resolved to a project id via your accessible projects (not the local folder config). If omitted, the backend applies your default project.
+- `complete` sets status=2 and, for a recurring task, stops the series and completes the current occurrence.
+- Reminders, recurrence, positions, kanban and timezone handling are all applied server-side (the tools reuse Planko's own task logic).
+
+#### Examples
+
+```
+planko_create_task(name: "Ship v2", projectName: "Work", dueDate: "2026-08-01", priority: 1)
+planko_create_note(name: "Meeting notes", description: "# Sync\n- point A\n- point B")
+planko_edit_task(taskId: "665f...c0", name: "Ship v2.1", alertLeadTime: "1hour")
+planko_complete_task(taskId: "665f...c0")
+planko_delete_note(taskId: "665f...aa")
+```
+
+### Standalone read tools
+
+These also work with the **same API key** and require **no folder setup**. `list_*` returns a concise, readable summary (one line per item plus a `total`/page footer) — never a raw JSON dump. `view_*` returns full detail with the `description` converted from BlockNote to **Markdown** for display.
+
+| Tool | Description | Key parameters |
+|---|---|---|
+| `planko_list_tasks` | List your tasks (type=1) | all filters below |
+| `planko_list_notes` | List your notes (type=2) | filter subset: `showCompleted`, `projectName`/`projectId`, `tags`, `search`, `sortBy`, `limit`, `page` |
+| `planko_view_task` | View one task by id | `taskId` (required) |
+| `planko_view_note` | View one note by id (shares the view endpoint) | `taskId` (required) |
+
+**Scope.** Without `projectId`/`projectName`, a list is scoped to **your own** items. With a project (resolved from `projectName` via your accessible projects), it includes that project's items **including workspace-shared** ones from other members. `view_*` returns the item if you own it or can access its project, otherwise it errors (404 if missing, 403 if not visible). `view_task`/`view_note` do not filter by type — either id resolves; the `task`/`note` label is informational.
+
+**List filters** (`planko_list_tasks` accepts all; `planko_list_notes` accepts the applicable subset):
+
+| Filter | Type | Notes |
+|---|---|---|
+| `status` | `1` \| `2` | 1=open, 2=complete |
+| `showCompleted` | boolean | When false/omitted and no explicit `status`, completed items are excluded |
+| `priority` | `1` \| `2` \| `3` | (tasks only) |
+| `projectName` | string | Resolved to a project id via your accessible projects |
+| `projectId` | ObjectId | Alternative to `projectName` |
+| `parentId` | ObjectId | (tasks only) list subtasks of this parent |
+| `tags` | array of ObjectId | AND semantics — item must have all tags |
+| `search` | string | Case-insensitive match on the name |
+| `dueDateFrom` / `dueDateTo` | `YYYY-MM-DD` | (tasks only) inclusive due-date bounds |
+| `sortBy` | `field:asc` \| `field:desc` | Fields: `dueDate`, `createdAt`, `updatedAt`, `priority`, `position`, `name`; default `updatedAt:desc` |
+| `limit` | int | Default 50, max 200 |
+| `page` | int | Default 1 |
+
+Notes-specific behavior: deleted notes and recurring-copy notes are excluded server-side. For tasks, recurring occurrences appear as separate dated items.
+
+#### Examples
+
+```
+planko_list_tasks(status: 1, priority: 1, dueDateFrom: "2026-07-20", dueDateTo: "2026-07-26", sortBy: "dueDate:asc")
+planko_list_tasks(projectName: "Work", search: "invoice", limit: 20)
+planko_list_notes(search: "meeting", showCompleted: false)
+planko_view_task(taskId: "665f...c0")
+planko_view_note(taskId: "665f...aa")
+```
+
 ### Sync preview
 
 ```
@@ -112,10 +216,14 @@ Sync order: delete, pull, push. Local changes overwrite remote on conflict.
 
 ## How it works
 
-- Each Planko task maps to a local `.md` file (task name becomes filename)
+- Each Planko task/note maps to a local `.md` file (task name becomes filename)
+- Each folder is **type-bound**: `planko_setup` records `type` (1=tasks, 2=notes) on the folder's sync state and in the global config, and sync only pulls/pushes that type. New local `.md` files are created with the folder's type.
+  - The chosen `type` is sent to the backend on every `status`/`pull` (`&type=`) and `push` (body `type`) call.
+  - Backward-compatible: a config entry created before this feature has no `type`, so its folder keeps the legacy type-agnostic behavior (syncs all task types).
 - 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`
+- Sync state is tracked in `.planko-mcp-sync.json` per folder (includes `syncType` when set)
+- Global config is stored at `~/.planko-mcp/config.json` (each project entry stores `projectId`, `folder`, `email`, `type`)
+- The standalone CRUD tools bypass folders entirely and call user-scoped endpoints directly with your API key
 - API keys are never written to any file
 
 ## License

package/index.js

@@ -24,6 +24,7 @@ import {
   blockNoteToMarkdown,
   markdownToBlockNote,
   descriptionToMarkdown,
+  markdownToDescription,
 } from './src/converters.js';
 import {
   readConfig,
@@ -71,9 +72,10 @@ function toolError(text) {
 async function computeSyncDiff(projectId, folder, sync) {
   const localFiles = listLocalFiles(folder);
   const { byFileName, byId } = buildIndexes(sync.tasks);
+  const syncType = sync.syncType;
 
   // Get ALL tasks from server (no mcpLastSyncDate filter) to detect deletions
-  const statusData = await api.status(projectId);
+  const statusData = await api.status(projectId, null, syncType);
   const remoteTasks = statusData.tasks || [];
   const remoteIdSet = new Set(remoteTasks.map((t) => t._id.toString()));
 
@@ -169,10 +171,11 @@ async function computeSyncDiff(projectId, folder, sync) {
 async function executeSync(projectId, folder, sync) {
   const localFiles = listLocalFiles(folder);
   const prePullSyncDate = sync.mcpLastSyncDate;
+  const syncType = sync.syncType;
   const results = [];
 
   // Get ALL tasks to detect deletions
-  const allStatusData = await api.status(projectId);
+  const allStatusData = await api.status(projectId, null, syncType);
   const allRemoteTasks = allStatusData.tasks || [];
   const remoteIdSet = new Set(allRemoteTasks.map((t) => t._id.toString()));
 
@@ -214,7 +217,7 @@ async function executeSync(projectId, folder, sync) {
   }
 
   if (toDeleteRemote.length > 0) {
-    const deleteResponse = await api.push(projectId, toDeleteRemote);
+    const deleteResponse = await api.push(projectId, toDeleteRemote, syncType);
     const deletedRemote = (deleteResponse.tasks || []).filter((t) => t.deleted);
     // Remove deleted tasks from sync state
     const deletedIds = new Set(deletedRemote.map((t) => t._id.toString()));
@@ -223,7 +226,7 @@ async function executeSync(projectId, folder, sync) {
   }
 
   // --- PULL phase ---
-  const pullData = await api.pull(projectId, prePullSyncDate);
+  const pullData = await api.pull(projectId, prePullSyncDate, syncType);
   const pulledTasks = pullData.tasks || [];
 
   const { byId } = buildIndexes(sync.tasks);
@@ -308,7 +311,7 @@ async function executeSync(projectId, folder, sync) {
       });
     }
 
-    const pushResponse = await api.push(projectId, pushItems);
+    const pushResponse = await api.push(projectId, pushItems, syncType);
     const responseTasks = (pushResponse.tasks || []).filter((t) => !t.deleted);
 
     const { byId: pushIdIdx, byFileName: pushFnIdx } = buildIndexes(sync.tasks);
@@ -363,13 +366,16 @@ const server = new McpServer({
 // ---- 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.',
+  '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, email, and whether the folder syncs tasks or notes.',
   {
     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'),
+    syncType: z
+      .enum(['tasks', 'notes'])
+      .describe("Whether this folder syncs 'tasks' (type=1) or 'notes' (type=2)"),
   },
-  async ({ projectName, folderPath, email }) => {
+  async ({ projectName, folderPath, email, syncType }) => {
     try {
       // List user's projects to find the matching one
       const { projects } = await api.projects();
@@ -390,6 +396,8 @@ server.tool(
         mkdirSync(folderPath, { recursive: true });
       }
 
+      const type = syncType === 'notes' ? 2 : 1;
+
       // Save to global config
       const config = readConfig();
       config.projects = config.projects || {};
@@ -398,20 +406,24 @@ server.tool(
         folder: folderPath,
         email,
         isWorkspace: match.isWorkspace,
+        type,
       };
       writeConfig(config);
 
       // Initialize sync state for this folder
-      const syncState = createSyncState(match._id, match.name);
+      const syncState = createSyncState(match._id, match.name, type);
       writeSyncState(folderPath, syncState);
 
+      const typeLabel = type === 2 ? 'Notes' : 'Tasks';
+
       return toolOk(
         `Setup complete for project "${match.name}".\n` +
           `  Project ID: ${match._id}\n` +
           `  Folder: ${folderPath}\n` +
           `  Email: ${email}\n` +
+          `  Syncs: ${typeLabel} (type=${type})\n` +
           `  Workspace: ${match.isWorkspace ? 'Yes' : 'No (personal)'}\n\n` +
-          `Run planko_sync to pull tasks into this folder.`
+          `Run planko_sync to pull ${typeLabel.toLowerCase()} into this folder.`
       );
     } catch (err) {
       return toolError(`Setup failed: ${err.message}`);
@@ -540,7 +552,8 @@ server.tool(
       for (const target of targets) {
         let sync = readSyncState(target.folder);
         if (!sync) {
-          sync = createSyncState(target.projectId, target.name);
+          // target.type is undefined for pre-feature config entries → legacy type-agnostic sync.
+          sync = createSyncState(target.projectId, target.name, target.type);
         }
 
         allResults.push(`--- ${target.name} (${target.folder}) ---`);
@@ -561,6 +574,505 @@ server.tool(
   }
 );
 
+// --- Standalone CRUD tools (Part B) ---
+// These operate directly via the user-scoped API key and do NOT require any
+// folder to be configured with planko_setup. Notes are Task docs with type=2;
+// tasks are type=1. Edit/Delete work on both; Complete is task-oriented.
+
+const objectId = z
+  .string()
+  .regex(/^[a-fA-F\d]{24}$/, 'Must be a 24-character hex ObjectId');
+
+const timeRegex = /^([01]?[0-9]|2[0-3]):[0-5][0-9]$/;
+
+// Shared editable task/note properties (all optional). `description` is Markdown
+// here and is converted to BlockNote JSON before being sent to the backend.
+const taskProps = {
+  description: z
+    .string()
+    .optional()
+    .describe('Body as Markdown (converted to BlockNote JSON before saving)'),
+  dueDate: z.string().optional().describe('Due date (ISO 8601 string)'),
+  datePlain: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
+    .optional()
+    .describe('Plain date, YYYY-MM-DD'),
+  time: z.string().regex(timeRegex, 'Must be HH:MM').optional().describe('Start time, HH:MM'),
+  endTime: z.string().regex(timeRegex, 'Must be HH:MM').optional().describe('End time, HH:MM'),
+  alert: z.boolean().optional().describe('Whether an alert/reminder is enabled'),
+  alertLeadTime: z
+    .enum(['ontime', '15min', '30min', '1hour', '1day'])
+    .nullable()
+    .optional()
+    .describe('Reminder lead time (null or one of ontime/15min/30min/1hour/1day)'),
+  priority: z
+    .union([z.literal(1), z.literal(2), z.literal(3)])
+    .optional()
+    .describe('Priority: 1, 2, or 3'),
+  repeat: z
+    .enum(['daily', 'workdays', 'weekly', 'biweekly', 'monthly', 'custom_weekly', 'yearly'])
+    .nullable()
+    .optional()
+    .describe('Recurrence rule (null or one of the recurrence keywords)'),
+  repeatDate: z.string().optional().describe('Recurrence end/anchor date (ISO 8601 string)'),
+  selectedWeekdays: z
+    .array(z.number().int().min(0).max(6))
+    .optional()
+    .describe('Weekdays for custom_weekly repeat (0=Sunday..6=Saturday)'),
+  parentId: objectId.optional().describe('Parent task id (for subtasks)'),
+  tags: z.array(objectId).optional().describe('Array of tag ids'),
+  kanbanColumnId: objectId.optional().describe('Kanban column id'),
+  boardId: objectId.optional().describe('Board id'),
+};
+
+/**
+ * Build a request body from tool params: drop undefined values and convert the
+ * Markdown `description` into BlockNote JSON.
+ */
+function buildTaskBody(params) {
+  const body = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    body[key] = value;
+  }
+  if ('description' in body) {
+    body.description = markdownToDescription(body.description);
+  }
+  return body;
+}
+
+/**
+ * Resolve a project name to a project id via the user's accessible projects
+ * (NOT the local folder config), so create tools work without any setup.
+ */
+async function resolveProjectId(projectName) {
+  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');
+    throw new Error(
+      `Project "${projectName}" not found.\n\nAvailable projects:\n${available}`
+    );
+  }
+  return match._id;
+}
+
+/** Extract { id, name } from a create/edit response (shape-tolerant). */
+function describeTask(res) {
+  const t = (res && (res.task || res.data)) || res || {};
+  return {
+    id: t._id || t.id || 'unknown',
+    name: t.name != null ? t.name : 'unknown',
+  };
+}
+
+/**
+ * Shared create handler for tasks (type=1) and notes (type=2).
+ */
+async function handleCreate(type, params, kindLabel) {
+  const { name, projectName, ...rest } = params;
+  const body = buildTaskBody(rest);
+  body.name = name;
+  body.type = type;
+
+  // Resolve projectName -> projectId via the API. When omitted, OMIT the key
+  // entirely so the backend applies the user's default project.
+  if (projectName) {
+    body.projectId = await resolveProjectId(projectName);
+  }
+
+  const res = await api.createTask(body);
+  const { id, name: savedName } = describeTask(res);
+  const where = body.projectId
+    ? ` in project ${body.projectId}`
+    : ' in your default project';
+  return toolOk(`Created ${kindLabel} "${savedName}" (id: ${id})${where}.`);
+}
+
+/**
+ * Shared edit handler for tasks and notes (same endpoint).
+ */
+async function handleEdit(params, kindLabel) {
+  const { taskId, ...rest } = params;
+  const body = buildTaskBody(rest);
+  const changed = Object.keys(body);
+  if (changed.length === 0) {
+    return toolError('Nothing to update: provide at least one field to change.');
+  }
+  const res = await api.updateTask(taskId, body);
+  const { id, name: savedName } = describeTask(res);
+  return toolOk(
+    `Updated ${kindLabel} "${savedName}" (id: ${id}). Changed: ${changed.join(', ')}.`
+  );
+}
+
+// ---- planko_create_task ----
+server.tool(
+  'planko_create_task',
+  'Create a Planko task (type=1) directly via your API key. Works without any folder setup. Provide a name (required); all other properties are optional. Optionally target a project by name (otherwise your default project is used).',
+  {
+    name: z.string().describe('Task name (required)'),
+    projectName: z
+      .string()
+      .optional()
+      .describe('Project name to create the task in (optional — omit for your default project)'),
+    ...taskProps,
+  },
+  async (params) => {
+    try {
+      return await handleCreate(1, params, 'task');
+    } catch (err) {
+      return toolError(`Create task failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_create_note ----
+server.tool(
+  'planko_create_note',
+  'Create a Planko note (type=2) directly via your API key. Works without any folder setup. Provide a name (required); all other properties are optional. Optionally target a project by name (otherwise your default project is used).',
+  {
+    name: z.string().describe('Note name (required)'),
+    projectName: z
+      .string()
+      .optional()
+      .describe('Project name to create the note in (optional — omit for your default project)'),
+    ...taskProps,
+  },
+  async (params) => {
+    try {
+      return await handleCreate(2, params, 'note');
+    } catch (err) {
+      return toolError(`Create note failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_edit_task ----
+server.tool(
+  'planko_edit_task',
+  'Edit an existing Planko task by id. Provide the taskId and any properties to change. The Markdown description is converted to BlockNote JSON.',
+  {
+    taskId: objectId.describe('Id of the task to edit (required)'),
+    name: z.string().optional().describe('New task name'),
+    type: z
+      .union([z.literal(1), z.literal(2)])
+      .optional()
+      .describe('Change type: 1=task, 2=note'),
+    projectId: objectId.optional().describe('Move to a different project by id'),
+    ...taskProps,
+  },
+  async (params) => {
+    try {
+      return await handleEdit(params, 'task');
+    } catch (err) {
+      return toolError(`Edit task failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_edit_note ----
+server.tool(
+  'planko_edit_note',
+  'Edit an existing Planko note by id (shares the task edit endpoint). Provide the taskId and any properties to change. The Markdown description is converted to BlockNote JSON.',
+  {
+    taskId: objectId.describe('Id of the note to edit (required)'),
+    name: z.string().optional().describe('New note name'),
+    type: z
+      .union([z.literal(1), z.literal(2)])
+      .optional()
+      .describe('Change type: 1=task, 2=note'),
+    projectId: objectId.optional().describe('Move to a different project by id'),
+    ...taskProps,
+  },
+  async (params) => {
+    try {
+      return await handleEdit(params, 'note');
+    } catch (err) {
+      return toolError(`Edit note failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_complete_task ----
+server.tool(
+  'planko_complete_task',
+  'Mark a Planko task complete (status=2) by id.',
+  {
+    taskId: objectId.describe('Id of the task to complete (required)'),
+  },
+  async ({ taskId }) => {
+    try {
+      const res = await api.completeTask(taskId);
+      const { id, name } = describeTask(res);
+      return toolOk(`Completed task "${name}" (id: ${id}).`);
+    } catch (err) {
+      return toolError(`Complete task failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_delete_task ----
+server.tool(
+  'planko_delete_task',
+  'Delete a Planko task by id.',
+  {
+    taskId: objectId.describe('Id of the task to delete (required)'),
+  },
+  async ({ taskId }) => {
+    try {
+      await api.deleteTask(taskId);
+      return toolOk(`Deleted task (id: ${taskId}).`);
+    } catch (err) {
+      return toolError(`Delete task failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_delete_note ----
+server.tool(
+  'planko_delete_note',
+  'Delete a Planko note by id (shares the task delete endpoint).',
+  {
+    taskId: objectId.describe('Id of the note to delete (required)'),
+  },
+  async ({ taskId }) => {
+    try {
+      await api.deleteTask(taskId);
+      return toolOk(`Deleted note (id: ${taskId}).`);
+    } catch (err) {
+      return toolError(`Delete note failed: ${err.message}`);
+    }
+  }
+);
+
+// --- Standalone READ tools (Part C) ---
+// Read-only, user-scoped via API key; no folder setup required. List tools send
+// `type` (1=tasks, 2=notes) and parametrized filters; view tools fetch one item
+// by id and render its BlockNote description as Markdown. No mutation.
+
+const datePlain = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD');
+
+const sortBySchema = z
+  .string()
+  .describe(
+    "Sort as 'field:asc' or 'field:desc'. Allowed fields: dueDate, createdAt, updatedAt, priority, position, name. Default updatedAt:desc."
+  );
+
+const STATUS_LABEL = { 1: 'open', 2: 'complete' };
+
+/** Human label for a status code. */
+function statusLabel(status) {
+  return STATUS_LABEL[status] || (status == null ? 'unknown' : String(status));
+}
+
+/** Render a task/note's tags as a comma list of names (fallback to ids). */
+function formatTags(tags) {
+  if (!Array.isArray(tags) || tags.length === 0) return null;
+  return tags
+    .map((t) => (t && typeof t === 'object' ? t.name || t._id : t))
+    .filter(Boolean)
+    .join(', ');
+}
+
+/** Build the API filter params from tool params, resolving projectName. */
+async function buildListParams(type, params) {
+  const { projectName, ...rest } = params;
+  const out = { type };
+  for (const [key, value] of Object.entries(rest)) {
+    if (value === undefined) continue;
+    out[key] = value;
+  }
+  if (projectName) {
+    out.projectId = await resolveProjectId(projectName);
+  }
+  return out;
+}
+
+/** One concise summary line per item for list output. */
+function summarizeItem(item, index) {
+  const parts = [];
+  parts.push(`status: ${statusLabel(item.status)}`);
+  if (item.priority != null) parts.push(`priority: ${item.priority}`);
+  if (item.dueDate) parts.push(`due: ${item.dueDate}${item.time ? ` ${item.time}` : ''}`);
+  else if (item.datePlain) parts.push(`due: ${item.datePlain}${item.time ? ` ${item.time}` : ''}`);
+  const tagStr = formatTags(item.tags);
+  if (tagStr) parts.push(`tags: ${tagStr}`);
+  if (item.projectId) parts.push(`project: ${item.projectId}`);
+  return (
+    `${index}. ${item.name || '(untitled)'} [id: ${item._id}]\n` +
+    `   ${parts.join(' | ')}`
+  );
+}
+
+/** Render a list response as a concise, readable summary (not raw JSON). */
+function renderList(result, kindLabelPlural) {
+  const tasks = Array.isArray(result?.tasks) ? result.tasks : [];
+  const total = result?.total ?? tasks.length;
+  const page = result?.page ?? 1;
+  const limit = result?.limit ?? tasks.length;
+
+  if (tasks.length === 0) {
+    return `No ${kindLabelPlural} found (total: ${total}, page ${page}).`;
+  }
+
+  const lines = tasks.map((t, i) => summarizeItem(t, i + 1));
+  const footer = `\nShowing ${tasks.length} of ${total} ${kindLabelPlural} (page ${page}, limit ${limit}).`;
+  return `${lines.join('\n')}\n${footer}`;
+}
+
+/** Render one item's full detail with the description converted to Markdown. */
+function renderItem(item, kindLabel) {
+  const lines = [];
+  lines.push(`${item.name || '(untitled)'}`);
+  lines.push(`id: ${item._id}`);
+  lines.push(`type: ${item.type === 2 ? 'note' : 'task'} (${kindLabel})`);
+  lines.push(`status: ${statusLabel(item.status)}`);
+  if (item.priority != null) lines.push(`priority: ${item.priority}`);
+  if (item.dueDate) lines.push(`due: ${item.dueDate}${item.time ? ` ${item.time}` : ''}`);
+  else if (item.datePlain) lines.push(`due: ${item.datePlain}${item.time ? ` ${item.time}` : ''}`);
+  const tagStr = formatTags(item.tags);
+  if (tagStr) lines.push(`tags: ${tagStr}`);
+  if (item.projectId) lines.push(`project: ${item.projectId}`);
+  if (item.parentId) lines.push(`parent: ${item.parentId}`);
+  if (item.createdAt) lines.push(`created: ${item.createdAt}`);
+  if (item.updatedAt) lines.push(`updated: ${item.updatedAt}`);
+
+  const md = descriptionToMarkdown(item.description);
+  lines.push('');
+  lines.push('--- description ---');
+  lines.push(md && md.trim() ? md : '(empty)');
+  return lines.join('\n');
+}
+
+/** Extract a single item from a view response (shape-tolerant). */
+function unwrapItem(res) {
+  return (res && (res.task || res.data)) || res || {};
+}
+
+// Shared list filter surface (task tools use all; note tools use the applicable subset).
+const listStatus = z
+  .union([z.literal(1), z.literal(2)])
+  .optional()
+  .describe('Filter by status: 1=open, 2=complete');
+const listShowCompleted = z
+  .boolean()
+  .optional()
+  .describe('When false/omitted (and no explicit status), completed items are excluded');
+const listProjectName = z
+  .string()
+  .optional()
+  .describe('Filter to a project by name (resolved to its id)');
+const listProjectId = objectId.optional().describe('Filter to a project by id');
+const listTags = z.array(objectId).optional().describe('Filter by tag ids (AND — item must have all)');
+const listSearch = z.string().optional().describe('Case-insensitive search on the name');
+const listSortBy = sortBySchema.optional();
+const listLimit = z
+  .number()
+  .int()
+  .min(1)
+  .max(200)
+  .optional()
+  .describe('Max items to return (default 50, max 200)');
+const listPage = z.number().int().min(1).optional().describe('Page number (default 1)');
+
+// ---- planko_list_tasks ----
+server.tool(
+  'planko_list_tasks',
+  'List your Planko tasks (type=1) via your API key, no folder setup required. Filters are optional. Without projectId/projectName the list is scoped to your own tasks; with a project it includes that project\'s (incl. workspace-shared) tasks. Note: recurring tasks appear as separate dated occurrences. Returns a concise summary, not raw JSON.',
+  {
+    status: listStatus,
+    showCompleted: listShowCompleted,
+    priority: z
+      .union([z.literal(1), z.literal(2), z.literal(3)])
+      .optional()
+      .describe('Filter by priority: 1, 2, or 3'),
+    projectName: listProjectName,
+    projectId: listProjectId,
+    parentId: objectId.optional().describe('List subtasks of this parent task id'),
+    tags: listTags,
+    search: listSearch,
+    dueDateFrom: datePlain.optional().describe('Inclusive lower bound on due date (YYYY-MM-DD)'),
+    dueDateTo: datePlain.optional().describe('Inclusive upper bound on due date (YYYY-MM-DD)'),
+    sortBy: listSortBy,
+    limit: listLimit,
+    page: listPage,
+  },
+  async (params) => {
+    try {
+      const apiParams = await buildListParams(1, params);
+      const result = await api.listTasks(apiParams);
+      return toolOk(renderList(result, 'tasks'));
+    } catch (err) {
+      return toolError(`List tasks failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_list_notes ----
+server.tool(
+  'planko_list_notes',
+  'List your Planko notes (type=2) via your API key, no folder setup required. Filters are optional. Without projectId/projectName the list is scoped to your own notes; with a project it includes that project\'s (incl. workspace-shared) notes. Deleted and recurring-copy notes are excluded. Returns a concise summary, not raw JSON.',
+  {
+    showCompleted: listShowCompleted,
+    projectName: listProjectName,
+    projectId: listProjectId,
+    tags: listTags,
+    search: listSearch,
+    sortBy: listSortBy,
+    limit: listLimit,
+    page: listPage,
+  },
+  async (params) => {
+    try {
+      const apiParams = await buildListParams(2, params);
+      const result = await api.listTasks(apiParams);
+      return toolOk(renderList(result, 'notes'));
+    } catch (err) {
+      return toolError(`List notes failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_view_task ----
+server.tool(
+  'planko_view_task',
+  'View one Planko task by id, with its description rendered as Markdown. The type is informational — this endpoint returns the item regardless of task/note type.',
+  {
+    taskId: objectId.describe('Id of the task to view (required)'),
+  },
+  async ({ taskId }) => {
+    try {
+      const res = await api.getTask(taskId);
+      return toolOk(renderItem(unwrapItem(res), 'task'));
+    } catch (err) {
+      return toolError(`View task failed: ${err.message}`);
+    }
+  }
+);
+
+// ---- planko_view_note ----
+server.tool(
+  'planko_view_note',
+  'View one Planko note by id, with its description rendered as Markdown. The type is informational — this endpoint returns the item regardless of task/note type.',
+  {
+    taskId: objectId.describe('Id of the note to view (required)'),
+  },
+  async ({ taskId }) => {
+    try {
+      const res = await api.getTask(taskId);
+      return toolOk(renderItem(unwrapItem(res), 'note'));
+    } catch (err) {
+      return toolError(`View note failed: ${err.message}`);
+    }
+  }
+);
+
 // --- Start server ---
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planko-mcp-server",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "MCP server for syncing Planko tasks with local Markdown files",
   "type": "module",
   "bin": {

package/src/api.js

@@ -51,35 +51,107 @@ export function createApiClient({ apiKey, apiBase }) {
     },
 
     /**
-     * GET /mcp-project-sync/status?projectId=...&mcpLastSyncDate=...
+     * GET /mcp-project-sync/status?projectId=...&mcpLastSyncDate=...&type=...
+     * `type` (1=tasks, 2=notes) is appended whenever set, independent of mcpLastSyncDate.
      */
-    async status(projectId, mcpLastSyncDate) {
+    async status(projectId, mcpLastSyncDate, type) {
       let qs = `projectId=${projectId}`;
       if (mcpLastSyncDate != null) {
         qs += `&mcpLastSyncDate=${mcpLastSyncDate}`;
       }
+      if (type === 1 || type === 2) {
+        qs += `&type=${type}`;
+      }
       return request('GET', `/mcp-project-sync/status?${qs}`);
     },
 
     /**
-     * GET /mcp-project-sync/pull?projectId=...&mcpLastSyncDate=...
+     * GET /mcp-project-sync/pull?projectId=...&mcpLastSyncDate=...&type=...
      */
-    async pull(projectId, mcpLastSyncDate) {
+    async pull(projectId, mcpLastSyncDate, type) {
       let qs = `projectId=${projectId}`;
       if (mcpLastSyncDate != null) {
         qs += `&mcpLastSyncDate=${mcpLastSyncDate}`;
       }
+      if (type === 1 || type === 2) {
+        qs += `&type=${type}`;
+      }
       return request('GET', `/mcp-project-sync/pull?${qs}`);
     },
 
     /**
      * POST /mcp-project-sync/push
+     * `type` (1=tasks, 2=notes) is included in the body whenever set.
+     */
+    async push(projectId, tasks, type) {
+      const body = { projectId, tasks };
+      if (type === 1 || type === 2) {
+        body.type = type;
+      }
+      return request('POST', '/mcp-project-sync/push', body);
+    },
+
+    // --- Standalone CRUD (user-scoped, no folder sync required) ---
+
+    /**
+     * POST /mcp-project-sync/tasks — create a task (type=1) or note (type=2).
+     */
+    async createTask(body) {
+      return request('POST', '/mcp-project-sync/tasks', body);
+    },
+
+    /**
+     * PATCH /mcp-project-sync/tasks/:taskId — edit a task or note.
+     */
+    async updateTask(taskId, body) {
+      return request('PATCH', `/mcp-project-sync/tasks/${taskId}`, body);
+    },
+
+    /**
+     * POST /mcp-project-sync/tasks/:taskId/complete — mark complete (status=2).
+     */
+    async completeTask(taskId) {
+      return request('POST', `/mcp-project-sync/tasks/${taskId}/complete`);
+    },
+
+    /**
+     * DELETE /mcp-project-sync/tasks/:taskId — delete a task or note.
+     */
+    async deleteTask(taskId) {
+      return request('DELETE', `/mcp-project-sync/tasks/${taskId}`);
+    },
+
+    // --- Read (user-scoped, no folder sync required) ---
+
+    /**
+     * GET /mcp-project-sync/tasks — list the user's tasks (type=1) or notes
+     * (type=2) with parametrized filters. Builds the query string from `params`,
+     * omitting undefined/null values. A `tags` array is serialized to a CSV
+     * string (the backend splits on comma).
+     */
+    async listTasks(params = {}) {
+      const qs = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null) continue;
+        if (key === 'tags' && Array.isArray(value)) {
+          if (value.length === 0) continue;
+          qs.set(key, value.join(','));
+        } else {
+          qs.set(key, String(value));
+        }
+      }
+      const query = qs.toString();
+      return request(
+        'GET',
+        `/mcp-project-sync/tasks${query ? `?${query}` : ''}`
+      );
+    },
+
+    /**
+     * GET /mcp-project-sync/tasks/:taskId — fetch one task or note by id.
      */
-    async push(projectId, tasks) {
-      return request('POST', '/mcp-project-sync/push', {
-        projectId,
-        tasks,
-      });
+    async getTask(taskId) {
+      return request('GET', `/mcp-project-sync/tasks/${taskId}`);
     },
   };
 }

package/src/sync-state.js

@@ -77,8 +77,8 @@ export function writeSyncState(folder, data) {
   writeFileSync(join(folder, SYNC_FILE), JSON.stringify(safe, null, 2));
 }
 
-export function createSyncState(projectId, projectName) {
-  return {
+export function createSyncState(projectId, projectName, syncType) {
+  const state = {
     project: {
       _id: projectId,
       name: projectName,
@@ -88,6 +88,11 @@ export function createSyncState(projectId, projectName) {
     mcpLastSyncPushChanges: [],
     tasks: [],
   };
+  // syncType: 1 = tasks, 2 = notes. Omitted (undefined) => legacy type-agnostic sync.
+  if (syncType === 1 || syncType === 2) {
+    state.syncType = syncType;
+  }
+  return state;
 }
 
 // --- Local file operations ---