planko-mcp-server 0.4.2 → 0.5.0

package/README.md

@@ -158,7 +158,9 @@ These also work with the **same API key** and require **no folder setup**. `list
 | `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.
+**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. Use `assigneeId` to narrow a project listing to one member; omit it for all 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.
+
+**Owner in output.** When the backend populates an item's `userId` as an object `{ _id, name, email }`, list lines and `view_*` detail append `owner: <name>` so you can tell whose task it is in a multi-member project listing. If `userId` is a bare id/string, nothing extra is shown.
 
 **List filters** (`planko_list_tasks` accepts all; `planko_list_notes` accepts the applicable subset):
 
@@ -169,6 +171,7 @@ These also work with the **same API key** and require **no folder setup**. `list
 | `priority` | `1` \| `2` \| `3` | (tasks only) |
 | `projectName` | string | Resolved to a project id via your accessible projects |
 | `projectId` | ObjectId | Alternative to `projectName` |
+| `assigneeId` | ObjectId | Filter to a single project member by their user id. Omit for **all members**. Applies within a project listing (needs a project scope to be meaningful) |
 | `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 |
@@ -213,6 +216,45 @@ Sync order: delete, pull, push. Local changes overwrite remote on conflict.
 |---|---|---|
 | `PLANKO_API_KEY` | Yes | Your MCP API key from app.planko.io/integrations |
 | `PLANKO_API_BASE` | No | API base URL override (defaults to production) |
+| `PLANKO_PROJECT_LOCK` | No | Confine every operation to a single project id (see below). **Off by default** — when unset the server behaves exactly as before. |
+
+### Project lock (`PLANKO_PROJECT_LOCK`)
+
+Set `PLANKO_PROJECT_LOCK` to a project id to restrict this server instance to that
+one project. This is a **hard override the agent cannot bypass** — useful when a
+shared automation should only ever touch a single project.
+
+When set, it changes behavior as follows:
+
+- **Create** (`create_task` / `create_note`): the new item is always created in the
+  locked project; any `projectName` the caller passes is ignored (and not resolved).
+- **List** (`list_tasks` / `list_notes`): always scoped to the locked project
+  (ignoring `projectName`/`projectId`), which yields the all-members listing for
+  that project. Combine with `assigneeId` to narrow to one member.
+- **Edit** (`edit_task` / `edit_note`): if the caller supplies a `projectId`, it is
+  forced back to the locked project (an edit can never move a task out of it). If no
+  project field is supplied, the project is left unchanged.
+- **By-id operations** (`edit_*`, `complete_task`, `delete_*`, `view_*`): the target
+  task is fetched first, and the operation is refused with an error if the task does
+  not belong to the locked project.
+
+**Off by default:** when `PLANKO_PROJECT_LOCK` is unset (or blank), none of the above
+applies and the server is fully backward-compatible.
+
+```json
+{
+  "mcpServers": {
+    "planko": {
+      "command": "npx",
+      "args": ["-y", "planko-mcp-server"],
+      "env": {
+        "PLANKO_API_KEY": "your-api-key",
+        "PLANKO_PROJECT_LOCK": "6742635e764bda007ab987ed"
+      }
+    }
+  }
+}
+```
 
 ## How it works
 

package/index.js

@@ -21,6 +21,12 @@ import { join } from 'node:path';
 
 import { createApiClient } from './src/api.js';
 import { isBlankValue, applyDueDateFallback } from './src/sanitize.js';
+import {
+  lockProjectId,
+  sanitizeFilters,
+  ownerName,
+  assertProjectAllowed,
+} from './src/projectLock.js';
 import {
   blockNoteToMarkdown,
   markdownToBlockNote,
@@ -54,6 +60,11 @@ if (!API_KEY) {
 
 const api = createApiClient({ apiKey: API_KEY });
 
+// Optional project lock. When set, EVERY operation is confined to this single
+// project id (a hard override the agent cannot bypass). Read once at startup.
+// When null (the default) behavior is identical to before this feature.
+const PROJECT_LOCK = (process.env.PLANKO_PROJECT_LOCK || '').trim() || null;
+
 // --- Tool helpers ---
 
 function toolOk(text) {
@@ -361,7 +372,7 @@ async function executeSync(projectId, folder, sync) {
 
 const server = new McpServer({
   name: 'planko-mcp-server',
-  version: '0.2.0',
+  version: '0.5.0',
 });
 
 // ---- planko_setup ----
@@ -671,6 +682,16 @@ function describeTask(res) {
   };
 }
 
+/**
+ * When PROJECT_LOCK is set, fetch a by-id task and refuse the operation unless
+ * it belongs to the locked project. No-op when the lock is null.
+ */
+async function assertTaskInLock(taskId) {
+  if (!PROJECT_LOCK) return;
+  const res = await api.getTask(taskId);
+  assertProjectAllowed(PROJECT_LOCK, unwrapItem(res));
+}
+
 /**
  * Shared create handler for tasks (type=1) and notes (type=2).
  */
@@ -680,9 +701,13 @@ async function handleCreate(type, params, kindLabel) {
   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 (!isBlankValue(projectName)) {
+  if (PROJECT_LOCK) {
+    // Hard override: always the locked project; ignore any caller project field
+    // and do NOT resolve projectName.
+    body.projectId = lockProjectId(PROJECT_LOCK, body.projectId);
+  } else if (!isBlankValue(projectName)) {
+    // Resolve projectName -> projectId via the API. When omitted, OMIT the key
+    // entirely so the backend applies the user's default project.
     body.projectId = await resolveProjectId(projectName);
   }
 
@@ -704,6 +729,16 @@ async function handleEdit(params, kindLabel) {
   if (changed.length === 0) {
     return toolError('Nothing to update: provide at least one field to change.');
   }
+  if (PROJECT_LOCK) {
+    // Refuse to touch a task outside the locked project.
+    await assertTaskInLock(taskId);
+    // If the caller tried to move the task to another project, force it back to
+    // the lock (never let an edit move a task OUT of the locked project). If no
+    // project field was passed, leave the project unchanged.
+    if ('projectId' in body) {
+      body.projectId = lockProjectId(PROJECT_LOCK, body.projectId);
+    }
+  }
   const res = await api.updateTask(taskId, body);
   const { id, name: savedName } = describeTask(res);
   return toolOk(
@@ -808,6 +843,7 @@ server.tool(
   },
   async ({ taskId }) => {
     try {
+      await assertTaskInLock(taskId);
       const res = await api.completeTask(taskId);
       const { id, name } = describeTask(res);
       return toolOk(`Completed task "${name}" (id: ${id}).`);
@@ -826,6 +862,7 @@ server.tool(
   },
   async ({ taskId }) => {
     try {
+      await assertTaskInLock(taskId);
       await api.deleteTask(taskId);
       return toolOk(`Deleted task (id: ${taskId}).`);
     } catch (err) {
@@ -843,6 +880,7 @@ server.tool(
   },
   async ({ taskId }) => {
     try {
+      await assertTaskInLock(taskId);
       await api.deleteTask(taskId);
       return toolOk(`Deleted note (id: ${taskId}).`);
     } catch (err) {
@@ -885,12 +923,17 @@ function formatTags(tags) {
 /** 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 (isBlankValue(value)) continue;
-    out[key] = value;
-  }
-  if (!isBlankValue(projectName)) {
+  // Sanitize scalar filters (drops blank/placeholder values, incl. a blank
+  // assigneeId => "all members"). projectId/assigneeId pass through here.
+  const out = { type, ...sanitizeFilters(rest) };
+  if (PROJECT_LOCK) {
+    // Hard override: force the project regardless of caller input. Do NOT
+    // resolve projectName here — the override wins unconditionally, so an
+    // invalid projectName must not be able to fail an otherwise-locked list
+    // (keeps list consistent with create, which also ignores projectName).
+    out.projectId = lockProjectId(PROJECT_LOCK, out.projectId);
+  } else if (!isBlankValue(projectName)) {
+    // Unlocked (default) path: unchanged behavior.
     out.projectId = await resolveProjectId(projectName);
   }
   return out;
@@ -906,6 +949,8 @@ function summarizeItem(item, index) {
   const tagStr = formatTags(item.tags);
   if (tagStr) parts.push(`tags: ${tagStr}`);
   if (item.projectId) parts.push(`project: ${item.projectId}`);
+  const owner = ownerName(item.userId);
+  if (owner) parts.push(`owner: ${owner}`);
   return (
     `${index}. ${item.name || '(untitled)'} [id: ${item._id}]\n` +
     `   ${parts.join(' | ')}`
@@ -941,6 +986,8 @@ function renderItem(item, kindLabel) {
   const tagStr = formatTags(item.tags);
   if (tagStr) lines.push(`tags: ${tagStr}`);
   if (item.projectId) lines.push(`project: ${item.projectId}`);
+  const owner = ownerName(item.userId);
+  if (owner) lines.push(`owner: ${owner}`);
   if (item.parentId) lines.push(`parent: ${item.parentId}`);
   if (item.createdAt) lines.push(`created: ${item.createdAt}`);
   if (item.updatedAt) lines.push(`updated: ${item.updatedAt}`);
@@ -971,6 +1018,9 @@ const listProjectName = z
   .optional()
   .describe('Filter to a project by name (resolved to its id)');
 const listProjectId = objectId.optional().describe('Filter to a project by id');
+const listAssigneeId = objectId
+  .optional()
+  .describe('Filter to a single project member by their user id (omit for all members)');
 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();
@@ -996,6 +1046,7 @@ server.tool(
       .describe('Filter by priority: 1, 2, or 3'),
     projectName: listProjectName,
     projectId: listProjectId,
+    assigneeId: listAssigneeId,
     parentId: objectId.optional().describe('List subtasks of this parent task id'),
     tags: listTags,
     search: listSearch,
@@ -1024,6 +1075,7 @@ server.tool(
     showCompleted: listShowCompleted,
     projectName: listProjectName,
     projectId: listProjectId,
+    assigneeId: listAssigneeId,
     tags: listTags,
     search: listSearch,
     sortBy: listSortBy,
@@ -1051,7 +1103,9 @@ server.tool(
   async ({ taskId }) => {
     try {
       const res = await api.getTask(taskId);
-      return toolOk(renderItem(unwrapItem(res), 'task'));
+      const item = unwrapItem(res);
+      assertProjectAllowed(PROJECT_LOCK, item);
+      return toolOk(renderItem(item, 'task'));
     } catch (err) {
       return toolError(`View task failed: ${err.message}`);
     }
@@ -1068,7 +1122,9 @@ server.tool(
   async ({ taskId }) => {
     try {
       const res = await api.getTask(taskId);
-      return toolOk(renderItem(unwrapItem(res), 'note'));
+      const item = unwrapItem(res);
+      assertProjectAllowed(PROJECT_LOCK, item);
+      return toolOk(renderItem(item, 'note'));
     } catch (err) {
       return toolError(`View note failed: ${err.message}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planko-mcp-server",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "MCP server for syncing Planko tasks with local Markdown files",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "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"
+    "prepublishOnly": "node --check index.js && node --check src/api.js && node --check src/converters.js && node --check src/sync-state.js && node --check src/projectLock.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1"

package/src/projectLock.js

@@ -0,0 +1,81 @@
+/**
+ * Project-lock decision logic (pure, testable).
+ *
+ * When the env var PLANKO_PROJECT_LOCK is set, the MCP server restricts EVERY
+ * operation to that single project id — a hard override the calling agent
+ * cannot bypass. When the lock is null (the default), all functions here behave
+ * as pass-throughs so existing callers (e.g. the "clawis" agent) are unaffected.
+ *
+ * These helpers are kept free of any I/O so they can be unit-tested directly;
+ * the server entrypoint (index.js) wires them into the tool handlers.
+ */
+
+import { isBlankValue } from './sanitize.js';
+
+/**
+ * Decide the effective projectId.
+ *   - lock set (truthy)  → always returns `lock` (ignores `requested`).
+ *   - lock null/blank     → returns `requested` unchanged (pass-through).
+ */
+export function lockProjectId(lock, requested) {
+  if (lock) return lock;
+  return requested;
+}
+
+/**
+ * Sanitize a bag of list/query filter params, dropping blank/placeholder values
+ * (empty strings, all-zero ObjectId, empty arrays) via isBlankValue. Used for
+ * every list filter including the optional `assigneeId` — when it is blank the
+ * key is omitted, which the backend treats as "all members".
+ * Returns a new object; does not mutate the input.
+ */
+export function sanitizeFilters(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(params || {})) {
+    if (isBlankValue(value)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Format an owner label from an item's `userId` field.
+ * The backend may populate `userId` as an object { _id, name, email } on
+ * list/view responses. Returns the owner's name when present, else null.
+ * Tolerates a bare string/id (returns null) and never throws.
+ */
+export function ownerName(userId) {
+  if (
+    userId &&
+    typeof userId === 'object' &&
+    !Array.isArray(userId) &&
+    typeof userId.name === 'string' &&
+    userId.name.trim() !== ''
+  ) {
+    return userId.name;
+  }
+  return null;
+}
+
+/**
+ * Extract a comparable project id string from a task's `projectId`, which may be
+ * a bare id string or a populated object { _id, ... }.
+ */
+function projectIdOf(task) {
+  const pid = task && task.projectId;
+  if (pid && typeof pid === 'object') return pid._id != null ? String(pid._id) : '';
+  return pid != null ? String(pid) : '';
+}
+
+/**
+ * Guard a by-id operation against the lock. When `lock` is null this is a no-op.
+ * When `lock` is set, throws unless the task belongs to the locked project.
+ * A missing/unknown projectId also throws (cannot prove it is in-scope).
+ */
+export function assertProjectAllowed(lock, task) {
+  if (!lock) return;
+  const pid = projectIdOf(task);
+  if (!pid || pid !== String(lock)) {
+    throw new Error('This agent is restricted to the "planko" project.');
+  }
+}